Fonction FltWriteFileEx (fltkernel.h)

Article
11/16/2023

FltWriteFileEx est utilisé pour écrire des données dans un fichier, un flux ou un appareil ouvert. Cette fonction étend FltWriteFile pour autoriser l’utilisation facultative d’un MDL pour l’écriture de données au lieu d’une adresse de mémoire tampon mappée.

Syntaxe

NTSTATUS FLTAPI FltWriteFileEx(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [in]            PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesWritten,
  [in, optional]  PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                            CallbackContext,
  [in, optional]  PULONG                           Key,
  [in, optional]  PMDL                             Mdl
);

Paramètres

[in] InitiatingInstance

Pointeur de instance opaque pour le pilote minifiltre instance à laquelle l’opération doit être envoyée. Le instance doit être attaché au volume où réside le fichier. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

[in] FileObject

Pointeur vers un FILE_OBJECT pour le fichier dans lequel les données doivent être écrites. Cet objet de fichier doit être actuellement ouvert. L’appel de FltWriteFileEx lorsque l’objet de fichier n’est pas encore ouvert ou n’est plus ouvert (par exemple, dans une routine de rappel avant création ou après nettoyage) entraîne l’assertion du système sur une build vérifiée. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

[in, optional] ByteOffset

Pointeur vers une variable allouée par l’appelant qui spécifie le décalage d’octet de début dans le fichier où l’opération de lecture doit commencer.

Si ByteOffset est spécifié, les E/S sont effectuées à ce décalage, quelle que soit la valeur actuelle du champ CurrentByteOffset de l’objet fichier.

Si le fichier a été ouvert pour les E/S synchrones (FO_SYNCHRONOUS_IO est défini dans le champ Flags de l’objet fichier), l’appelant peut définir ByteOffset-LowPart> sur FILE_USE_FILE_POINTER_POSITION et ByteOffset-HighPart> sur -1 pour que les E/S s’effectuent dans le champ CurrentByteOffset de l’objet fichier. Si le fichier n’a pas été ouvert pour les E/S synchrones, l’utilisation de FILE_USE_FILE_POINTER_POSITION est une erreur.
L’appelant peut définir ByteOffset-LowPart> sur FILE_WRITE_TO_END_OF_FILE et ByteOffset-HighPart> sur -1 pour démarrer l’écriture à la fin du fichier (par exemple, effectuer une écriture d’ajout).

Si ByteOffset n’est pas spécifié :

Si le fichier n’a pas été ouvert pour les E/S synchrones, il s’agit d’une erreur.
Dans le cas contraire, les E/S sont effectuées au niveau du CurrentByteOffset de l’objet fichier.

Si l’objet fichier a été ouvert pour les E/S synchrones, le champ CurrentByteOffset est mis à jour, sauf si l’appelant passe l’indicateur FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET.

Remarque : le système de fichiers met toujours à jour CurrentByteOffset dans ce cas. Le Gestionnaire de filtres enregistre la valeur CurrentByteOffset avant d’envoyer les E/S dans la pile et les restaure lorsque l’E/S est retournée. Du point de vue de l’appelant de FltWriteFileEx (et des filtres à des altitudes plus élevées), le CurrrentByteOffset n’est pas mis à jour. Mais les filtres situés sous l’appelant voient la valeur CurrentByteOffset mise à jour dans leurs rappels post-lecture/écriture.

Si l’objet fichier n’a pas été ouvert pour les E/S synchrones, le champ CurrentByteOffset n’est pas mis à jour quel que soit l’état du paramètre ByteOffset .

Si l’objet de fichier vers lequel FileObject pointe a été ouvert pour les E/S asynchrones, ce paramètre est obligatoire et ne peut pas être NULL.

FltWriteFileEx ne prend pas en charge l’indicateur FILE_WRITE_TO_END_OF_FILE.

[in] Length

Taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre Buffer . Si un MDL est fourni dans Mdl, longueur est la taille des données décrites par MDL.

[in] Buffer

Pointeur vers une mémoire tampon qui contient les données à écrire dans le fichier. Si le fichier est ouvert pour les E/S non mises en cache, cette mémoire tampon doit être alignée conformément à l’exigence d’alignement du périphérique de stockage sous-jacent. Les pilotes de minifiltre peuvent allouer une telle mémoire tampon alignée en appelant FltAllocatePoolAlignedWithTag.

Si un MDL est fourni dans Mdl, la mémoire tampon doit avoir la valeur NULL.

[in] Flags

Masque de bits d’indicateurs qui spécifient le type d’opération d’écriture à effectuer.

