Fonction IoCreateFileEx (ntddk.h)

Article
03/08/2023

La routine IoCreateFileEx entraîne la création d’un fichier ou d’un répertoire, ou ouvre un fichier, un appareil, un répertoire ou un volume existant et donne à l’appelant un handle pour l’objet fichier. Les pilotes de filtre de système de fichiers (pilotes de filtre hérités) appellent cette routine.

Syntaxe

NTSTATUS IoCreateFileEx(
  [out]          PHANDLE                   FileHandle,
  [in]           ACCESS_MASK               DesiredAccess,
  [in]           POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]          PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional] PLARGE_INTEGER            AllocationSize,
  [in]           ULONG                     FileAttributes,
  [in]           ULONG                     ShareAccess,
  [in]           ULONG                     Disposition,
  [in]           ULONG                     CreateOptions,
  [in, optional] PVOID                     EaBuffer,
  [in]           ULONG                     EaLength,
  [in]           CREATE_FILE_TYPE          CreateFileType,
  [in, optional] PVOID                     InternalParameters,
  [in]           ULONG                     Options,
  [in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Paramètres

[out] FileHandle

Pointeur vers une variable qui reçoit le handle de fichier si l’appel réussit. Le pilote doit fermer la poignée avec ZwClose dès que la poignée n’est plus utilisée.

[in] DesiredAccess

Masque de bits d’indicateurs (voir ACCESS_MASK) qui spécifie le type d’accès requis par l’appelant au fichier ou au répertoire. Cet ensemble d’indicateurs DesiredAccess définis par le système détermine les droits d’accès spécifiques suivants pour les objets de fichier.

Indicateur DesiredAccess	Signification
Suppression	Le fichier peut être supprimé.
FILE_READ_DATA	Les données peuvent être lues à partir du fichier.
FILE_READ_ATTRIBUTES	Les indicateurs FileAttributes, décrits ci-dessous, peuvent être lus.
FILE_READ_EA	Les attributs étendus (EA) associés au fichier peuvent être lus.
READ_CONTROL	La liste de contrôle d’accès (ACL) et les informations de propriété associées au fichier peuvent être lues.
FILE_WRITE_DATA	Les données peuvent être écrites dans le fichier.
FILE_WRITE_ATTRIBUTES	Les indicateurs FileAttributes peuvent être écrits.
FILE_WRITE_EA	Les EA associées au fichier peuvent être écrites.
FILE_APPEND_DATA	Les données peuvent être ajoutées au fichier.
WRITE_DAC	La liste de contrôle d’accès discrétionnaire (DACL) associée au fichier peut être écrite.
WRITE_OWNER	Les informations de propriété associées au fichier peuvent être écrites.
SYNCHRONIZE	L’appelant peut synchroniser l’achèvement d’une opération d’E/S en attendant que l’état FileHandle retourné soit défini sur l’état Signaled. Cet indicateur doit être défini si l’indicateur CreateOptions FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT est défini.
FILE_EXECUTE	Les données peuvent être lues en mémoire à partir du fichier à l’aide d’E/S de pagination système.

Vous pouvez également spécifier un ou plusieurs des indicateurs de ACCESS_MASK génériques suivants pour tout objet fichier qui ne représente pas de répertoire. Les indicateurs STANDARD_RIGHTS_XXX sont des valeurs système prédéfinies utilisées pour appliquer la sécurité sur les objets système. Vous pouvez également combiner ces indicateurs génériques avec des indicateurs supplémentaires du tableau précédent.

Accès souhaité aux valeurs de fichier	Mappe aux indicateurs DesiredAccess
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SYNCHRONIZE.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SYNCHRONIZE.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, FILE_READ_ATTRIBUTES FILE_EXECUTE.

Pour les répertoires (l’indicateur CreateOptions FILE_DIRECTORY_FILE est défini), vous pouvez spécifier un ou plusieurs des indicateurs de ACCESS_MASK suivants, que vous pouvez également combiner avec les indicateurs compatibles décrits précédemment.

Accès souhaité aux valeurs d’annuaire	Signification
FILE_LIST_DIRECTORY	Les fichiers du répertoire peuvent être répertoriés.
FILE_TRAVERSE	Le répertoire peut être parcouru ; autrement dit, il peut faire partie du chemin d’accès d’un fichier.

Les indicateurs FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE et FILE_APPEND_DATA DesiredAccess ne sont pas compatibles avec la création ou l’ouverture d’un fichier de répertoire.

[in] ObjectAttributes

Pointeur vers une structure OBJECT_ATTRIBUTES déjà initialisée par la routine InitializeObjectAttributes . Si l’appelant s’exécute dans le contexte du processus système, ce paramètre peut être NULL. Sinon, l’appelant doit définir l’attribut OBJ_KERNEL_HANDLE dans l’appel sur InitializeObjectAttributes. Les membres de cette structure pour un objet fichier sont les suivants :

Membre	Valeur
Longueur ULONG	Nombre d’octets des données ObjectAttributes fournies. Cette valeur doit être au moins `sizeof(OBJECT_ATTRIBUTES)`.
PUNICODE_STRING ObjectName	Pointeur vers une chaîne Unicode mise en mémoire tampon qui contient le nom du fichier à créer ou ouvrir. Cette valeur doit être une spécification de fichier complète, sauf s’il s’agit du nom d’un fichier relatif au répertoire spécifié par RootDirectory. Par exemple, « \Device\Floppy1\myfile.dat » ou « ?? \B :\myfile.dat » peut être la spécification de fichier complète, tant que le pilote de lecteur de disque de disquette et le système de fichiers surchargé sont déjà chargés. (Remarque : « ? ? » remplace « \DosDevices » comme nom de l’espace de noms de l’objet Win32. « \DosDevices » fonctionne toujours, mais « ?? » est traduit plus rapidement par le gestionnaire d’objets.)
HANDLE RootDirectory	Handle facultatif vers un répertoire qui a été obtenu par un appel précédent à IoCreateFileEx. Si cette valeur est NULL, le membre ObjectName doit être une spécification de fichier complète qui inclut le chemin d’accès complet au fichier cible. Si cette valeur n’est pas NULL, le membre ObjectName spécifie un nom de fichier relatif à ce répertoire.
PSECURITY_DESCRIPTOR SecurityDescriptor	Descripteur de sécurité facultatif à appliquer à un fichier. Les listes de contrôle d’accès spécifiées par un descripteur de sécurité de ce type ne sont appliquées au fichier qu’au moment de sa création. Si la valeur est NULL lors de la création d’un fichier, la liste de contrôle d’accès placée sur le fichier dépend du système de fichiers ; la plupart des systèmes de fichiers propagent une partie de cette liste de contrôle d’accès à partir du fichier de répertoire parent combiné avec la liste de contrôle d’accès par défaut de l’appelant.
Attributs ULONG	Ensemble d’indicateurs qui contrôle les attributs de l’objet fichier. Si l’appelant s’exécute dans le contexte du processus système, ce paramètre peut être égal à zéro. Sinon, l’appelant doit définir l’indicateur OBJ_KERNEL_HANDLE . L’appelant peut également définir l’indicateur OBJ_CASE_INSENSITIVE , ce qui indique que le code de recherche de nom doit ignorer la casse de ObjectName au lieu d’effectuer une recherche de correspondance exacte.

[out] IoStatusBlock

Pointeur vers une variable de type IO_STATUS_BLOCK qui reçoit la status d’achèvement finale et des informations sur l’opération demandée. Lors du retour d’IoCreateFileEx, le membre Information de la variable contient l’une des valeurs suivantes :

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Spécifie éventuellement la taille d’allocation initiale, en octets, pour le fichier. Une valeur différente de zéro n’a aucun effet, sauf si le fichier est en cours de création, de remplacement ou de remplacement.

[in] FileAttributes

Les attributs explicitement spécifiés sont appliqués uniquement lorsque le fichier est créé, remplacé ou, dans certains cas, remplacé. Par défaut, cette valeur est FILE_ATTRIBUTE_NORMAL, qui peut être remplacée par n’importe quel autre indicateur ou par une combinaison (par le biais d’une opération OR au niveau du bit) d’indicateurs compatibles. Les indicateurs FileAttributes possibles incluent les éléments suivants.

Indicateurs FileAttributes	Signification
FILE_ATTRIBUTE_NORMAL	Un fichier qui a des attributs standard doit être créé.
FILE_ATTRIBUTE_READONLY	Un fichier en lecture seule doit être créé.
FILE_ATTRIBUTE_HIDDEN	Un fichier masqué doit être créé.
FILE_ATTRIBUTE_SYSTEM	Un fichier système doit être créé.
FILE_ATTRIBUTE_ARCHIVE	Le fichier doit être marqué pour qu’il soit archivé.
FILE_ATTRIBUTE_TEMPORARY	Un fichier temporaire doit être créé.

[in] ShareAccess

Spécifie le type d’accès partagé au fichier que l’appelant souhaite, comme zéro, ou un, ou une combinaison des indicateurs suivants. Pour demander l’accès exclusif, définissez ce paramètre sur zéro. Si l’indicateur IO_IGNORE_SHARE_ACCESS_CHECK est spécifié dans le paramètre Options , le gestionnaire d’E/S ignore le paramètre ShareAccess . Toutefois, le système de fichiers peut toujours effectuer des vérifications d’accès. Par conséquent, il est important de spécifier le mode de partage souhaité pour ce paramètre, même lorsque vous utilisez l’indicateur IO_IGNORE_SHARE_ACCESS_CHECK. Pour éviter les erreurs de violation de partage, spécifiez tous les indicateurs d’accès de partage suivants.

Indicateurs ShareAccess	Signification
FILE_SHARE_READ	Le fichier peut être ouvert pour l’accès en lecture par les appels de création de fichier d’autres threads.
FILE_SHARE_WRITE	Le fichier peut être ouvert pour l’accès en écriture par les appels de création de fichier d’autres threads.
FILE_SHARE_DELETE	Le fichier peut être ouvert pour supprimer l’accès par les appels de création de fichier d’autres threads.

Les pilotes de périphérique et les pilotes intermédiaires définissent généralement ShareAccess sur zéro, ce qui donne à l’appelant un accès exclusif au fichier ouvert.

[in] Disposition

Valeur qui détermine la façon dont le fichier doit être géré lorsque le fichier existe déjà. La disposition peut être l’une des suivantes.

Valeur	Signification
FILE_SUPERSEDE	Si le fichier existe déjà, remplacez-le par le fichier donné. S’il n’existe pas, créez le fichier donné.
FILE_CREATE	Si le fichier existe déjà, échouez la demande et ne créez pas ou n’ouvrez pas le fichier donné. S’il n’existe pas, créez le fichier donné.
FILE_OPEN	Si le fichier existe déjà, ouvrez-le au lieu de créer un fichier. S’il n’existe pas, échouez la demande et ne créez pas de fichier.
FILE_OPEN_IF	Si le fichier existe déjà, ouvrez-le. S’il n’existe pas, créez le fichier donné.
FILE_OVERWRITE	Si le fichier existe déjà, ouvrez-le et remplacez-le. S’il n’existe pas, la demande échoue.
FILE_OVERWRITE_IF	Si le fichier existe déjà, ouvrez-le et remplacez-le. S’il n’existe pas, créez le fichier donné.

[in] CreateOptions

Spécifie les options à appliquer lors de la création ou de l’ouverture du fichier, en tant que combinaison compatible des indicateurs suivants.

Indicateur CreateOptions	Signification
FILE_DIRECTORY_FILE (0x00000001)	Le fichier en cours de création ou d’ouverture est un fichier de répertoire. Avec cet indicateur, le paramètre Disposition doit être défini sur l’un des FILE_CREATE, FILE_OPEN ou FILE_OPEN_IF. Les indicateurs CreateOptions compatibles avec cet indicateur sont les suivants : FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT et FILE_OPEN_BY_FILE_ID.
FILE_WRITE_THROUGH (0x00000002)	Les services système, les systèmes de fichiers et les pilotes qui écrivent des données dans le fichier doivent effectivement transférer les données dans le fichier avant que toute opération d’écriture demandée soit considérée comme terminée.
FILE_SEQUENTIAL_ONLY (0x00000004)	Tous les accès au fichier seront séquentiels.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	Le fichier ne peut pas être mis en cache ou mis en mémoire tampon dans les mémoires tampons internes d’un pilote. Cet indicateur n’est pas compatible avec l’indicateur DesiredAccessFILE_APPEND_DATA.
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Toutes les opérations sur le fichier sont effectuées de manière synchrone. Toute attente de la part de l’appelant est sujette à l’arrêt prématuré des alertes. Cet indicateur permet également au système d’E/S de conserver le contexte de position du fichier. Si cet indicateur est défini, l’indicateur DesiredAccess SYNCHRONIZE doit également être défini pour que le Gestionnaire d’E/S utilise l’objet file comme objet de synchronisation.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Toutes les opérations sur le fichier sont effectuées de manière synchrone. Les attentes dans le système pour synchroniser la file d’attente d’E/S et l’achèvement ne sont pas soumises à des alertes. Cet indicateur permet également au système d’E/S de conserver le contexte de position du fichier. Si cet indicateur est défini, l’indicateur DesiredAccess SYNCHRONIZE doit également être défini pour que le Gestionnaire d’E/S utilise l’objet file comme objet de synchronisation.
FILE_NON_DIRECTORY_FILE (0x00000040)	Le fichier en cours d’ouverture ne doit pas être un fichier de répertoire, sinon cet appel échoue. L’objet file en cours d’ouverture peut représenter un fichier de données ; un appareil logique, virtuel ou physique ; ou un volume.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Créez une connexion d’arborescence pour ce fichier afin de l’ouvrir sur le réseau.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Effectuez cette opération immédiatement avec un autre code de réussite si le fichier cible est verrouillé, au lieu de bloquer le thread de l’appelant. Si le fichier est bloqué, un autre appelant a déjà accès au fichier sur le réseau.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Si les attributs étendus d’un fichier existant en cours d’ouverture indiquent que l’appelant doit comprendre les attributs étendus pour interpréter correctement le fichier, cette demande échoue, car l’appelant ne comprend pas comment traiter les attributs étendus.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Réservé à l’utilisation du système ; n’utilisez pas.
FILE_RANDOM_ACCESS (0x00000800)	Les accès au fichier pouvant être aléatoires, aucune opération de lecture anticipée séquentielle ne doit être effectuée sur le fichier par les systèmes de fichiers ou le système d’exploitation.
FILE_DELETE_ON_CLOSE (0x00001000)	Supprimez le fichier lorsque le dernier handle est passé à FltClose.
FILE_OPEN_BY_FILE_ID (0x00002000)	Le fichier est ouvert par ID. Le nom de fichier contient le nom d’un appareil et un ID 64 bits à utiliser pour ouvrir le fichier.
FILE_OPEN_FOR_BACKUP_INTENT (0x000004000)	Le fichier est ouvert pour l’intention de sauvegarde ; Par conséquent, le système doit case activée pour certains droits d’accès et accorder à l’appelant les accès appropriés au fichier avant de vérifier l’entrée DesiredAccess par rapport au descripteur de sécurité du fichier.
FILE_NO_COMPRESSION (0x00008000)	Supprimez l’héritage des FILE_ATTRIBUTE_COMPRESSED du répertoire parent. Cela permet de créer un fichier non compressé dans un répertoire marqué compressé.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000)	Le fichier est en cours d’ouverture et un verrou opportuniste (oplock) sur le fichier est demandé en tant qu’opération atomique unique. Le système de fichiers recherche les oplocks avant d’effectuer l’opération de création, et l’opération de création échoue avec un code de retour de STATUS_CANNOT_BREAK_OPLOCK si l’opération de création interrompt un oplock existant. Cet indicateur est disponible dans les systèmes d’exploitation Windows 7, Windows Server 2008 R2 et ultérieurs.
FILE_DISALLOW_EXCLUSIVE (0x00020000)	Lors de l’ouverture d’un fichier existant, si FILE_SHARE_READ n’est pas spécifié et que les vérifications d’accès au système de fichiers n’accordent pas à l’appelant l’accès en écriture au fichier, échouez cette ouverture avec STATUS_ACCESS_DENIED. Il s’agissait d’un comportement par défaut antérieur à Windows 7.
FILE_SESSION_AWARE (0x00040000)	Le fichier ou l’appareil est en cours d’ouverture avec la reconnaissance de session. Si cet indicateur n’est pas spécifié, les appareils par session (par exemple, un appareil utilisant la redirection USB RemoteFX) ne peuvent pas être ouverts par les processus s’exécutant dans la session 0. Cet indicateur n’a aucun effet pour les appelants qui ne sont pas dans la session 0. Cet indicateur est pris en charge uniquement sur les éditions serveur de Windows. Cet indicateur n’est pas pris en charge avant Windows Server 2012.
FILE_RESERVE_OPFILTER (0x00100000)	Cet indicateur permet à une application de demander un verrou opportuniste de filtre (oplock) pour empêcher d’autres applications d’obtenir des violations de partage. S’il existe déjà des handles ouverts, la demande de création échoue avec STATUS_OPLOCK_NOT_GRANTED. Pour plus d'informations, consultez la section Notes qui suit.
FILE_OPEN_REPARSE_POINT (0x00200000)	Ouvrez un fichier avec un point d’analyse et ignorez le traitement normal du point d’analyse pour le fichier. Pour plus d'informations, consultez la section Notes qui suit.
FILE_OPEN_NO_RECALL (0x00400000)	Indique à tous les filtres qui effectuent un stockage ou une virtualisation hors connexion de ne pas rappeler le contenu du fichier à la suite de cette ouverture.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000)	Cet indicateur indique au système de fichiers de capturer l’utilisateur associé au thread appelant. Tous les appels ultérieurs à FltQueryVolumeInformation ou ZwQueryVolumeInformationFile à l’aide du handle retourné supposent que l’utilisateur capturé, plutôt que l’utilisateur appelant à l’époque, afin de calculer l’espace libre disponible pour l’appelant. Cela s’applique aux valeurs FsInformationClass suivantes : FileFsSizeInformation, FileFsFullSizeInformation et FileFsFullSizeInformationEx.

