CREATEFILE2_EXTENDED_PARAMETERS-Struktur (fileapi.h)
Enthält optionale erweiterte Parameter für CreateFile2.
Syntax
typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
LPSECURITY_ATTRIBUTES lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;
Member
dwSize
Enthält die Größe dieser Struktur, sizeof(CREATEFILE2_EXTENDED_PARAMETERS).
dwFileAttributes
Die Datei- oder Geräteattribute und -flags FILE_ATTRIBUTE_NORMAL der gängigste Standardwert für Dateien.
Dieser Parameter kann eine beliebige Kombination der verfügbaren Dateiattribute (FILE_ATTRIBUTE_*) enthalten. Alle anderen Dateiattribute überschreiben FILE_ATTRIBUTE_NORMAL.
Hinweis
Wenn CreateFile2 eine vorhandene Datei öffnet, kombiniert es im Allgemeinen die Dateiflags mit den Dateiattributen der vorhandenen Datei und ignoriert alle Dateiattribute, die als Teil von dwFlagsAndAttributes bereitgestellt werden. Spezielle Fälle werden unter Erstellen und Öffnen von Dateien beschrieben.
Einige der folgenden Dateiattribute und -flags gelten möglicherweise nur für Dateien und nicht unbedingt für alle anderen Gerätetypen, die createFile2 öffnen kann. Weitere Informationen finden Sie im Abschnitt "Hinweise" der CreateFile2 Referenzseite und unter Erstellen und Öffnen von Dateien.
Weitere Informationen zum erweiterten Zugriff auf Dateiattribute finden Sie unter SetFileAttributes. Eine vollständige Liste aller Dateiattribute mit ihren Werten und Beschreibungen finden Sie unter Dateiattributekonstanten.
| attribute | Bedeutung |
|---|---|
|
Die Datei sollte archiviert werden. Anwendungen verwenden dieses Attribut, um Dateien für die Sicherung oder Entfernung zu markieren. |
|
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 die Standardeinstellung 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. Dieses Flag wird nicht unterstützt, wenn es von einer Windows Store-App aufgerufen wird. |
|
Die Datei ist ausgeblendet. Schließen Sie es nicht in eine normale Verzeichnisauflistung ein. |
|
Eine Datei oder ein Verzeichnis, das mit Integrität konfiguriert ist. Für eine Datei verfügen alle Datenströme in der Datei über Integrität. Für ein Verzeichnis ist integrität die Standardeinstellung für neu erstellte Dateien und Unterverzeichnisse, es sei denn, der Aufrufer gibt etwas anderes an.
Dieses Flag wird nur im ReFS-Dateisystem unterstützt. |
|
Für die Datei sind keine anderen Attribute festgelegt. Dieses Attribut ist nur gültig, wenn es allein verwendet wird. |
|
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. |
|
Die Datei ist schreibgeschützter. Anwendungen können die Datei lesen, aber nicht in sie schreiben oder löschen. |
|
Die Datei ist Teil von oder wird ausschließlich von einem Betriebssystem verwendet. |
|
Die Datei wird für den temporären Speicher verwendet.
Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas. |
dwFileFlags
Dieser Parameter kann Kombinationen von Flags (FILE_FLAG_*) zur Steuerung des Zwischenspeicherverhaltens von Dateien oder Geräten, Zugriffsmodi und anderen speziellen Flags enthalten.
| Flag | Bedeutung |
|---|---|
|
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. |
|
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. |
|
Eine Gerätezuordnung ist eine Zuordnung zwischen DOS-Gerätenamen und Geräten im System und wird beim Auflösen von DOS-Namen verwendet. Für jeden Benutzer im System gibt es separate Gerätezuordnungen, und Benutzer können ihre eigenen Gerätezuordnungen verwalten. Während des Identitätswechsels wird in der Regel die Gerätezuordnung des identitätswechselten Benutzers verwendet. Wenn dieses Flag jedoch festgelegt ist, wird stattdessen die Gerätezuordnung des Prozessbenutzers verwendet. |
|
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 gelten strenge Anforderungen für die erfolgreiche Arbeit mit Dateien, die mit CreateFile2 mithilfe des FILE_FLAG_NO_BUFFERING-Flags geöffnet wurden. Ausführliche Informationen finden Sie unter Dateipufferung. |
|
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. |
|
Die normale Analysepunktverarbeitung erfolgt nicht. CreateFile2 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. |
|
Die Datei wird geöffnet, und eine opportunistische Sperre (Oplock) für die Datei wird als einzelner atomarer Vorgang angefordert. Das Dateisystem überprüft auf Oplocks, bevor es den Erstellungsvorgang ausführt, und schlägt beim Erstellen mit dem letzten Fehlercode ERROR_CANNOT_BREAK_OPLOCK fehl, wenn das Ergebnis wäre, einen vorhandenen Oplock zu unterbrechen.
Wenn Sie dieses Flag verwenden und Ihr Aufruf der CreateFile2-Funktion erfolgreich zurückgegeben wird, sollten Sie den ersten Vorgang für das Dateihandle ausführen, indem Sie einen Oplock anfordern, indem Sie die DeviceIOControl-Funktion aufrufen und dann FSCTL_REQUEST_OPLOCK oder einen der anderen opportunistischen Sperrvorgänge übergeben. Wenn Sie andere Dateisystemvorgänge mit dem Dateihandle ausführen, bevor Sie einen Oplock anfordern, kann es zu einem Deadlock kommen. Hinweis Sie können die CloseHandle-Funktion im Dateihandle sicher aufrufen, ohne zuerst einen Oplock anzufordern.
|
|
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. |
|
Der Zugriff erfolgt gemäß POSIX-Regeln. Dies schließt das Zulassen mehrerer Dateien mit Namen ein, die sich nur für den Fall unterscheiden, für Dateisysteme, die diese Benennung unterstützen. Verwenden Sie diese Option vorsichtig, da dateien, die mit diesem Flag erstellt wurden, möglicherweise nicht für Anwendungen zugänglich sind, die für MS-DOS oder 16-Bit-Windows geschrieben wurden. |
|
Der Zugriff ist als zufällig vorgesehen. Das System kann dies als Hinweis zur Optimierung der Zwischenspeicherung von Dateien verwenden.
Dieses Flag hat keine Auswirkung, wenn das Dateisystem zwischengespeicherte E/A- und FILE_FLAG_NO_BUFFERING nicht unterstützt. Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas. |
|
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 Auswirkung auf Anrufer, die sich nicht in Sitzung 0 befinden. Dieses Flag wird nur in Servereditionen von Windows unterstützt.
Windows Server 2008 R2 und Windows Server 2008: Dieses Flag wird vor Windows Server 2012 nicht unterstützt. |
|
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. Rückwärtsscans) verwendet wird. Dieses Flag hat keine Auswirkung, wenn das Dateisystem zwischengespeicherte E/A- und FILE_FLAG_NO_BUFFERING nicht unterstützt. Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas. |
|
Schreibvorgänge durchlaufen keinen Zwischencache, sie werden direkt auf den Datenträger weitergeleitet.
Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas. |
dwSecurityQosFlags
Der dwSecurityQosFlags-Parameter gibt SQOS-Informationen an. Weitere Informationen finden Sie unter Identitätswechselebenen.
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 von CreateFile2 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 einen Standardsicherheitsdeskriptor.
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.
CreateFile2 ignoriert den lpSecurityDescriptor-Member beim Öffnen einer vorhandenen Datei oder eines vorhandenen Geräts, verwendet aber weiterhin das bInheritHandle-Element .
Das bInheritHandle-Element der Struktur gibt an, ob das zurückgegebene Handle geerbt werden kann.
Weitere Informationen finden Sie im Abschnitt Hinweise des Themas CreateFile2 .
hTemplateFile
Ein gültiges Handle für eine Vorlagendatei mit dem GENERIC_READ Zugriffsrecht. Die Vorlagendatei stellt Dateiattribute und erweiterte Attribute für die zu erstellende Datei bereit.
Dieser Parameter kann NULL sein.
Beim Öffnen einer vorhandenen Datei ignoriert CreateFile2 diesen Parameter.
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.
Hinweise
Um eine Anwendung zu kompilieren, die die CREATEFILE2_EXTENDED_PARAMETERS-Struktur verwendet, definieren Sie das _WIN32_WINNT Makro als 0x0602 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.
Cacheverhalten
Mehrere der möglichen Werte für den dwFileFlags-Member werden verwendet, um zu steuern oder zu beeinflussen, wie die dem Handle zugeordneten Daten vom System zwischengespeichert werden. Sie lauten wie folgt:
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Wenn keines dieser Flags angegeben ist, verwendet das System ein Standardschema für die allgemeine Zwischenspeicherung. Andernfalls verhält sich die Systemzwischenspeicherung wie für jedes Flag angegeben.
Einige dieser Flags sollten nicht kombiniert werden. Für instance ist die Kombination von FILE_FLAG_RANDOM_ACCESS mit FILE_FLAG_SEQUENTIAL_SCAN eine Selbstzerstörung.
Das Angeben des FILE_FLAG_SEQUENTIAL_SCAN-Flags kann die Leistung von Anwendungen erhöhen, die große Dateien mit sequenziellem Zugriff lesen. Noch deutlicher kann die Leistung bei Anwendungen sein, die große Dateien meist sequenziell lesen, aber gelegentlich über kleine Bytesbereiche überspringen. Wenn eine Anwendung den Dateizeiger für den zufälligen Zugriff verschiebt, tritt höchstwahrscheinlich keine optimale Zwischenspeicherungsleistung auf. Der korrekte Betrieb ist jedoch weiterhin garantiert.
Die Flags FILE_FLAG_WRITE_THROUGH und FILE_FLAG_NO_BUFFERING sind unabhängig und können kombiniert werden.
Wenn FILE_FLAG_WRITE_THROUGH verwendet wird, aber nicht auch FILE_FLAG_NO_BUFFERING angegeben wird, sodass die Systemzwischenspeicherung wirksam ist, werden die Daten in den Systemcache geschrieben, aber ohne Verzögerung auf den Datenträger geleert.
Wenn FILE_FLAG_WRITE_THROUGH und FILE_FLAG_NO_BUFFERING angegeben sind, sodass die Systemzwischenspeicherung nicht wirksam ist, werden die Daten sofort auf den Datenträger geleert, ohne den Windows-Systemcache zu durchlaufen. Das Betriebssystem fordert auch eine Durchschreibung des lokalen Hardwarecaches der Festplatte auf persistente Medien an.
Hinweis
Nicht alle Festplattenhardware unterstützt diese Durchschreibfunktion.
Die ordnungsgemäße Verwendung des FILE_FLAG_NO_BUFFERING-Flags erfordert besondere Anwendungsüberlegungen. Weitere Informationen finden Sie unter Dateipufferung.
Eine Durchschreibanforderung über FILE_FLAG_WRITE_THROUGH bewirkt auch, dass NTFS alle Metadatenänderungen, z. B. eine Zeitstempelaktualisierung oder einen Umbenennungsvorgang, die sich aus der Verarbeitung der Anforderung ergeben, leert. Aus diesem Grund wird das FILE_FLAG_WRITE_THROUGH-Flag häufig mit dem FILE_FLAG_NO_BUFFERING-Flag als Ersatz für das Aufrufen der FlushFileBuffers-Funktion nach jedem Schreibvorgang verwendet, was zu unnötigen Leistungseinbußen führen kann. Wenn Sie diese Flags zusammen verwenden, werden diese Strafen vermieden. Allgemeine Informationen zum Zwischenspeichern von Dateien und Metadaten finden Sie unter Dateizwischenspeicherung.
Wenn FILE_FLAG_NO_BUFFERING mit FILE_FLAG_OVERLAPPED kombiniert wird, bieten die Flags maximale asynchrone Leistung, da die E/A-Vorgänge nicht von den synchronen Vorgängen des Speicher-Managers abhängig sind. Einige E/A-Vorgänge nehmen jedoch mehr Zeit in Anspruch, da die Daten nicht im Cache gespeichert werden. Außerdem können die Dateimetadaten weiterhin zwischengespeichert werden (z. B. beim Erstellen einer leeren Datei). Um sicherzustellen, dass die Metadaten auf den Datenträger geleert werden, verwenden Sie die FlushFileBuffers-Funktion .
Die Angabe des FILE_ATTRIBUTE_TEMPORARY-Attributs führt dazu, dass Dateisysteme das Zurückschreiben von Daten in den Massenspeicher vermeiden, wenn genügend Cachespeicher verfügbar ist, da eine Anwendung eine temporäre Datei löscht, nachdem ein Handle geschlossen wurde. In diesem Fall kann das System das Schreiben der Daten vollständig vermeiden. Obwohl die Datenzwischenspeicherung nicht direkt wie die zuvor erwähnten Flags gesteuert wird, weist das FILE_ATTRIBUTE_TEMPORARY-Attribut das System an, so viel wie möglich im Systemcache zu speichern, ohne zu schreiben, und kann daher für bestimmte Anwendungen von Bedenklich sein.
Synchrone und asynchrone E/A-Handles
CreateFile2 ermöglicht das Erstellen eines Datei- oder Gerätehandles, das entweder synchron oder asynchron ist. Ein synchrones Handle verhält sich so, dass E/A-Funktionsaufrufe mit diesem Handle blockiert werden, bis sie abgeschlossen sind, während ein asynchrones Dateihandle es ermöglicht, dass das System sofort von E/A-Funktionsaufrufen zurückgibt, unabhängig davon, ob er den E/A-Vorgang abgeschlossen hat oder nicht. Wie bereits erwähnt, wird dieses synchrone und asynchrone Verhalten bestimmt, indem FILE_FLAG_OVERLAPPED innerhalb des dwFileFlags-Members der CREATEFILE2_EXTENDED_PARAMETERS Struktur angegeben wird, die im pCreateExParams-Parameter übergeben wird. Bei der Verwendung asynchroner E/A-Vorgänge gibt es mehrere Komplexitäten und potenzielle Fallstricke; Weitere Informationen finden Sie unter Synchrone und asynchrone E/A.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 8 [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2012 [Desktop-Apps | UWP-Apps] |
| Kopfzeile | fileapi.h (Einschließen von Windows.h) |