FltWriteFile, fonction (fltkernel.h)

FltWriteFile est utilisé pour écrire des données dans un fichier ouvert, un flux ou un appareil.

Syntaxe

NTSTATUS FLTAPI FltWriteFile(
  [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
);

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 FltWriteFile 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 FltWriteFile (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.

Avant Windows 8, les constantes spéciales FILE_WRITE_TO_END_OF_FILE et FILE_USE_FILE_POINTER_POSITION ne sont pas prises en charge pour ce paramètre.

[in] Length

Taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre tampon.

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

[in] Flags

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

[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ée 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 à l'CallbackRoutine s’il en existe un. Ce paramètre est facultatif et peut être NULL. Si CallbackRoutine a la valeur NULL, ce paramètre est ignoré.

Valeur de retour

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

Remarques

Un pilote minifilter appelle FltWriteFile pour écrire des données dans un fichier ouvert.

FltWriteFile 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.

FltWriteFile 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. En règle générale, cela est fait en spécifiant l’indicateur CreateOptions FILE_NO_INTERMEDIATE_BUFFERING 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 à FltWriteFile:

• 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, FltWriteFile 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 FltWriteFile 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, FltWriteFile diffère de ZwWriteFile.

Exigences

Voir aussi

FILE_OBJECT

FltAllocatePoolAlignedWithTag

FltCreateFile

FltCreateFileEx

FltReadFile

ObReferenceObjectByHandle

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwCreateFile

ZwReadFile

ZwWriteFile