[in, optional] EaBuffer

Pointeur vers une variable fournie par l’appelant de type FILE_FULL_EA_INFORMATION qui contient des informations d’attribut étendu (EA) à appliquer au fichier. Pour les pilotes d’appareil et intermédiaires, ce paramètre doit avoir la valeur NULL.

[in] EaLength

Longueur, en octets, d’EaBuffer. Pour les pilotes de périphérique et les pilotes intermédiaires, ce paramètre doit être égal à zéro.

[in] CreateFileType

Les pilotes doivent définir ce paramètre sur CreateFileTypeNone.

[in, optional] InternalParameters

Les pilotes doivent définir ce paramètre sur NULL.

[in] Options

Spécifie les options à utiliser pendant la génération de la demande de création. Zéro ou plusieurs des valeurs d’indicateur de bits suivantes peuvent être utilisées.

Indicateur Options	Signification
IO_FORCE_ACCESS_CHECK	Le gestionnaire d’E/S doit case activée la demande de création sur le descripteur de sécurité du fichier. Pour plus d'informations, consultez la section Notes.
IO_IGNORE_SHARE_ACCESS_CHECK	Le gestionnaire d’E/S ne doit pas effectuer de vérifications d’accès au partage sur l’objet de fichier après sa création. Toutefois, le système de fichiers peut toujours effectuer ces vérifications.
IO_STOP_ON_SYMLINK	Si une jonction, un lien symbolique ou un point d’analyse global est rencontré lors de l’ouverture ou de la création du fichier, le gestionnaire d’E/S retourne STATUS_STOPPED_ON_SYMLINK. En outre, une structure REPARSE_DATA_BUFFER sera retournée dans IoStatusBlock-Information>. L’appelant est chargé de libérer la structure REPARSE_DATA_BUFFER .
IO_OPEN_TARGET_DIRECTORY	Ouvrez le répertoire parent du fichier.

