MapViewOfFileEx, fonction (memoryapi.h)

Article
11/12/2024

Mappe une vue d’un mappage de fichiers dans l’espace d’adressage d’un processus appelant. Un appelant peut éventuellement spécifier une adresse de mémoire de base suggérée pour la vue.

Pour spécifier le nœud NUMA pour la mémoire physique, consultez MapViewOfFileExNuma.

Syntaxe

LPVOID MapViewOfFileEx(
  [in]           HANDLE hFileMappingObject,
  [in]           DWORD  dwDesiredAccess,
  [in]           DWORD  dwFileOffsetHigh,
  [in]           DWORD  dwFileOffsetLow,
  [in]           SIZE_T dwNumberOfBytesToMap,
  [in, optional] LPVOID lpBaseAddress
);

Paramètres

[in] hFileMappingObject

Handle d’un objet de mappage de fichiers. Les fonctions CreateFileMapping et OpenFileMapping retournent ce handle.

[in] dwDesiredAccess

Type d’accès à un objet de mappage de fichiers, qui détermine la protection des pages. Ce paramètre peut être l’une des valeurs suivantes, ou une combinaison OR au niveau du bit de plusieurs valeurs, le cas échéant.

Valeur	Signification
FILE_MAP_ALL_ACCESS	Une vue en lecture/écriture du fichier est mappée. L’objet de mappage de fichiers doit avoir été créé avec PAGE_READWRITE ou PAGE_EXECUTE_READWRITE protection. Lorsqu’elle est utilisée avec la fonction MapViewOfFileEx, FILE_MAP_ALL_ACCESS équivaut à FILE_MAP_WRITE.
FILE_MAP_READ	Une vue en lecture seule du fichier est mappée. Une tentative d’écriture dans la vue de fichier entraîne une violation d’accès. L’objet de mappage de fichiers doit avoir été créé avec PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE_READou PAGE_EXECUTE_READWRITE protection.
FILE_MAP_WRITE	Une vue en lecture/écriture du fichier est mappée. L’objet de mappage de fichiers doit avoir été créé avec PAGE_READWRITE ou PAGE_EXECUTE_READWRITE protection. Lorsqu’il est utilisé avec MapViewOfFileEx, (FILE_MAP_WRITE \| FILE_MAP_READ) et FILE_MAP_ALL_ACCESS sont équivalents à FILE_MAP_WRITE.

À l’aide d’or au niveau du bit, vous pouvez combiner les valeurs ci-dessus avec ces valeurs.

Valeur	Signification
FILE_MAP_COPY	Une vue de copie en écriture du fichier est mappée. L’objet de mappage de fichiers doit avoir été créé avec PAGE_READONLY, PAGE_EXECUTE_READ, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITEou PAGE_EXECUTE_READWRITE protection. Lorsqu’un processus écrit dans une page de copie en écriture, le système copie la page d’origine vers une nouvelle page privée dans le processus. La nouvelle page est sauvegardée par le fichier de pagination. Protection des modifications apportées à la nouvelle page de la copie en écriture en lecture-écriture. Lorsque l’accès en copie en écriture est spécifié, le système et le processus sont facturés pour l’ensemble de l’affichage, car le processus appelant peut potentiellement écrire dans chaque page de l’affichage, ce qui rend toutes les pages privées. Le contenu de la nouvelle page n’est jamais réécrit dans le fichier d’origine et est perdu lorsque la vue n’est pas mappée.
FILE_MAP_LARGE_PAGES	À compter de Windows 10, version 1703, cet indicateur spécifie que la vue doit être mappée à l’aide de prise en charge des grandes pages. La taille de la vue doit être un multiple de la taille d’une grande page signalée par la fonction GetLargePageMinimum, et l’objet de mappage de fichiers doit avoir été créé à l’aide de l’option SEC_LARGE_PAGES. Si vous fournissez une valeur non null pour lpBaseAddress, la valeur doit être un multiple de GetLargePageMinimum.
FILE_MAP_EXECUTE	Une vue exécutable du fichier est mappée (la mémoire mappée peut être exécutée en tant que code). L’objet de mappage de fichiers doit avoir été créé avec PAGE_EXECUTE_READ, PAGE_EXECUTE_WRITECOPYou PAGE_EXECUTE_READWRITE protection. Windows Server 2003 et Windows XP : Cette valeur est disponible à partir de Windows XP avec SP2 et Windows Server 2003 avec SP1.
FILE_MAP_TARGETS_INVALID	Définit tous les emplacements du fichier mappé comme cibles non valides pour Control Flow Guard (CFG). Cet indicateur est similaire à PAGE_TARGETS_INVALID. Utilisez cet indicateur en combinaison avec le droit d’accès d’exécution FILE_MAP_EXECUTE. Tout appel indirect à des emplacements dans ces pages échouera les vérifications CFG et le processus sera arrêté. Le comportement par défaut des pages exécutables allouées doit être marqué comme cibles d’appel valides pour CFG.

Pour les objets de mappage de fichiers créés avec l’attribut SEC_IMAGE, le paramètre dwDesiredAccess n’a aucun effet et doit être défini sur n’importe quelle valeur valide telle que FILE_MAP_READ.

Pour plus d’informations sur l’accès aux objets de mappage de fichiers, consultez sécurité de mappage de fichiers et droits d’accès.

[in] dwFileOffsetHigh

L’ordre élevé DWORD du décalage de fichier où l’affichage doit commencer.

[in] dwFileOffsetLow

L’ordre faible DWORD du décalage de fichier où la vue doit commencer. La combinaison des décalages élevés et faibles doit spécifier un décalage dans le mappage de fichiers. Ils doivent également correspondre à la granularité d’allocation de mémoire du système. Autrement dit, le décalage doit être un multiple de la granularité d’allocation. Pour obtenir la granularité d’allocation de mémoire du système, utilisez la fonction GetSystemInfo, qui remplit les membres d’une structure SYSTEM_INFO.

[in] dwNumberOfBytesToMap

Nombre d’octets d’un mappage de fichiers à mapper à une vue. Tous les octets doivent être au sein de la taille maximale spécifiée par CreateFileMapping. Si ce paramètre est égal à 0 (zéro), le mappage s’étend du décalage spécifié à la fin du mappage de fichiers.

[in, optional] lpBaseAddress

Pointeur vers l’adresse mémoire dans l’espace d’adressage du processus appelant où le mappage commence. Il doit s’agir d’un multiple de la granularité d’allocation de mémoire du système, ou la fonction échoue. Pour déterminer la granularité d’allocation de mémoire du système, utilisez la fonction GetSystemInfo. S’il n’y a pas suffisamment d’espace d’adressage à l’adresse spécifiée, la fonction échoue.

Si lpBaseAddress est NULL, le système d’exploitation choisit l’adresse de mappage. Dans ce scénario, la fonction est équivalente à la fonction MapViewOfFile.

Bien qu’il soit possible de spécifier une adresse sécurisée maintenant (non utilisée par le système d’exploitation), il n’existe aucune garantie que l’adresse restera sécurisée au fil du temps. Par conséquent, il est préférable de laisser le système d’exploitation choisir l’adresse. Dans ce cas, vous ne stockez pas de pointeurs dans le fichier mappé en mémoire, vous devez stocker les décalages de la base du mappage de fichiers afin que le mappage puisse être utilisé à n’importe quelle adresse.

Valeur de retour

Si la fonction réussit, la valeur de retour est l’adresse de départ de la vue mappée.

Si la fonction échoue, la valeur de retour est NULL . Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

Le mappage d’un fichier rend la partie spécifiée du fichier visible dans l’espace d’adressage du processus appelant.

Pour les fichiers dont la taille est supérieure à l’espace d’adressage, vous ne pouvez mapper qu’une petite partie des données de fichier à la fois. Une fois la première vue terminée, vous l’annulez et mappez une nouvelle vue.

Pour obtenir la taille d’une vue, utilisez la fonction VirtualQueryEx.

Le contenu initial des pages d’un objet de mappage de fichiers soutenu par le fichier de page est 0 (zéro).

En règle générale, l’adresse suggérée est utilisée pour spécifier qu’un fichier doit être mappé à la même adresse dans plusieurs processus. Cela nécessite que la région de l’espace d’adressage soit disponible dans tous les processus impliqués. Aucune autre allocation de mémoire ne peut se produire dans la région utilisée pour le mappage, y compris l’utilisation de la VirtualAlloc ou fonction VirtualAllocEx pour réserver de la mémoire.

Si le paramètre lpBaseAddress spécifie un décalage de base, la fonction réussit si la région de mémoire spécifiée n’est pas déjà utilisée par le processus appelant. Le système ne garantit pas que la même région de mémoire est disponible pour le fichier mappé en mémoire dans d’autres processus 32 bits.

Plusieurs vues d’un fichier (ou d’un objet de mappage de fichiers et de son fichier mappé) sont cohérentes s’ils contiennent des données identiques à un moment spécifié. Cela se produit si les vues de fichiers sont dérivées du même objet de mappage de fichiers. Un processus peut dupliquer un handle d’objet de mappage de fichiers dans un autre processus à l’aide de la fonction DuplicateHandle , ou un autre processus peut ouvrir un objet de mappage de fichiers par nom à l’aide de la fonction OpenFileMapping.

À une exception importante, les vues de fichiers dérivées d’un objet de mappage de fichiers soutenu par le même fichier sont cohérentes ou identiques à un moment spécifique. La cohérence est garantie pour les vues au sein d’un processus et pour les vues mappées par différents processus.

L’exception est liée aux fichiers distants. Bien que MapViewOfFileEx fonctionne avec des fichiers distants, il ne les maintient pas cohérents. Par exemple, si deux ordinateurs mappent un fichier en écriture et modifient la même page, chaque ordinateur ne voit que ses propres écritures dans la page. Lorsque les données sont mises à jour sur le disque, elles ne sont pas fusionnées.

Une vue mappée d’un fichier n’est pas garantie d’être cohérente avec un fichier accessible par l'ReadFile ou fonction WriteFile.

Pour vous protéger contre les exceptions EXCEPTION_IN_PAGE_ERROR, utilisez la gestion des exceptions structurées pour protéger tout code qui écrit ou lit à partir d’une vue mappée en mémoire d’un fichier autre que le fichier de page. Pour plus d’informations, consultez lecture et écriture à partir d’une vue de fichier.

Lors de la modification d’un fichier via une vue mappée, le dernier horodatage de modification peut ne pas être mis à jour automatiquement. Si nécessaire, l’appelant doit utiliser SetFileTime pour définir l’horodatage.

Pour disposer d’un fichier disposant d’autorisations exécutables, une application doit appeler CreateFileMapping avec PAGE_EXECUTE_READWRITE ou PAGE_EXECUTE_READ, puis appeler MapViewOfFileEx avec FILE_MAP_EXECUTE | FILE_MAP_WRITE ou FILE_MAP_EXECUTE | FILE_MAP_READ.

Dans Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Supporté
Protocole SMB (Server Message Block) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Oui
Cluster Shared Volume File System (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	memoryapi.h (include Windows.h, Memoryapi.h)
bibliothèque	onecore.lib
DLL	Kernel32.dll