Partager via

Fonction NtCreateFile (winternl.h)

  • Article

Crée un fichier ou un répertoire, ou ouvre un fichier, un appareil, un répertoire ou un volume existant.

 

Cette fonction est l’équivalent en mode utilisateur de la fonction ZwCreateFile documentée dans le Kit de pilotes Windows (WDK).

Syntaxe

__kernel_entry 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]           PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

Paramètres

[out] FileHandle

Pointeur vers une variable qui reçoit le handle de fichier si l’appel réussit.

[in] DesiredAccess

Valeur ACCESS_MASK qui exprime le type d’accès requis par l’appelant au fichier ou au répertoire. L’ensemble d’indicateurs de DesiredAccess définis par le système détermine les droits d’accès spécifiques suivants pour les objets de fichier.

Valeur Signification
DELETE
 Le fichier peut être supprimé.
FILE_READ_DATA
 Les données peuvent être lues à partir du fichier.
FILE_READ_ATTRIBUTES
 Des indicateurs de FileAttributes, décrits plus tard, peuvent être lus.
FILE_READ_EA
 Les attributs étendus associés au fichier peuvent être lus. Cet indicateur n’est pas pertinent pour les pilotes de périphérique et intermédiaire.
READ_CONTROL
 Les informations de propriété et de liste de contrôle d’accès (ACL) associées au fichier peuvent être lues.
FILE_WRITE_DATA
 Les données peuvent être écrites dans le fichier.
FILE_WRITE_ATTRIBUTES
 indicateurs de FileAttributes peuvent être écrits.
FILE_WRITE_EA
 Les attributs étendus associés au fichier peuvent être écrits. Cet indicateur n’est pas pertinent pour les pilotes de périphérique et intermédiaire.
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
 Le FileHandle retourné peut être attendu pour se synchroniser avec l’achèvement d’une opération d’E/S. Si FileHandle n’a pas été ouvert pour les E/S synchrones, cette valeur est ignorée.
FILE_EXECUTE
 Les données peuvent être lues en mémoire à partir du fichier à l’aide des E/S de pagination système. Cet indicateur n’est pas pertinent pour les pilotes de périphérique et intermédiaire.
 

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

Les appelants de NtCreateFile peuvent spécifier une ou une combinaison des éléments suivants, éventuellement à l’aide d’un bit-OR avec des indicateurs compatibles supplémentaires provenant de la liste des indicateurs DesiredAccess, pour tout objet de fichier qui ne représente pas un fichier de répertoire.

Valeur Signification
FILE_GENERIC_READ
 STANDARD_RIGHTS_READ | FILE_READ_DATA | FILE_READ_ATTRIBUTES | FILE_READ_EA | SYNCHRONIZE
FILE_GENERIC_WRITE
 STANDARD_RIGHTS_WRITE | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES | FILE_WRITE_EA | FILE_APPEND_DATA | SYNCHRONIZE
FILE_GENERIC_EXECUTE
 STANDARD_RIGHTS_EXECUTE | FILE_READ_ATTRIBUTES | FILE_EXECUTE | SYNCHRONIZE
 

La valeur FILE_GENERIC_EXECUTE n’est pas pertinente pour les pilotes de périphérique et intermédiaire.

Les STANDARD_RIGHTS_XXX sont des valeurs système prédéfinies utilisées pour appliquer la sécurité sur les objets système.

Pour ouvrir ou créer un fichier de répertoire, comme indiqué avec le paramètre CreateOptions, les appelants d'NtCreateFile peuvent spécifier une ou une combinaison des éléments suivants, éventuellement à l’aide d’un ou plusieurs indicateurs compatibles à partir de la liste des indicateurs DesiredAccess.

Valeur 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.

[in] ObjectAttributes

Pointeur vers une structure déjà initialisée avec InitializeObjectAttributes. Les membres de cette structure pour un objet de fichier incluent les éléments suivants.

