Fonction CcPinMappedData (ntifs.h)

Article
02/26/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’octet de début 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 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 :

Indicateur	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, la broche é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 comme entrée sur tous les appels suivants pour cette mémoire tampon.

Valeur retournée

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 que 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, il doit également appeler CcSetDirtyPinnedData afin que les données modifiées soient finalement écrites sur le disque.

CcPinMappedData ne peut pas épingler les 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 vues alignées 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.

En cas d’échec, CcPinMappedData déclenche une exception status 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 status de l’erreur d’E/S. Par conséquent, pour contrôler si une défaillance se produit, le pilote doit encapsuler l’appel à CcPinMappedData dans une instruction try-except ou try-finally .

Pour mapper les données d’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 l’appel de CcPinMappedData , car la référence d’épingle correspond à CcMapData.