CcPreparePinWrite, fonction (ntifs.h)

Article
02/29/2024

La routine CcPreparePinWrite épingle la plage d’octets spécifiée d’un fichier mis en cache pour l’accès en écriture.

Syntaxe

BOOLEAN CcPreparePinWrite(
  [in]  PFILE_OBJECT   FileObject,
  [in]  PLARGE_INTEGER FileOffset,
  [in]  ULONG          Length,
  [in]  BOOLEAN        Zero,
  [in]  ULONG          Flags,
  [out] PVOID          *Bcb,
  [out] PVOID          *Buffer
);

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épart dans le fichier où les données doivent être écrites.

[in] Length

Longueur des données souhaitées en octets.

[in] Zero

Définissez sur TRUE si la mémoire tampon doit être mise à zéro au retour. Ce paramètre est ignoré si l’indicateur PIN_CALLER_TRACKS_DIRTY_DATA est défini dans le paramètre Flags .

[in] Flags

Masque de bits d’indicateurs spécifiant la façon dont l’opération d’épinglage doit être effectuée. Combinaison ORed d’une ou plusieurs des valeurs suivantes :

Valeur	Signification
PIN_WAIT	L’appelant peut être placé dans un état d’attente jusqu’à ce que les données soient épinglées.
PIN_EXCLUSIVE	Le bloc de contrôle de mémoire tampon (BCB) doit être acquis exclusivement.
PIN_NO_READ	Seules les pages qui sont déjà en mémoire doivent être épinglées. Si cet indicateur est défini, PIN_WAIT doit également être défini.
PIN_IF_BCB	Les données doivent être épinglées uniquement si un BCB existe déjà. Sinon, l’épingle échoue et aucun BCB n’est retourné.
PIN_CALLER_TRACKS_DIRTY_DATA	L’appelant est chargé de suivre sale pages. Si cet indicateur est défini, tous les autres indicateurs sont ignorés. Cet indicateur est disponible sur Microsoft Windows Server 2003 SP1 et versions ultérieures.

[out] Bcb

Pointeur opaque vers un bloc de contrôle de mémoire tampon épinglé (BCB). Ce pointeur doit être fourni en entrée sur tous les appels ultérieurs à CcPreparePinWrite ou CcUnpinData pour cette mémoire tampon.

[out] Buffer

Retourne le pointeur vers les données souhaitées, valide jusqu’à ce que la mémoire tampon soit désépinglé ou libérée.

Valeur retournée

CcPreparePinWrite retourne TRUE si le fichier mis en cache a été épinglé correctement, false dans le cas contraire.

Remarques

CcPreparePinWrite épingle les pages de fichiers spécifiées dans le cache système. Les pages à remplacer complètement peuvent être satisfaites avec des pages de zéros.

Si l’indicateur PIN_WAIT est défini, CcPreparePinWrite est garanti pour terminer la demande de préparation et retourner TRUE. Si toutes les pages peuvent être préparées immédiatement, aucun blocage ne se produit. Si les pages nécessaires ne sont pas résidentes, l’appelant est mis en état d’attente jusqu’à ce que toutes les pages requises aient été rendues résidentes et que les pages puissent être préparées. Si l’indicateur PIN_WAIT n’est pas défini, mais que toutes les pages ne peuvent pas être préparées immédiatement, CcPreparePinWrite retourne FALSE et ses valeurs de paramètre de sortie sont sans signification.

Microsoft Windows Server 2003 SP1 et versions ultérieures : L’indicateur PIN_CALLER_TRACKS_DIRTY_DATA est couramment utilisé dans les cas où un système de fichiers gère un fichier journal écrit dans, mais non lu. Étant donné que les données de fichier existantes seront remplacées et non lues, le gestionnaire de cache peut retourner des pages de zéros au lieu d’une erreur dans les pages réelles de données de fichier à partir du disque. Si cet indicateur est défini, le gestionnaire de cache ne suit pas sale pages. L’appelant est responsable du suivi des pages sale. Notez que CcPreparePinWrite ne doit être utilisé pour épingler les données de cette manière que si la mémoire tampon sera finalement vidée sur le disque. Avant d’appeler CcFlushCache pour vider la mémoire tampon sur le disque, l’appelant doit d’abord appeler MmSetAddressRangeModified pour informer le gestionnaire de mémoire que les pages spécifiées dans la mémoire tampon du cache système sont sale et doivent être écrites.

Chaque appel réussi à CcPreparePinWrite doit être mis en correspondance par un appel ultérieur à CcUnpinData. Si CcPreparePinWrite est appelé plusieurs fois pour les mêmes données, CcUnpinData doit être appelé le même nombre de fois.

Le pointeur retourné dans Buffer est valide jusqu’à ce que CcUnpinData soit appelé. Si CcPinMappedData est appelé alors que ce pointeur est toujours valide, le pointeur reste valide après l’appel à CcPinMappedData (mais uniquement jusqu’à ce que CcUnpinData soit appelé).

CcPreparePinWrite ne peut pas épingler des données au-delà des limites de la vue dans le gestionnaire de cache. Le gestionnaire de cache gère les fichiers dans le système dans des affichages alignés de 256 Ko. (La taille d’affichage du gestionnaire de cache est spécifiée par la constante définie par le système VACB_MAPPING_GRANULARITY, qui est définie sur 256 Ko dans ntifs.h.) Les régions épinglées ne peuvent pas s’étendre sur plus d’une vue de 256 Ko. Par conséquent, la plus grande région pouvant être épinglée est de 256 Ko, en commençant par un décalage aligné de 256 Ko dans le fichier.

L’épinglage d’une plage d’octets dans un fichier mis en cache ne garantit pas que les pages restent résidentes en mémoire. Tant que les pages sont épinglées, la plage d’octets est garantie de rester mappée dans l’espace d’adressage virtuel du cache système, mais le gestionnaire de mémoire peut supprimer les pages physiques en fonction de la demande de mémoire du système.

Il n’est pas nécessaire d’appeler CcSetDirtyPinnedData après avoir appelé CcPreparePinWrite. Si CcPreparePinWrite retourne TRUE, le BCB est déjà marqué comme sale.

En cas d’échec, CcPreparePinWrite déclenche une exception status pour cet échec particulier. Par exemple, si un échec d’allocation de pool se produit, CcPreparePinWrite déclenche une exception STATUS_INSUFFICIENT_RESOURCES ; si une erreur d’E/S se produit, CcPreparePinWrite déclenche la status exception de l’erreur d’E/S. Par conséquent, pour prendre le contrôle en cas de défaillance, le pilote doit encapsuler l’appel à CcPreparePinWrite dans une instruction try-except ou try-finally .