Valeur Signification
de longueur ULONG
 Spécifie le nombre d’octets de ObjectAttributes données fournies. Cette valeur doit être au moins sizeof(OBJECT_ATTRIBUTES).
HANDLE RootDirectory
 Spécifie éventuellement un handle dans un répertoire obtenu par un appel précédent à NtCreateFile. Si cette valeur est null, le membre ObjectName doit être une spécification de fichier complète qui inclut le chemin complet du fichier cible. Si cette valeur n’est pasNULL, le membre ObjectName spécifie un nom de fichier par rapport à ce répertoire.
PUNICODE_STRING ObjectName
 Pointe vers une chaîne Unicode mise en mémoire tampon qui nomme le fichier à créer ou ouvrir. Cette valeur doit être une spécification de fichier complète ou le nom d’un objet d’appareil, sauf s’il s’agit du nom d’un fichier par rapport au répertoire spécifié par RootDirectory. Par exemple, \Device\Floppy1\myfile.dat ou \ ?? \B :\myfile.dat peut être la spécification complète du fichier, à condition que le pilote de floppy et le système de fichiers surchargé soient déjà chargés. Pour plus d’informations, consultez noms de fichiers, chemins d’accès et espaces de noms.
attributs ULONG
 Ensemble d’indicateurs qui contrôlent les attributs de l’objet de fichier. Cette valeur peut être égale à zéro ou OBJ_CASE_INSENSITIVE, ce qui indique que le code de recherche de noms doit ignorer le cas du membre ObjectName plutôt que d’effectuer une recherche exacte-correspondance. La valeur OBJ_INHERIT n’est pas pertinente pour les pilotes de périphérique et intermédiaire.
PSECURITY_DESCRIPTOR SecurityDescriptor
 Spécifie éventuellement un descripteur de sécurité à appliquer à un fichier. Les listes de contrôle d’accès spécifiées par un descripteur de sécurité de ce type sont appliquées au fichier uniquement lors de sa création. Si la valeur est null lorsqu’un fichier est créé, 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é à la liste de contrôle d’accès par défaut de l’appelant. Les pilotes de périphérique et intermédiaire peuvent définir ce membre sur NULL.
PSECURITY_QUALITY_OF_SERVICE SecurityQualityOfService
 Spécifie les droits d’accès qu’un serveur doit être donné au contexte de sécurité du client. Cette valeur n’est pasNULL uniquement lorsqu’une connexion à un serveur protégé est établie, ce qui permet à l’appelant de contrôler quelles parties du contexte de sécurité de l’appelant sont mises à la disposition du serveur et si le serveur est autorisé à emprunter l’identité de l’appelant.

[out] IoStatusBlock

Pointeur vers une variable qui reçoit l’état d’achèvement final et les informations relatives à l’opération demandée. Lors du retour de NtCreateFile, le membre Information contient l’une des valeurs suivantes :

  • FILE_CREATED
  • FILE_OPENED
  • FILE_OVERWRITTEN
  • FILE_SUPERSEDED
  • FILE_EXISTS
  • FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

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 créé, remplacé ou remplacé.

[in] FileAttributes

Attributs de fichier. Les attributs spécifiés explicitement sont appliqués uniquement lorsque le fichier est créé, remplacé ou, dans certains cas, remplacé. Par défaut, cette valeur est un FILE_ATTRIBUTE_NORMAL, qui peut être substitué par une combinaison ORed d’un ou plusieurs indicateurs FILE_ATTRIBUTE_xxxx, qui sont définis dans Wdm.h et NtDdk.h. Pour obtenir la liste des indicateurs qui peuvent être utilisés avec NtCreateFile, consultez CreateFile.

[in] ShareAccess

Type d’accès de partage que l’appelant souhaite utiliser dans le fichier, comme zéro, ou comme une ou une combinaison des valeurs suivantes.

