Fonction FsRtlCopyRead (ntifs.h)

La routine FsRtlCopyRead copie les données d’un fichier mis en cache vers une mémoire tampon utilisateur.

Syntaxe

BOOLEAN FsRtlCopyRead(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [in]  ULONG            LockKey,
  [out] PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PDEVICE_OBJECT   DeviceObject
);

Paramètres

[in] FileObject

Pointeur vers un objet fichier pour le fichier mis en cache à partir duquel les données doivent être lues.

[in] FileOffset

Décalage d’octets de démarrage dans le fichier mis en cache.

[in] Length

Longueur en octets des données à lire.

[in] Wait

Définissez sur TRUE si l’appelant peut être placé dans un état d’attente jusqu’à ce que toutes les données soient copiées ; FALSE dans le cas contraire.

[in] LockKey

Valeur associée à la plage d’octets à verrouiller. Si la plage à verrouiller chevauche une autre plage déjà verrouillée avec un verrou non exclusif, ou si la plage à lire est une sous-plage d’une autre plage déjà verrouillée de manière nonexclusive, la valeur de ce paramètre doit être la clé de ce verrou non exclusif Le verrou doit être conservé par le processus parent du thread appelant. Sinon, ce paramètre n’a aucun effet.

[out] Buffer

Pointeur vers une mémoire tampon dans laquelle les données doivent être copiées.

[out] IoStatus

Pointeur vers une structure allouée par l’appelant qui reçoit l’achèvement final status et des informations sur l’opération. Si les données sont correctement copiées, IoStatus.Status contient STATUS_SUCCESS. Si toutes les données ne sont pas copiées correctement, IoStatus.Information contient le nombre réel d’octets qui ont été copiés.

[in] DeviceObject

Objet d’appareil pour l’appareil qui contient les données du fichier.

Valeur retournée

FsRtlCopyRead retourne TRUE si la demande de copie a été effectuée, false dans le cas contraire. Notez qu’une valeur de retour true ne signifie pas nécessairement que l’opération de copie a réussi.

Si FsRtlCopyRead retourne FALSE, ou si le contenu d’IoStatus indique que l’opération de copie a échoué, l’appelant doit allouer un IRP de lecture au lieu d’appeler FsRtlCopyRead.

Remarques

Au lieu d’implémenter une routine de lecture d’E/S rapide spécifique au système de fichiers, les développeurs de systèmes de fichiers qui prennent en charge la mise en cache des fichiers doivent envisager d’utiliser FsRtlCopyRead comme point d’entrée du système de fichiers pour le traitement des demandes de lecture d’E/S rapides. Cela nécessite que la routine DriverEntry du système de fichiers définisse le point d’entrée FastIoRead sur FsRtlCopyRead dans la structure FAST_IO_DISPATCH de l’objet pilote du système de fichiers. En outre, le système de fichiers doit effectuer les opérations suivantes :

1. Pour chaque fichier sur lequel des E/S rapides peuvent être effectuées, le système de fichiers doit allouer et initialiser une structure FSRTL_COMMON_FCB_HEADER.

   Dans la plupart des systèmes de fichiers, cela s’effectue en incluant la structure FSRTL_COMMON_FCB_HEADER dans un bloc de contrôle de fichier (FCB) ou une structure comparable utilisée pour maintenir l’état d’un fichier ouvert.

   Le stockage pour la structure FSRTL_COMMON_FCB_HEADER est généralement alloué à partir d’un pool paginé.

2. Pour chaque fichier sur lequel des E/S rapides peuvent être effectuées, le système de fichiers doit lier tous les objets de fichier pour le fichier à la structure FSRTL_COMMON_FCB_HEADER. Pour ce faire, définissez le membre FsContext de chaque objet de fichier pour qu’il pointe vers cette structure (ou le fcb ou une autre structure qui contient la structure FSRTL_COMMON_FCB_HEADER).

3. Lors de la mise en cache d’un fichier, le système de fichiers doit définir le membre IsFastIoPossible de la structure FSRTL_COMMON_FCB_HEADER du fichier sur une valeur appropriée. Cette valeur doit être mise à jour en fonction des besoins tant que le fichier reste mis en cache.

   En particulier, les systèmes de fichiers doivent définir le membre IsFastIoPossible de la structure FSRTL_COMMON_FCB_HEADER sur FastIoIsQuestionable dès qu’il existe un verrou exclusif de plage d’octets sur le fichier mis en cache.

Si Wait a la valeur TRUE, FsRtlCopyRead est garanti pour terminer la demande de copie et retourner TRUE. Si les pages requises du fichier mis en cache résident déjà en mémoire, les données sont copiées immédiatement et aucun blocage ne se produit. Si les pages nécessaires ne sont pas résidentes, l’appelant est placé dans un état d’attente jusqu’à ce que toutes les pages requises aient été rendues résidentes et que les données puissent être copiées.

Si Wait a la valeur FALSE, FsRtlCopyRead refuse de bloquer et retourne FALSE, s’il ne peut pas acquérir la ressource main du fichier ou si les pages requises du fichier mis en cache ne résident pas déjà en mémoire.

La routine FastIoCheckIfPossible du système de fichiers est chargée de s’assurer que la plage d’octets définie par FileOffset et Length n’inclut aucune plage d’octets exclusivement verrouillée pour laquelle l’appelant ne passe pas la valeur LockKey appropriée. Si le système de fichiers utilise les routines de prise en charge FsRtlXxxLockYyy pour gérer les verrous de plage d’octets, vous pouvez appeler FsRtlFastCheckLockForRead à partir de la routine FastIoCheckIfPossible avant d’appeler FsRtlCopyRead.

Pour mettre en cache un fichier, utilisez la routine CcInitializeCacheMap .

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	ntifs.h (include Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	PowerIrpDDis(wdm)

Voir aussi

CcInitializeCacheMap

FsRtlCopyWrite

FsRtlFastCheckLockForRead