CcPinRead, fonction (ntifs.h)

Article
12/21/2024

Le CcPinRead routine é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 en mémoire.

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’octets 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 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. 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.

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

[out] Buffer

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

Valeur de retour

CcPinRead retourne TRUE si les données du fichier mis en cache ont été épinglées et lues correctement, FALSE autrement.

Remarques

Si l’indicateur de 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 de 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 ne sont pas sensées.

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

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

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

CcPinRead 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.

Si une défaillance se produit, CcPinRead déclenche une exception d’état pour cet échec particulier. Par exemple, si un échec d’allocation de pool se produit, CcPinRead déclenche une exception de STATUS_INSUFFICIENT_RESOURCES ; si une erreur d’E/S se produit, CcPinRead 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 à CcPinRead dans une instruction 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.