FltWriteFileEx, fonction (fltkernel.h)
FltWriteFileEx est utilisé pour écrire des données dans un fichier ouvert, un flux ou un appareil. Cette fonction étend FltWriteFile pour autoriser l’utilisation facultative d’un MDL pour écrire des 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 d’instance opaque pour l’instance de pilote minifilter à laquelle l’opération doit être envoyée. L’instance doit être attachée au volume où réside le fichier. Ce paramètre est obligatoire et ne peut pas être 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 être NULL.
[in, optional] ByteOffset
Pointeur vers une variable allouée par l’appelant qui spécifie le décalage d’octets de départ 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 de 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 de fichier), l’appelant peut définir ByteOffset->LowPart pour FILE_USE_FILE_POINTER_POSITION et ByteOffset->HighPart pour -1 effectuer les E/S sur 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.
- Sinon, l’E/S est effectuée au CurrentByteOffset de l’objet de fichier.
Si l’objet de fichier a été ouvert pour les E/S synchrones, le champ CurrentByteOffset est mis à jour, sauf si l’appelant transmet l’indicateur FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET.
- Remarque : le système de fichiers met toujours à jour CurrentByteOffset dans ce cas. Filter Manager enregistre le CurrentByteOffset valeur avant d’envoyer l’E/S vers le bas de la pile et le restaure lorsque l’E/S est retournée. Du point de vue de l’appelant de FltWriteFileEx (et filtre à des altitudes supérieures) le CurrrentByteOffset n’est pas mis à jour. Toutefois, les filtres sous l’appelant voient la mise à jour CurrentByteOffset valeur dans leurs rappels post-lecture/écriture.
Si l’objet de 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 qui FileObject points à ouvrir pour les E/S asynchrones, ce paramètre est requis et ne peut pas être NULL.
FltWriteFileEx ne prend pas en charge l’indicateur de FILE_WRITE_TO_END_OF_FILE.
[in] Length
Taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre tampon. 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 de l’appareil de stockage sous-jacent. Les pilotes minifilter peuvent allouer une telle mémoire tampon alignée en appelant FltAllocatePoolAlignedWithTag.
Si un MDL est fourni dans Mdl, tampon doit être NULL.
[in] Flags
Masque de bits des indicateurs qui spécifient le type d’opération d’écriture à effectuer.
| Drapeau | 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 fichier. |
| FLTFL_IO_OPERATION_NON_CACHED | Les pilotes minifilter peuvent définir cet indicateur pour spécifier une écriture non mise en cache, même si l’objet fichier n’a pas été ouvert avec FILE_NO_INTERMEDIATE_BUFFERING. |
| FLTFL_IO_OPERATION_PAGING | Les pilotes minifilter 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 minifilter 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’est pas NULL, ce paramètre est ignoré. Dans le cas contraire, ce paramètre est facultatif et peut être NULL.
[in, optional] CallbackRoutine
Pointeur vers une routine de rappel PFLT_COMPLETED_ASYNC_IO_CALLBACK-typé pour 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 si un pointeur de contexte est présent. 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 tampon, Mdl doit être NULL.
Valeur de retour
FltWriteFileEx retourne la valeur NTSTATUS retournée par le système de fichiers.
Remarques
Un pilote minifilter appelle FltWriteFileEx pour écrire des données dans un fichier ouvert.
FltWriteFileEx provoque l’envoi d’une demande d’écriture aux instances de pilote minifilter attachées sous l’instance de lancement et au système de fichiers. L’instance spécifiée 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 opérations suivantes est vraie :
L’appelant définit l’indicateur FLTFL_IO_OPERATION_NON_CACHED dans le paramètre indicateurs de.
L’objet fichier a été ouvert pour les E/S non mises en cache. Cela se fait généralement en spécifiant l’indicateur FILE_NO_INTERMEDIATE_BUFFERING****CreateOptions dans l’appel précédent à fltCreateFile, FltCreateFileExou ZwCreateFile.
Les E/S non mises en cache imposent les restrictions suivantes sur les valeurs de paramètre passées à FltWriteFileEx:
Mémoire tampon à laquelle le paramètre tampon doit être aligné conformément à l’exigence d’alignement de l’appareil de stockage sous-jacent. Pour allouer une telle mémoire tampon alignée, appelez FltAllocatePoolAlignedWithTag.
Décalage d’octet dont le paramètre ByteOffset doit être un multiple non négatif de la taille du secteur du volume.
La longueur spécifiée dans le paramètre Length doit être un multiple non négatif de la taille du 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 qui FileObject points à ouvrir pour les E/S asynchrones.
Si plusieurs threads appellent FltWriteFileEx pour le même objet de fichier et que l’objet de 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 par commodité lorsqu’un minifilter dispose déjà d’un MDL disponible. Le MDL est utilisé directement et l’étape supplémentaire de mappage d’une adresse pour tampon peut être évitée.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 8 |
| plateforme cible | Universel |
| d’en-tête | fltkernel.h (include Fltkernel.h) |
| bibliothèque | FltMgr.lib |
| DLL | Fltmgr.sys |
| IRQL | PASSIVE_LEVEL |