FsRtlCopyRead, fonction (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 de fichier pour le fichier mis en cache à partir duquel les données doivent être lues.
[in] FileOffset
Début du décalage d’octet dans le fichier mis en cache.
[in] Length
Longueur en octets des données à lire.
[in] Wait
Définissez la valeur TRUE si l’appelant peut être placé dans un état d’attente jusqu’à ce que toutes les données aient été 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 qui est déjà verrouillée avec un verrou non-cluster ou si la plage à lire est une sous-plage d’une autre plage qui est déjà verrouillée de manière non-cluster, la valeur de ce paramètre doit être la clé de ce verrou non cluster. 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’état d’achèvement final et les informations relatives à l’opération. Si les données sont copiées avec succès, 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 copiés.
[in] DeviceObject
Objet d’appareil pour l’appareil qui contient les données du fichier.
Valeur de retour
FsRtlCopyRead retourne TRUE si la demande de copie a été effectuée, FALSE sinon. Notez qu’une valeur de retour de TRUE ne signifie pas nécessairement que l’opération de copie a réussi.
Si FsRtlCopyRead retourne FALSE ou si le contenu de 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 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
Pour chaque fichier sur lequel des E/S rapides peuvent être effectuées, le système de fichiers doit allouer et initialiser une structure de 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 de la structure FSRTL_COMMON_FCB_HEADER est généralement alloué à partir d’un pool paginé.
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 du fichier à la structure FSRTL_COMMON_FCB_HEADER. Pour ce faire, définissez le membre
FsCon textde chaque objet de fichier pour qu’il pointe vers cette structure (ou la structure FCB ou autre qui contient la structure FSRTL_COMMON_FCB_HEADER). Lors de la mise en cache d’un fichier, le système de fichiers doit définir l'IsFastIoPossible membre de la structure FSRTL_COMMON_FCB_HEADER du fichier sur une valeur appropriée. Cette valeur doit être mise à jour si nécessaire 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 de plage d’octets exclusif 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 'attente a la valeur FALSE, FsRtlCopyRead refuse de bloquer et retourne FALSE, s’il ne peut pas acquérir la ressource principale 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 verrouillée exclusivement pour laquelle l’appelant ne passe pas la valeur LockKey appropriée. Si le système de fichiers utilise les routines FsRtlXxxLockYyy prennent en charge les routines de gestion des verrous de plage d’octets, cela peut être effectué en appelant FsRtlFastCheckLockForRead à partir de la routine FastIoCheckIfPoss ible avant d’appeler FsRtlCopyRead.
Pour mettre en cache un fichier, utilisez la routine CcInitializeCacheMap.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Universel |
| d’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) |