Fonction CcPinRead (ntifs.h)

Article
08/07/2023

La routine CcPinRead épingle la plage d’octets spécifiée d’un fichier mis en cache et lit les données épinglées dans une mémoire tampon.

Syntaxe

BOOLEAN CcPinRead(
  [in]  PFILE_OBJECT   FileObject,
  [in]  PLARGE_INTEGER FileOffset,
  [in]  ULONG          Length,
  [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 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épart dans le fichier mis en cache où résident les données souhaitées.

[in] Length

Longueur des données souhaitées en octets.

[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. Si cet indicateur est défini, PIN_WAIT doit également être défini.
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, la broche échoue et Bcb a la valeur NULL.

[out] Bcb

Lors du premier appel, 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.

[out] Buffer

Pointeur vers une mémoire tampon contenant les données épinglées.

Valeur retournée

CcPinRead retourne TRUE si les données du fichier mis en cache ont été épinglées et lues correctement, false dans le cas contraire.

Remarques

Si l’indicateur PIN_WAIT est défini, CcPinRead est garanti pour terminer la demande d’épinglage et retourner TRUE. Si les pages requises du fichier mis en cache résident déjà en mémoire, les données sont épinglé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 aient été rendues résidentes et que les données puissent être épinglées. Si l’indicateur PIN_WAIT n’est pas défini, mais que les données ne peuvent pas être épinglées immédiatement, CcPinRead retourne FALSE et ses valeurs de paramètre de sortie sont sans signification.

Si l’appelant modifie par la suite les données lues par CcPinRead, il doit également appeler CcSetDirtyPinnedData afin que les données modifiées soient écrites sur le disque.

Chaque appel réussi à CcPinRead doit être mis en correspondance par un appel ultérieur à CcUnpinData.

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é).

CcPinRead ne peut pas épingler des données au-delà des limites de 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.

En cas d’échec, CcPinRead déclenche une exception status pour cet échec particulier. Par exemple, si un échec d’allocation de pool se produit, CcPinRead déclenche une exception STATUS_INSUFFICIENT_RESOURCES ; si une erreur d’E/S se produit, CcPinRead déclenche la status exception de l’erreur d’E/S. Par conséquent, pour contrôler si une défaillance se produit, le pilote doit encapsuler l’appel à CcPinRead 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.