Valeur Signification
FILE_SHARE_READ
 Le fichier peut être ouvert pour l’accès en lecture par les appels d’autres threads à NtCreateFile.
FILE_SHARE_WRITE
 Le fichier peut être ouvert pour l’accès en écriture par les appels d’autres threads à NtCreateFile.
FILE_SHARE_DELETE
 Le fichier peut être ouvert pour supprimer l’accès par les appels d’autres threads à NtCreateFile.
 

Pour plus d’informations, consultez le Kit de développement logiciel (SDK) Windows.

[in] CreateDisposition

Spécifie ce qu’il faut faire, selon que le fichier existe déjà, comme l’une des valeurs suivantes.

Valeur Signification
FILE_SUPERSEDE
 Si le fichier existe déjà, remplacez-le par le fichier donné. Si ce n’est pas le cas, 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é. Si ce n’est pas le cas, créez le fichier donné.
FILE_OPEN
 Si le fichier existe déjà, ouvrez-le au lieu de créer un fichier. Si ce n’est pas le cas, échouez la requête et ne créez pas de fichier.
FILE_OPEN_IF
 Si le fichier existe déjà, ouvrez-le. Si ce n’est pas le cas, créez le fichier donné.
FILE_OVERWRITE
 Si le fichier existe déjà, ouvrez-le et remplacez-le. Si ce n’est pas le cas, échouez la requête.
FILE_OVERWRITE_IF
 Si le fichier existe déjà, ouvrez-le et remplacez-le. Si ce n’est pas le cas, créez le fichier donné.

[in] CreateOptions

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

Valeur Signification
FILE_DIRECTORY_FILE
 Le fichier en cours de création ou ouvert est un fichier de répertoire. Avec cet indicateur, le paramètre CreateDisposition doit être défini sur FILE_CREATE, FILE_OPENou FILE_OPEN_IF. Avec cet indicateur, d’autres indicateurs de CreateOptions compatibles incluent uniquement les indicateurs suivants : FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO _NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENTet FILE_OPEN_BY_FILE_ID.
FILE_NON_DIRECTORY_FILE
 Le fichier ouvert ne doit pas être un fichier de répertoire ou cet appel échoue. L’objet de fichier ouvert peut représenter un fichier de données, un appareil logique, virtuel ou physique, ou un volume.
FILE_WRITE_THROUGH
 Les applications qui écrivent des données dans le fichier doivent réellement transférer les données dans le fichier avant toute opération d’écriture demandée est considérée comme terminée. Cet indicateur est automatiquement défini si l’indicateur CreateOptionsFILE_NO_INTERMEDIATE _BUFFERING est défini.
FILE_SEQUENTIAL_ONLY
 Tous les accès au fichier sont séquentiels.
FILE_RANDOM_ACCESS
 Les accès au fichier peuvent être aléatoires. Par conséquent, aucune opération séquentielle en lecture anticipée ne doit être effectuée sur le fichier par des disques FSD ou le système.
FILE_NO_INTERMEDIATE_BUFFERING
 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’indicateurFILE_APPEND_DATA DesiredAccess .
FILE_SYNCHRONOUS_IO_ALERT
 Toutes les opérations sur le fichier sont effectuées de manière synchrone. Toute attente au nom de l’appelant est soumise à un arrêt prématuré des alertes. Cet indicateur entraîne également le maintien du contexte de position du fichier par le système d’E/S. Si cet indicateur est défini, l’indicateur DesiredAccessSYNCHRONIZE doit également être défini.
FILE_SYNCHRONOUS_IO_NONALERT
 Toutes les opérations sur le fichier sont effectuées de manière synchrone. Les attentes dans le système pour synchroniser la mise en file d’attente d’E/S et la saisie semi-automatique ne sont pas soumises à des alertes. Cet indicateur entraîne également le maintien du contexte de position du fichier par le système d’E/S. Si cet indicateur est défini, l’indicateur DesiredAccessSYNCHRONIZE doit également être défini.
