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;
Angehörige
dwSize
Enthält die Größe dieser Struktur, sizeof(CREATEFILE2_EXTENDED_PARAMETERS).
dwFileAttributes
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.
Anmerkung
Wenn CreateFile2 eine vorhandene Datei öffnet, kombiniert es in der Regel die Dateikennzeichnungen mit den Dateiattributen der vorhandenen Datei und ignoriert alle Dateiattribute, die als Teil dwFlagsAndAttributesbereitgestellt werden. Spezielle Fälle sind in Erstellen und Öffnen von Dateiendetailliert beschrieben.
Einige der folgenden Dateiattribute und Flags gelten möglicherweise nur für Dateien und nicht unbedingt alle anderen Gerätetypen, die CreateFile2 öffnen können. Weitere Informationen finden Sie im Abschnitt Anmerkungen der Referenzseite CreateFile2 und 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 File Attribute Constants.
| Attribut | 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. 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. Dieses Kennzeichen wird nicht unterstützt, wenn sie von einer Windows Store-App aufgerufen wird. |
|
Die Datei ist ausgeblendet. Fügen Sie sie nicht in eine normale Verzeichnisauflistung ein. |
|
Eine Datei oder ein Verzeichnis, die 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 die Integrität die Standardeinstellung für neu erstellte Dateien und Unterverzeichnisse, es sei denn, der Aufrufer gibt andernfalls 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, der hierarchischen Speicherverwaltungssoftware, verwendet. Anwendungen sollten dieses Attribut nicht willkürlich ändern. |
|
Die Datei ist schreibgeschützt. Anwendungen können die Datei lesen, aber nicht in die Datei schreiben oder löschen. |
|
Die Datei ist Teil oder wird ausschließlich von einem Betriebssystem verwendet. |
|
Die Datei wird für temporären Speicher verwendet.
Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhalten dieses Themas. |
dwFileFlags
Dieser Parameter kann Kombinationen von Flags (FILE_FLAG_*) zur Kontrolle des Datei- oder Gerätezwischenspeicherungsverhaltens, Zugriffsmodi und anderen speziellen Flags enthalten.
| Flagge | 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 anstelle eines Dateihandles an einige Funktionen übergeben werden. Weitere Informationen finden Sie im Abschnitt "Hinweise". |
|
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. |
|
Eine Gerätezuordnung ist eine Zuordnung zwischen DOS-Gerätenamen und -Geräten im System und wird beim Auflösen von DOS-Namen verwendet. Separate Gerätezuordnungen sind für jeden Benutzer im System vorhanden, und Benutzer können ihre eigenen Gerätezuordnungen verwalten. Normalerweise wird während des Identitätswechsels die Gerätezuordnung des imitierten Benutzers verwendet. Wenn diese Kennzeichnung festgelegt ist, wird stattdessen die Gerätezuordnung des Prozessbenutzers verwendet. |
|
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 CreateFile2 mithilfe des FILE_FLAG_NO_BUFFERING Flags geöffnet wurden, ausführliche Informationen finden Sie unter Dateipufferung. |
|
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. |
|
Normale Analysepunkt Verarbeitung 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, 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". |
|
Die Datei wird geöffnet, und eine opportunistische Sperre (Oplock) auf der Datei wird als einzelner atomischer Vorgang angefordert. Das Dateisystem sucht vor dem Ausführen des Erstellungsvorgangs nach Oplocks und schlägt die Erstellung mit einem letzten Fehlercode von ERROR_CANNOT_BREAK_OPLOCK fehl, wenn das Ergebnis ein vorhandenes Oplock unterbrechen würde.
Wenn Sie dieses Flag und ihren Aufruf der CreateFile2--Funktion erfolgreich zurückgeben, besteht der erste Vorgang, den Sie für das Dateihandle ausführen sollten, darin, einen Oplock anzufordern, indem sie die DeviceIOControl--Funktion aufruft und dann FSCTL_REQUEST_OPLOCK oder einen der anderen Opportunistic Lock Operationsübergeben. Wenn Sie andere Dateisystemvorgänge mit dem Dateihandle ausführen, bevor Sie ein Oplock anfordern, kann ein Deadlock auftreten.
Hinweis Sie können die CloseHandle-Funktion sicher auf dem Dateihandle aufrufen, ohne zuerst ein Oplock anzufordern.
|
|
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 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 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. |
|
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 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 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.
Windows Server 2008 R2 und Windows Server 2008: Dieses Flag wird vor Windows Server 2012 nicht unterstützt. |
|
Access soll von Anfang bis Ende sequenziell sein. Das System kann dies als Hinweis verwenden, um das Zwischenspeichern von Dateien zu optimieren.
Dieses Kennzeichen sollte nicht verwendet werden, wenn Lesebehind (d. h. Rückwärtsscans) 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 dieses Themas. |
|
Schreibvorgänge durchlaufen keinen Zwischencache, sie wechseln direkt auf den Datenträger.
Weitere Informationen finden Sie im Abschnitt Zwischenspeicherungsverhaltens 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 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.
CreateFile2 ignoriert das lpSecurityDescriptor Member beim Öffnen einer vorhandenen Datei oder eines vorhandenen Geräts, verwendet aber weiterhin das bInheritHandle Member.
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ü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 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.
Bemerkungen
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.
Zwischenspeicherungsverhalten
Mehrere der möglichen Werte für das dwFileFlags Member werden verwendet, um zu steuern oder zu beeinflussen, wie die dem Handle zugeordneten Daten vom System zwischengespeichert werden. Sie sind:
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Wenn keine dieser Flags angegeben ist, verwendet das System ein standardmäßiges allgemeines Zwischenspeicherungsschema. Andernfalls verhält sich die Systemzwischenspeicherung wie für jedes Flag angegeben.
Einige dieser Kennzeichen sollten nicht kombiniert werden. Zum Beispiel ist die Kombination von FILE_FLAG_RANDOM_ACCESS mit FILE_FLAG_SEQUENTIAL_SCAN selbst zu besiegen.
Die Angabe des FILE_FLAG_SEQUENTIAL_SCAN-Flags kann die Leistung für Anwendungen erhöhen, die große Dateien mit sequenziellem Zugriff lesen. Leistungssteigerungen können für Anwendungen, die große Dateien hauptsächlich sequenziell lesen, noch deutlicher sein, aber gelegentlich über kleine Bytebereiche vorwärts springen. 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 gewährleistet.
Die Kennzeichen 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 FILE_FLAG_NO_BUFFERING nicht ebenfalls angegeben ist, sodass das Zwischenspeichern des Systems 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 das Zwischenspeichern des Systems nicht wirksam ist, werden die Daten sofort auf den Datenträger geleert, ohne den Windows-Systemcache zu durchlaufen. Das Betriebssystem fordert außerdem einen Schreibvorgang des lokalen Hardwarecaches der Festplatte auf persistente Medien an.
Anmerkung
Nicht alle Festplattenhardware unterstützt diese Schreibzugriffsfunktion.
Die ordnungsgemäße Verwendung des FILE_FLAG_NO_BUFFERING-Flags erfordert besondere Anwendungsüberlegungen. Weitere Informationen finden Sie unter Dateipufferung.
Eine Schreib-Through-Anforderung über FILE_FLAG_WRITE_THROUGH führt auch dazu, dass NTFS metadatenänderungen, z. B. ein Zeitstempelupdate oder einen Umbenennungsvorgang, die aus der Verarbeitung der Anforderung resultieren, leeren. 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 Schreiben verwendet, was unnötige Leistungseinbußen verursachen kann. Durch die gemeinsame Verwendung dieser Kennzeichnungen werden diese Sanktionen vermieden. Allgemeine Informationen zum Zwischenspeichern von Dateien und Metadaten finden Sie unter Dateizwischenspeicherung.
Wenn FILE_FLAG_NO_BUFFERING mit FILE_FLAG_OVERLAPPEDkombiniert wird, bieten die Flags eine maximale asynchrone Leistung, da die E/A nicht auf die synchronen Vorgänge des Speicher-Managers basiert. Einige E/A-Vorgänge dauern jedoch mehr Zeit, da 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 bewirkt, dass Dateisysteme das Schreiben 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 auf die gleiche Weise wie die zuvor erwähnten Flags gesteuert wird, weist das attribut FILE_ATTRIBUTE_TEMPORARY das System an, so viel wie möglich im Systemcache zu speichern, ohne zu schreiben und daher für bestimmte Anwendungen zu sorgen.
Synchrone und asynchrone E/A-Handles
CreateFile2- bietet das Erstellen eines Datei- oder Gerätehandles, das synchron oder asynchron ist. Ein synchroner Handle verhält sich so, dass E/A-Funktionsaufrufe mit diesem Handle blockiert werden, bis sie abgeschlossen sind, während ein asynchroner Dateihandle es dem System ermöglicht, sofort von E/A-Funktionsaufrufen zurückzugeben, 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 Member 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
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 8 [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2012 [Desktop-Apps | UWP-Apps] |
| Header- | fileapi.h (include Windows.h) |