Indicateur	Signification
FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET	Les pilotes minifilter peuvent définir cet indicateur pour spécifier que FltWriteFileEx ne met pas à jour le champ CurrentByteOffset de l’objet de fichier.
FLTFL_IO_OPERATION_NON_CACHED	Les pilotes de minifiltre peuvent définir cet indicateur pour spécifier une écriture non mise en cache, même si l’objet de fichier n’a pas été ouvert avec FILE_NO_INTERMEDIATE_BUFFERING.
FLTFL_IO_OPERATION_PAGING	Les pilotes de minifiltre peuvent définir cet indicateur pour spécifier une écriture de pagination.
FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING	Les pilotes minifilter peuvent définir cet indicateur pour spécifier une écriture d’E/S de pagination synchrone. Les pilotes de minifiltre qui définissent cet indicateur doivent également définir l’indicateur FLTFL_IO_OPERATION_PAGING. Cet indicateur est disponible à partir de Windows Vista.

[out, optional] BytesWritten

Pointeur vers une variable allouée par l’appelant qui reçoit le nombre d’octets écrits dans le fichier. Si CallbackRoutine n’a pas la valeur NULL, ce paramètre est ignoré. Sinon, ce paramètre est facultatif et peut avoir la valeur NULL.

[in, optional] CallbackRoutine

Pointeur vers une routine de rappel de type PFLT_COMPLETED_ASYNC_IO_CALLBACK à appeler une fois l’opération d’écriture terminée. Ce paramètre est facultatif et peut être NULL.

[in, optional] CallbackContext

Pointeur de contexte à passer à la routine dans CallbackRoutine , le cas échéant. Ce paramètre est facultatif et peut être NULL. Si CallbackRoutine a la valeur NULL, ce paramètre est ignoré.

[in, optional] Key

Clé facultative associée à un verrou d’objet de fichier.

[in, optional] Mdl

MdL facultatif qui décrit les données à écrire. Si une mémoire tampon est fournie dans Mémoire tampon, Mdl doit avoir la valeur NULL.

Valeur retournée

FltWriteFileEx retourne la valeur NTSTATUS retournée par le système de fichiers.

Remarques

Un pilote de minifiltre appelle FltWriteFileEx pour écrire des données dans un fichier ouvert.

FltWriteFileEx entraîne l’envoi d’une demande d’écriture aux instances de pilote de minifiltre attachées sous le instance initial et au système de fichiers. Le instance spécifié et les instances jointes ci-dessus ne reçoivent pas la demande d’écriture.

FltWriteFileEx effectue des E/S non mises en cache si l’une des conditions suivantes est vraie :

L’appelant définit l’indicateur FLTFL_IO_OPERATION_NON_CACHED dans le paramètre Flags .
L’objet file a été ouvert pour les E/S non mises en cache. En règle générale, pour ce faire, spécifiez l’indicateur FILE_NO_INTERMEDIATE_BUFFERING***CreateOptions dans l’appel précédent à FltCreateFile, FltCreateFileEx ou ZwCreateFile.

Les E/S non mises en cache imposent les restrictions suivantes sur les valeurs de paramètre transmises à FltWriteFileEx :

La mémoire tampon vers laquelle pointe le paramètre Buffer doit être alignée conformément à l’exigence d’alignement du périphérique de stockage sous-jacent. Pour allouer une telle mémoire tampon alignée, appelez FltAllocatePoolAlignedWithTag.
Le décalage d’octet vers lequel pointe le paramètre ByteOffset doit être un multiple non négatif de la taille de secteur du volume.
La longueur spécifiée dans le paramètre Length doit être un multiple non négatif de la taille de secteur du volume.

Si la valeur du paramètre CallbackRoutine n’est pas NULL, l’opération d’écriture est effectuée de manière asynchrone.

Si la valeur du paramètre CallbackRoutine est NULL, l’opération d’écriture est effectuée de manière synchrone. Autrement dit, FltWriteFileEx attend que l’opération d’écriture soit terminée avant de retourner. Cela est vrai même si l’objet de fichier vers lequel FileObject pointe a été ouvert pour les E/S asynchrones.

Si plusieurs threads appellent FltWriteFileEx pour le même objet de fichier et que l’objet fichier a été ouvert pour les E/S synchrones, le gestionnaire de filtres ne tente pas de sérialiser les E/S sur le fichier. À cet égard, FltWriteFileEx diffère de ZwWriteFile.

Le paramètre Mdl est fourni à titre pratique lorsqu’un minifiltre a déjà un MDL disponible. Le MDL est utilisé directement et l’étape supplémentaire du mappage d’une adresse pour Buffer peut être évitée.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8
Plateforme cible	Universal
En-tête	fltkernel.h (inclure Fltkernel.h)
Bibliothèque	FltMgr.lib
DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL