CreateFileFromAppW-Funktion (fileapifromapp.h)

Artikel
08/23/2023

Erstellt oder öffnet eine Datei oder ein E/A-Gerät. Das Verhalten dieser Funktion ist identisch mit CreateFile, mit der Ausnahme, dass diese Funktion dem Universelle Windows-Plattform App-Sicherheitsmodells entspricht.

Syntax

WINSTORAGEAPI HANDLE CreateFileFromAppW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
) noexcept;

Parameter

lpFileName

Der Name der Datei oder des Geräts, die erstellt oder geöffnet werden soll. In diesem Namen können Sie schräge Schrägstriche (/) oder umgekehrte Schrägstriche (\) verwenden.

In der ANSI-Version dieser Funktion ist der Name auf MAX_PATH Zeichen beschränkt. Um diesen Grenzwert auf 32.767 Breite Zeichen zu erweitern, rufen Sie die Unicode-Version der Funktion auf, und stellen Sie dem Pfad "\\?\" voran. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Informationen zu speziellen Gerätenamen finden Sie unter Definieren eines MS-DOS-Gerätenamens.

Geben Sie zum Erstellen eines Dateidatenstroms den Namen der Datei, einen Doppelpunkt und dann den Namen des Datenstroms an. Weitere Informationen finden Sie unter Dateistreams.

Für die Unicode-Version dieser Funktion (CreateFileFromAppW) können Sie die MAX_PATH Einschränkung entfernen, ohne "\\?\" vorauszuschreiten. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .

dwDesiredAccess

Der angeforderte Zugriff auf die Datei oder das Gerät, der als Lese-, Schreib-, beides oder weder null) zusammengefasst werden kann.

Die am häufigsten verwendeten Werte sind GENERIC_READ, GENERIC_WRITE oder beides (GENERIC_READ | GENERIC_WRITE). Weitere Informationen finden Sie unter Generische Zugriffsrechte, Dateisicherheit und Zugriffsrechte, Dateizugriffsrechtekonstanten und ACCESS_MASK.

Wenn dieser Parameter null ist, kann die Anwendung bestimmte Metadaten wie Datei-, Verzeichnis- oder Geräteattribute abfragen, ohne auf diese Datei oder das Gerät zuzugreifen, auch wenn GENERIC_READ Zugriff verweigert worden wäre.

Sie können keinen Zugriffsmodus anfordern, der mit dem Freigabemodus in Konflikt steht, der durch den dwShareMode-Parameter in einer offenen Anforderung angegeben wird, die bereits über ein geöffnetes Handle verfügt.

dwShareMode

Der angeforderte Freigabemodus der Datei oder des Geräts, der gelesen, geschrieben, beide, gelöscht, alle oder keine (siehe folgende Tabelle) sein kann. Zugriffsanforderungen auf Attribute oder erweiterte Attribute sind von diesem Flag nicht betroffen.

Wert	Bedeutung
0 0x00000000	Verhindert, dass andere Prozesse eine Datei oder ein Gerät öffnen, wenn sie Lösch-, Lese- oder Schreibzugriff anfordern.
FILE_SHARE_DELETE 0x00000004	Ermöglicht nachfolgende Geöffnete Vorgänge für eine Datei oder ein Gerät, um den Löschzugriff anzufordern. Andernfalls können andere Prozesse die Datei oder das Gerät nicht öffnen, wenn sie Löschzugriff anfordern. Wenn dieses Flag nicht angegeben ist, aber die Datei oder das Gerät für den Löschzugriff geöffnet wurde, schlägt die Funktion fehl. Hinweis Der Löschzugriff ermöglicht sowohl Lösch- als auch Umbenennungsvorgänge.
FILE_SHARE_READ 0x00000001	Ermöglicht nachfolgende Geöffnete Vorgänge für eine Datei oder ein Gerät, um Lesezugriff anzufordern. Andernfalls können andere Prozesse die Datei oder das Gerät nicht öffnen, wenn sie Lesezugriff anfordern. Wenn dieses Flag nicht angegeben ist, aber die Datei oder das Gerät für den Lesezugriff geöffnet wurde, schlägt die Funktion fehl.
FILE_SHARE_WRITE 0x00000002	Ermöglicht nachfolgende Geöffnete Vorgänge für eine Datei oder ein Gerät, um Schreibzugriff anzufordern. Andernfalls können andere Prozesse die Datei oder das Gerät nicht öffnen, wenn sie Schreibzugriff anfordern. Wenn dieses Flag nicht angegeben ist, die Datei oder das Gerät jedoch für den Schreibzugriff geöffnet wurde oder über eine Dateizuordnung mit Schreibzugriff verfügt, schlägt die Funktion fehl.

lpSecurityAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur , die zwei separate, aber verwandte Datenmember enthält: einen optionalen Sicherheitsdeskriptor und einen booleschen Wert, der bestimmt, ob das zurückgegebene Handle von untergeordneten Prozessen geerbt werden kann.

Dieser Parameter kann NULL sein.

Wenn dieser Parameter NULL ist, kann das zurückgegebene Handle nicht von untergeordneten Prozessen geerbt werden, die die Anwendung möglicherweise erstellt, und die Datei oder das Gerät, das dem zurückgegebenen Handle zugeordnet ist, erhält eine Standardsicherheitsbeschreibung.

Das lpSecurityDescriptor-Element der Struktur gibt einen SECURITY_DESCRIPTOR für eine Datei oder ein Gerät an. Wenn dieses Element NULL ist, wird der Datei oder dem gerät, das dem zurückgegebenen Handle zugeordnet ist, eine Standardsicherheitsbeschreibung zugewiesen.

Diese Funktion ignoriert den lpSecurityDescriptor-Member beim Öffnen einer vorhandenen Datei oder eines vorhandenen Geräts, verwendet aber weiterhin den bInheritHandle-Member .

Das bInheritHandle-Element der Struktur gibt an, ob das zurückgegebene Handle geerbt werden kann.

dwCreationDisposition

Eine Aktion, die für eine Datei oder ein Gerät ausgeführt werden soll, die vorhanden ist oder nicht vorhanden ist.

Für andere Geräte als Dateien ist dieser Parameter normalerweise auf OPEN_EXISTING festgelegt.

Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

Dieser Parameter muss einer der folgenden Werte sein, die nicht kombiniert werden können:

Wert	Bedeutung
CREATE_ALWAYS 2	Erstellt immer eine neue Datei. Wenn die angegebene Datei vorhanden und beschreibbar ist, schneidet die Funktion die Datei ab, die Funktion ist erfolgreich, und der Code für den letzten Fehler ist auf ERROR_ALREADY_EXISTS (183) festgelegt. Wenn die angegebene Datei nicht vorhanden ist und ein gültiger Pfad ist, wird eine neue Datei erstellt, die Funktion erfolgreich ausgeführt, und der Code des letzten Fehlers wird auf Null festgelegt. Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.
CREATE_NEW 1	Erstellt eine neue Datei nur, wenn sie noch nicht vorhanden ist. Wenn die angegebene Datei vorhanden ist, schlägt die Funktion fehl, und der Letzte Fehlercode wird auf ERROR_FILE_EXISTS (80) festgelegt. Wenn die angegebene Datei nicht vorhanden ist und ein gültiger Pfad zu einem beschreibbaren Speicherort ist, wird eine neue Datei erstellt.
OPEN_ALWAYS 4	Öffnet eine Datei immer. Wenn die angegebene Datei vorhanden ist, ist die Funktion erfolgreich, und der Letzte Fehlercode wird auf ERROR_ALREADY_EXISTS (183) festgelegt. Wenn die angegebene Datei nicht vorhanden ist und ein gültiger Pfad zu einem beschreibbaren Speicherort ist, erstellt die Funktion eine Datei, und der Code des letzten Fehlers wird auf 0 festgelegt.
OPEN_EXISTING 3	Öffnet eine Datei oder ein Gerät nur, wenn es vorhanden ist. Wenn die angegebene Datei oder das angegebene Gerät nicht vorhanden ist, schlägt die Funktion fehl, und der Code des letzten Fehlers ist auf ERROR_FILE_NOT_FOUND (2) festgelegt. Weitere Informationen zu Geräten finden Sie im Abschnitt Hinweise.
TRUNCATE_EXISTING 5	Öffnet eine Datei und schneidet sie ab, sodass ihre Größe null Bytes beträgt, nur wenn sie vorhanden ist. Wenn die angegebene Datei nicht vorhanden ist, schlägt die Funktion fehl, und der Letzte Fehlercode ist auf ERROR_FILE_NOT_FOUND (2) festgelegt. Der aufrufende Prozess muss die Datei mit dem GENERIC_WRITE Bit öffnen, das als Teil des dwDesiredAccess-Parameters festgelegt ist.

dwFlagsAndAttributes

Die Datei- oder Geräteattribute und -flags FILE_ATTRIBUTE_NORMAL der häufigste Standardwert für Dateien.

Dieser Parameter kann eine beliebige Kombination der verfügbaren Dateiattribute (FILE_ATTRIBUTE_*) enthalten. Alle anderen Dateiattribute überschreiben FILE_ATTRIBUTE_NORMAL.

Dieser Parameter kann auch Kombinationen von Flags (FILE_FLAG_*) für die Steuerung des Zwischenspeicherverhaltens von Dateien oder Geräten, Zugriffsmodi und anderen Sonderflags enthalten. Diese werden mit beliebigen FILE_ATTRIBUTE_* -Werten kombiniert.

Dieser Parameter kann auch SQOS-Informationen (Security Quality of Service) enthalten, indem er das SECURITY_SQOS_PRESENT-Flag angibt. Zusätzliche Informationen zu SQOS-bezogenen Flags werden in der Tabelle nach den Attributen und Flags-Tabellen angezeigt.

attribute	Bedeutung
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	Die Datei sollte archiviert werden. Anwendungen verwenden dieses Attribut, um Dateien für die Sicherung oder Entfernung zu markieren.
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	Die Datei oder das Verzeichnis ist verschlüsselt. Bei einer Datei bedeutet dies, dass alle Daten in der Datei verschlüsselt sind. Für ein Verzeichnis bedeutet dies, dass die Verschlüsselung der Standard für neu erstellte Dateien und Unterverzeichnisse ist. Weitere Informationen finden Sie unter Dateiverschlüsselung. Dieses Flag hat keine Auswirkung, wenn auch FILE_ATTRIBUTE_SYSTEM angegeben wird. Dieses Flag wird in den Windows-Editionen Home, Home Premium, Starter oder ARM nicht unterstützt.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	Die Datei ist ausgeblendet. Fügen Sie es nicht in eine normale Verzeichnisliste ein.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	Für die Datei sind keine anderen Attribute festgelegt. Dieses Attribut ist nur gültig, wenn es allein verwendet wird.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	Die Daten einer Datei sind nicht sofort verfügbar. Dieses Attribut gibt an, dass Dateidaten physisch in den Offlinespeicher verschoben werden. Dieses Attribut wird von Remote storage verwendet, der hierarchischen Speicherverwaltungssoftware. Anwendungen sollten dieses Attribut nicht willkürlich ändern.
FILE_ATTRIBUTE_READONLY 1 (0x1)	Die Datei ist schreibgeschützter. Anwendungen können die Datei lesen, aber nicht in sie schreiben oder löschen.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	Die Datei ist Teil von oder wird ausschließlich von einem Betriebssystem verwendet.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	Die Datei wird für den temporären Speicher verwendet. Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas.

