CreateFileFromAppW-Funktion (fileapifromapp.h)
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 Sicherheitsmodell der Universellen Windows-Plattform-App 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 zu erstellenden oder geöffneten Datei oder des Geräts. Sie können entweder Schrägstriche (/) oder umgekehrte Schrägstriche (\) in diesem Namen 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 Namensdateien, Pfade und Namespaces.
Informationen zu speziellen Gerätenamen finden Sie unter Definieren eines MS-DOS Gerätenamens.
Um einen Dateidatenstrom zu erstellen, geben Sie den Namen der Datei, einen Doppelpunkt und dann den Namen des Datenstroms an. Weitere Informationen finden Sie unter File Streams.
Für die Unicode-Version dieser Funktion (CreateFileFromAppW) können Sie sich anmelden, um die MAX_PATH Einschränkung zu entfernen, ohne "\\?\". Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbeschränkung" Benennungsdateien, Pfade und Namespaces.
dwDesiredAccess
Der angeforderte Zugriff auf die Datei oder das Gerät, die als Lese-, Schreib-, Schreib- oder keine Null zusammengefasst werden kann).
Die am häufigsten verwendeten Werte sind GENERIC_READ, GENERIC_WRITEoder beide (GENERIC_READ | GENERIC_WRITE). Weitere Informationen finden Sie unter Generic Access Rights, File Security and Access Rights, File Access Rights Constantsund 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 wurde.
Sie können keinen Zugriffsmodus anfordern, der mit dem Freigabemodus in Konflikt steht, der durch den dwShareMode Parameter in einer geöffneten 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 werden kann, beides, löschen, all diese oder keine (siehe die folgende Tabelle). Zugriffsanforderungen an 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 nachfolgenden Öffnenvorgängen auf einer Datei oder einem Gerät das Anfordern des Löschzugriffs. Andernfalls können andere Prozesse die Datei oder das Gerät nicht öffnen, wenn sie den 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 Löschzugriff ermöglicht sowohl Lösch- als auch Umbenennungsvorgänge. |
| FILE_SHARE_READ 0x00000001 | Ermöglicht nachfolgenden Öffnenvorgängen auf einer Datei oder einem Gerät das Anfordern des Lesezugriffs. 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 nachfolgenden Öffnenvorgängen auf einer Datei oder einem Gerät das Anfordern des Schreibzugriffs. Andernfalls können andere Prozesse die Datei oder das Gerät nicht öffnen, wenn sie Schreibzugriff anfordern. Wenn dieses Flag nicht angegeben ist, aber die Datei oder das Gerät 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 erstellen kann, und die Datei oder das dem zurückgegebenen Handle zugeordnete Gerät erhält einen Standardsicherheitsdeskriptor.
Der lpSecurityDescriptor Element der Struktur gibt eine SECURITY_DESCRIPTOR für eine Datei oder ein Gerät an. Wenn dieses Element NULL-ist, wird der dem zurückgegebenen Handle zugeordnete Datei oder das gerät einem Standardsicherheitsdeskriptor zugewiesen.
Diese Funktion ignoriert den lpSecurityDescriptor Member beim Öffnen einer vorhandenen Datei oder eines vorhandenen Geräts, verwendet jedoch weiterhin das bInheritHandle Member.
Das bInheritHandle Element der Struktur gibt an, ob das zurückgegebene Handle geerbt werden kann.
dwCreationDisposition
Eine Aktion, die auf einer Datei oder einem Gerät ausgeführt werden soll, die vorhanden ist oder nicht vorhanden ist.
Für andere Geräte als Dateien wird dieser Parameter in der Regel auf OPEN_EXISTINGfestgelegt.
Weitere Informationen finden Sie im Abschnitt "Hinweise".
Dieser Parameter muss eines 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 ist und schreibbar ist, schneidet die Funktion die Datei ab, die Funktion wird erfolgreich ausgeführt, und der Letzte-Fehler-Code wird 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 ist und der letzte Fehlercode auf Null festgelegt ist. Weitere Informationen finden Sie im Abschnitt "Hinweise" dieses Themas. |
| 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 schreibbaren Speicherort ist, wird eine neue Datei erstellt. |
| OPEN_ALWAYS 4 | Öffnet immer eine Datei. Wenn die angegebene Datei vorhanden ist, wird die Funktion erfolgreich ausgeführt, 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 schreibbaren Speicherort ist, erstellt die Funktion eine Datei, und der letzte Fehlercode wird auf Null festgelegt. |
| OPEN_EXISTING 3 | Öffnet eine Datei oder ein Gerät nur, wenn sie vorhanden ist. Wenn die angegebene Datei oder das angegebene Gerät nicht vorhanden ist, schlägt die Funktion fehl, und der letzte Fehlercode wird 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 die Größe null Byte ist, nur wenn sie vorhanden ist. Wenn die angegebene Datei nicht vorhanden ist, schlägt die Funktion fehl, und der letzte Fehlercode wird auf ERROR_FILE_NOT_FOUND (2) festgelegt. Der aufrufende Prozess muss die Datei mit dem GENERIC_WRITE Bitsatz im Rahmen des dwDesiredAccess--Parameters öffnen. |
dwFlagsAndAttributes
Die Datei- oder Geräteattribute und -flags FILE_ATTRIBUTE_NORMAL der am häufigsten verwendete 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_*) zur Kontrolle des Datei- oder Gerätezwischenspeicherungsverhaltens, Zugriffsmodi und anderen speziellen Flags enthalten. Diese werden mit allen FILE_ATTRIBUTE_* Werten kombiniert.
Dieser Parameter kann auch SqOS-Informationen (Security Quality of Service) enthalten, indem das SECURITY_SQOS_PRESENT Flag angegeben wird. Zusätzliche SQOS-bezogene Flags-Informationen werden in der Tabelle nach den Attributen und Flags-Tabellen dargestellt.
| Attribut | 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. Bei einem Verzeichnis bedeutet dies, dass die Verschlüsselung die Standardeinstellung für neu erstellte Dateien und Unterverzeichnisse ist. Weitere Informationen finden Sie unter Dateiverschlüsselung. Dieses Kennzeichen hat keine Auswirkung, wenn auch FILE_ATTRIBUTE_SYSTEM angegeben wird. Dieses Kennzeichen wird in den Editionen Home, Home Premium, Starter oder ARM von Windows nicht unterstützt. |
| FILE_ATTRIBUTE_HIDDEN 2 (0x2) | Die Datei ist ausgeblendet. Fügen Sie sie nicht in eine normale Verzeichnisauflistung 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, der hierarchischen Speicherverwaltungssoftware, verwendet. Anwendungen sollten dieses Attribut nicht willkürlich ändern. |
| FILE_ATTRIBUTE_READONLY 1 (0x1) | Die Datei ist schreibgeschützt. Anwendungen können die Datei lesen, aber nicht in die Datei schreiben oder löschen. |
| FILE_ATTRIBUTE_SYSTEM 4 (0x4) | Die Datei ist Teil oder wird ausschließlich von einem Betriebssystem verwendet. |
| FILE_ATTRIBUTE_TEMPORARY 256 (0x100) | Die Datei wird für temporären Speicher verwendet. Weitere Informationen finden Sie im Abschnitt "Zwischenspeicherungsverhalten" in diesem Thema. |
| Flagge | 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 anstelle eines Dateihandles an einige Funktionen übergeben werden. Weitere Informationen finden Sie im Abschnitt "Hinweise". |
| FILE_FLAG_DELETE_ON_CLOSE 0x04000000 | Die Datei muss unmittelbar gelöscht werden, nachdem alle Ziehpunkte geschlossen wurden, die das angegebene Handle und alle anderen geöffneten oder duplizierten Handles enthalten. Wenn eine Datei geöffnete Handles enthält, schlägt der Aufruf fehl, es sei denn, sie wurden alle mit dem FILE_SHARE_DELETE Freigabemodus geöffnet. Nachfolgende offene Anforderungen für die Datei schlagen fehl, es sei denn, der FILE_SHARE_DELETE Freigabemodus ist angegeben. |
| FILE_FLAG_NO_BUFFERING 0x20000000 | Die Datei oder das Gerät wird ohne Systemzwischenspeicherung für Datenlese- und Schreibvorgänge geöffnet. Dieses Flag wirkt sich nicht auf das Zwischenspeichern der Festplatte oder die zugeordneten Speicherdateien aus. Es gibt strenge Anforderungen für das erfolgreiche Arbeiten mit Dateien, die mit dieser Funktion mithilfe des FILE_FLAG_NO_BUFFERING-Flags geöffnet wurden, ausführliche Informationen finden Sie unter Dateipufferung. |
| FILE_FLAG_OPEN_NO_RECALL 0x00100000 | Die Dateidaten werden angefordert, sollten sich aber weiterhin im Remotespeicher befinden. Es sollte nicht zurück in die lokale Lagerung transportiert werden. Dieses Kennzeichen dient der Verwendung durch Remotespeichersysteme. |
| FILE_FLAG_OPEN_REPARSE_POINT 0x00200000 | Normale Analysepunkt Verarbeitung 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, betriebsbereit ist. 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 "Hinweise". |
| FILE_FLAG_OVERLAPPED 0x40000000 | Die Datei oder das Gerät wird für asynchrone E/A 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 ÜBERLAPPEND- 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 nach POSIX-Regeln. Dies umfasst das Zulassen mehrerer Dateien mit Namen, die sich nur für Dateisysteme unterscheiden, die diese Benennung unterstützen. Verwenden Sie bei verwendung dieser Option Sorgfalt, da dateien, die mit diesem Flag erstellt wurden, möglicherweise nicht von Anwendungen zugänglich sind, die für MS-DOS oder 16-Bit-Windows geschrieben sind. |
| FILE_FLAG_RANDOM_ACCESS 0x10000000 | Access soll zufällig sein. Das System kann dies als Hinweis verwenden, um das Zwischenspeichern von Dateien zu optimieren. Dieses Flag hat keine Auswirkung, wenn das Dateisystem keine zwischengespeicherte E/A und FILE_FLAG_NO_BUFFERINGunterstützt. Weitere Informationen finden Sie im Abschnitt "Zwischenspeicherungsverhalten" in diesem Thema. |
| 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 Redirection) nicht durch Prozesse geöffnet werden, die in Sitzung 0 ausgeführt werden. Dieses Kennzeichen hat keine Auswirkung für Anrufer, die sich nicht in Sitzung 0 befinden. Dieses Flag wird nur für Servereditionen von Windows unterstützt. |
| FILE_FLAG_SEQUENTIAL_SCAN 0x08000000 | Access soll von Anfang bis Ende sequenziell sein. Das System kann dies als Hinweis verwenden, um das Zwischenspeichern von Dateien zu optimieren. Dieses Flag sollte nicht verwendet werden, wenn Lesebehind (d. h. Umgekehrte Scans) verwendet werden. Dieses Flag hat keine Auswirkung, wenn das Dateisystem keine zwischengespeicherte E/A und FILE_FLAG_NO_BUFFERINGunterstützt. Weitere Informationen finden Sie im Abschnitt "Zwischenspeicherungsverhalten" in diesem Thema. |
| FILE_FLAG_WRITE_THROUGH 0x80000000 | Schreibvorgänge durchlaufen keinen Zwischencache, sie wechseln direkt auf den Datenträger. Weitere Informationen finden Sie im Abschnitt "Caching Behavior" in diesem Thema. |
Der dwFlagsAndAttributesParameter kann auch SQOS-Informationen angeben. Weitere Informationen finden Sie unter Identitätswechselebenen. Wenn die aufrufende Anwendung das SECURITY_SQOS_PRESENT Flag als Teil dwFlagsAndAttributesangibt, kann sie auch einen oder mehrere der folgenden Werte enthalten.
| Sicherheitskennzeichnung | Bedeutung |
|---|---|
| SECURITY_ANONYMOUS | Imitiert einen Client auf der Ebene des anonymen Identitätswechsels. |
| SECURITY_CONTEXT_TRACKING | Der Sicherheitsüberwachungsmodus ist dynamisch. Wenn dieses Flag nicht angegeben ist, ist der Sicherheitsüberwachungsmodus statisch. |
| SECURITY_DELEGATION | Imitiert einen Client auf Der Ebene des Identitätswechsels der Delegierung. |
| SECURITY_EFFECTIVE_ONLY | Nur die aktivierten Aspekte des Sicherheitskontexts des Clients stehen dem Server zur Verfügung. Wenn Sie dieses Kennzeichen nicht angeben, sind alle Aspekte des Sicherheitskontexts des Clients verfügbar. Auf diese Weise kann der Client die Gruppen und Berechtigungen einschränken, die ein Server beim Identitätswechsel des Clients verwenden kann. |
| SECURITY_IDENTIFICATION | Imitiert einen Client auf Identitätswechselebene. |
| SECURITY_IMPERSONATION | Identitätswechsel 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ültiger Handle für eine Vorlagendatei mit dem GENERIC_READ Zugriffsrecht. Die Vorlagendatei stellt Dateiattribute und erweiterte Attribute für die datei, 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 diskretionäre Zugriffssteuerungsliste 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 Gerät, das benannte Pipe oder den E-Mail-Steckplatz.
Wenn die Funktion fehlschlägt, wird der Rückgabewert INVALID_HANDLE_VALUE. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 10, Version 1803 |
| Header- | fileapifromapp.h |