FltReadFileEx, fonction (fltkernel.h)
FltReadFileEx lit les données à partir d’un fichier ouvert, d’un flux ou d’un appareil. Cette fonction étend fltReadFile pour autoriser l’utilisation facultative d’un MDL pour lire les données 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 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 à partir duquel les données doivent être lues. Cet objet de fichier doit être actuellement ouvert. L’appel de FltReadFileEx 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.
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 FltReadFileEx (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.
[in] Length
Taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre tampon.
[out] Buffer
Pointeur vers une mémoire tampon allouée par l’appelant qui reçoit les données lues à partir du fichier. 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 de lecture à effectuer.
| Drapeau | Signification |
|---|---|
| FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET | Les pilotes minifilter peuvent définir cet indicateur pour spécifier que FltReadFile ne doit pas mettre à jour le champ CurrentByteOffset de l’objet de fichier. |
| FLTFL_IO_OPERATION_NON_CACHED | Les pilotes Minifilter peuvent définir cet indicateur pour spécifier une lecture 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 minifilter peuvent définir cet indicateur pour spécifier une lecture de pagination. |
| FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING | Les pilotes minifilter peuvent définir cet indicateur pour spécifier une lecture d’E/S de pagination synchrone. Les pilotes minifilter qui définissent cet indicateur doivent également définir l’indicateur FLTFL_IO_OPERATION_PAGING. Disponible à partir de Windows Vista. |
[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’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 de lecture 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é.
[in, optional] Key
Clé facultative associée à un verrou de plage d’octets.
[in, optional] Mdl
MDL facultatif qui décrit la mémoire où les données sont lues. Si une mémoire tampon est fournie dans tampon, Mdl doit être NULL.
Valeur de retour
FltReadFileEx retourne la valeur NTSTATUS retournée par le système de fichiers.
Remarques
Un pilote minifilter appelle FltReadFileEx pour lire des données à partir d’un fichier ouvert.
FltReadFileEx crée une demande de lecture et l’envoie 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 de lecture.
FltReadFileEx 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 à FltReadFileEx:
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 une tentative est effectuée pour lire 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 a la valeur 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 de fichier qui FileObject points à ouvrir pour les E/S asynchrones.
Si plusieurs threads appellent FltReadFileEx 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, FltReadFileEx diffère de ZwReadFile.
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 |