CcPinMappedData, fonction (ntifs.h)

Article
12/21/2024

La routine CcPinMappedData épingle la plage d’octets spécifiée d’un fichier mis en cache.

Syntaxe

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

Paramètres

[in] FileObject

Pointeur vers un objet de fichier pour le fichier mis en cache dans lequel une plage de données doit être épinglée.

[in] FileOffset

Pointeur vers une variable qui spécifie le décalage d’octets de départ dans le fichier mis en cache où résident les données souhaitées.

[in] Length

Longueur en octets des données à épingler.

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

Drapeau	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. Si cet indicateur est défini, PIN_WAIT doit également être défini.
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, l’épingle échoue et Bcb est défini sur NULL.

[in, out] Bcb

Lors du premier appel, cela retourne un pointeur vers un bloc de contrôle de mémoire tampon (BCB). Ce pointeur doit être fourni en tant qu’entrée sur tous les appels suivants pour cette mémoire tampon.

Valeur de retour

CcPinMappedData retourne TRUE si les données du fichier mis en cache ont été épinglées correctement, FALSE sinon.

Remarques

Un retour réussi de CcPinMappedData garantit que les données précédemment mappées dans un appel à CcMapData sont épinglées dans le cache et les données de la plage spécifiée peuvent être modifiées en toute sécurité. Si l’appelant modifie par la suite les données épinglées par CcPinMappedData, elle doit également appeler CcSetDirtyPinnedData afin que les données modifiées soient écrites sur le disque.

CcPinMappedData ne peut pas épingler des données à travers 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.

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

Pour mapper des données pour un fichier mis en cache, utilisez la routine CcMapData. Pour mettre en cache un fichier, utilisez CcInitializeCacheMap.

Il n’est pas nécessaire d’appeler CcUnpinData après avoir appelé CcPinMappedData, car la référence de broche est comparée à CcMapData.