FILE_CREATE_TREE_CONNECTION
 Créez une connexion d’arborescence pour ce fichier afin de l’ouvrir sur le réseau. Cet indicateur n’est pas utilisé par les pilotes de périphérique et intermédiaire.
FILE_NO_EA_KNOWLEDGE
 Si les attributs étendus d’un fichier existant en cours d’ouverture indiquent que l’appelant doit comprendre les EA pour interpréter correctement le fichier, échouez cette demande, car l’appelant ne comprend pas comment traiter les EA. Cet indicateur n’est pas pertinent pour les pilotes de périphérique et intermédiaire.
FILE_OPEN_REPARSE_POINT
 Ouvrez un fichier avec un point d’analyse et contournez le traitement normal du point d’analyse pour le fichier. Pour plus d’informations, consultez la section Remarques.
FILE_DELETE_ON_CLOSE
 Supprimez le fichier lorsque le dernier handle à celui-ci 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
 Le nom de fichier spécifié par le paramètre ObjectAttributes inclut le numéro de référence de fichier de 8 octets pour le fichier. Ce nombre est attribué et spécifique au système de fichiers particulier. Si le fichier est un point d’analyse, le nom du fichier inclut également le nom d’un appareil. Notez que le système de fichiers FAT ne prend pas en charge cet indicateur. Cet indicateur n’est pas utilisé par les pilotes de périphérique et intermédiaire.
FILE_OPEN_FOR_BACKUP_INTENT
 Le fichier est ouvert pour l’intention de sauvegarde. Par conséquent, le système doit vérifier 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 de périphérique et intermédiaire.
FILE_RESERVE_OPFILTER
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 Remarques.
FILE_OPEN_REQUIRING_OPLOCK
 Le fichier est ouvert et un verrou opportuniste (oplock) sur le fichier est demandé en tant qu’opération atomique unique. Le système de fichiers vérifie 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 serait de briser un oplock existant. Pour plus d’informations, consultez la section Remarques.Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : cet indicateur n’est pas pris en charge.

Cet indicateur est pris en charge sur les systèmes de fichiers suivants : NTFS, FAT et exFAT.
FILE_COMPLETE_IF_OPLOCKED
 Effectuez cette opération immédiatement 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 oplocked, un autre appelant a déjà accès au fichier. Cet indicateur n’est pas utilisé par les pilotes de périphérique et intermédiaire.

[in] EaBuffer

Pointeur vers une mémoire tampon EA utilisée pour passer des attributs étendus.

Remarque Certains systèmes de fichiers peuvent ne pas prendre en charge les mémoires tampons EA.
 

[in] EaLength

Longueur de la mémoire tampon EA.

Valeur de retour

NtCreateFile retourne STATUS_SUCCESS ou un état d’erreur approprié. S’il retourne un état d’erreur, l’appelant peut trouver plus d’informations sur la cause de l’échec en vérifiant le IoStatusBlock. Pour simplifier cette vérification, une application peut utiliser les macros NT_SUCCESS, NT_ERRORet NT_WARNING.

Remarques

Le handle, donné par NtCreateFile, peut être utilisé par des appels suivants pour manipuler des données dans le fichier ou l’état ou les attributs de l’objet fichier.

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

  • En tant que nom de chemin complet, fourni dans le ObjectName membre 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 RootDirectory membre de l’entrée ObjectAttributes
Certains indicateurs DesiredAccess et les combinaisons d’indicateurs ont les effets suivants :
  • Pour qu’un appelant synchronise une saisie semi-automatique en attendant laFileHandle retournée, l’indicateur SYNCHRONIZE doit être défini.
  • Le passage d’un zéro à DesiredFlags n’est pas valide.
  • Si seuls les indicateurs FILE_APPEND_DATA et SYNCHRONIZE sont définis, l’appelant ne peut écrire qu’à 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 de 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 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 FileHandleretourné, 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.
Le paramètre ShareAccess détermine si des threads distincts peuvent accéder au même fichier, éventuellement simultanément. À condition que les deux openeurs de fichiers aient le privilège d’accéder à un fichier de la manière spécifiée, le fichier peut être correctement ouvert et partagé. Si l’appelant d’origine de NtCreateFile ne spécifie pas FILE_SHARE_READ, FILE_SHARE_WRITEou 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, le paramètre DesiredAccess demandé au fichier doit être compatible avec les spécifications DesiredAccess et ShareAccess de toutes les ouvertures précédentes qui n’ont pas encore été publiées avec NtClose . Autrement dit, le paramètre DesiredAccess spécifié pour NtCreateFile pour un fichier donné ne doit pas entrer en conflit avec les accès que d’autres openers du fichier n’ont pas autorisés.

La valeur CreateDispositionFILE_SUPERSEDE nécessite que l’appelant ait 'accès DELETE à un objet de fichier existant. Dans ce cas, un appel réussi à NtCreateFile avec FILE_SUPERSEDE sur un fichier existant supprime efficacement 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 le jeu d’indicateurs de FILE_SHARE_DELETE. Notez que ce type de disposition est cohérent avec le style POSIX de remplacement des fichiers. Les valeurs CreateDispositionFILE_OVERWRITE_IF et FILE_SUPERSEDE sont similaires. Si ZwCreateFile est appelé avec un fichier existant et que 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 disposer d’un accès en écriture au fichier, plutôt que 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 de FILE_SHARE_WRITE défini dans le paramètre d’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 de FileAttributes existants, mais peut activer des indicateurs supplémentaires pour le même fichier. Notez que ce style de remplacement de fichiers est cohérent avec les systèmes d’exploitation MS-DOS, Windows 3.1 et OS/2.
La valeur CreateOptionsFILE_DIRECTORY_FILE spécifie que le fichier à créer ou ouvert 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 createOptions incohérente ou valeur CreateDisposition, l’appel à NtCreateFile échoue.

L’indicateur CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING 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 à d’autres routines NtXXXFile, notamment les suivantes :

  • Toute ByteOffset facultative transmise à la fonction NtReadFile ou NtWriteFile doit être intégrale de la taille du secteur.
  • La Length passée à NtReadFile ou NtWriteFile, doit être intégrale de la taille du secteur. Notez que la spécification d’une opération de lecture dans une mémoire tampon dont la longueur est exactement la taille du secteur peut entraîner un nombre moindre d’octets significatifs transférés vers cette mémoire tampon si la fin du fichier a été atteinte pendant le transfert.
  • Les mémoires tampons doivent être ajustées conformément aux exigences d’alignement de l’appareil sous-jacent. Ces informations peuvent être obtenues en appelant NtCreateFile pour obtenir un handle pour l’objet de fichier qui représente l’appareil physique, puis en appelant NtQueryInformationFile avec ce handle. Pour obtenir la liste des valeurs du système FILE_XXX_ALIGNMENT, consultez la documentation du Kit de développement logiciel (SDK) Windows.
  • Les appels à NtSetInformationFile avec le paramètre FileInformationClass défini sur FilePositionInformation doivent spécifier un décalage qui est une partie intégrante de la taille du secteur.
Les CreateOptionsFILE_SYNCHRONOUS_IO_ALERT et les indicateurs FILE_SYNCHRONOUS_IO_NONALERT, qui s’excluent mutuellement à mesure que leurs noms le suggèrent, spécifient que toutes les opérations d’E/S sur le fichier doivent être synchrones tant qu’elles se produisent via l’objet de fichier appelé par le FileHandle retourné. Toutes les E/S sur un tel fichier sont sérialisées sur tous les threads à l’aide du handle retourné. Avec l’un de ces CreateOptions, l’indicateur SYNCHRONIZESYNCHRONIZE doit être défini afin que le Gestionnaire d’E/S utilise l’objet de fichier en tant qu’objet de synchronisation. Avec l’un de ces CreateOptions défini, le Gestionnaire d’E/S gère le « contexte de position de fichier » pour l’objet de fichier, un décalage de position de fichier interne et actuel. Ce décalage peut être utilisé dans les appels à NtReadFile et NtWriteFile . Sa position peut également être interrogée ou définie avec NtQueryInformationFile et NtSetInformationFile.

