Fonction IoCreateFileSpecifyDeviceObjectHint (ntddk.h)

Article
03/08/2023

La routine IoCreateFileSpecifyDeviceObjectHint est utilisée par les pilotes de filtre de système de fichiers pour envoyer une demande de création uniquement aux filtres situés sous un objet d’appareil spécifié et au système de fichiers.

Syntaxe

NTSTATUS IoCreateFileSpecifyDeviceObjectHint(
  [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] PVOID              DeviceObject
);

Paramètres

[out] FileHandle

Pointeur vers une variable qui reçoit un handle pour l’objet fichier si cet appel réussit.

[in] DesiredAccess

Masque de bits d’indicateurs qui spécifient le type d’accès requis par l’appelant au fichier ou au répertoire. L’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.

Indicateurs 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 plus loin, 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 attributs étendus associés au fichier peuvent être écrits.
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.

Les appelants d’IoCreateFileSpecifyDeviceObjectHint peuvent spécifier un ou une combinaison des éléments suivants, éventuellement ORed avec des indicateurs compatibles supplémentaires de la liste précédente d’indicateursDesiredAccess , pour tout objet de fichier qui ne représente pas de fichier de répertoire :

DesiredAccess to file values	Mappe aux indicateurs DesiredAccess
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, SYNCHRONIZE, FILE_READ_ATTRIBUTES et FILE_EXECUTE.

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

Si l’indicateur CreateOptions FILE_DIRECTORY_FILE est défini, les appelants d’IoCreateFileSpecifyDeviceObjectHint peuvent spécifier un ou une combinaison des éléments suivants, éventuellement ORed avec un ou plusieurs indicateurs compatibles de la liste précédente d’indicateursDesiredAccess .

DesiredAccess to directory values	Signification
FILE_LIST_DIRECTORY	Les fichiers du répertoire peuvent être répertoriés.
FILE_TRAVERSE	Le répertoire peut être parcouru : c’est-à-dire qu’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 (ObjectAttributes) peut avoir la valeur NULL. Sinon, l’appelant doit définir l’attribut OBJ_KERNEL_HANDLE dans l’appel sur la routine InitializeObjectAttributes . Les membres de la structure OBJECT_ATTRIBUTES d’un objet de fichier incluent les éléments suivants.

Membre	Valeur
ULONGLength	Spécifie le nombre d’octets de 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 nommant le 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, à condition que le pilote de disquette et le système de fichiers surchargé soient déjà chargés. (Notez que \ ?? remplace \DosDevices comme nom de l’espace de noms de l’objet Win32. \DosDevices fonctionnera toujours, mais \ ?? est traduit plus rapidement par le gestionnaire d’objets.)
HANDLERootDirectory	Spécifie éventuellement un handle dans un répertoire qui a été obtenu par un appel précédent à IoCreateFileSpecifyDeviceObjectHint. 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	Spécifie éventuellement un descripteur de sécurité à appliquer à un fichier. Les listes de contrôle d’accès spécifiées par ce descripteur de sécurité 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 ACL à partir du fichier de répertoire parent associé à la liste de contrôle d’accès par défaut de l’appelant.
ULONGAttributes	Ensemble d’indicateurs qui contrôle les attributs de l’objet de 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 éventuellement définir l’indicateur OBJ_CASE_INSENSITIVE, ce qui indique que le code de recherche de nom doit ignorer la casse de ObjectName plutôt que d’effectuer une recherche de correspondance exacte.

[out] IoStatusBlock

Pointeur vers une structure de IO_STATUS_BLOCK qui reçoit le status d’achèvement final et des informations sur l’opération demandée. Au retour de IoCreateFileSpecifyDeviceObjectHint, 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

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 ORed d’indicateurs compatibles. Les indicateurs FileAttributes possibles incluent les éléments suivants.

Indicateurs FileAttributes	Signification
FILE_ATTRIBUTE_NORMAL	Un fichier avec 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 ce paramètre. 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 lors de l’utilisation de l’indicateur IO_IGNORE_SHARE_ACCESS_CHECK. Pour plus de chances d’é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 un accès en lecture par d’autres threads.
FILE_SHARE_WRITE	Le fichier peut être ouvert pour l’accès en écriture par d’autres threads.
FILE_SHARE_DELETE	Le fichier peut être ouvert pour supprimer l’accès par d’autres threads.

[in] Disposition

Spécifie une valeur qui détermine l’action à entreprendre, selon que le fichier existe déjà. La valeur peut être l’une des valeurs décrites ci-dessous.

Valeurs de disposition	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 demande 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, la demande échoue.
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

