Fonction IoCreateFileSpecifyDeviceObjectHint (ntddk.h)

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.

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 :

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 .

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.

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

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

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

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

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

[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 :

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 :

1. En tant que chemin d’accès complet, fourni dans le membre ObjectName de l’entrée ObjectAttributes

2. 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 :

1. É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.

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.

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

Voir aussi

ACCESS_MASK

ACL

FILE_FULL_EA_INFORMATION

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoCheckEaBufferValidity

IoCreateFile

IoCreateFileEx

UNICODE_STRING

ZwClose

ZwCreateFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile