Fonction FltReadFileEx (fltkernel.h)

FltReadFileEx lit les données d’un fichier, d’un flux ou d’un appareil ouvert. Cette fonction étend FltReadFile pour autoriser l’utilisation facultative d’une MDL pour les données de lecture au lieu d’une adresse de mémoire tampon mappée.

Syntaxe

NTSTATUS FLTAPI FltReadFileEx(
  [in]            PFLT_INSTANCE                    InitiatingInstance,
  [in]            PFILE_OBJECT                     FileObject,
  [in, optional]  PLARGE_INTEGER                   ByteOffset,
  [in]            ULONG                            Length,
  [out]           PVOID                            Buffer,
  [in]            FLT_IO_OPERATION_FLAGS           Flags,
  [out, optional] PULONG                           BytesRead,
  [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 minifilter instance auquel 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 être NULL.

[in] FileObject

Pointeur vers un FILE_OBJECT pour le fichier à partir duquel les données doivent être lues. Cet objet fichier doit être actuellement ouvert. L’appel de FltReadFileEx lorsque l’objet 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 fichier.

• Si le fichier a été ouvert pour les E/S synchrones (FO_SYNCHRONOUS_IO est défini dans le champ Indicateurs 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 effectuées 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.

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, les E/S sont effectuées au niveau du CurrentByteOffset de l’objet fichier.

Si l’objet file 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 vers le bas de la pile et la restaure lorsque les E/S sont retournées. Du point de vue de l’appelant de FltReadFileEx (et des filtres à des altitudes plus élevées), le CurrrentByteOffset n’est pas mis à jour. Toutefois, les filtres sous l’appelant voient la valeur CurrentByteOffset mise à jour dans leurs rappels post-lecture/écriture.

Si l’objet file 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 .

[in] Length

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

[out] Buffer

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit les données lues à partir du fichier. Si une MDL est fournie dans Mdl, Buffer doit avoir la valeur NULL.

[in] Flags

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

[out, optional] BytesRead

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

[in, optional] CallbackRoutine

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

[in, optional] CallbackContext

Pointeur de contexte à passer à callbackRoutine s’il y en a un. 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 de plage d’octets.

[in, optional] Mdl

MdL facultatif qui décrit la mémoire dans laquelle les données sont lues. Si une mémoire tampon est fournie dans Buffer , Mdl doit être NULL.

Valeur retournée

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

Remarques

Un pilote minifilter appelle FltReadFileEx pour lire les données d’un fichier ouvert.

FltReadFileEx crée une demande de lecture et l’envoie aux instances de pilote minifilter attachées sous la instance de lancement, ainsi qu’au système de fichiers. Le instance spécifié et les instances jointes ci-dessus ne reçoivent pas la demande de lecture.

FltReadFileEx 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, cela s’effectue en spécifiant 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 passées à FltReadFileEx :

• 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 une tentative de lecture est effectuée au-delà de la fin du fichier, FltReadFileEx retourne une erreur.

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

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

Si plusieurs threads appellent FltReadFileEx pour le même objet fichier et que l’objet file 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, FltReadFileEx diffère de ZwReadFile.

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

Configuration requise

Voir aussi

FILE_OBJECT

FltAllocatePoolAlignedWithTag

FltCreateFile

FltCreateFileEx

FltWriteFile

ObReferenceObjectByHandle

PFLT_COMPLETED_ASYNC_IO_CALLBACK

ZwCreateFile

ZwReadFile

ZwWriteFile