Spécifie les options à appliquer lors de la création ou de l’ouverture du fichier. Ces options sont spécifiées sous la forme d’une combinaison compatible des indicateurs suivants.

Indicateurs CreateOptions	Signification
FILE_DIRECTORY_FILE	Le fichier en cours de création ou d’ouverture est un fichier de répertoire. Si cet indicateur est défini, le paramètre Disposition doit être défini sur l’un des FILE_CREATE, FILE_OPEN ou FILE_OPEN_IF. Cet indicateur est compatible avec les indicateurs CreateOptions suivants : FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT et FILE_OPEN_BY_FILE_ID.
FILE_NON_DIRECTORY_FILE	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 doit représenter un fichier de données.
FILE_WRITE_THROUGH	Les services système, les FSD 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	Tous les accès au fichier seront séquentiels.
FILE_RANDOM_ACCESS	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 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’indicateur DesiredAccess FILE_APPEND_DATA.
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 contexte de position du fichier. Si cet indicateur est défini, l’indicateur DesiredAccess SYNCHRONIZE 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 qui existent dans le système pour synchroniser la mise en 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.
FILE_CREATE_TREE_CONNECTION	Créez une connexion d’arborescence pour ce fichier afin de l’ouvrir sur le réseau.
FILE_COMPLETE_IF_OPLOCKED	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	Si les attributs étendus sur 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 EAs.
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 Remarques ci-dessous.
FILE_DELETE_ON_CLOSE	Supprimez le fichier lorsque le dernier handle est passé à ZwClose.
FILE_OPEN_BY_FILE_ID	Le nom de fichier spécifié dans le paramètre ObjectAttributes inclut le numéro de référence de fichier de 8 octets pour le fichier. Ce numéro est attribué par le système de fichiers et est spécifique au système de fichiers. Si le fichier est un point d’analyse, le nom de fichier inclut également le nom d’un appareil. Remarque : le système de fichiers FAT ne prend pas en charge FILE_OPEN_BY_FILE_ID.
FILE_OPEN_FOR_BACKUP_INTENT	Le fichier est ouvert 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 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_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 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 la création interrompt un oplock existant.
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.

[in, optional] EaBuffer

Pointeur vers une mémoire tampon FILE_FULL_EA_INFORMATION structurée fournie par l’appelant contenant des informations d’attribut étendu (EA) à appliquer au fichier.

[in] EaLength

Longueur, en octets, d’EaBuffer.

