Fonction FltCreateFile (fltkernel.h)

Article
08/07/2023

Les pilotes de minifiltre appellent FltCreateFile pour créer un fichier ou ouvrir un fichier existant.

Syntaxe

NTSTATUS FLTAPI FltCreateFile(
  [in]           PFLT_FILTER        Filter,
  [in, optional] PFLT_INSTANCE      Instance,
  [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              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 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 elle n’est pas 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 à FltCreateFile réussit.

[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 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 Optionsd’IoCreateFileEx pour obtenir la liste des options possibles.

Valeur retournée

FltCreateFile 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

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

Remarques

Sur les versions de Windows antérieures à Microsoft Windows Update correctif cumulatif pour Windows 2000 SP4 et Windows Server 2003 SP1, les pilotes de minifiltre doivent appeler FltCreateFile au lieu d’IoCreateFile, IoCreateFileSpecifyDeviceObjectHint ou ZwCreateFile pour obtenir un handle de fichier à utiliser avec des routines d’E/S ZwXxx telles que ZwReadFile et ZwQueryInformationFile.

Sur microsoft Windows Update correctif cumulatif pour Windows 2000 SP4, Windows Server 2003 SP1 et versions ultérieures, les pilotes de minifiltre peuvent utiliser FltCreateFileEx pour obtenir un pointeur d’objet de fichier à utiliser avec des routines de fichier FltXxx telles que FltReadFile et FltWriteFile. Sur les versions antérieures de Windows, le handle obtenu à partir de FltCreateFile peut être converti en pointeur d’objet de fichier en appelant ObReferenceObjectByHandle comme suit :

status = ObReferenceObjectByHandle(
           handle,                 //Handle
           0,                      //DesiredAccess
           NULL,                   //ObjectType
           KernelMode,             //AccessMode
           &handleFileObject,      //Object
           NULL);                  //HandleInformation</pre>

FltCreateFile envoie la demande de création uniquement aux instances attachées sous le pilote de minifiltre 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 FltCreateFile :

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 handle obtenu à partir de FltCreateFile doit finalement être libéré en appelant FltClose.

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 FltCreateFile. La définition de cet attribut restreint l’utilisation du handle retourné par FltCreateFile 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.

N’appelez pas cette routine avec des API désactivés (un FsRtlEnterFileSystem ou KeEnterCriticalRegion en suspens, car cela peut provoquer un blocage de thread.

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 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 ouvert et partagé avec succès. Si l’appelant d’origine de FltCreateFile 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 tous les ouvertures précédentes qui n’ont pas encore été publiées avec FltClose. Autrement dit, le DesiredAccess spécifié dans FltCreateFile pour un fichier donné ne doit pas entrer en conflit avec les accès que les 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 à FltCreateFile 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 FltCreateFile 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 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 fltCreateFile suivant 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 à FltCreateFile é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 sur Zw.. Routines de fichiers, notamment les suivantes :

Toute valeur offset d’octet passée à ZwReadFile ou ZwWriteFile doit être un multiple de la taille du secteur.
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 de moins 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 FltCreateFile 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 FileAlignmentInformationInformation 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 d’appareil.
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 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 de fichier auquel le FileHandle retourné 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 createOptions définis, le Gestionnaire d’E/S conserve le décalage de position de fichier actuel dans le champ CurrentByteOffset de l’objet de 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 que FltCreateFile 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 FltCreateFile tente d’ouvrir directement le fichier de points d’analyse. Dans les deux cas, si l’opération d’ouverture a réussi, FltCreateFile retourne STATUS_SUCCESS ; sinon, la routine retourne un code d’erreur NTSTATUS. FltCreateFile 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 FltCreateFile , 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 interrompt un blocage d’opération qui existe déjà sur 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 le bénéfice 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é l’échec de la demande d’oplock.

Notes

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.

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 filtrer les oplocks. Pour l’utiliser, vous devez effectuer les étapes suivantes :

Émettre une demande de création avec CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess d’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 prochain oplock demandé é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 cela pratique uniquement pour les oplocks 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 blocage 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 de minifiltre 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 , FltCreateFile 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 FltCreateFile pour ouvrir un handle avec accès direct au périphérique de stockage pour le volume, sinon vous allez fuiter des ressources système. Si vous souhaitez ouvrir un handle avec un accès direct à un appareil de stockage, appelez plutôt la fonction IoCreateFileEx, IoCreateFileSpecifyDeviceObjectHint ou ZwCreateFile .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Correctif cumulatif Windows 2000 1 pour SP4, Windows XP SP2, Windows Server 2003 SP1
Plateforme cible	Universal
En-tête	fltkernel.h (inclure FltKernel.h)
Bibliothèque	Fltmgr.lib
IRQL	PASSIVE_LEVEL