Flag	Bedeutung
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	Die Datei wird für einen Sicherungs- oder Wiederherstellungsvorgang geöffnet oder erstellt. Das System stellt sicher, dass der aufrufende Prozess dateisicherheitsprüfungen außer Kraft setzt, wenn der Prozess über SE_BACKUP_NAME - und SE_RESTORE_NAME-Berechtigungen verfügt. Weitere Informationen finden Sie unter Ändern von Berechtigungen in einem Token. Sie müssen dieses Flag festlegen, um ein Handle für ein Verzeichnis abzurufen. Ein Verzeichnishandle kann an einige Funktionen anstelle eines Dateihandles übergeben werden. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	Die Datei ist sofort zu löschen, nachdem alle ihre Handles geschlossen wurden, einschließlich des angegebenen Handles und aller anderen geöffneten oder duplizierten Handles. Wenn geöffnete Handles für eine Datei vorhanden sind, schlägt der Aufruf fehl, es sei denn, sie wurden alle mit dem FILE_SHARE_DELETE Freigabemodus geöffnet. Nachfolgende Öffnungsanforderungen für die Datei fehlschlagen, es sei denn, der Freigabemodus FILE_SHARE_DELETE ist angegeben.
FILE_FLAG_NO_BUFFERING 0x20000000	Die Datei oder das Gerät wird ohne Systemzwischenspeicherung für Lese- und Schreibvorgänge geöffnet. Dieses Flag wirkt sich nicht auf die Zwischenspeicherung von Festplatten oder zugeordnete Dateien im Arbeitsspeicher aus. Es gibt strenge Anforderungen für die erfolgreiche Arbeit mit Dateien, die mit dieser Funktion mit dem flag FILE_FLAG_NO_BUFFERING geöffnet wurden. Weitere Informationen finden Sie unter Dateipufferung.
FILE_FLAG_OPEN_NO_RECALL 0x00100000	Die Dateidaten werden angefordert, sollten sich jedoch weiterhin im Remotespeicher befinden. Es sollte nicht zurück in den lokalen Speicher transportiert werden. Dieses Flag ist für Remotespeichersysteme vorgesehen.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	Die normale Analysepunktverarbeitung erfolgt nicht. Diese Funktion versucht, den Analysepunkt zu öffnen. Wenn eine Datei geöffnet wird, wird ein Dateihandle zurückgegeben, unabhängig davon, ob der Filter, der den Analysepunkt steuert, funktionsfähig ist oder nicht. Dieses Flag kann nicht mit dem CREATE_ALWAYS-Flag verwendet werden. Wenn die Datei kein Analysepunkt ist, wird dieses Flag ignoriert. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
FILE_FLAG_OVERLAPPED 0x40000000	Die Datei oder das Gerät wird für asynchrone E/A-Vorgänge geöffnet oder erstellt. Wenn nachfolgende E/A-Vorgänge für dieses Handle abgeschlossen werden, wird das in der OVERLAPPED-Struktur angegebene Ereignis auf den signalierten Zustand festgelegt. Wenn dieses Flag angegeben ist, kann die Datei für gleichzeitige Lese- und Schreibvorgänge verwendet werden. Wenn dieses Flag nicht angegeben ist, werden E/A-Vorgänge serialisiert, auch wenn die Aufrufe der Lese- und Schreibfunktionen eine OVERLAPPED-Struktur angeben. Informationen zu Überlegungen bei der Verwendung eines mit diesem Flag erstellten Dateihandles finden Sie im Abschnitt Synchrone und asynchrone E/A-Handles dieses Themas.
FILE_FLAG_POSIX_SEMANTICS 0x0100000	Der Zugriff erfolgt gemäß den POSIX-Regeln. Dies schließt das Zulassen mehrerer Dateien mit Namen ein, die sich nur für die Groß- und Kleinschreibung unterscheiden, für Dateisysteme, die diese Benennung unterstützen. Gehen Sie bei der Verwendung dieser Option vorsichtig vor, da mit diesem Flag erstellte Dateien möglicherweise nicht für Anwendungen zugänglich sind, die für MS-DOS oder 16-Bit-Windows geschrieben wurden.
FILE_FLAG_RANDOM_ACCESS 0x10000000	Der Zugriff soll zufällig erfolgen. Das System kann dies als Hinweis zur Optimierung der Zwischenspeicherung von Dateien verwenden. Dieses Flag hat keine Auswirkung, wenn das Dateisystem keine zwischengespeicherten E/A- und FILE_FLAG_NO_BUFFERING unterstützt. Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas.
FILE_FLAG_SESSION_AWARE 0x00800000	Die Datei oder das Gerät wird mit Sitzungsbewusstsein geöffnet. Wenn dieses Flag nicht angegeben ist, können Geräte pro Sitzung (z. B. ein Gerät mit RemoteFX-USB-Umleitung) nicht von Prozessen geöffnet werden, die in Sitzung 0 ausgeführt werden. Dieses Flag hat keine Auswirkungen auf Aufrufer, die sich nicht in Sitzung 0 befinden. Dieses Flag wird nur in Servereditionen von Windows unterstützt.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	Der Zugriff soll von Anfang bis Ende sequenziell erfolgen. Das System kann dies als Hinweis zur Optimierung der Zwischenspeicherung von Dateien verwenden. Dieses Flag sollte nicht verwendet werden, wenn Read-Behind (d. h. umgekehrte Überprüfungen) verwendet wird. Dieses Flag hat keine Auswirkung, wenn das Dateisystem keine zwischengespeicherten E/A- und FILE_FLAG_NO_BUFFERING unterstützt. Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas.
FILE_FLAG_WRITE_THROUGH 0x80000000	Schreibvorgänge durchlaufen keinen Zwischencache, sie werden direkt auf den Datenträger weitergeleitet. Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas.

Der dwFlagsAndAttributes-Parameterkann auch SQOS-Informationen angeben. Weitere Informationen finden Sie unter Identitätswechsel. Wenn die aufrufende Anwendung das SECURITY_SQOS_PRESENT-Flag als Teil von dwFlagsAndAttributes angibt, kann sie auch einen oder mehrere der folgenden Werte enthalten.

Sicherheitsflag	Bedeutung
SECURITY_ANONYMOUS	Imitiert einen Client auf der Ebene Anonymer Identitätswechsel.
SECURITY_CONTEXT_TRACKING	Der Sicherheitsnachverfolgungsmodus ist dynamisch. Wenn dieses Flag nicht angegeben ist, ist der Sicherheitsnachverfolgungsmodus statisch.
SECURITY_DELEGATION	Identitätswechsel eines Clients auf Der Ebene des Delegierungswechsels.
SECURITY_EFFECTIVE_ONLY	Dem Server stehen nur die aktivierten Aspekte des Sicherheitskontexts des Clients zur Verfügung. Wenn Sie dieses Flag nicht angeben, sind alle Aspekte des Sicherheitskontexts des Clients verfügbar. Dadurch kann der Client die Gruppen und Berechtigungen einschränken, die ein Server beim Annehmen der Identität des Clients verwenden kann.
SECURITY_IDENTIFICATION	Imitiert einen Client auf der Identitätswechselebene der Identifizierung.
SECURITY_IMPERSONATION	Annehmen der Identität eines Clients auf Identitätswechselebene. Dies ist das Standardverhalten, wenn keine anderen Flags zusammen mit dem SECURITY_SQOS_PRESENT-Flag angegeben werden.

hTemplateFile

Ein gültiges Handle für eine Vorlagendatei mit dem zugriffsrecht GENERIC_READ . Die Vorlagendatei stellt Dateiattribute und erweiterte Attribute für die Datei bereit, die erstellt wird.

Dieser Parameter kann NULL sein.

Beim Öffnen einer vorhandenen Datei wird dieser Parameter ignoriert.

Beim Öffnen einer neuen verschlüsselten Datei erbt die Datei die liste der zugriffskontrollberechtigten Elemente aus dem übergeordneten Verzeichnis. Weitere Informationen finden Sie unter Dateiverschlüsselung.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein geöffnetes Handle für die angegebene Datei, das angegebene Gerät, die angegebene Named Pipe oder den angegebenen E-Mail-Slot.

Wenn die Funktion fehlschlägt, ist der Rückgabewert INVALID_HANDLE_VALUE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 10, Version 1803
Kopfzeile	fileapifromapp.h