[in, optional] DriverContext

Pointeur facultatif vers une structure IO_DRIVER_CREATE_CONTEXT précédemment initialisée par la routine IoInitializeDriverCreateContext . La structure IO_DRIVER_CREATE_CONTEXT peut être utilisée pour passer des paramètres supplémentaires aux routines IoCreateFileEx et FltCreateFileEx2 . Pour plus d’informations, consultez la section Remarques suivante.

Valeur retournée

IoCreateFileEx retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, comme l’une des valeurs suivantes.

Code de retour	Description
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	IoCreateFileEx retourne cette valeur status si le paramètre DriverContext n’a pas la valeur NULL et si l’objet d’appareil spécifié n’est pas attaché à la pile de pilotes du système de fichiers pour le volume spécifié dans le nom du fichier ou du répertoire. Cet objet d’appareil est spécifié par le membre DeviceObjectHint de la structure IO_DRIVER_CREATE_CONTEXT. Pour plus d’informations, consultez IO_DRIVER_CREATE_CONTEXT.
STATUS_MOUNT_POINT_NOT_RESOLVED	IoCreateFileEx retourne cette valeur status si le paramètre DriverContext n’a pas la valeur NULL et si le nom du fichier ou du répertoire contient un point de montage qui se résout en un volume autre que celui auquel l’objet d’appareil spécifié est attaché. Cet objet d’appareil est spécifié par le membre DeviceObjectHint de la structure IO_DRIVER_CREATE_CONTEXT. Pour plus d’informations, consultez IO_DRIVER_CREATE_CONTEXT.
STATUS_OBJECT_PATH_SYNTAX_BAD	IoCreateFileEx retourne cette valeur status si le paramètre ObjectAttributes ne contenait pas de membre RootDirectory, mais que le membre ObjectName de la structure OBJECT_ATTRIBUTES était une chaîne vide ou ne contenait pas de caractère OBJECT_NAME_PATH_SEPARATOR. Cela indique une syntaxe incorrecte pour le chemin d’accès de l’objet.
STATUS_STOPPED_ON_SYMLINK	IoCreateFileEx retourne cette valeur status si l’indicateur de paramètre OptionsIO_STOP_ON_SYMLINK est défini et qu’un lien symbolique est rencontré lors de l’ouverture ou de la création du fichier.

