Fonction CcMapData (ntifs.h)

Article
08/07/2023

La routine CcMapData mappe une plage d’octets spécifiée d’un fichier mis en cache à une mémoire tampon en mémoire tampon.

Syntaxe

BOOLEAN CcMapData(
  [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 fichier pour le fichier dont les données doivent être mappées pour l’accès en lecture.

[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 de mappage doit être effectuée. Il s’agit d’une combinaison OR au niveau du bit d’une ou plusieurs des valeurs suivantes :

Valeur	Signification
MAP_WAIT	L’appelant peut être placé dans un état d’attente jusqu’à ce que les données soient mappées.
MAP_NO_READ	Seules les pages qui sont déjà en mémoire doivent être mappées.

Note Dans Windows 2000et les versions antérieures, ce paramètre était une valeur BOOLEAN nommée Wait :

Wait

Définissez sur TRUE si l’appelant peut être placé dans un état d’attente jusqu’à ce que les données soient mappées ; FALSE dans le cas contraire.

[out] Bcb

Lors du premier appel, cela retourne un pointeur vers une structure de 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 mappées.

Valeur retournée

CcMapData retourne TRUE si les données du fichier mis en cache ont été correctement mappées, false dans le cas contraire.

Remarques

CcMapData mappe les données dans un fichier mis en cache pour l’accès en lecture. Notez qu’après l’appel de CcMapData , les données sont mappées ; mais il n’est pas épinglé. Cette distinction est importante. Les données mappées mais non épinglées ne peuvent pas être modifiées en toute sécurité. Pour épingler les données, utilisez CcPinMappedData, CcPinRead ou CcPreparePinWrite.

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

CcMapData ne peut pas mapper 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 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 mappées ne peuvent pas s’étendre sur plus d’une vue de 256 Ko. Par conséquent, la plus grande région pouvant être mappée est de 256 Ko, à partir d’un décalage aligné de 256 Ko dans le fichier.

Le mappage 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 mappé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 paginer les pages physiques en fonction de la demande de mémoire du système.

Si l’indicateur MAP_WAIT est défini (ou si Wait a la valeur TRUE), CcMapData est garanti pour terminer la demande de mappage et retourner TRUE. Si les pages requises du fichier mis en cache résident déjà en mémoire, les données sont mappé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 mappées. Si l’indicateur MAP_WAIT n’est pas défini (ou si Wait a la valeur FALSE) et que les données ne peuvent pas être mappées immédiatement, CcMapData retourne FALSE.

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

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

Pour mettre en cache un fichier, utilisez CcInitializeCacheMap.