Si le paramètre CreateOptions spécifie l’indicateur FILE_OPEN_REPARSE_POINT et NtCreateFile ouvre un fichier avec un point d’analyse, le traitement d’analyse normal n’a pas lieu et NtCreateFile tente d’ouvrir directement le fichier de point d’analyse. Si l’indicateur FILE_OPEN_REPARSE_POINT n’est pas spécifié, le traitement normal du point d’analyse se produit pour le fichier. Dans les deux cas, si l’opération ouverte a réussi, NtCreateFile retourne STATUS_SUCCESS; sinon, un code d’erreur. La fonction NtCreateFile ne retourne jamais STATUS_REPARSE.

L’indicateur de FILE_OPEN_REQUIRING_OPLOCK du paramètre CreateOptions élimine le temps entre l’ouverture du fichier et la demande d’un oplock qui pourrait permettre à un tiers d’ouvrir le fichier, ce qui entraînerait une violation de partage. Une application peut utiliser l’indicateur FILE_OPEN_REQUIRING_OPLOCK avec NtCreateFile, puis demander n’importe quel oplock. Cela garantit qu’un propriétaire 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 cet indicateur, 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 interrompt un oplock qui existe déjà sur le fichier, la définition de l’indicateur de 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, ou toutes les tentatives suivantes d’ouverture du fichier seront bloquées sans bénéficier du traitement normal d’oplock. De même, si cet appel réussit mais que la requête oplock suivante échoue, une application qui utilise cet indicateur doit fermer son handle après qu’elle détecte que la demande oplock a échoué.

Remarque L’indicateur de FILE_OPEN_REQUIRING_OPLOCK est disponible dans Windows 7, Windows Server 2008 R2 et versions ultérieures pour les systèmes de fichiers suivants : NTFS, FAT et exFAT.
 

L’indicateur de FILE_RESERVE_OPFILTER du paramètre CreateOptions 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, en termes pratiques, le FILE_RESERVE_OPFILTER est utile uniquement pour les verrous de filtre. Pour l’utiliser, vous devez effectuer les étapes suivantes :

  1. Émettez une demande de création avec CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess exactement FILE_READ_ATTRIBUTESet ShareAccess de (FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)exactement. Les échecs possibles sont les suivants :
    • S’il existe déjà des handles ouverts, la demande de création échoue avec STATUS_OPLOCK_NOT_GRANTED, et l’oplock demandé suivant échoue également.
    • Si vous ouvrez avec plus d’accès que FILE_READ_ATTRIBUTES ou moins de partage que (FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE), la requête échoue avec STATUS_OPLOCK_NOT_GRANTED.
  2. Si la demande de création réussit, demandez un oplock.
  3. Ouvrez un autre handle dans le fichier pour effectuer des E/S.
L’étape 3 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 qui n’interrompt toujours pas un oplock de filtre. Toutefois, toute DesiredAccess supérieure à (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 d’oplocks.

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

Pour plus d’informations sur les oplocks, consultez sémantique Oplock.

Notez que le fichier d’en-tête WDK NtDef.h est nécessaire pour de nombreuses définitions constantes ainsi que pour la macro InitializeObjectAttributes. Vous pouvez également utiliser les fonctions LoadLibrary et GetProcAddress pour lier dynamiquement à NtDll.dll.

Exigences

Exigence Valeur
plateforme cible Windows
d’en-tête winternl.h
bibliothèque ntdll.lib
DLL ntdll.dll