MapViewOfFileEx-Funktion (memoryapi.h)
Ordnet eine Ansicht einer Dateizuordnung dem Adressraum eines Aufrufvorgangs zu. Ein Aufrufer kann optional eine vorgeschlagene Basisspeicheradresse für die Ansicht angeben.
Informationen zum Angeben des NUMA-Knotens für den physischen Speicher finden Sie unter MapViewOfFileExNuma.
Syntax
LPVOID MapViewOfFileEx(
[in] HANDLE hFileMappingObject,
[in] DWORD dwDesiredAccess,
[in] DWORD dwFileOffsetHigh,
[in] DWORD dwFileOffsetLow,
[in] SIZE_T dwNumberOfBytesToMap,
[in, optional] LPVOID lpBaseAddress
);
Parameter
[in] hFileMappingObject
Ein Handle zu einem Dateizuordnungsobjekt. Die CreateFileMapping und OpenFileMapping Funktionen geben dieses Handle zurück.
[in] dwDesiredAccess
Der Typ des Zugriffs auf ein Dateizuordnungsobjekt, das den Seitenschutz der Seiten bestimmt. Bei diesem Parameter kann es sich um einen der folgenden Werte oder um eine bitweise ODER Kombination aus mehreren Werten handeln.
Mit bitweisem OR können Sie die oben genannten Werte mit diesen Werten kombinieren.
| Wert | Bedeutung |
|---|---|
|
Eine Kopier-on-Write-Ansicht der Datei wird zugeordnet. Das Dateizuordnungsobjekt muss mit PAGE_READONLY, PAGE_EXECUTE_READ, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITEoder PAGE_EXECUTE_READWRITE Schutz erstellt worden sein.
Wenn ein Prozess auf eine Kopie-on-Write-Seite schreibt, kopiert das System die ursprüngliche Seite auf eine neue Seite, die für den Prozess privat ist. Die neue Seite wird von der Auslagerungsdatei unterstützt. Der Schutz der neuen Seite ändert sich von "Kopieren beim Schreiben" in "Lese-/Schreibzugriff". Wenn der Schreibzugriff auf Kopieren angegeben ist, wird das System und der Prozess für die gesamte Ansicht übernommen, da der Aufrufvorgang potenziell auf jede Seite in der Ansicht schreiben kann, wodurch alle Seiten privat sind. Der Inhalt der neuen Seite wird nie wieder in die Originaldatei geschrieben und geht verloren, wenn die Ansicht nicht zugeordnet ist. |
|
Ab Windows 10, Version 1703, gibt dieses Flag 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 lpBaseAddressangeben, muss der Wert ein Vielfaches von GetLargePageMinimumsein. |
|
Eine ausführbare Ansicht der Datei ist zugeordnet (zugeordneter Speicher kann als Code ausgeführt werden). Das Dateizuordnungsobjekt muss mit PAGE_EXECUTE_READ, PAGE_EXECUTE_WRITECOPYoder PAGE_EXECUTE_READWRITE Schutz erstellt worden sein.
Windows Server 2003 und Windows XP: Dieser Wert ist ab Windows XP mit SP2 und Windows Server 2003 mit SP1 verfügbar. |
|
Legt alle Speicherorte in der zugeordneten Datei als ungültige Ziele für Control Flow Guard (CFG) fest. Diese Kennzeichnung ähnelt PAGE_TARGETS_INVALID. Verwenden Sie dieses Kennzeichen in Kombination mit der Ausführungsberechtigung FILE_MAP_EXECUTE. Alle indirekten Aufrufe an Speicherorte auf diesen Seiten schlagen CFG-Prüfungen fehl, und der Vorgang wird beendet. Das Standardverhalten für zugeordnete ausführbare Seiten besteht darin, gültige Anrufziele für CFG zu markieren. |
Für dateizuordnungsobjekte, die mit dem attribut SEC_IMAGE erstellt wurden, hat der dwDesiredAccess Parameter keine Auswirkung und sollte auf einen beliebigen gültigen Wert wie FILE_MAP_READfestgelegt werden.
Weitere Informationen zum Zugriff auf Dateizuordnungsobjekte finden Sie unter Dateizuordnungssicherheit und Zugriffsberechtigungen.
[in] dwFileOffsetHigh
Die hohe Reihenfolge DWORD- des Dateioffsets, in dem die Ansicht beginnen soll.
[in] dwFileOffsetLow
Die niedrige Reihenfolge DWORD- des Dateioffsets, in dem die Ansicht beginnen soll. Die Kombination der hohen und niedrigen Offsets muss einen Offset innerhalb der Dateizuordnung angeben. Sie müssen auch mit der Granularität der Speicherzuweisung des Systems übereinstimmen. Das heißt, der Offset muss ein Vielfaches der Zuordnungs granularität sein. Um die Granularität der Speicherzuweisung des Systems zu erhalten, verwenden Sie die GetSystemInfo--Funktion, die die Member einer SYSTEM_INFO-Struktur ausfüllt.
[in] dwNumberOfBytesToMap
Die Anzahl der Bytes einer Dateizuordnung, die einer Ansicht zugeordnet werden soll. Alle Bytes müssen sich innerhalb der maximalen Größe befinden, die durch CreateFileMappingangegeben wird. Wenn dieser Parameter 0 (null) ist, erstreckt sich die Zuordnung vom angegebenen Offset bis zum Ende der Dateizuordnung.
[in, optional] lpBaseAddress
Ein Zeiger auf die Speicheradresse im Adressraum des aufrufenden Prozesses, in dem die Zuordnung beginnt. Dies muss ein Vielfaches der Speicherzuweisungs granularität des Systems sein, oder die Funktion schlägt fehl. Verwenden Sie die GetSystemInfo-Funktion, um die Granularität der Speicherzuweisung des Systems zu ermitteln. Wenn nicht genügend Adressraum an der angegebenen Adresse vorhanden ist, schlägt die Funktion fehl.
Wenn lpBaseAddressNULL-ist, wählt das Betriebssystem die Zuordnungsadresse aus. In diesem Szenario entspricht die Funktion der MapViewOfFile--Funktion.
Obwohl es möglich ist, eine Adresse anzugeben, die jetzt sicher ist (nicht vom Betriebssystem verwendet), gibt es keine Garantie dafür, dass die Adresse im Laufe der Zeit sicher bleibt. Daher ist es besser, das Betriebssystem die Adresse auswählen zu lassen. In diesem Fall würden Sie keine Zeiger in der zugeordneten Speicherdatei speichern, Sie würden Offsets von der Basis der Dateizuordnung speichern, sodass die Zuordnung an jeder Adresse verwendet werden kann.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Startadresse der zugeordneten Ansicht.
Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
Durch die Zuordnung einer Datei wird der angegebene Teil der Datei im Adressraum des aufrufenden Prozesses sichtbar.
Bei Dateien, die größer als der Adressraum sind, können Sie nur einen kleinen Teil der Dateidaten gleichzeitig zuordnen. Wenn die erste Ansicht abgeschlossen ist, heben Sie die Zuordnung auf, und ordnen Sie eine neue Ansicht zu.
Um die Größe einer Ansicht abzurufen, verwenden Sie die VirtualQueryEx--Funktion.
Der anfängliche Inhalt der Seiten in einem Dateizuordnungsobjekt, das von der Seitendatei unterstützt wird, ist 0 (null).
In der Regel wird die vorgeschlagene Adresse verwendet, um anzugeben, dass eine Datei an derselben Adresse in mehreren Prozessen zugeordnet werden soll. Dazu muss die Region des Adressraums in allen beteiligten Prozessen verfügbar sein. Es kann keine andere Speicherzuweisung in der Region erfolgen, die für die Zuordnung verwendet wird, einschließlich der Verwendung der VirtualAlloc- oder VirtualAllocEx--Funktion, um Arbeitsspeicher zu reservieren.
Wenn der parameter lpBaseAddress einen Basisoffset angibt, wird die Funktion erfolgreich ausgeführt, wenn der angegebene Speicherbereich nicht bereits vom aufrufenden Prozess verwendet wird. Das System stellt nicht sicher, dass derselbe Speicherbereich für die zugeordnete Speicherdatei in anderen 32-Bit-Prozessen verfügbar ist.
Mehrere Ansichten einer Datei (oder eines Dateizuordnungsobjekts und der zugeordneten Datei) werden kohärente, wenn sie identische Daten zu einem bestimmten Zeitpunkt enthalten. Dies tritt auf, wenn die Dateiansichten vom gleichen Dateizuordnungsobjekt abgeleitet werden. Ein Prozess kann ein Dateizuordnungsobjekthandle in einen anderen Prozess duplizieren, indem die DuplicateHandle--Funktion verwendet wird, oder ein anderer Prozess kann ein Dateizuordnungsobjekt anhand des Namens mithilfe der OpenFileMapping--Funktion öffnen.
Mit einer wichtigen Ausnahme sind Dateiansichten, die von jedem Dateizuordnungsobjekt abgeleitet werden, das von derselben Datei unterstützt wird, kohärent oder identisch zu einem bestimmten Zeitpunkt. Die Kohärenz ist für Ansichten innerhalb eines Prozesses und für Ansichten gewährleistet, die von verschiedenen Prozessen zugeordnet werden.
Die Ausnahme bezieht sich auf Remotedateien. Obwohl MapViewOfFileEx- mit Remotedateien funktioniert, bleiben sie nicht kohärent. Wenn beispielsweise zwei Computer eine Datei als schreibbar zuordnen und beide die gleiche Seite ändern, sieht jeder Computer nur eigene Schreibvorgänge auf der Seite. Wenn die Daten auf dem Datenträger aktualisiert werden, wird sie nicht zusammengeführt.
Eine zugeordnete Ansicht einer Datei ist nicht garantiert mit einer Datei, auf die von der ReadFile- oder WriteFile--Funktion zugegriffen wird, nicht kohärent.
Um vor EXCEPTION_IN_PAGE_ERROR Ausnahmen zu schützen, verwenden Sie die strukturierte Ausnahmebehandlung, um Code zu schützen, der in eine speicherzuordnunge Ansicht einer anderen Datei als der Seitendatei schreibt oder liest. Weitere Informationen finden Sie unter Lesen und Schreiben aus einer Dateiansicht.
Beim Ändern einer Datei über eine zugeordnete Ansicht wird der Zeitstempel der letzten Änderung möglicherweise nicht automatisch aktualisiert. Bei Bedarf sollte der Aufrufer SetFileTime- verwenden, um den Zeitstempel festzulegen.
Um über eine Datei mit ausführbaren Berechtigungen zu verfügen, muss eine Anwendung CreateFileMapping- mit PAGE_EXECUTE_READWRITE oder PAGE_EXECUTE_READaufrufen und dann MapViewOfFileEx- mit FILE_MAP_EXECUTE | FILE_MAP_WRITE oder FILE_MAP_EXECUTE | FILE_MAP_READaufrufen.
In Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.
| Technologie | Abgestützt |
|---|---|
| Server Message Block (SMB) 3.0-Protokoll | Ja |
| SMB 3.0 Transparent Failover (TFO) | Ja |
| SMB 3.0 mit Skalierungsdateifreigaben (SO) | Ja |
| Freigegebenes Clustervolumedateisystem (CsvFS) | Ja |
| Resilient File System (ReFS) | Ja |
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | memoryapi.h (include Windows.h, Memoryapi.h) |
| Library | onecore.lib |
| DLL- | Kernel32.dll |