[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 lors de la création de la demande de création. Le tableau suivant répertorie les options disponibles.

Indicateurs d’options	Signification
IO_FORCE_ACCESS_CHECK	Indique que le gestionnaire d’E/S doit case activée la demande de création sur le descripteur de sécurité du fichier.
IO_IGNORE_SHARE_ACCESS_CHECK	Indique que 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.

[in, optional] DeviceObject

Pointeur vers l’objet d’appareil auquel la demande de création doit être envoyée. L’objet d’appareil doit être un objet de filtre ou de périphérique de système de fichiers dans la pile de pilotes de système de fichiers pour le volume sur lequel réside le fichier ou le répertoire. Ce paramètre est facultatif et peut être NULL. Si ce paramètre a la valeur NULL, la demande est envoyée à l’objet d’appareil situé en haut de la pile de pilotes.

Valeur retournée

IoCreateFileSpecifyDeviceObjectHint retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple :

Code de retour	Description
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	L’objet DeviceObject spécifié n’est pas attaché à la pile de pilotes de système de fichiers pour le volume spécifié dans le nom du fichier ou du répertoire. Cette erreur peut également se produire si le nom contient un point d’analyse autre qu’un point de montage.
STATUS_MOUNT_POINT_NOT_RESOLVED	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 DeviceObject spécifié est attaché.
STATUS_OBJECT_PATH_SYNTAX_BAD

IoCreateFileSpecifyDeviceObjectHint peut retourner STATUS_FILE_LOCK_CONFLICT en tant que 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’IoCreateFileSpecifyDeviceObjectHint tente de gérer cette situation.

Remarques

Cette routine est utilisée par les pilotes de filtre de système de fichiers pour envoyer une demande de création uniquement aux filtres situés sous un objet d’appareil spécifié et au système de fichiers. Les filtres attachés au-dessus de l’objet d’appareil spécifié dans la pile de pilotes ne reçoivent pas la demande de création.

La routine IoCreateFileEx de Windows Vista est similaire à la routine IoCreateFileSpecifyDeviceObjectHint , mais fournit des fonctionnalités supérieures à la routine IoCreateFileSpecifyDeviceObjectHint , y compris l’accès à des paramètres de création supplémentaires (ECPs) et aux informations de transaction.

Si vous utilisez la routine IoCreateFileEx au lieu de la routine IoCreateFileSpecifyDeviceObjectHint , notez que le paramètre DriverContext de la routine IoCreateFileSpecifyDeviceObjectHint a été déplacé vers le membre DeviceObjectHint de la structure IO_DRIVER_CREATE_CONTEXT . La structure IO_DRIVER_CREATE_CONTEXT est transmise à la routine IoCreateFileEx via son paramètre DriverContext .

Les pilotes de filtre de système de fichiers appellent IoCreateFileSpecifyDeviceObjectHint 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. Il en va de même pour toutes les demandes de nettoyage ou de fermeture sur l’objet de fichier créé par IoCreateFileSpecifyDeviceObjectHint.

Il existe deux autres façons de spécifier le nom du fichier à créer ou ouvrir à l’aide de IoCreateFileSpecifyDeviceObjectHint :

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

Tout handle obtenu à partir de IoCreateFileSpecifyDeviceObjectHint doit être libéré en appelant ZwClose.

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’IoCreateFileSpecifyDeviceObjectHint. Cela limite l’utilisation du handle retourné par IoCreateFileSpecifyDeviceObjectHint 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.

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.
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 automatiquement é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 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.

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’IoCreateFileSpecifyDeviceObjectHint 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, l’accès souhaité demandé au fichier doit être compatible avec les spécifications DesiredAccess et ShareAccess de tous les ouvertures précédentes qui n’ont pas encore été publiées avec ZwClose. Autrement dit, le DesiredAccess spécifié à IoCreateFileSpecifyDeviceObjectHint pour un fichier donné ne doit pas entrer en conflit avec les accès interdits par d’autres ouvreurs du fichier.

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 à IoCreateFileSpecifyDeviceObjectHint 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 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 Disposition FILE_OVERWRITE_IF et FILE_SUPERSEDE sont similaires. Si IoCreateFileSpecifyDeviceObjectHint 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 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 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’IoCreateFileSpecifyDeviceObjectHint ne peut pas désactiver les indicateurs FileAttributes existants, mais peut activer des indicateurs supplémentaires pour le même fichier.

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 à IoCreateFileSpecifyDeviceObjectHint échoue.

L’indicateur CreateOptions FILE_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 pour d’autres Zw.. Routines de fichiers, notamment les suivantes :

Toute valeur offset d’octet passée à ZwReadFile ou ZwWriteFile doit être un multiple de la taille de secteur de l’appareil sous-jacent.
La longueur passée à ZwReadFile ou ZwWriteFile doit être un multiple 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 IoCreateFileSpecifyDeviceObjectHint pour obtenir un handle pour l’objet de fichier 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 est un multiple de la taille du secteur.

Les options CreateOptions mutuellement exclusives, 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 auquel fait référence 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’un de ces CreateOptions, l’indicateur DesiredAccess SYNCHRONIZE doit être défini pour que le Gestionnaire d’E/S utilise l’objet file comme objet de synchronisation. Avec l’un de ces createOptions définis, le Gestionnaire d’E/S conserve le « contexte de position de fichier » pour l’objet de fichier, un décalage interne et actuel de position 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 CreateOptions FILE_OPEN_REPARSE_POINT n’est pas spécifié et qu’IoCreateFileSpecifyDeviceObjectHint 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 IoCreateFileSpecifyDeviceObjectHint tente d’ouvrir directement le fichier de point d’analyse. Dans les deux cas, si l’opération d’ouverture a réussi, IoCreateFileSpecifyDeviceObjectHint retourne STATUS_SUCCESS ; sinon, la routine retourne un code d’erreur NTSTATUS. IoCreateFileSpecifyDeviceObjectHint ne retourne jamais STATUS_REPARSE.

L’indicateur CreateOptions FILE_OPEN_REQUIRING_OPLOCK é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 IoCreateFileSpecifyDeviceObjectHint , puis demander un 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 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é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, 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 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.

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.

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

IoCreateFileSpecifyDeviceObjectHint ne peut pas être utilisé pour obtenir un handle pour un volume.

Si le chemin du nom de fichier transmis à IoCreateFileSpecifyDeviceObjectHint contient un point d’analyse, le point d’analyse doit être résolu dans le même volume que celui où réside le fichier ou le répertoire. Si ce n’est pas le cas, l’erreur STATUS_INVALID_DEVICE_OBJECT_PARAMETER ou STATUS_MOUNT_POINT_NOT_RESOLVED est retournée.

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