ZwCreateFile, fonction (wdm.h)
La routine ZwCreateFile crée un fichier ou ouvre un fichier existant.
Syntaxe
NTSYSAPI NTSTATUS ZwCreateFile(
[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 définis pour tous les types d’objets, l’appelant peut spécifier l’un des droits d’accès suivants, qui sont 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. |
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 uniquement spécifier un droit d’accès générique, GENERIC_XXX, pour un fichier, et non un répertoire. Les droits d’accès génériques correspondent à des droits d’accès spécifiques, comme indiqué dans le tableau suivant.
| Droit d’accès générique | Ensemble de 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. |
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 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.
[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 . 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 | 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_NON_DIRECTORY_FILE | 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. |
| FILE_WRITE_THROUGH | 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 | Tous les accès au fichier seront séquentiels. |
| FILE_RANDOM_ACCESS | 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_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’indicateur FILE_APPEND_DATA du paramètre DesiredAccess . |
| FILE_SYNCHRONOUS_IO_ALERT | 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 | 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_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 d’appareil et intermédiaires. |
| FILE_COMPLETE_IF_OPLOCKED | 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é opportuniste (oplock), 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. Pour plus d’informations sur oplock, consultez Verrous opportunistes. |
| FILE_NO_EA_KNOWLEDGE | Si les attributs étendus (EA) d’un fichier existant en cours d’ouverture indiquent que l’appelant doit comprendre les EA pour interpréter correctement le fichier, ZwCreateFile doit retourner une erreur. Cet indicateur n’est pas pertinent pour les pilotes d’appareil et intermédiaires. |
| FILE_OPEN_REPARSE_POINT | 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. Pour plus d’informations sur le point d’analyse, consultez Points d’analyse. |
| FILE_DELETE_ON_CLOSE | Le système supprime le fichier lorsque le dernier handle du fichier est passé à ZwClose. 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 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, comme indiqué ci-dessous. Si vous le souhaitez, un nom d’appareil suivi d’un caractère de barre oblique inverse peut procéder à ces valeurs binaires. Par exemple, un 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 ou 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 ou 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 cet indicateur. 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 null terminée. |
| FILE_OPEN_FOR_BACKUP_INTENT | 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_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 Notes qui suit. Pour plus d’informations sur oplock, consultez Verrous opportunistes. |
| FILE_OPEN_REQUIRING_OPLOCK | 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. L’indicateur FILE_OPEN_REQUIRING_OPLOCK est disponible dans les systèmes d’exploitation Windows 7, Windows Server 2008 R2 et versions ultérieures. |
| FILE_SESSION_AWARE | 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. L’indicateur FILE_SESSION_AWARE est disponible à partir deWindows 8. |
[in, optional] EaBuffer
Pour les pilotes d’appareil et intermédiaires, ce paramètre doit être un pointeur NULL .
[in] EaLength
Pour les pilotes d’appareil et intermédiaires, ce paramètre doit être égal à zéro.
Valeur retournée
ZwCreateFile retourne STATUS_SUCCESS sur la 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 la défaillance en vérifiant le paramètre IoStatusBlock .
ZwCreateFile peut renvoyer 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 que ZwCreateFile tente de gérer cette situation.
Remarques
ZwCreateFile 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 ZwClose 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 ZwCreateFile :
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 ZwCreateFile 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é à ZwCreateFile 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 à ZwCreateFile 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 ZwCreateFile 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 ZwCreateFile ne peut pas désactiver les indicateurs FileAttributes existants, mais peut activer des indicateurs supplémentaires pour le même fichier.
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 à ZwCreateFile é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é à ZwReadFile ou ZwWriteFile doit être un multiple de la taille du secteur.
La longueur transmise à 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. Pour obtenir ces informations, appelez ZwCreateFile pour obtenir un handle pour l’objet file qui représente l’appareil physique, puis transmettez ce handle à ZwQueryInformationFile. Pour obtenir la liste des valeurs FILE_XXX_ALIGNMENT du système, consultez DEVICE_OBJECT.
Les appels à ZwSetInformationFile 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 comme leur nom le suggère, spécifient que toutes les opérations d’E/S sur le fichier seront 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é. 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 fichier 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 à ZwReadFile et ZwWriteFile. Appelez ZwQueryInformationFile ou ZwSetInformationFile pour obtenir ou définir cette position.
Si l’indicateur de FILE_OPEN_REPARSE_POINT CreateOptions n’est pas spécifié et que ZwCreateFile 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 ZwCreateFile tente d’ouvrir directement le fichier de point d’analyse. Dans les deux cas, si l’opération d’ouverture a réussi, ZwCreateFile retourne STATUS_SUCCESS ; sinon, la routine retourne un code d’erreur NTSTATUS. ZwCreateFile 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 ZwCreateFile , 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é.
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 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 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.
Les appelants de ZwCreateFile doivent s’exécuter sur IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.
Si l’appel à cette fonction se produit en mode utilisateur, vous devez utiliser le nom « NtCreateFile » au lieu de « ZwCreateFile ».
Pour les appels provenant 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 Using Nt and Zw Versions of the Native System Services Routines.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| En-tête | wdm.h (include 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(storport), PowerIrpDDis(wdm) |
Voir aussi
Utilisation des versions Nt et Zw des routines des services système natifs
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour