FsRtlCopyWrite, fonction (ntifs.h)
Le FsRtlCopyWrite routine copie les données d’une mémoire tampon utilisateur vers un fichier mis en cache.
Syntaxe
BOOLEAN FsRtlCopyWrite(
[in] PFILE_OBJECT FileObject,
[in] PLARGE_INTEGER FileOffset,
[in] ULONG Length,
[in] BOOLEAN Wait,
[in] ULONG LockKey,
[in] 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 dans lequel les données doivent être écrites.
[in] FileOffset
Pointeur vers une variable qui spécifie le décalage d’octets de départ dans le fichier mis en cache.
[in] Length
Longueur en octets des données à écrire.
[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.
[in] Buffer
Pointeur vers la mémoire tampon à partir de 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
Pointeur vers l’objet d’appareil pour le volume monté qui contient les données du fichier.
Valeur de retour
FsRtlCopyWrite 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 FsRtlCopyWrite retourne FALSE, ou si le contenu de IoStatus indique que l’opération de copie a échoué, l’appelant doit allouer un IRP d’écriture au lieu d’appeler FsRtlCopyWrite.
Remarques
Au lieu d’implémenter une routine d’écriture 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 FsRtlCopyWrite comme point d’entrée du système de fichiers pour le traitement des demandes d’écriture d’E/S rapides. Cela nécessite que la routine DriverEntry du système de fichiers définisse le point d’entrée FastIoWrite sur FsRtlCopyWrite 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 :
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 les FsContext membre de chaque objet de fichier pour qu’il pointe vers cette structure (ou vers la structure FCB ou une autre structure 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, FsRtlCopyWrite est garanti pour copier les données 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, FsRtlCopyWrite refusera de bloquer et retournera 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 FsRtlFastCheckLockForWrite à 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 | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |