MapViewOfFile-Funktion (memoryapi.h)
Ordnet eine Ansicht einer Dateizuordnung dem Adressraum eines Aufrufvorgangs zu.
Verwenden Sie die MapViewOfFileEx--Funktion, um eine vorgeschlagene Basisadresse für die Ansicht anzugeben. Diese Vorgehensweise wird jedoch nicht empfohlen.
Syntax
LPVOID MapViewOfFile(
[in] HANDLE hFileMappingObject,
[in] DWORD dwDesiredAccess,
[in] DWORD dwFileOffsetHigh,
[in] DWORD dwFileOffsetLow,
[in] SIZE_T dwNumberOfBytesToMap
);
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. |
|
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. |
|
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. Hinweis: Unter Betriebssystemversionen vor Windows 10, Version 1703, hat das FILE_MAP_LARGE_PAGES Flag keine Auswirkung. In diesen Versionen wird die Ansicht automatisch mit großen Seiten zugeordnet, wenn der Abschnitt mit dem SEC_LARGE_PAGES Flag festgelegt wurde. |
|
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
Eine hohe Reihenfolge DWORD- des Dateioffsets, in dem die Ansicht beginnt.
[in] dwFileOffsetLow
Eine 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 virtuellen Speicherzuweisung des Systems übereinstimmen. Das heißt, der Offset muss ein Vielfaches der VirtualAlloc-Zuordnungs granularität sein. Um die Granularität der VirtualAlloc-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 der 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.
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 einer 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. Nach Abschluss der ersten Ansicht können Sie die Zuordnung aufheben und eine neue Ansicht zuordnen.
Verwenden Sie zum Abrufen der Größe einer Ansicht die VirtualQuery-Funktion.
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 von jedem Dateizuordnungsobjekt abgeleitet werden, das von derselben Datei unterstützt wird. 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 MapViewOfFile 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, dass sie mit einer Datei kohärent ist, auf die über die ReadFile- oder WriteFile--Funktion zugegriffen wird.
Speichern Sie keine Zeiger in der zugeordneten Speicherdatei. Speichern Sie Offsets aus der Basis der Dateizuordnung, sodass die Zuordnung an einer beliebigen Adresse verwendet werden kann.
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.
Wenn ein Dateizuordnungsobjekt von der Auslagerungsdatei unterstützt wird (CreateFileMapping aufgerufen wird, wobei der hFile Parameter auf INVALID_HANDLE_VALUEfestgelegt ist), muss die Pagingdatei groß genug sein, um die gesamte Zuordnung zu speichern. Ist dies nicht der Fehler, schlägt MapViewOfFile- fehl. Der anfängliche Inhalt der Seiten in einem Dateizuordnungsobjekt, das von der Auslagerungsdatei unterstützt wird, ist 0 (null).
Wenn ein Dateizuordnungsobjekt erstellt wird, das von der Auslagerungsdatei unterstützt wird, kann der Aufrufer angeben, ob MapViewOfFile- Seiten gleichzeitig reservieren und übernehmen soll (SEC_COMMIT) oder einfach Seiten reservieren (SEC_RESERVE). Die Zuordnung der Datei macht den gesamten zugeordneten virtuellen Adressbereich für andere Zuordnungen im Prozess nicht verfügbar. Nachdem eine Seite aus dem reservierten Bereich zugesichert wurde, kann sie nicht durch Aufrufen von VirtualFreefreigegeben oder dekommissioniert werden. Reservierte und zugesicherte Seiten werden freigegeben, wenn die Ansicht nicht zugeordnet ist und das Dateizuordnungsobjekt geschlossen wird. Ausführliche Informationen finden Sie in den funktionen UnmapViewOfFile- und CloseHandle-.
Damit eine Datei mit ausführbaren Berechtigungen vorhanden ist, muss eine Anwendung CreateFileMapping- entweder mit PAGE_EXECUTE_READWRITE oder PAGE_EXECUTE_READaufrufen und dann MapViewOfFile- 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 |
Wenn CSVFs angehalten werden, schlägt dieser Aufruf möglicherweise mit einem Fehler fehl, der angibt, dass ein Sperrkonflikt vorliegt.
Beispiele
Ein Beispiel finden Sie unter Creating Named Shared Memory.
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 |