CcPreparePinWrite, fonction (ntifs.h)

Article
12/21/2024

Le CcPreparePinWrite routine é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 vers 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 où les données doivent être écrites.

[in] Length

Longueur des données souhaitées en octets.

[in] Zero

Définissez la valeur TRUE si la mémoire tampon doit être zéro lors du retour. Ce paramètre est ignoré si l’indicateur PIN_CALLER_TRACKS_DIRTY_DATA est défini dans le paramètre Indicateurs.

[in] Flags

Masque de bits des 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 résident déjà dans la 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, la broche échoue et aucun BCB n’est retourné.
PIN_CALLER_TRACKS_DIRTY_DATA	L’appelant est responsable du suivi des pages sales. 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 comme entrée sur les appels suivants à 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 annulée ou libérée.

Valeur de retour

CcPreparePinWrite retourne TRUE si le fichier mis en cache a été épinglé correctement, FALSE sinon.

Remarques

CcPreparePinWrite épingle les pages de fichiers spécifiées dans le cache système. Les pages à remplacer complètement peuvent être satisfaites 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 placé dans un é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 de PIN_CALLER_TRACKS_DIRTY_DATA est couramment utilisé dans les cas où un système de fichiers gère un fichier journal écrit dans un fichier journal dans lequel il n’est pas lu. Étant donné que les données de fichier existantes sont remplacées et ne sont pas lues, le gestionnaire de cache peut retourner des pages de zéros au lieu d’effectuer des erreurs dans les pages réelles des données de fichier à partir du disque. Si cet indicateur est défini, le gestionnaire de cache ne suit pas les pages sales. L’appelant est chargé de suivre les pages sales. Notez que CcPreparePinWrite ne doit être utilisé que pour épingler les données de cette manière 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 avertir le gestionnaire de mémoire que les pages spécifiées dans la mémoire tampon du cache système sont incorrectes 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 tampon 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 les données entre les limites d’affichage dans le gestionnaire de cache. Le gestionnaire de cache gère les fichiers du système dans les vues alignées sur 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é sur 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 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 pager 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.

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