Si la routine IoCreateFileEx retourne une erreur status, l’appelant peut trouver des informations supplémentaires sur la cause de l’échec en vérifiant le paramètre IoStatusBlock.

IoCreateFileEx peut retourner STATUS_FILE_LOCK_CONFLICT comme valeur de retour ou dans le membre Status de la structure IO_STATUS_BLOCK vers laquelle pointe le paramètre IoStatusBlock . Cela se produit uniquement si le fichier journal NTFS est plein et qu’une erreur se produit alors qu’IoCreateFileEx tente de gérer cette situation.

Remarques

La routine IoCreateFileEx est similaire à la routine IoCreateFile et à la routine IoCreateFileSpecifyDeviceObjectHint, mais offre des fonctionnalités supplémentaires, notamment l’accès à des paramètres de création supplémentaires (ECPs), des indicateurs d’objets d’appareil et des informations de transaction via le paramètre DriverContext de la routine IoCreateFileEx. Pour plus d’informations sur ces paramètres basés sur la structure, consultez IO_DRIVER_CREATE_CONTEXT.

Les pilotes de filtre de système de fichiers appellent IoCreateFileEx pour envoyer une demande de création uniquement à un objet d’appareil spécifié, aux filtres attachés en dessous de celui-ci et au système de fichiers. Les filtres attachés au-dessus de l’objet d’appareil spécifié dans la pile des pilotes ne reçoivent pas la demande de création. Toutefois, si le membre DeviceObjectHint de la structure IO_DRIVER_CREATE_CONTEXT (transmis via le paramètre DriverContext ) a la valeur NULL, la demande va en haut de la pile et est reçue par tous les filtres et le système de fichiers.

