FltCreateFileEx2, fonction (fltkernel.h)

Article
02/06/2025

Les pilotes minifilter appellent FltCreateFileEx2 pour créer un fichier ou ouvrir un fichier existant. Cette routine inclut un paramètre de contexte de création facultatif (ECP).

Syntaxe

NTSTATUS FLTAPI FltCreateFileEx2(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [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,
  [in]            ULONG                     Flags,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Paramètres

[in] Filter

Pointeur de filtre opaque pour l’appelant.

[in, optional] Instance

Pointeur d’instance opaque pour l’instance de pilote minifilter à laquelle la demande de création doit être envoyée. L’instance doit être attachée au volume où réside le fichier ou le répertoire. Ce paramètre est facultatif et peut être NULL. Si ce paramètre est NULL, la requête est envoyée à l’objet d’appareil en haut de la pile de pilotes du système de fichiers pour le volume. Si ce paramètre n’est pasnull, la requête est envoyée uniquement aux instances de pilote minifilter attachées sous l’instance spécifiée.

[out] FileHandle

Pointeur vers une variable allouée par l’appelant qui reçoit le handle de fichier si l’appel à FltCreateFileEx2 réussit.

[out, optional] FileObject

Pointeur vers une variable allouée par l’appelant qui reçoit le pointeur d’objet de fichier si l’appel à FltCreateFileEx2 réussit. Ce paramètre est facultatif et peut être NULL.

[in] DesiredAccess

Masque de bits des indicateurs spécifiant le type d’accès au fichier ou au répertoire requis par l’appelant. Consultez le paramètre DesiredAccess de IoCreateFileEx pour plus d’informations sur ce paramètre et pour obtenir la liste des valeurs d’indicateur.

[in] ObjectAttributes

Pointeur vers une structure de OBJECT_ATTRIBUTES opaque déjà initialisée avec InitializeObjectAttributes. Consultez le paramètre ObjectAttributes de IoCreateFileEx pour plus d’informations et pour obtenir une description de chaque membre de structure.

[out] IoStatusBlock

Pointeur vers une structure IO_STATUS_BLOCK qui reçoit l’état d’achèvement final et les informations relatives à l’opération demandée. Consultez le paramètre IoStatusBlock de IoCreateFileEx pour plus d’informations sur ce paramètre.

[in, optional] AllocationSize

Spécifie éventuellement la taille d’allocation initiale, en octets, pour le flux de fichiers. Une valeur différente de zéro n’a aucun effet, sauf si le fichier est créé, remplacé ou remplacé.

[in] FileAttributes

Spécifie un ou plusieurs indicateurs FILE_ATTRIBUTE_XXX, qui représentent les attributs de fichier à définir si vous créez, superseding ou remplacez un fichier. Consultez le paramètre FileAttributes de IoCreateFileEx pour plus d’informations et pour obtenir la liste des indicateurs.

[in] ShareAccess

Spécifie le type d’accès au partage au fichier requis par l’appelant, comme zéro ou un, ou une combinaison des indicateurs. Consultez le paramètre ShareAccess de IoCreateFileEx pour plus d’informations et pour obtenir la liste des indicateurs.

[in] CreateDisposition

Spécifie une valeur qui détermine l’action à entreprendre, selon que le fichier existe déjà. Consultez le paramètre Disposition de IoCreateFileEx pour obtenir la liste des valeurs possibles.

[in] CreateOptions

Spécifie les options à appliquer lors de la création ou de l’ouverture du fichier. Ce paramètre est une combinaison compatible des indicateurs répertoriés et décrit dans le paramètre CreateOptions de IoCreateFileEx.

[in, optional] EaBuffer

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

[in] EaLength

Longueur, en octets, de EaBuffer.

[in] Flags

Spécifie les options à utiliser lors de la création de la demande de création. Consultez le paramètre options de IoCreateFileEx pour obtenir la liste des options possibles.

[in, optional] DriverContext

Pointeur facultatif vers une structure IO_DRIVER_CREATE_CONTEXT déjà initialisée par IoInitializeDriverCreateContext.

Valeur de retour

FltCreateFileEx2 retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée. Consultez la section Valeur de retour de IoCreateFileEx pour obtenir la liste des codes de retour possibles.

Note

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

Remarques

FltCreateFileEx2 est similaire à FltCreateFile et FltCreateFileEx, sauf qu’il prend en charge le paramètre d’entrée DriverContext.

Pour spécifier un ecP dans le cadre d’une opération de création, initialisez le membre ExtraCreateParameter de la structure IO_DRIVER_CREATE_CONTEXT avec la routine FltAllocateExtraCreateParameterList. Si les PPE sont utilisées, elles doivent être créées, manipulées et libérées à l’aide des routines appropriées.

Les pilotes de filtre en dessous de l’appelant de FltCreateFileEx2 ne doivent pas ajouter ou supprimer d’ecPs sur l’appelant. Par conséquent, lors du retour de l’appel à FltCreateFileEx2, la liste ECP doit être inchangée et peut être passée à des appels supplémentaires de FltCreateFileEx2 pour d’autres opérations de création. Notez que le système d’exploitation ne désalloue pas automatiquement la structure de liste ECP : l’appelant de FltCreateFileEx2 doit libérer cette structure en appelant la routine FltFreeExtraCreateParameterList.

Pour créer/ouvrir un fichier dans le contexte d’une transaction, définissez le TxnParameters membre de la structure IO_DRIVER_CREATE_CONTEXT sur la valeur retournée par la routine IoGetTransactionParameterBlock.

FltCreateFileEx2 envoie la demande de création uniquement aux instances jointes sous l’instance de pilote minifilter spécifiée et au système de fichiers. L’instance spécifiée et les instances jointes ci-dessus ne reçoivent pas la demande de création. Si aucune instance n’est spécifiée, la requête passe en haut de la pile et est reçue par toutes les instances et le système de fichiers.

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

En tant que chemin d’accès 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 du RootDirectory membre de l’entrée ObjectAttributes.

Tout FileHandle obtenu à partir de FltCreateFileEx2 doit finalement être libéré en appelant FltClose. En outre, tout pointeur FileObject retourné doit être déréférencé lorsqu’il n’est plus nécessaire en appelant ObDereferenceObject.

Les routines de pilote qui ne s’exécutent pas dans le contexte du processus système doivent définir l’attribut OBJ_KERNEL_HANDLE pour le paramètre ObjectAttributes de FltCreateFileEx2. La définition de cet attribut limite l’utilisation du handle retourné par FltCreateFileEx2 aux processus en mode noyau. Sinon, le handle est accessible par le processus dans lequel le pilote est en cours d’exécution.

Note

N’appelez pas cette routine avec une valeur IRP de niveau supérieur non NULL, car cela peut entraîner un interblocage système.

Certains indicateurs DesiredAccess et les 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 demandes d’écriture 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 d’écrire des requêtes au-delà de la fin du fichier. Le fichier est également étendu pour ce type de demande d’écriture.
Si seuls les indicateurs FILE_EXECUTE et SYNCHRONIZE sont définis, l’appelant ne peut pas utiliser le handle retourné dans le paramètre FileHandle pour lire ou écrire directement des données dans ou à partir du fichier. Autrement dit, toutes les opérations sur le fichier doivent utiliser les E/S de pagination système pour lire ou écrire des données de fichier.

Le paramètre ShareAccess détermine si des threads distincts peuvent accéder au même fichier, éventuellement simultanément. Si les deux openeurs de fichiers ont 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 FltCreateFileEx2 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, car l’appelant d’origine a un accès exclusif au fichier.

Pour qu’un fichier partagé soit correctement ouvert, le DesiredAccess demandé au fichier doit être compatible avec les DesiredAccess et les spécifications ShareAccess de toutes les demandes ouvertes précédentes qui n’ont pas encore été publiées avec FltClose. Autrement dit, le paramètre DesiredAccess spécifié pour FltCreateFileEx2 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.

Note

Si IO_IGNORE_SHARE_ACCESS_CHECK est spécifié dans le paramètre indicateurs de, 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 de IO_IGNORE_SHARE_ACCESS_CHECK. Notez également que lorsque IO_IGNORE_SHARE_ACCESS_CHECK est spécifié, le système de fichiers ne suit pas l’accès souhaité ou l’accès partagé de l’ouverture actuelle. En raison de cela, les appels ouverts suivants sur le même fichier peuvent réussir.

La valeur CreateDisposition FILE_SUPERSEDE nécessite que l’appelant dispose d’un accès DELETE à un objet de fichier existant. Dans ce cas, un appel réussi à FltCreateFileEx2 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 ShareAccessavec 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 CreateDisposition FILE_OVERWRITE_IF et FILE_SUPERSEDE sont similaires. Si FltCreateFileEx2 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 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 combinés à ceux qui sont déjà appliqués au fichier à l’aide d’une opération OR au niveau du bit. Cela implique que si le fichier a déjà été ouvert par un autre thread, un appelant suivant de FltCreateFileEx2 ne peut pas désactiver les indicateurs FileAttributes existants, mais peut activer des indicateurs supplémentaires pour le même fichier. Notez que ce style de remplacement de fichiers est cohérent avec MS-DOS, Windows 3.1 et OS/2.

La valeur CreateOptions FILE_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é un createOptions ou valeur CreateDisposition, l’appel à FltCreateFileEx2 é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 cette valeur place certaines restrictions sur les paramètres de l’appelant à d’autres Flt.. Fichier routines ou Zw.. Fichiers routines, notamment les suivantes :

Toute valeur de décalage d’octet passée au paramètre ByteOffset de FltReadFile, ZwReadFile, FltWriteFileou ZwWriteFile doit être un multiple de la taille du secteur.
Le paramètre Length passé à FltReadFile, ZwReadFile, FltWriteFileou 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 est exactement la taille du secteur peut entraîner un transfert 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 aux exigences d’alignement de l’appareil de stockage sous-jacent. Ces informations peuvent être obtenues en appelant FltCreateFileEx2 pour obtenir un handle pour l’objet de fichier qui représente l’appareil physique, puis en appelant ZwQueryInformationFile avec ce handle, en spécifiant FileAlignmentInformation comme valeur pour paramètre FileInformationClass. Pour plus d’informations sur les valeurs de_ALIGNMENT XXX FILE_système, définies dans Ntifs.h, consultez DEVICE_OBJECT et Initialisation d’un objet device.
Les appels à FltSetInformationFile ou 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 indicateurs CreateOptions FILE_SYNCHRONOUS_IO_ALERT et FILE_SYNCHRONOUS_IO_NONALERT, qui s’excluent mutuellement à mesure que leurs noms le suggèrent, spécifient que le fichier est ouvert pour les E/S synchrones. Cela signifie que toutes les opérations d’E/S sur le fichier doivent être synchrones tant qu’elles se produisent via l’objet de fichier auquel le FileHandle retourné fait référence. 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 indicateurs CreateOptions définis, le Gestionnaire d’E/S conserve le décalage de position de fichier actuel dans le champ CurrentByteOffset de l’objet fichier. Ce décalage peut être utilisé dans les appels à ZwReadFile et ZwWriteFile. Il peut également être interrogé ou défini en appelant ZwQueryInformationFile ou ZwSetInformationFile.

Si l’indicateur createOptions FILE_OPEN_REPARSE_POINT n’est pas spécifié et FltCreateFileEx2 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 de FILE_OPEN_REPARSE_POINT est spécifié, le traitement d’analyse normal n'pas se produit et FltCreateFileEx2 tente d’ouvrir directement le fichier de point d’analyse. Dans les deux cas, si l’opération ouverte a réussi, FltCreateFileEx2 retourne STATUS_SUCCESS ; sinon, la routine retourne un code d’erreur NTSTATUS. FltCreateFileEx2 ne retourne jamais STATUS_REPARSE.

L’indicateur FILE_OPEN_REQUIRING_OPLOCK CreateOptions élimine le temps entre l’ouverture du fichier et la demande d’un oplock qui pourrait 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 FltCreateFileEx2, 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 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 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 ultérieures d’ouverture du fichier seront bloquées sans bénéficier d’un traitement oplock classique. De même, si cet appel réussit mais que la demande d’oplock ultérieure échoue, une application qui utilise cet indicateur doit fermer son handle après qu’elle détecte que la demande oplock a échoué.

Note

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

Le CreateOptions indicateur FILE_RESERVE_OPFILTER permet à une application de demander un oplock de niveau 1, de traitement 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 oplocks de filtre. Pour l’utiliser, vous devez effectuer les étapes suivantes :

Émettre une demande de création avec CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess exactement FILE_READ_ATTRIBUTES et ShareAccess 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 verrou d’opération demandé 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 | SYNCHRONISER | READ_CONTROL et n’interrompez toujours pas un oplock 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 d’oplock.

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

Les pilotes Minifilter doivent utiliser FltSetInformationFile, et non ZwSetInformationFile, pour renommer un fichier.

Note

Si vous essayez d’ouvrir un volume, mais spécifiez uniquement une combinaison des indicateurs suivants pour le paramètre DesiredAccess, FltCreateFileEx2 ouvre un handle, indépendamment du système de fichiers, qui a un accès direct à l’appareil de stockage pour le volume.

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONISER

Vous ne devez pas utiliser FltCreateFileEx2 pour ouvrir un handle avec un accès direct à l’appareil de stockage pour le volume ou vous allez fuiter des ressources système. Si vous souhaitez ouvrir un handle avec un accès direct à un appareil de stockage, appelez laIoCreateFileEx, IoCreateFileSpecifyDeviceObjectHintou zwCreateFile fonction à la place.

Lorsqu’un appelant de FltCreateFileEx2 souhaite activer l’analyse d’une cible de volume, un FLT_CREATEFILE_TARGET_ECP_CONTEXT peut être inclus en tant qu’ECP dans la liste ECP dans le paramètre DriverContext. Si ce programme ECP est présent, FltCreateFileEx2 ajuste l’appareil cible pour l’opération de création et tente de trouver une instance filtrée d’un volume approprié pour les informations de fichier données. L’utilisation de cet ECP est disponible à partir de Windows 8.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible à partir de Windows Vista.
plateforme cible	Universel
d’en-tête	fltkernel.h (include FltKernel.h)
bibliothèque	Fltmgr.lib
IRQL	PASSIVE_LEVEL