Fonction FltCreateFileEx (fltkernel.h)

Article
08/07/2023

Les pilotes Minifilter appellent FltCreateFileEx pour créer un fichier ou ouvrir un fichier existant.

Syntaxe

NTSTATUS FLTAPI FltCreateFileEx(
  [in]           PFLT_FILTER        Filter,
  [in, optional] PFLT_INSTANCE      Instance,
  [out]          PHANDLE            FileHandle,
  [out]          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
);

Paramètres

[in] Filter

Pointeur de filtre opaque pour l’appelant.

[in, optional] Instance

Pointeur de instance opaque pour le pilote minifilter instance auquel 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 de périphérique en haut de la pile des pilotes du système de fichiers pour le volume. Si elle n’est pas NULL, la demande est envoyée uniquement aux instances de pilote minifilter qui sont 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 à FltCreateFileEx réussit.

[out] FileObject

Pointeur vers une variable allouée par l’appelant qui reçoit le pointeur d’objet fichier si l’appel à FltCreateFileEx 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. Pour plus d’informations sur ce paramètre et la liste des valeurs d’indicateur, consultez le paramètre DesiredAccess de IoCreateFileEx .

[in] ObjectAttributes

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

[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. Consultez le paramètre IoStatusBlock de IoCreateFileEx.

[in, optional] AllocationSize

Spécifie éventuellement la taille d’allocation initiale, en octets, pour le flux de 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

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 FileAttributes de IoCreateFileEx .

[in] ShareAccess

Spécifie le type d’accès partagé 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 ShareAccess de 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 Disposition de 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 CreateOptions de IoCreateFileEx.

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

Valeur retournée

FltCreateFileEx 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

FltCreateFileEx 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 pendant que FltCreateFileEx tente de gérer cette situation.

Remarques

Les pilotes de minifiltre du système de fichiers doivent appeler FltCreateFileEx au lieu de FltCreateFile pour obtenir un pointeur d’objet de fichier à utiliser avec des routines d’E/S FltXxx telles que FltReadFile et FltQueryInformationFile.

FltCreateFileEx 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 va 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 FltCreateFileEx :

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

Tout FileHandle obtenu à partir de FltCreateFileEx 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 de processus système doivent définir l’attribut OBJ_KERNEL_HANDLE pour le paramètre ObjectAttributes de FltCreateFileEx. La définition de cet attribut limite l’utilisation du handle retourné par FltCreateFileEx aux processus s’exécutant en mode noyau. Sinon, le handle est accessible par le processus dans le contexte 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 entraîner un blocage du système.

Certains indicateurs DesiredAccess et certaines combinaisons d’indicateurs ont les effets suivants :

Pour qu’un appelant synchronise une fin d’E/S en attendant que l’état 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 d’effectuer des écritures au-delà de la fin du fichier. 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 utiliser le FileHandle retourné 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 correctement ouvert et partagé. Si l’appelant d’origine de FltCreateFileEx 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, l’élément DesiredAccess demandé au fichier doit être compatible avec les spécifications DesiredAccess et ShareAccess de toutes les ouvertures précédentes qui n’ont pas encore été publiées avec FltClose. Autrement dit, le DesiredAccess spécifié à FltCreateFileEx pour un fichier donné ne doit pas entrer en conflit avec les accès que d’autres ouvreurs du fichier ont refusés.

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 à FltCreateFileEx avec FILE_SUPERSEDE sur un fichier existant supprime ce fichier, puis le recrée. Cela implique que si le fichier a déjà été ouvert par un autre thread, il a ouvert le fichier en spécifiant un paramètre ShareAccess avec l’indicateur FILE_SHARE_DELETE défini. Notez que ce type de disposition est cohérent avec le style POSIX de remplacement des fichiers.

Les valeurs CreateDisposition FILE_OVERWRITE_IF et FILE_SUPERSEDE sont similaires. Si FltCreateFileEx est appelé avec un fichier existant et l’une de ces valeurs CreateDisposition , le fichier est remplacé.

Le remplacement d’un fichier équivaut sémantiquement à une opération de remplacement, à l’exception des éléments suivants :

L’appelant doit avoir un accès en écriture au fichier, au lieu de supprimer l’accès. Cela implique que, si le fichier a déjà été ouvert par un autre thread, il a ouvert le fichier avec l’indicateur FILE_SHARE_WRITE défini dans l’entrée ShareAccess.
Les attributs de fichier spécifiés sont logiquement ORed avec ceux déjà présents dans le fichier. Cela implique que si le fichier a déjà été ouvert par un autre thread, un appelant suivant de FltCreateFileEx 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 à FltCreateFileEx é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 offset d’octet passée à FltReadFile, ZwReadFile, FltWriteFile ou ZwWriteFile doit être un multiple de la taille du secteur.
La longueur transmise à FltReadFile, ZwReadFile, FltWriteFile 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’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 FltCreateFileEx 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 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 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 de secteur.

Les FILE_SYNCHRONOUS_IO_ALERT et FILE_SYNCHRONOUS_IO_NONALERT CreateOptions , 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é. Une fois l’une de ces options CreateOptions définie, 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 CreateOptions n’est pas spécifié et que FltCreateFileEx 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 FltCreateFileEx tente d’ouvrir directement le fichier de point d’analyse. Dans les deux cas, si l’opération d’ouverture a réussi, FltCreateFileEx retourne STATUS_SUCCESS ; sinon, la routine retourne un code d’erreur NTSTATUS. FltCreateFileEx 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 FltCreateFileEx , puis demander n’importe quel 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 exactement FILE_READ_ATTRIBUTES et ShareAccess de FILE_SHARE_READ exactement | 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 FltCreateFileEx pour ouvrir un handle avec un accès direct au périphérique de stockage pour le volume, sinon vous allez faire fuiter des 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.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans microsoft Windows 2000 Update Rollup 1 pour SP4, Windows XP SP3, Windows Server 2003 SP1 et versions ultérieures du système d’exploitation Windows.
Plateforme cible	Universal
En-tête	fltkernel.h (incluez FltKernel.h)
Bibliothèque	Fltmgr.lib
IRQL	PASSIVE_LEVEL