Si la demande d’E/S n’est pas en haut de la pile de pilotes, c’est-à-dire si le paramètre DriverContext n’est pas NULL et qu’un objet d’appareil valide est spécifié par le membre DeviceObjectHint de la structure IO_DRIVER_CREATE_CONTEXT, la restriction suivante s’applique :

Si le chemin d’accès du nom de fichier passé à la routine IoCreateFileEx contient un point de montage, le point de montage doit être résolu au même volume que celui où réside le fichier ou le répertoire.

Le handle obtenu par IoCreateFileEx peut être utilisé par les appels suivants pour manipuler des données dans le fichier ou l’état ou les attributs de l’objet fichier. Tout handle obtenu à partir d’IoCreateFileEx doit finalement être libéré en appelant ZwClose.

Il existe deux autres façons de spécifier le nom du fichier à créer ou à ouvrir avec IoCreateFileEx :

En tant que chemin d’accès complet, fourni dans le membre ObjectName du paramètre d’entrée ObjectAttributes .
En tant que chemin d’accès relatif au handle dans le membre RootDirectory du paramètre ObjectAttributes d’entrée . (Ce handle peut représenter un fichier de répertoire.)

Les routines de pilotes qui s’exécutent dans un contexte de processus autre que celui du processus système doivent définir l’attribut OBJ_KERNEL_HANDLE pour le paramètre ObjectAttributesd’IoCreateFileEx. Cela limite l’utilisation du handle retourné par IoCreateFileEx aux processus s’exécutant en mode noyau. Sinon, le handle est accessible par le processus dans lequel le pilote est en cours d’exécution. Les pilotes peuvent appeler InitializeObjectAttributes pour définir l’attribut OBJ_KERNEL_HANDLE.

