Fonction NtCreateFile (ntifs.h)

Article
05/24/2024

La routine NtCreateFile crée un fichier ou ouvre un fichier existant.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateFile(
  [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              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

Paramètres

[out] FileHandle

Pointeur vers une variable HANDLE qui reçoit un handle pour le fichier.

[in] DesiredAccess

Spécifie une valeur ACCESS_MASK qui détermine l’accès demandé à l’objet .

En plus des droits d’accès standard définis pour tous les types d’objets, l’appelant peut spécifier l’un des droits d’accès spécifiques suivants : c’est-à-dire des droits spécifiques aux fichiers.

indicateur ACCESS_MASK	Permet à l’appelant d’effectuer cette opération
FILE_READ_DATA	Lit les données du fichier.
FILE_READ_ATTRIBUTES	Lisez les attributs du fichier. Pour plus d’informations, consultez la description du paramètre FileAttributes .
FILE_READ_EA	Lisez les attributs étendus (EA) du fichier. Cet indicateur n’est pas pertinent pour l’appareil et les pilotes intermédiaires.
FILE_WRITE_DATA	Écrire des données dans le fichier.
FILE_WRITE_ATTRIBUTES	Écrivez les attributs du fichier. Pour plus d’informations, consultez la description du paramètre FileAttributes .
FILE_WRITE_EA	Modifiez les attributs étendus (EA) du fichier. Cet indicateur n’est pas pertinent pour l’appareil et les pilotes intermédiaires.
FILE_APPEND_DATA	Ajoutez des données au fichier.
FILE_EXECUTE	Utilisez les E/S de pagination système pour lire les données du fichier en mémoire. Cet indicateur n’est pas pertinent pour l’appareil et les pilotes intermédiaires.

Notes

Ne spécifiez pas FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA ou FILE_EXECUTE lorsque vous créez ou ouvrez un répertoire.

L’appelant peut également spécifier les droits d’accès génériques suivants (droits qui s’appliquent à tous les types d’objets, où la signification de chaque droit d’accès générique est spécifique au type d’objet). Les droits d’accès génériques pour les objets fichier correspondent à des droits d’accès spécifiques, comme indiqué dans le tableau suivant. (Notez que « correspond » signifie « mappe à » et ne signifie pas que la valeur du droit générique est « égale » à la valeur du ou au niveau du bit de son mappage de droits spécifiques). Le gestionnaire d’E/S définit le mappage réel.

Droit d’accès générique	Mappe à ces droits d’accès spécifiques
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA et SYNCHRONIZE
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA et SYNCHRONIZE
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, FILE_EXECUTE, FILE_READ_ATTRIBUTES et SYNCHRONIZE. Cette valeur n’est pas pertinente pour l’appareil et les pilotes intermédiaires.
GENERIC_ALL	FILE_ALL_ACCESS

Notes

Les droits d’accès génériques ne peuvent être spécifiés que pour un fichier ; ils ne peuvent pas être spécifiés pour un répertoire.

Certains indicateurs CreateOptions nécessitent que certains indicateurs d’accès soient définis dans DesiredAccess lorsque NtCreateFile est appelé. Pour plus d’informations, consultez le paramètre CreateOptions .

Par exemple, si vous spécifiez GENERIC_READ pour un objet fichier, la routine mappe cette valeur au masque de bits FILE_GENERIC_READ des droits d’accès spécifiques. Dans le tableau précédent, les droits d’accès spécifiques répertoriés pour GENERIC_READ correspondent (mais ne sont pas égaux à) aux indicateurs d’accès contenus dans le masque de bits FILE_GENERIC_READ.

Si le fichier est en fait un répertoire, l’appelant peut également spécifier les droits d’accès génériques suivants.

Indicateur DesiredAccess	Permet à l’appelant d’effectuer cette opération
FILE_LIST_DIRECTORY	Répertoriez les fichiers dans le répertoire.
FILE_TRAVERSE	Parcourez le répertoire, en d’autres termes, incluez le répertoire dans le chemin d’accès d’un fichier.

Pour plus d’informations sur les droits d’accès, consultez ACCESS_MASK et Droits d’accès.

[in] ObjectAttributes

Pointeur vers une structure OBJECT_ATTRIBUTES qui spécifie le nom de l’objet et d’autres attributs. Utilisez InitializeObjectAttributes pour initialiser cette structure. Si l’appelant n’est pas en cours d’exécution dans un contexte de thread système, il doit définir l’attribut OBJ_KERNEL_HANDLE lorsqu’il appelle InitializeObjectAttributes.

[out] IoStatusBlock

Pointeur vers une structure de IO_STATUS_BLOCK qui reçoit la status d’achèvement finale et d’autres informations sur l’opération demandée. En particulier, le membre Information reçoit l’une des valeurs suivantes :

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Pointeur vers un LARGE_INTEGER qui contient la taille d’allocation initiale, en octets, pour un fichier créé ou remplacé. Si AllocationSize a la valeur NULL, aucune taille d’allocation n’est spécifiée. Si aucun fichier n’est créé ou remplacé, AllocationSize est ignoré.

[in] FileAttributes

Spécifie un ou plusieurs indicateurs FILE_ATTRIBUTE_XXX , qui représentent les attributs de fichier à définir si vous créez ou remplacez un fichier. L’appelant spécifie généralement FILE_ATTRIBUTE_NORMAL, ce qui définit les attributs par défaut. Pour obtenir la liste des indicateurs FILE_ATTRIBUTE_XXX valides, consultez la routine CreateFile dans la documentation Microsoft Windows SDK. Si aucun fichier n’est créé ou remplacé, FileAttributes est ignoré.

[in] ShareAccess

Type d’accès au partage, qui est spécifié comme zéro ou toute combinaison des indicateurs suivants.

Indicateur ShareAccess	Autorise d’autres threads à effectuer cette opération
FILE_SHARE_READ	Lire le fichier
FILE_SHARE_WRITE	Écrire le fichier
FILE_SHARE_DELETE	Supprimer le fichier

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

[in] CreateDisposition

Spécifie l’action à effectuer si le fichier existe ou n’existe pas. CreateDisposition peut être l’une des valeurs du tableau suivant.

Valeur CreateDisposition	Action si le fichier existe	Action si le fichier n’existe pas
FILE_SUPERSEDE	Remplacez le fichier.	Créez le fichier.
FILE_CREATE	Retourne une erreur.	Créez le fichier.
FILE_OPEN	Ouvrez le fichier.	Retourne une erreur.
FILE_OPEN_IF	Ouvrez le fichier.	Créez le fichier.
FILE_OVERWRITE	Ouvrez le fichier et remplacez-le.	Retourne une erreur.
FILE_OVERWRITE_IF	Ouvrez le fichier et remplacez-le.	Créez le fichier.

[in] CreateOptions

Spécifie les options à appliquer lorsque le pilote crée ou ouvre le fichier. Utilisez un ou plusieurs des indicateurs dans le tableau suivant.

Indicateur CreateOptions	Signification
FILE_DIRECTORY_FILE (0x00000001)	Le fichier est un répertoire. Les indicateurs CreateOptions compatibles sont FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT et FILE_OPEN_BY_FILE_ID. Le paramètre CreateDisposition doit être défini sur FILE_CREATE, FILE_OPEN ou FILE_OPEN_IF.
FILE_WRITE_THROUGH (0x00000002)	Les services système, les pilotes de système de fichiers et les pilotes qui écrivent des données dans le fichier doivent effectivement transférer les données vers 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 FILE_APPEND_DATA du paramètre DesiredAccess .
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 pointeur de position de fichier. Si cet indicateur est défini, l’indicateur SYNCHRONIZE doit être défini dans le paramètre DesiredAccess .
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 qui synchronisent la file d’attente d’E/S et l’achèvement ne font pas l’objet d’alertes. Cet indicateur permet également au système d’E/S de conserver le contexte de position de fichier. Si cet indicateur est défini, l’indicateur SYNCHRONIZE doit être défini dans le paramètre DesiredAccess .
FILE_NON_DIRECTORY_FILE (0x00000040)	Le fichier n’est pas un répertoire. L’objet file à ouvrir peut représenter un fichier de données ; un appareil logique, virtuel ou physique ; ou un volume. À compter de Windows 11, version 24H2, NTFS respecte désormais cet indicateur lors de l’ouverture d’un attribut $INDEX_ALLOCATION.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Create une connexion d’arborescence pour ce fichier afin de l’ouvrir sur le réseau. Cet indicateur n’est pas utilisé par les pilotes d’appareil et intermédiaires.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Effectuez immédiatement cette opération avec un autre code de réussite de STATUS_OPLOCK_BREAK_IN_PROGRESS si le fichier cible est verrouillé, plutôt que de bloquer le thread de l’appelant. Si le fichier est bloqué, un autre appelant a déjà accès au fichier. Cet indicateur n’est pas utilisé par les pilotes d’appareil et intermédiaires.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Si les attributs étendus (EAs) d’un fichier existant en cours d’ouverture indiquent que l’appelant doit comprendre les EAs pour interpréter correctement le fichier, NtCreateFile doit retourner une erreur. Cet indicateur n’est pas pertinent pour les pilotes d’appareil et intermédiaires.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Réservé à l’utilisation du système ; n’utilisez pas.
FILE_RANDOM_ACCESS (0x00000800)	L’accès au fichier étant aléatoire, aucune opération de lecture séquentielle ne doit être effectuée par les pilotes de système de fichiers ou par le système.
FILE_DELETE_ON_CLOSE (0x00001000)	Le système supprime le fichier lorsque le dernier handle du fichier est passé à NtClose. Si cet indicateur est défini, l’indicateur DELETE doit être défini dans le paramètre DesiredAccess .
FILE_OPEN_BY_FILE_ID (0x00002000)	Le nom de fichier spécifié par le paramètre ObjectAttributes inclut un numéro de référence de fichier binaire de 8 ou 16 octets ou un ID d’objet pour le fichier, en fonction du système de fichiers. Si vous le souhaitez, un nom d’appareil suivi d’un caractère de barre oblique inverse peut procéder à ces valeurs binaires. Pour plus d’informations et un exemple, consultez Remarques.
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000)	Le fichier est en cours d’ouverture pour une intention de sauvegarde. Par conséquent, le système doit case activée pour certains droits d’accès et accorder à l’appelant l’accès approprié au fichier avant de vérifier le paramètre DesiredAccess par rapport au descripteur de sécurité du fichier. Cet indicateur n’est pas utilisé par les pilotes d’appareil et intermédiaires.
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é comme 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 échouera la création avec un code de retour de STATUS_CANNOT_BREAK_OPLOCK si le résultat est d’interrompre un oplock existant. Cet indicateur est disponible à partir de Windows 7 et Windows Server 2008 R2.
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. Cet indicateur est disponible à partir de Windows 7 et Windows Server 2008 R2.
FILE_SESSION_AWARE (0x00040000)	Le client qui ouvre le fichier ou l’appareil prend en charge la session et l’accès par session est validé si nécessaire. Cet indicateur est disponible à partir de Windows 8.
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.
FILE_CONTAINS_EXTENDED_CREATE_INFORMATION (0x10000000)	Interpréter le paramètre EaBuffer comme un instance de EXTENDED_CREATE_INFORMATION. Cet indicateur est disponible à partir de Windows 11, version 22H2.

[in, optional] EaBuffer

Pour les pilotes de périphérique et intermédiaires, ce paramètre doit être un pointeur NULL .

[in] EaLength

Pour les pilotes de périphérique et intermédiaires, ce paramètre doit être égal à zéro.

Valeur retournée

NtCreateFile retourne STATUS_SUCCESS en cas de réussite ou un code d’erreur NTSTATUS approprié en cas d’échec. Dans ce dernier cas, l’appelant peut déterminer la cause de l’échec en vérifiant le paramètre IoStatusBlock .

Notes

NtCreateFile peut retourner STATUS_FILE_LOCK_CONFLICT en tant que valeur de retour ou dans le membre Status de la structure IO_STATUS_BLOCK pointée par le paramètre IoStatusBlock . Cela se produit uniquement si le fichier journal NTFS est plein et qu’une erreur se produit pendant que NtCreateFile tente de gérer cette situation.

Remarques

NtCreateFile fournit un handle que l’appelant peut utiliser pour manipuler les données d’un fichier, ou l’état et les attributs de l’objet fichier. Pour plus d’informations, consultez Utilisation de fichiers dans un pilote.

Une fois que le handle pointé par FileHandle n’est plus utilisé, le pilote doit appeler NtClose pour le fermer.

Si l’appelant n’est pas en cours d’exécution dans un contexte de thread système, il doit s’assurer que tous les handles qu’il crée sont des handles privés. Sinon, le handle est accessible par le processus dans le contexte dans lequel le pilote est en cours d’exécution. Pour plus d’informations, consultez Handles d’objet.

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

En tant que chemin d’accès complet, fourni dans le membre ObjectName de l’entrée ObjectAttributes.
En tant que chemin d’accès relatif au fichier de répertoire représenté par le handle dans le membre RootDirectory de l’entrée ObjectAttributes.

La définition de certains indicateurs dans le paramètre DesiredAccess entraîne les effets suivants :

Pour qu’un appelant synchronise une fin d’E/S en attendant le FileHandle retourné, l’indicateur SYNCHRONIZE doit être défini. Sinon, un appelant qui est un périphérique ou un pilote intermédiaire doit synchroniser une complétion d’E/S à l’aide d’un objet d’événement.
Si l’appelant définit uniquement les indicateurs FILE_APPEND_DATA et SYNCHRONIZE, il peut écrire uniquement à la fin du fichier, et toutes les informations de décalage sur les opérations d’écriture dans le fichier sont ignorées. Le fichier est automatiquement étendu si nécessaire pour ce type d’opération.
La définition de l’indicateur FILE_WRITE_DATA pour un fichier permet également à l’appelant d’écrire au-delà de la fin du fichier. Là encore, le fichier est automatiquement étendu si nécessaire.
Si l’appelant définit uniquement les indicateurs FILE_EXECUTE et SYNCHRONIZE, il 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 opérations d’instruction et d’accès aux données. Les pilotes de périphérique et intermédiaire ne doivent pas définir l’indicateur FILE_EXECUTE.

Le paramètre ShareAccess détermine si des threads distincts peuvent accéder au même fichier, éventuellement simultanément. À condition que les deux appelants disposent des privilèges d’accès appropriés, le fichier peut être correctement ouvert et partagé. Si l’appelant d’origine de NtCreateFile ne spécifie pas FILE_SHARE_READ, FILE_SHARE_WRITE ou FILE_SHARE_DELETE, aucun autre appelant ne peut ouvrir le fichier, c’est-à-dire qu’un accès exclusif est accordé à l’appelant d’origine.

Pour ouvrir un fichier partagé, les indicateurs DesiredAccess doivent être compatibles avec les indicateurs DesiredAccess et ShareAccess de toutes les opérations d’ouverture précédentes qui n’ont pas encore été publiées via . Autrement dit, le DesiredAccess spécifié à NtCreateFile pour un fichier donné ne doit pas entrer en conflit avec les accès que d’autres ouvreurs du fichier ont refusés.

La valeur CreateDisposition 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 à NtCreateFile 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, il 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 CreateDisposition FILE_OVERWRITE_IF et FILE_SUPERSEDE sont similaires. Si NtCreateFile est appelé avec un fichier existant et l’une de ces valeurs CreateDisposition , 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 de NtCreateFile 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, Microsoft Windows 3.1 et OS/2.

La valeur FILE_DIRECTORY_FILE CreateOptions spécifie que le fichier à créer ou ouvrir est un 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 CreateDisposition incohérente, l’appel à NtCreateFile échoue.

L’indicateur 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 cet indicateur place les restrictions suivantes sur les paramètres de l’appelant pour d’autres routines ZwXxxFile .

Tout ByteOffset facultatif passé à NtReadFile ou NtWriteFile doit être un multiple de la taille de secteur.
La longueur passée à NtReadFile ou NtWriteFile 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. Pour obtenir ces informations, appelez NtCreateFile pour obtenir un handle pour l’objet file qui représente l’appareil physique, puis transmettez ce handle à NtQueryInformationFile. Pour obtenir la liste des valeurs FILE_XXX_ALIGNMENT du système, consultez DEVICE_OBJECT.
Les appels à NtSetInformationFile avec le paramètre FileInformationClass défini sur FilePositionInformation doivent spécifier un décalage qui est un multiple de la taille de secteur.

Les indicateurs CreateOptions FILE_SYNCHRONOUS_IO_ALERT et FILE_SYNCHRONOUS_IO_NONALERT (qui s’excluent mutuellement) spécifient que toutes les opérations d’E/S sur le fichier seront synchrones, tant que les opérations 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é. Si l’un de ces indicateurs CreateOptions est défini, l’indicateur SYNCHRONIZE DesiredAccess doit également être défini pour obliger le gestionnaire d’E/S à utiliser l’objet file comme objet de synchronisation. Dans ce cas, le gestionnaire d’E/S effectue le suivi du décalage actuel de la position du fichier, que vous pouvez passer à NtReadFile et NtWriteFile. Appelez NtQueryInformationFile ou NtSetInformationFile pour obtenir ou définir cette position.

Si l’indicateur de FILE_OPEN_REPARSE_POINT CreateOptionsn’est pas spécifié et que NtCreateFile 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 ne se produit pas et NtCreateFile tente d’ouvrir directement le fichier de point d’analyse. Dans les deux cas, si l’opération d’ouverture a réussi, NtCreateFile retourne STATUS_SUCCESS ; sinon, la routine retourne un code d’erreur NTSTATUS. NtCreateFile 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 NtCreateFile , 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 l’indicateur FILE_OPEN_REQUIRING_OPLOCK doit demander un oplock une fois cet appel réussi, sinon toutes les tentatives suivantes d’ouverture du fichier seront bloquées sans l’avantage d’un traitement oplock normal. De même, si cet appel réussit mais que la demande oplock suivante échoue, une application qui utilise cet indicateur doit fermer son handle après avoir détecté que la demande d’oplock a échoué.

Notes

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

L’indicateur CreateOptions FILE_RESERVE_OPFILTER permet à une application de demander un oplock de niveau 1, Batch ou Filter 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 effectuer les étapes suivantes :

Émettre une demande de création avec CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess de FILE_READ_ATTRIBUTES exactement 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.

L’étape 3 rend cela 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 Batch et rend l’indicateur FILE_RESERVE_OPFILTER inutile pour ces types de verrous d’opération.

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

Pour l’indicateur de FILE_OPEN_BY_FILE_ID CreateOptions , un exemple de nom d’appareil aura le format suivant :

\??\C:\<FileID>
\device\HardDiskVolume1\<ObjectID>

où FileID est de 8 octets et ObjectID de 16 octets :

Sur NTFS, il peut s’agir d’un numéro de référence ou d’un ID d’objet de 8 octets ou de 16 octets. Un numéro de référence de 16 octets est identique à un nombre de 8 octets rempli de zéros.
Sur ReFS, il peut s’agir d’un numéro de référence de 8 octets ou de 16 octets. Un nombre de 16 octets n’est pas lié à un nombre de 8 octets. Les ID d’objet ne sont pas pris en charge.
Les systèmes de fichiers FAT, ExFAT, UDFS et CDFS ne prennent pas en charge l’indicateur FILE_OPEN_BY_FILE_ID.

Ce numéro est attribué par et spécifique au système de fichiers particulier. Étant donné que le champ nom de fichier contient en partie un objet blob binaire, il est incorrect de supposer qu’il s’agit d’une chaîne Unicode valide et, plus important encore, peut ne pas être une chaîne terminée par null.

Les appelants de NtCreateFile doivent être en cours d’exécution à IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.

Notes

Si l’appel à cette fonction se produit en mode utilisateur, vous devez utiliser le nom « NtCreateFile » au lieu de « ZwCreateFile ».

Pour les appels à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000
Plateforme cible	Universal
En-tête	ntifs.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (voir la section Remarques)
Règles de conformité DDI	HwStorPortProhibitedDDIs, PowerIrpDDis