Fonction FsRtlCopyWrite (ntifs.h)

La routine FsRtlCopyWrite 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’octet de début dans le fichier mis en cache.

[in] Length

Longueur en octets des données à écrire.

[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 sinon.

[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 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.

[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’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

Pointeur vers l’objet d’appareil pour le volume monté qui contient les données du fichier.

Valeur retournée

FsRtlCopyWrite retourne TRUE si la demande de copie a été effectuée, FALSE sinon. Notez qu’une valeur de retour true ne signifie pas nécessairement que l’opération de copie a réussi.

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

Remarques

Plutôt que d’implémenter une routine d’écriture 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 FsRtlCopyWrite comme point d’entrée du système de fichiers pour traiter les demandes d’écriture d’E/S rapides. Pour cela, la routine DriverEntry du système de fichiers doit définir 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 :

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 vers 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’un verrou exclusif de plage d’octets existe 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 sont 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 soient devenues résidentes et que les données puissent être copiées.

Si Wait a la valeur FALSE, FsRtlCopyWrite 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 pas de plage d’octets verrouillés exclusivement 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 FsRtlXxxLockYyyy pour gérer les verrous de plage d’octets, cela peut être effectué en appelant FsRtlFastCheckLockForWrite à partir de la routine FastIoCheckIfPossible avant d’appeler FsRtlCopyRead.

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

Configuration requise

Voir aussi

CcInitializeCacheMap

FsRtlCopyRead

FsRtlFastCheckLockForWrite