Certains indicateurs DesiredAccess et combinaisons d’indicateurs ont les effets suivants :

Pour qu’un appelant synchronise une fin d’E/S en attendant que le FileHandle retourné soit défini sur l’état Signaled, l’indicateur SYNCHRONIZE doit être défini. Sinon, un appelant qui est un périphérique ou un pilote intermédiaire doit synchroniser une fin d’E/S à l’aide d’un objet d’événement.
Si seuls les indicateurs FILE_APPEND_DATA et SYNCHRONIZE sont définis, l’appelant peut écrire uniquement à la fin du fichier, et toutes les informations de décalage sur les écritures dans le fichier sont ignorées. Toutefois, le fichier est automatiquement étendu si nécessaire pour ce type d’opération d’écriture.
La définition de l’indicateur FILE_WRITE_DATA pour un fichier permet également aux écritures au-delà de la fin du fichier de se produire. Le fichier est également étendu automatiquement pour ce type d’écriture.
Si seuls les indicateurs FILE_EXECUTE et SYNCHRONIZE sont définis, l’appelant ne peut pas lire ou écrire directement des données dans le fichier à l’aide du FileHandle retourné : autrement dit, toutes les opérations sur le fichier se produisent via le pagineur système en réponse aux instructions et aux accès aux données. Les pilotes d’appareil et intermédiaires ne doivent pas définir l’indicateur FILE_EXECUTE dans DesiredAccess.

Le paramètre ShareAccess détermine si des threads distincts peuvent accéder au même fichier, éventuellement simultanément. À condition que les deux ouvreurs de fichiers aient le privilège d’accéder à un fichier de la manière spécifiée, le fichier peut être ouvert et partagé avec succès. Si l’appelant d’origine d’IoCreateFileEx ne spécifie pas FILE_SHARE_READ, FILE_SHARE_WRITE ou FILE_SHARE_DELETE, aucune autre opération ouverte ne peut être effectuée sur le fichier : autrement dit, l’appelant d’origine reçoit un accès exclusif au fichier.

Pour qu’un fichier partagé soit correctement ouvert, la valeur DesiredAccess demandée pour le fichier doit être compatible avec les spécifications DesiredAccess et ShareAccess de toutes les demandes ouvertes précédentes qui n’ont pas encore été publiées avec ZwClose. Autrement dit, la valeur DesiredAccess spécifiée à IoCreateFileEx pour un fichier donné ne doit pas entrer en conflit avec les accès que d’autres ouvreurs du fichier ont interdits.

Si IO_IGNORE_SHARE_ACCESS_CHECK est spécifié dans le paramètre Options , le gestionnaire d’E/S ignore le paramètre ShareAccess . Toutefois, le système de fichiers peut toujours effectuer des vérifications d’accès. Par conséquent, il est important de spécifier le mode de partage souhaité pour le paramètre ShareAccess , même lors de l’utilisation de l’indicateur IO_IGNORE_SHARE_ACCESS_CHECK.

