Fonction FltCreateFileEx2 (fltkernel.h)

Article
03/08/2023

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

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 de instance opaque pour le pilote minifiltre instance à laquelle la demande de création doit être envoyée. Le instance doit être attaché au volume où 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 de système de fichiers pour le volume. Si ce paramètre n’a pas la valeur NULL, la demande est envoyée uniquement aux instances de pilote de minifiltre attachées sous la 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 fichier si l’appel à FltCreateFileEx2 réussit. Ce paramètre est facultatif et peut être NULL.

[in] DesiredAccess

Masque de bits d’indicateurs spécifiant le type d’accès au fichier ou au répertoire requis par l’appelant. Consultez le paramètre DesiredAccessd’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. Pour plus d’informations et pour obtenir une description de chaque membre de structure, consultez le paramètre ObjectAttributesd’IoCreateFileEx .

[out] IoStatusBlock

Pointeur vers une structure IO_STATUS_BLOCK qui reçoit l’achèvement final status et des informations sur l’opération demandée. Pour plus d’informations sur ce paramètre, consultez le paramètre IoStatusBlockd’IoCreateFileEx .

[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 en cours de création, de remplacement ou de remplacement.

[in] FileAttributes

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

[in] ShareAccess

Spécifie le type d’accès de partage au fichier dont l’appelant a besoin, comme zéro ou un, ou une combinaison des indicateurs. Pour plus d’informations et pour obtenir la liste des indicateurs, consultez le paramètre ShareAccessd’IoCreateFileEx .

[in] CreateDisposition

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

[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écrits dans le paramètre CreateOptionsd’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, d’EaBuffer.

[in] Flags

Spécifie les options à utiliser lors de la création de la demande de création. Consultez le paramètre Optionsd’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 retournée

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

Notes

FltCreateFileEx2 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 pendant que 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 des fournisseurs d’environnement d’environnement sont utilisés, ils doivent être créés, manipulés et libérés à l’aide des routines appropriées.

Les pilotes de filtre sous 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 libère 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 membre TxnParameters 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 le pilote minifilter spécifié instance et au système de fichiers. Le instance spécifié et les instances jointes ci-dessus ne reçoivent pas la demande de création. Si aucune instance n’est spécifiée, la demande passe en haut de la pile et est reçue par toutes les instances et le système de fichiers.

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

En tant que chemin 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.

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 pilotes 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 restreint l’utilisation du handle retourné par FltCreateFileEx2 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.

Notes

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

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 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 de FILE_WRITE_DATA pour un fichier permet également aux demandes d’écriture au-delà de la fin du fichier de se produire. Le fichier est également automatiquement é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 ouvreurs de fichiers ont 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 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 reçoit un accès exclusif au fichier.

Pour qu’un fichier partagé soit correctement ouvert, le desiredAccess demandé au fichier doit être compatible avec les spécifications DesiredAccess et 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é sur FltCreateFileEx2 pour un fichier donné ne doit pas entrer en conflit avec les accès interdits par d’autres ouvreurs du fichier.

Notes

Si IO_IGNORE_SHARE_ACCESS_CHECK est spécifié dans le paramètre Flags , 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. En outre, notez 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. Pour cette raison, 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. Si c’est le cas, un appel réussi à FltCreateFileEx2 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 ShareAccessavec 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 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 FILE_SHARE_WRITE défini dans le paramètre ShareAccess d’entrée.
Les attributs de fichier spécifiés sont combinés avec les attributs 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 des fichiers est cohérent avec MS-DOS, Windows 3.1 et OS/2.

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 CreateDisposition incohérente, l’appel à FltCreateFileEx2 échoue.

L’indicateur de 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 impose certaines restrictions sur les paramètres de l’appelant à d’autres flt.. Routines de fichiers ou Zw.. Routines de fichiers, notamment les suivantes :

Toute valeur de décalage d’octet passée au paramètre ByteOffset de FltReadFile, ZwReadFile, FltWriteFile ou ZwWriteFile doit être un multiple de la taille du secteur.
Le paramètre Length passé à FltReadFile, ZwReadFile, FltWriteFile ou ZwWriteFile doit être un multiple de la taille de 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’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 du périphérique de stockage sous-jacent. Ces informations peuvent être obtenues en appelant FltCreateFileEx2 pour obtenir un handle pour l’objet file qui représente l’appareil physique, puis en appelant ZwQueryInformationFile avec ce handle, en spécifiant FileAlignmentInformation comme valeur pour le paramètre FileInformationClass . Pour plus d’informations sur les valeurs système FILE_XXX_ALIGNMENT définies dans Ntifs.h, consultez DEVICE_OBJECT et Initialisation d’un objet d’appareil.
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 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 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 file auquel le FileHandle renvoyé fait référence. 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 indicateurs CreateOptions définis, le Gestionnaire d’E/S conserve le décalage actuel de la position du fichier 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 de FILE_OPEN_REPARSE_POINT CreateOptionsn’est pas spécifié et que 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 FILE_OPEN_REPARSE_POINT est spécifié, le traitement normal de l’analyse ne se produit pas et FltCreateFileEx2 tente d’ouvrir directement le fichier de point d’analyse. Dans les deux cas, si l’opération d’ouverture a réussi, FltCreateFileEx2 retourne STATUS_SUCCESS ; sinon, la routine retourne un code d’erreur NTSTATUS. FltCreateFileEx2 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 FltCreateFileEx2 , 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 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é.

Notes

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.

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

Notes

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

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONIZE

Vous ne devez pas utiliser FltCreateFileEx2 pour ouvrir un handle avec un accès direct au périphérique de stockage pour le volume, sinon vous allez faire fuiter les ressources système. Si vous souhaitez ouvrir un handle avec un accès direct à un périphérique de stockage, appelez la fonction IoCreateFileEx, IoCreateFileSpecifyDeviceObjectHint ou ZwCreateFile à la place.

Lorsqu’un appelant de FltCreateFileEx2 souhaite activer l’analyse pour une cible de volume, une FLT_CREATEFILE_TARGET_ECP_CONTEXT peut être incluse en tant qu’ECP dans la liste ECP dans le paramètre DriverContext . Si cet 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 ce PCE est disponible à partir de Windows 8.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows Vista.
Plateforme cible	Universal
En-tête	fltkernel.h (incluez FltKernel.h)
Bibliothèque	Fltmgr.lib
IRQL	PASSIVE_LEVEL