CreateFileMappingFromApp-Funktion (memoryapi.h)
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 Schutzkennzeichnungen kompatibel sind, die der parameter flProtect angibt. Es ist nicht erforderlich, aber es wird empfohlen, dass Dateien, die Sie zuordnen möchten, für exklusiven Zugriff geöffnet werden sollen. Weitere Informationen finden Sie unter Dateisicherheits- und Zugriffsberechtigungen.
Wenn hFile-INVALID_HANDLE_VALUEist, muss der aufrufende Prozess auch eine Größe für das Dateizuordnungsobjekt im dwMaximumSizeHigh und dwMaximumSizeLow Parameter angeben. In diesem Szenario erstellt CreateFileMappingFromApp ein Dateizuordnungsobjekt mit einer angegebenen Größe, die von der System-Auslagerungsdatei anstelle 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 SecurityAttributes-NULL-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 oder Identitätswechseltoken des Erstellers. Weitere Informationen finden Sie unter Dateizuordnungssicherheit und Zugriffsberechtigungen.
[in] PageProtection
Gibt den Seitenschutz des Dateizuordnungsobjekts an. Alle zugeordneten Ansichten des Objekts müssen mit diesem Schutz kompatibel sein.
Dieser Parameter kann einer der folgenden Werte sein:
Eine Anwendung kann ein oder mehrere der folgenden Attribute für das Dateizuordnungsobjekt angeben, indem sie mit einem der vorherigen Seitenschutzwerte kombiniert werden.
| Wert | Bedeutung |
|---|---|
|
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 zugesichert wird, anstatt reserviert. Das System muss über genügend Committable-Seiten verfügen, um die gesamte Zuordnung zu enthalten. Andernfalls schlägt CreateFileMappingFromApp fehl.
Dieses Attribut hat keine Auswirkung 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_RESERVEkombiniert werden. Wenn kein Attribut angegeben wird, wird SEC_COMMIT angenommen. |
|
Gibt an, dass die Datei, die der hFile Parameter angibt, eine ausführbare Bilddatei ist, die nicht ausgeführt wird und die geladene Bilddatei keine erzwungenen Integritätsprüfungen ausgeführt wird.
Darüber hinaus ruft die Zuordnung einer Ansicht eines dateizuordnungsobjekts, das mit dem attribut SEC_IMAGE_NO_EXECUTE erstellt wurde, keine Treiberrückrufe auf, die mithilfe der PsSetLoadImageNotifyRoutine Kernel-API registriert sind.
Das attribut SEC_IMAGE_NO_EXECUTE muss mit dem PAGE_READONLY Seitenschutzwert kombiniert werden. Mit SEC_IMAGE_NO_EXECUTEsind keine anderen Attribute gültig. |
|
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 gesichert werden, nicht unterstützt (der hFile- Parameter ist ein Handle für ein ausführbares Bild oder eine 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. Ist dies nicht der Fehler, schlägt CreateFileMappingFromApp fehl. Beim Zuordnen einer Ansicht eines dateizuordnungsobjekts, das mit SEC_LARGE_PAGESerstellt wurde, muss die Basisadresse und die Ansichtsgröße auch Vielfache der minimal großen Seitengröße sein. SEC_LARGE_PAGES erfordert, dass das SeLockMemoryPrivilege Berechtigung im Token des Aufrufers aktiviert werden muss. Wenn SEC_LARGE_PAGES angegeben ist, muss auch SEC_COMMIT angegeben werden. |
|
Legt fest, dass alle Seiten nicht zwischengespeichert werden können.
Anwendungen sollten dieses Attribut nicht verwenden, es sei denn, dies ist explizit für ein Gerät erforderlich. Die Verwendung der verriegelten Funktionen mit speicherinternen Funktionen, die mit SEC_NOCACHE zugeordnet sind, kann zu einer EXCEPTION_ILLEGAL_INSTRUCTION Ausnahme führen. SEC_NOCACHE muss entweder das SEC_RESERVE- oder SEC_COMMIT Attribut festgelegt werden. |
|
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 in einem Prozessadressraum zugeordnet wird, der gesamte Seitenbereich für die spätere Verwendung durch den Prozess reserviert ist und nicht zugesichert wird.
Reservierte Seiten können in nachfolgenden Aufrufen der VirtualAlloc--Funktion zugesichert werden. Nachdem die Seiten zugesichert wurden, können sie nicht mit der funktion VirtualFree freigegeben oder dekommissioniert werden. Dieses Attribut hat keine Auswirkung 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_COMMITkombiniert werden. |
|
Legt fest, dass alle Seiten kombiniert werden sollen.
Anwendungen sollten dieses Attribut nicht verwenden, es sei denn, dies ist explizit für ein Gerät erforderlich. Die Verwendung der verriegelten Funktionen mit Speicher, der mit 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.
Ein Versuch, eine Datei mit einer Länge von 0 (Null) zuzuordnen, schlägt mit einem Fehlercode von ERROR_FILE_INVALIDfehl. 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 dem Namen eines vorhandenen Zuordnungsobjekts entspricht, fordert die Funktion den Zugriff auf das Objekt mit dem Schutz an, der flProtect- angibt.
Wenn dieser Parameter NULL-ist, wird das Dateizuordnungsobjekt ohne Namen erstellt.
Wenn lpName- mit dem Namen eines vorhandenen Ereignisses, Semaphor, Mutex, Wartezeitgeber oder Auftragsobjekts übereinstimmt, schlägt die Funktion fehl, und die GetLastError--Funktion gibt ERROR_INVALID_HANDLEzurück. Dies geschieht, da diese Objekte denselben Namespace gemeinsam nutzen.
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 Null erfordert das SeCreateGlobalPrivilege-Berechtigung. Weitere Informationen finden Sie unter Kernel Object Namespaces.
Schnelle Benutzerumschaltung wird mithilfe von Terminaldienstesitzungen implementiert. Der erste Benutzer, der sich anmeldet, verwendet Sitzung 0 (Null), der nächste Benutzer zum Anmelden Sitzung 1 (eins) 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_EXISTSzurück.
Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
Nachdem ein Dateizuordnungsobjekt erstellt wurde, darf die Größe der Datei die Größe des Dateizuordnungsobjekts nicht überschreiten. Wenn dies der Fall ist, stehen nicht alle Dateiinhalte für die Freigabe zur Verfügung.
Wenn eine Anwendung eine Größe für das Dateizuordnungsobjekt angibt, das 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 parameter flProtect 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 der Inhalt der Datei zwischen dem alten Ende der Datei und dem neuen Ende der Datei nicht garantiert null; das Verhalten wird vom Dateisystem definiert. Wenn die Datei auf dem Datenträger nicht erhöht werden kann, schlägt CreateFileMappingFromApp fehl und GetLastError gibt ERROR_DISK_FULLzurück.
Der anfängliche Inhalt der Seiten in einem Dateizuordnungsobjekt, das von der Auslagerungsdatei des Betriebssystems unterstützt wird, ist 0 (null).
Das Handle, das CreateFileMappingFromApp zurückgibt, 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 freigeben, 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 gemeinsam genutzt werden, indem er das Handle bei der Prozesserstellung erbt, das Handle dupliziert oder das Dateizuordnungsobjekt anhand des Namens öffnet. Weitere Informationen finden Sie unter CreateProcess, DuplicateHandle- und OpenFileMapping- funktionen.
Durch das Erstellen eines Dateizuordnungsobjekts wird die Ansicht nicht tatsächlich einem Prozessadressraum zugeordnet. Die MapViewOfFileEx- Funktion ordnen eine Ansicht einer Datei in einem Prozessadressraum zu.
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 CreateFileMappingFromApp 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 Datei und eine Datei, auf die mithilfe der Eingabe- und Ausgabefunktionen (E/A) zugegriffen wird (ReadFile- und WriteFile-) sind nicht notwendigerweise kohärent.
Zugeordnete Ansichten eines Dateizuordnungsobjekts verwalten interne Verweise auf das Objekt, und ein Dateizuordnungsobjekt wird erst geschlossen, wenn alle Verweise darauf freigegeben werden. Um ein Dateizuordnungsobjekt vollständig zu schließen, muss eine Anwendung daher alle 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.
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.
Verwenden Sie die strukturierte Ausnahmebehandlung, um Code zu schützen, der in eine Dateiansicht schreibt oder liest. Weitere Informationen finden Sie unter Lesen und Schreiben aus einer Dateiansicht.
Sie können nur erfolgreich ausführbaren Schutz anfordern, wenn Ihre App über die CodeGeneration--Funktion verfügt.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 8 [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2012 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | memoryapi.h (include Windows.h) |
| Library | onecore.lib |
| DLL- | Kernel32.dll |
Siehe auch
Erstellen eines Dateizuordnungsobjekts
Dateizuordnungsfunktionen