La valeur Disposition FILE_SUPERSEDE nécessite que l’appelant dispose d’un accès DELETE à un objet de fichier existant. Si c’est le cas, un appel réussi à IoCreateFileEx avec FILE_SUPERSEDE sur un fichier existant supprime ce fichier, puis le recrée. Cela implique que, si le fichier a déjà été ouvert par un autre thread, le thread a ouvert le fichier en spécifiant un paramètre ShareAccess avec l’indicateur FILE_SHARE_DELETE défini. Notez que ce type de disposition est cohérent avec le style POSIX de remplacement des fichiers.

Les valeurs de disposition FILE_OVERWRITE_IF et FILE_SUPERSEDE sont similaires. Si IoCreateFileEx est appelé avec un fichier existant et l’une de ces valeurs de disposition , le fichier est remplacé.

Le remplacement d’un fichier équivaut sémantiquement à une opération de remplacement, à l’exception des éléments suivants :

L’appelant doit avoir un accès en écriture au fichier, au lieu de supprimer l’accès. Cela implique que, si le fichier a déjà été ouvert par un autre thread, il a ouvert le fichier avec l’indicateur FILE_SHARE_WRITE défini dans l’entrée ShareAccess.
Les attributs de fichier spécifiés sont logiquement ORed avec ceux déjà présents dans le fichier. Cela implique que si le fichier a déjà été ouvert par un autre thread, un appelant suivant d’IoCreateFileEx ne peut pas désactiver les indicateurs FileAttributes existants, mais peut activer des indicateurs supplémentaires pour le même fichier. Notez que ce style de remplacement des fichiers est cohérent avec MS-DOS, Windows 3.1 et OS/2.

La valeur de FILE_DIRECTORY_FILE CreateOptions spécifie que le fichier à créer ou ouvrir est un fichier de répertoire. Lorsqu’un fichier de répertoire est créé, le système de fichiers crée une structure appropriée sur le disque pour représenter un répertoire vide pour la structure sur disque de ce système de fichiers particulier. Si cette option a été spécifiée et que le fichier donné à ouvrir n’est pas un fichier de répertoire, ou si l’appelant a spécifié une valeur CreateOptions ou Disposition incohérente, l’appel à IoCreateFileEx échoue.

L’indicateur de FILE_NO_INTERMEDIATE_BUFFERING CreateOptions empêche le système de fichiers d’effectuer une mise en mémoire tampon intermédiaire pour le compte de l’appelant. La spécification de cette valeur place certaines restrictions sur les paramètres de l’appelant sur le Zw.. Routines de fichiers, notamment les suivantes :

Tout ByteOffset facultatif passé à ZwReadFile ou ZwWriteFile doit être un entier (multiple entier) de la taille de secteur.
La longueur passée à ZwReadFile ou ZwWriteFile doit être une partie intégrante de la taille du secteur. Notez que la spécification d’une opération de lecture dans une mémoire tampon dont la longueur correspond exactement à la taille du secteur peut entraîner le transfert d’un nombre inférieur d’octets significatifs vers cette mémoire tampon si la fin du fichier a été atteinte pendant le transfert.
Les mémoires tampons doivent être alignées conformément à l’exigence d’alignement de l’appareil sous-jacent. Ces informations peuvent être obtenues en appelant IoCreateFileEx pour obtenir un handle pour l’objet file qui représente l’appareil physique, puis en appelant ZwQueryInformationFile avec ce handle. Pour obtenir la liste des valeurs système FILE_XXX_ALIGNMENT, consultez DEVICE_OBJECT.
Les appels à ZwSetInformationFile avec le paramètre FileInformationClass défini sur FilePositionInformation doivent spécifier un décalage qui fait partie intégrante de la taille du secteur.

Les indicateurs CreateOptions mutuellement exclusifs, FILE_SYNCHRONOUS_IO_ALERT et FILE_SYNCHRONOUS_IO_NONALERT, spécifient que toutes les opérations d’E/S sur le fichier doivent être synchrones tant qu’elles se produisent via l’objet file référencé par le FileHandle retourné. Toutes les E/S d’un tel fichier sont sérialisées sur tous les threads à l’aide du handle retourné. Avec l’une de ces valeurs CreateOptions , l’indicateur DesiredAccess SYNCHRONIZE doit être défini afin que le Gestionnaire d’E/S utilise l’objet file comme objet de synchronisation. Avec l’une ou l’autre de ces valeurs CreateOptions définies, le Gestionnaire d’E/S conserve le « contexte de position de fichier » pour l’objet fichier, un décalage interne de la position actuelle du fichier. Ce décalage peut être utilisé dans les appels à ZwReadFile et ZwWriteFile. Sa position peut également être interrogée en appelant ZwQueryInformationFile, ou définie en appelant ZwSetInformationFile.

