Fonction CcMapData (ntifs.h)

Article
12/21/2024

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

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 de 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’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 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 résident déjà en mémoire doivent être mappées.

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

Attendre

Défini sur TRUE si l’appelant peut être placé dans un état d’attente jusqu’à ce que les données aient été mappées, FALSE sinon.

[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 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 mappées.

Valeur de retour

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

Remarques

CcMapData mappe les données dans un fichier mis en cache pour l’accès en lecture. Notez qu’après CcMapData est appelée, les données sont mappées ; mais ce 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, CcPinReadou 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 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 mappées ne peuvent pas couvrir plus d’une vue de 256 Ko. Par conséquent, la plus grande région qui peut être mappée est de 256 Ko, en commençant par un décalage aligné sur 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 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 pager les pages physiques en fonction de la demande de mémoire du système.

Si l’indicateur de MAP_WAIT est défini (ou si d’attente est 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 d’attente est false) et que les données ne peuvent pas être mappées immédiatement, CcMapData retourne FALSE.

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

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

Pour mettre en cache un fichier, utilisez CcInitializeCacheMap.