CreateFileMappingFromApp-Funktion (memoryapi.h)

Artikel
08/24/2023

Erstellt oder öffnet ein benanntes oder unbenannte Dateizuordnungsobjekt für eine angegebene Datei aus einer Windows Store-App.

Syntax

HANDLE CreateFileMappingFromApp(
  [in]           HANDLE               hFile,
  [in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
  [in]           ULONG                PageProtection,
  [in]           ULONG64              MaximumSize,
  [in, optional] PCWSTR               Name
);

Parameter

[in] hFile

Ein Handle für die Datei, aus der ein Dateizuordnungsobjekt erstellt werden soll.

Die Datei muss mit Zugriffsrechten geöffnet werden, die mit den Vom flProtect-Parameter angegebenen Schutzflags kompatibel sind. Es ist nicht erforderlich, aber es wird empfohlen, dateien, die Sie zuordnen möchten, für den exklusiven Zugriff geöffnet zu werden. Weitere Informationen finden Sie unter Dateisicherheit und Zugriffsrechte.

Wenn hFileINVALID_HANDLE_VALUE ist, muss der aufrufende Prozess auch eine Größe für das Dateizuordnungsobjekt in den Parametern dwMaximumSizeHigh und dwMaximumSizeLow angeben. In diesem Szenario erstellt CreateFileMappingFromApp ein Dateizuordnungsobjekt einer angegebenen Größe, das von der Systemauslagerungsdatei und nicht von einer Datei im Dateisystem unterstützt wird.

[in, optional] SecurityAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur , die bestimmt, ob ein zurückgegebenes Handle von untergeordneten Prozessen geerbt werden kann. Der lpSecurityDescriptor-Member der SECURITY_ATTRIBUTES-Struktur gibt einen Sicherheitsdeskriptor für ein neues Dateizuordnungsobjekt an.

Wenn SecurityAttributesNULL ist, kann das Handle nicht geerbt werden, und das Dateizuordnungsobjekt erhält einen Standardsicherheitsdeskriptor. Die Zugriffssteuerungslisten (Access Control Lists, ACL) im Standardsicherheitsdeskriptor für ein Dateizuordnungsobjekt stammen aus dem primären Token oder dem Identitätswechseltoken des Erstellers. Weitere Informationen finden Sie unter Dateizuordnungssicherheit und -zugriffsrechte.

[in] PageProtection

Gibt den Seitenschutz des Dateizuordnungsobjekts an. Alle zugeordneten Ansichten des Objekts müssen mit diesem Schutz kompatibel sein.

Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
PAGE_READONLY 0x02	Ermöglicht die Zuordnung von Ansichten für schreibgeschützten Zugriff oder Schreibzugriff. Ein Versuch, in eine bestimmte Region zu schreiben, führt zu einer Zugriffsverletzung. Das Dateihandle, das der hFile-Parameter angibt, muss mit dem zugriffsrecht GENERIC_READ erstellt werden.
PAGE_READWRITE 0x04	Ermöglicht das Zuordnen von Ansichten für schreibgeschützten Lesezugriff, Kopierzugriff oder Lese-/Schreibzugriff. Das Dateihandle, das der hFile-Parameter angibt, muss mit dem GENERIC_READ und GENERIC_WRITE Zugriffsrechten erstellt werden.
PAGE_WRITECOPY 0x08	Ermöglicht die Zuordnung von Ansichten für schreibgeschützten Zugriff oder Schreibzugriff. Dieser Wert entspricht PAGE_READONLY. Das Dateihandle, das der hFile-Parameter angibt, muss mit dem zugriffsrecht GENERIC_READ erstellt werden.

Eine Anwendung kann eines oder mehrere der folgenden Attribute für das Dateizuordnungsobjekt angeben, indem sie sie mit einem der vorherigen Seitenschutzwerte kombiniert.

Wert	Bedeutung
SEC_COMMIT 0x8000000	Wenn das Dateizuordnungsobjekt von der Auslagerungsdatei des Betriebssystems unterstützt wird (der hfile-Parameter ist INVALID_HANDLE_VALUE), gibt an, dass, wenn eine Ansicht der Datei einem Prozessadressraum zugeordnet wird, der gesamte Seitenbereich committet und nicht reserviert wird. Das System muss über genügend commitfähige Seiten verfügen, um die gesamte Zuordnung zu enthalten. Andernfalls schlägt CreateFileMappingFromApp fehl. Dieses Attribut hat keine Auswirkungen auf Dateizuordnungsobjekte, die von ausführbaren Bilddateien oder Datendateien unterstützt werden (der hfile-Parameter ist ein Handle für eine Datei). SEC_COMMIT können nicht mit SEC_RESERVE kombiniert werden. Wenn kein Attribut angegeben wird, wird von SEC_COMMIT ausgegangen.
SEC_IMAGE_NO_EXECUTE 0x11000000	Gibt an, dass die datei, die der hFile-Parameter angibt, eine ausführbare Imagedatei ist, die nicht ausgeführt wird und die geladene Imagedatei keine erzwungenen Integritätsprüfungen ausgeführt wird. Darüber hinaus ruft das Zuordnen einer Ansicht eines Dateizuordnungsobjekts, das mit dem attribut SEC_IMAGE_NO_EXECUTE erstellt wurde, keine Treiberrückrufe auf, die mit der PsSetLoadImageNotifyRoutine-Kernel-API registriert wurden. Das SEC_IMAGE_NO_EXECUTE-Attribut muss mit dem Wert für den Seitenschutz PAGE_READONLY kombiniert werden. Mit SEC_IMAGE_NO_EXECUTE sind keine anderen Attribute gültig.
SEC_LARGE_PAGES 0x80000000	Ermöglicht die Verwendung großer Seiten für Dateizuordnungsobjekte, die von der Auslagerungsdatei des Betriebssystems unterstützt werden (der hfile-Parameter ist INVALID_HANDLE_VALUE). Dieses Attribut wird für Dateizuordnungsobjekte, die von ausführbaren Bilddateien oder Datendateien unterstützt werden, nicht unterstützt (der hFile-Parameter ist ein Handle für ein ausführbares Image oder eine ausführbare Datendatei). Die maximale Größe des Dateizuordnungsobjekts muss ein Vielfaches der Mindestgröße einer großen Seite sein, die von der GetLargePageMinimum-Funktion zurückgegeben wird. Andernfalls schlägt CreateFileMappingFromApp fehl. Beim Zuordnen einer Ansicht eines Dateizuordnungsobjekts, das mit SEC_LARGE_PAGES erstellt wurde, müssen die Basisadresse und die Ansichtsgröße ebenfalls ein Vielfaches der minimalen großen Seitengröße sein. SEC_LARGE_PAGES erfordert, dass die SeLockMemoryPrivilege-Berechtigung im Token des Aufrufers aktiviert ist. Wenn SEC_LARGE_PAGES angegeben ist, muss auch SEC_COMMIT angegeben werden.
SEC_NOCACHE 0x10000000	Legt fest, dass alle Seiten nicht zwischengespeichert werden können. Anwendungen sollten dieses Attribut nur verwenden, wenn sie explizit für ein Gerät erforderlich sind. Die Verwendung der verriegelten Funktionen mit Speicher, der SEC_NOCACHE zugeordnet ist, kann zu einer EXCEPTION_ILLEGAL_INSTRUCTION Ausnahme führen. SEC_NOCACHE muss entweder das SEC_RESERVE - oder SEC_COMMIT-Attribut festgelegt werden.
SEC_RESERVE 0x4000000	Wenn das Dateizuordnungsobjekt von der Auslagerungsdatei des Betriebssystems unterstützt wird (der hfile-Parameter ist INVALID_HANDLE_VALUE), gibt an, dass, wenn eine Ansicht der Datei einem Prozessadressraum zugeordnet wird, der gesamte Seitenbereich für die spätere Verwendung durch den Prozess reserviert ist, anstatt committet zu werden. Reservierte Seiten können in nachfolgenden Aufrufen der VirtualAlloc-Funktion committet werden. Nachdem die Seiten committet wurden, können sie nicht mit der VirtualFree-Funktion freigegeben oder decommittediert werden. Dieses Attribut hat keine Auswirkungen auf Dateizuordnungsobjekte, die von ausführbaren Bilddateien oder Datendateien unterstützt werden (der hfile-Parameter ist ein Handle für eine Datei). SEC_RESERVE können nicht mit SEC_COMMIT kombiniert werden.
SEC_WRITECOMBINE 0x40000000	Legt fest, dass alle Seiten kombiniert werden sollen. Anwendungen sollten dieses Attribut nur verwenden, wenn sie explizit für ein Gerät erforderlich sind. Die Verwendung der verriegelten Funktionen mit Speicher, der SEC_WRITECOMBINE zugeordnet ist, kann zu einer EXCEPTION_ILLEGAL_INSTRUCTION Ausnahme führen. SEC_WRITECOMBINE muss entweder das SEC_RESERVE - oder SEC_COMMIT-Attribut festgelegt werden.

[in] MaximumSize

Die maximale Größe des Dateizuordnungsobjekts.

Beim Versuch, eine Datei mit der Länge 0 (null) zuzuordnen, tritt der Fehlercode ERROR_FILE_INVALID auf. Anwendungen sollten auf Dateien mit einer Länge von 0 (null) testen und diese Dateien ablehnen.

[in, optional] Name

Der Name des Dateizuordnungsobjekts.

Wenn dieser Parameter mit dem Namen eines vorhandenen Zuordnungsobjekts übereinstimmt, fordert die Funktion den Zugriff auf das Objekt mit dem von flProtect angegebenen Schutz an.

Wenn dieser Parameter NULL ist, wird das Dateizuordnungsobjekt ohne Namen erstellt.

Wenn lpName mit dem Namen eines vorhandenen Ereignisses, Semaphors, Mutex, wartebaren Timers oder Auftragsobjekts übereinstimmt, schlägt die Funktion fehl, und die GetLastError-Funktion gibt ERROR_INVALID_HANDLE zurück. Dies liegt daran, dass diese Objekte denselben Namespace verwenden.

Der Name kann ein Präfix "Global" oder "Local" aufweisen, um das Objekt explizit im globalen Oder Sitzungsnamespace zu erstellen. Der Rest des Namens kann ein beliebiges Zeichen mit Ausnahme des umgekehrten Schrägstrichs (\) enthalten. Das Erstellen eines Dateizuordnungsobjekts im globalen Namespace aus einer anderen Sitzung als Sitzung 0 erfordert die SeCreateGlobalPrivilege-Berechtigung . Weitere Informationen finden Sie unter Kernelobjektnamespaces.

Ein schneller Benutzerwechsel wird mithilfe von Terminaldienstesitzungen implementiert. Der erste Benutzer, der sich anmeldet, verwendet Sitzung 0 (null), der nächste Benutzer, der sich anmeldet, sitzung 1 (1) usw. Kernelobjektnamen müssen den Richtlinien entsprechen, die für Terminaldienste beschrieben sind, damit Anwendungen mehrere Benutzer unterstützen können.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das neu erstellte Dateizuordnungsobjekt.

Wenn das Objekt vor dem Funktionsaufruf vorhanden ist, gibt die Funktion ein Handle an das vorhandene Objekt zurück (mit seiner aktuellen Größe, nicht der angegebenen Größe), und GetLastError gibt ERROR_ALREADY_EXISTS zurück.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Nachdem ein Dateizuordnungsobjekt erstellt wurde, darf die Größe der Datei die Größe des Dateizuordnungsobjekts nicht überschreiten. wenn dies der Fall ist, sind nicht alle Dateiinhalte für die Freigabe verfügbar.

Wenn eine Anwendung eine Größe für das Dateizuordnungsobjekt angibt, die größer als die Größe der tatsächlich benannten Datei auf dem Datenträger ist, und wenn der Seitenschutz Schreibzugriff zulässt (d. h. der flProtect-Parameter gibt PAGE_READWRITE an), wird die Datei auf dem Datenträger erhöht, um der angegebenen Größe des Dateizuordnungsobjekts zu entsprechen. Wenn die Datei erweitert wird, ist nicht garantiert, dass der Inhalt der Datei zwischen dem alten Ende der Datei und dem neuen Ende der Datei null ist. das Verhalten vom Dateisystem definiert wird. Wenn die Datei auf dem Datenträger nicht erhöht werden kann, schlägt CreateFileMappingFromApp fehl, und GetLastError gibt ERROR_DISK_FULL zurück.

Der anfängliche Inhalt der Seiten in einem Dateizuordnungsobjekt, das von der Auslagerungsdatei des Betriebssystems unterstützt wird, ist 0 (null).

Das Von CreateFileMappingFromApp zurückgegebene Handle hat Vollzugriff auf ein neues Dateizuordnungsobjekt und kann mit jeder Funktion verwendet werden, die ein Handle für ein Dateizuordnungsobjekt erfordert.

Mehrere Prozesse können eine Ansicht derselben Datei gemeinsam nutzen, indem sie entweder ein einzelnes freigegebenes Dateizuordnungsobjekt verwenden oder separate Dateizuordnungsobjekte erstellen, die von derselben Datei unterstützt werden. Ein einzelnes Dateizuordnungsobjekt kann von mehreren Prozessen freigegeben werden, indem das Handle bei der Prozesserstellung geerbt, das Handle dupliziert oder das Dateizuordnungsobjekt anhand des Namens geöffnet wird. Weitere Informationen finden Sie unter den Funktionen CreateProcess, DuplicateHandle und OpenFileMapping .

Beim Erstellen eines Dateizuordnungsobjekts wird die Ansicht nicht tatsächlich einem Prozessadressraum zugeordnet. Die MapViewOfFileEx-Funktion zuordnen eine Ansicht einer Datei einem Prozessadressraum.

Mit einer wichtigen Ausnahme sind Dateiansichten, die von einem Dateizuordnungsobjekt abgeleitet werden, das von derselben Datei unterstützt wird, kohärent oder zu einem bestimmten Zeitpunkt identisch. Die Kohärenz wird für Ansichten innerhalb eines Prozesses und für Sichten garantiert, die von verschiedenen Prozessen zugeordnet werden.

Die Ausnahme bezieht sich auf Remotedateien. CreateFileMappingFromApp funktioniert zwar mit Remotedateien, hält sie jedoch nicht kohärent. Wenn z. B. zwei Computer eine Datei als schreibbar zuordnen und beide dieselbe Seite ändern, sieht jeder Computer nur seine eigenen Schreibvorgänge auf der Seite. Wenn die Daten auf dem Datenträger aktualisiert werden, werden sie nicht zusammengeführt.

Eine zugeordnete Datei und eine Datei, auf die über die Eingabe- und Ausgabefunktionen (E/A) (ReadFile und WriteFile) zugegriffen wird, sind nicht unbedingt kohärent.

Zugeordnete Ansichten eines Dateizuordnungsobjekts behalten interne Verweise auf das Objekt bei, und ein Dateizuordnungsobjekt wird erst geschlossen, wenn alle Verweise auf das Objekt freigegeben wurden. Um ein Dateizuordnungsobjekt vollständig zu schließen, muss eine Anwendung daher die Zuordnung aller zugeordneten Ansichten des Dateizuordnungsobjekts aufheben, indem UnmapViewOfFile aufgerufen und das Dateizuordnungsobjekthandle durch Aufrufen von CloseHandle geschlossen wird. Diese Funktionen können in beliebiger Reihenfolge aufgerufen werden.

Wenn Sie eine Datei über eine zugeordnete Ansicht ändern, wird der Zeitstempel der letzten Änderung möglicherweise nicht automatisch aktualisiert. Bei Bedarf sollte der Aufrufer SetFileTime verwenden, um den Zeitstempel festzulegen.

Verwenden Sie die strukturierte Ausnahmebehandlung, um code zu schützen, der in eine Dateiansicht schreibt oder aus dieser liest. Weitere Informationen finden Sie unter Lesen und Schreiben aus einer Dateiansicht.

Sie können nur erfolgreich schutz vor ausführbaren Dateien anfordern, wenn Ihre App über die funktion codeGeneration verfügt .

Anforderungen


Unterstützte Mindestversion (Client)	Windows 8 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	memoryapi.h (windows.h einschließen)
Bibliothek	onecore.lib
DLL	Kernel32.dll