Si l’indicateur de FILE_OPEN_REPARSE_POINT CreateOptionsn’est pas spécifié et qu’IoCreateFileEx tente d’ouvrir un fichier avec un point d’analyse, le traitement normal du point d’analyse se produit pour le fichier. Si, en revanche, l’indicateur FILE_OPEN_REPARSE_POINT est spécifié, le traitement normal de l’analyse n’a pas lieu et IoCreateFileEx tente d’ouvrir directement le fichier de point d’analyse. Dans les deux cas, si l’opération d’ouverture a réussi, IoCreateFileEx retourne STATUS_SUCCESS ; sinon, la routine retourne un code d’erreur NTSTATUS. IoCreateFileEx ne retourne jamais STATUS_REPARSE.

L’indicateur de FILE_OPEN_REQUIRING_OPLOCK CreateOptions élimine le délai entre l’ouverture du fichier et la demande d’un oplock qui pourrait potentiellement permettre à un tiers d’ouvrir le fichier et d’obtenir une violation de partage. Une application peut utiliser l’indicateur FILE_OPEN_REQUIRING_OPLOCK sur IoCreateFileEx , puis demander un oplock. Cela garantit qu’un propriétaire d’oplock sera averti de toute demande ouverte ultérieure qui provoque une violation de partage.

Dans Windows 7, si d’autres handles existent sur le fichier lorsqu’une application utilise l’indicateur FILE_OPEN_REQUIRING_OPLOCK, l’opération de création échoue avec STATUS_OPLOCK_NOT_GRANTED. Cette restriction n’existe plus à partir de Windows 8.

Si cette opération de création permet d’arrêter un oplock qui existe déjà dans le fichier, la définition de l’indicateur FILE_OPEN_REQUIRING_OPLOCK entraîne l’échec de l’opération de création avec STATUS_CANNOT_BREAK_OPLOCK. L’oplock existant ne sera pas rompu par cette opération de création.

Une application qui utilise cet indicateur doit demander un oplock une fois cet appel réussi, sinon toutes les tentatives ultérieures d’ouverture du fichier seront bloquées sans l’avantage d’un traitement oplock classique. De même, si cet appel réussit mais que la demande oplock ultérieure échoue, une application qui utilise cet indicateur doit fermer son handle après avoir détecté que la demande oplock a échoué.

L’indicateur FILE_OPEN_REQUIRING_OPLOCK est disponible dans les systèmes d’exploitation Windows 7, Windows Server 2008 R2 et ultérieurs. Les systèmes de fichiers Microsoft qui implémentent cet indicateur sont NTFS, FAT et exFAT.

L’indicateur CreateOptions , FILE_RESERVE_OPFILTER, permet à une application de demander un oplock de niveau 1, par lot ou de filtre pour empêcher d’autres applications d’obtenir des violations de partage. Toutefois, FILE_RESERVE_OPFILTER n’est pratiquement utile que pour les verrous de filtrage. Pour l’utiliser, vous devez suivre les étapes suivantes :

Émettre une demande de création avec CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess exactement FILE_READ_ATTRIBUTES et ShareAccess d’exactement FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- S’il existe déjà des handles ouverts, la demande de création échoue avec STATUS_OPLOCK_NOT_GRANTED et le verrouillage d’opération suivant échoue également.
- Si vous ouvrez avec plus d’accès ou moins de partage, cela entraîne également un échec de STATUS_OPLOCK_NOT_GRANTED.
Si la demande de création réussit, demandez un oplock.
Ouvrez un autre handle dans le fichier pour effectuer des E/S.

La troisième étape rend cette opération pratique uniquement pour les verrous de filtre. Le handle ouvert à l’étape 3 peut avoir un DesiredAccess qui contient un maximum de FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL et n’interrompez toujours pas un blocage de filtre. Toutefois, tout DesiredAccess supérieur à FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE interrompt un oplock de niveau 1 ou par lot et rend l’indicateur de FILE_RESERVE_OPFILTER inutile pour ces types d’oplock.

Pour les demandes de création provenant du mode utilisateur, si le pilote définit IO_FORCE_ACCESS_CHECK dans le paramètre Options de IoCreateFileEx , il doit également définir OBJ_FORCE_ACCESS_CHECK dans le paramètre ObjectAttributes . Pour plus d’informations sur cet indicateur, consultez le membre Attributs de OBJECT_ATTRIBUTES.

NTFS est le seul système de fichiers Microsoft qui implémente FILE_RESERVE_OPFILTER.

IoCreateFileEx peut être utilisé pour obtenir un handle pour un volume.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	ntddk.h (inclure Ntddk.h, Ntifs.h, FltKernel.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL