MapViewOfFile3-Funktion (memoryapi.h)

Artikel
06/27/2024

Ordnet eine Ansicht einer Datei oder eines pagefile-gesicherten Abschnitts dem Adressraum des angegebenen Prozesses zu.

Syntax

PVOID MapViewOfFile3(
  [in]                HANDLE                 FileMapping,
  [in]                HANDLE                 Process,
  [in, optional]      PVOID                  BaseAddress,
  [in]                ULONG64                Offset,
  [in]                SIZE_T                 ViewSize,
  [in]                ULONG                  AllocationType,
  [in]                ULONG                  PageProtection,
  [in, out, optional] MEM_EXTENDED_PARAMETER *ExtendedParameters,
  [in]                ULONG                  ParameterCount
);

Parameter

[in] FileMapping

Ein HANDLE einem Abschnitt, der dem Adressraum des angegebenen Prozesses zugeordnet werden soll.

[in] Process

Ein HANDLE einem Prozess, dem der Abschnitt zugeordnet wird.

[in, optional] BaseAddress

Die gewünschte Basisadresse der Ansicht (die Adresse wird auf die nächste Grenze von 64k aufgerundet).

Wenn dieser Parameter NULL-ist, wählt das System die Basisadresse aus.

Wenn BaseAddress- nicht NULL-ist, müssen alle bereitgestellten MEM_ADDRESS_REQUIREMENTS aus allen Nullen bestehen.

[in] Offset

Der Offset vom Anfang des Abschnitts.

Der Offset muss 64k ausgerichtet sein.

[in] ViewSize

Die Anzahl der zuzuordnenden Bytes. Ein Wert von Null (0) gibt an, dass der gesamte Abschnitt zugeordnet werden soll.

Die Größe muss immer ein Vielfaches der Seitengröße sein.

[in] AllocationType

Der Typ der Speicherzuweisung. Dieser Parameter kann null (0) oder einer der folgenden Werte sein.

Wert	Bedeutung
MEM_RESERVE 0x00002000	Ordnet eine reservierte Ansicht zu.
MEM_REPLACE_PLACEHOLDER 0x00004000	Ersetzt einen Platzhalter durch eine zugeordnete Ansicht. Es werden nur Daten-/Pf-gesicherte Abschnittsansichten unterstützt (keine Bilder, physischen Arbeitsspeicher usw.). Wenn Sie einen Platzhalter ersetzen, müssen BaseAddress- und ViewSize- genau mit denen des Platzhalters übereinstimmen, und alle bereitgestellten MEM_ADDRESS_REQUIREMENTS Struktur müssen aus allen Nullen bestehen. Nachdem Sie einen Platzhalter durch eine zugeordnete Ansicht ersetzt haben, sehen Sie den UnmapFlags Parameter von UnmapOfFileEx und UnmapViewOfFile2-. Ein Platzhalter ist ein Typ des reservierten Speicherbereichs. Die 64k-Ausrichtungsanforderungen für Offset- und BaseAddress- gelten nicht, wenn dieses Flag angegeben wird.
MEM_LARGE_PAGES 0x20000000	Ordnet eine große Seitenansicht zu. Dieses Flag gibt an, dass die Ansicht mithilfe Unterstützung für große Seitenzugeordnet werden soll. Die Größe der Ansicht muss ein Vielfaches der Größe einer großen Seite sein, die vom GetLargePageMinimum-Funktion gemeldet wird, und das Dateizuordnungsobjekt muss mithilfe der Option SEC_LARGE_PAGES erstellt worden sein. Wenn Sie einen Wert ungleich NULL für den BaseAddress--Parameter angeben, muss der Wert ein Vielfaches von GetLargePageMinimumsein.

Wert

Bedeutung

MEM_RESERVE
0x00002000

Ordnet eine reservierte Ansicht zu.

MEM_REPLACE_PLACEHOLDER
0x00004000

Ersetzt einen Platzhalter durch eine zugeordnete Ansicht. Es werden nur Daten-/Pf-gesicherte Abschnittsansichten unterstützt (keine Bilder, physischen Arbeitsspeicher usw.). Wenn Sie einen Platzhalter ersetzen, müssen BaseAddress- und ViewSize- genau mit denen des Platzhalters übereinstimmen, und alle bereitgestellten MEM_ADDRESS_REQUIREMENTS Struktur müssen aus allen Nullen bestehen.

Nachdem Sie einen Platzhalter durch eine zugeordnete Ansicht ersetzt haben, sehen Sie den UnmapFlags Parameter von UnmapOfFileEx und UnmapViewOfFile2-.

Ein Platzhalter ist ein Typ des reservierten Speicherbereichs.

Die 64k-Ausrichtungsanforderungen für Offset- und BaseAddress- gelten nicht, wenn dieses Flag angegeben wird.

MEM_LARGE_PAGES
0x20000000

Ordnet eine große Seitenansicht zu. Dieses Flag gibt an, dass die Ansicht mithilfe Unterstützung für große Seitenzugeordnet werden soll. Die Größe der Ansicht muss ein Vielfaches der Größe einer großen Seite sein, die vom GetLargePageMinimum-Funktion gemeldet wird, und das Dateizuordnungsobjekt muss mithilfe der Option SEC_LARGE_PAGES erstellt worden sein. Wenn Sie einen Wert ungleich NULL für den BaseAddress--Parameter angeben, muss der Wert ein Vielfaches von GetLargePageMinimumsein.

[in] PageProtection

Der gewünschte Seitenschutz.

Für dateizuordnungsobjekte, die mit dem attribut SEC_IMAGE erstellt wurden, hat der PageProtection Parameter keine Auswirkung und sollte auf einen beliebigen gültigen Wert wie PAGE_READONLYfestgelegt werden.

[in, out, optional] ExtendedParameters

Ein optionaler Zeiger auf einen oder mehrere erweiterte Parameter vom Typ MEM_EXTENDED_PARAMETER. Jeder dieser erweiterten Parameterwerte kann selbst ein Type-Feld von entweder MemExtendedParameterAddressRequirements oder MemExtendedParameterNumaNodehaben. Wenn kein MemExtendedParameterNumaNode erweiterter Parameter bereitgestellt wird, ist das Verhalten identisch mit den Funktionen VirtualAlloc/MapViewOfFile (d. a. der bevorzugte NUMA-Knoten für die physischen Seiten wird basierend auf dem idealen Prozessor des Threads bestimmt, der zuerst auf den Speicher zugreift).

[in] ParameterCount

Die Anzahl der erweiterten Parameter, auf die durch ExtendedParametersverwiesen wird.

Rückgabewert

Gibt die Basisadresse der zugeordneten Ansicht zurück, wenn dies erfolgreich ist. Andernfalls wird NULL- zurückgegeben, und der erweiterte Fehlerstatus ist mit GetLastError-verfügbar.

Bemerkungen

Diese API unterstützt leistungsstarke Spiele und Serveranwendungen, die spezielle Anforderungen hinsichtlich der Verwaltung des virtuellen Adressraums haben. Beispiel: Zuordnen des Speichers über einem zuvor reservierten Bereich; Dies ist nützlich für die Implementierung eines automatisch umbrochenen Ringpuffers. Und das Zuordnen des Speichers mit einer bestimmten Ausrichtung; Um ihre Anwendung z. B. das Commit großer/riesiger seitenzuordnunger Regionen bei Bedarf zu ermöglichen.

Mit dieser Funktion für neue Zuordnungen können Sie folgende Aktionen ausführen:

Angeben eines Bereichs des virtuellen Adressraums und einer Power-of-2-Ausrichtungseinschränkung
Angeben einer beliebigen Anzahl erweiterter Parameter
Angeben eines bevorzugten NUMA-Knotens für den physischen Speicher als erweiterter Parameter
geben Sie einen Platzhaltervorgang an (insbesondere ersetzung).

Informationen zum Angeben des NUMA-Knotens finden Sie unter ExtendedParameters Parameter.

Beispiele

Ein Codebeispiel finden Sie unter Szenario 1 in VirtualAlloc2.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 10, Version 1803 [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2016 [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	memoryapi.h (include Windows.h)
Library	onecore.lib
DLL-	Kernel32.dll