IoCreateFileEx-Funktion (ntddk.h)

Artikel
03/08/2023

Die IoCreateFileEx-Routine bewirkt entweder, dass eine neue Datei oder ein neues Verzeichnis erstellt wird, oder öffnet eine vorhandene Datei, ein vorhandenes Gerät, ein Verzeichnis oder ein Volume und gibt dem Aufrufer ein Handle für das Dateiobjekt. Dateisystemfiltertreiber (Legacyfiltertreiber) rufen diese Routine auf.

Syntax

NTSTATUS IoCreateFileEx(
  [out]          PHANDLE                   FileHandle,
  [in]           ACCESS_MASK               DesiredAccess,
  [in]           POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]          PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional] PLARGE_INTEGER            AllocationSize,
  [in]           ULONG                     FileAttributes,
  [in]           ULONG                     ShareAccess,
  [in]           ULONG                     Disposition,
  [in]           ULONG                     CreateOptions,
  [in, optional] PVOID                     EaBuffer,
  [in]           ULONG                     EaLength,
  [in]           CREATE_FILE_TYPE          CreateFileType,
  [in, optional] PVOID                     InternalParameters,
  [in]           ULONG                     Options,
  [in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Parameter

[out] FileHandle

Ein Zeiger auf eine Variable, die das Dateihandle empfängt, wenn der Aufruf erfolgreich ist. Der Treiber muss das Handle mit ZwClose schließen, sobald das Handle nicht mehr verwendet wird.

[in] DesiredAccess

Eine Bitmaske von Flags (siehe ACCESS_MASK), die den Typ des Zugriffs angibt, den der Aufrufer für die Datei oder das Verzeichnis benötigt. Dieser Satz systemdefinierter DesiredAccess-Flags bestimmt die folgenden spezifischen Zugriffsrechte für Dateiobjekte.

DesiredAccess-Flag	Bedeutung
Delete	Die Datei kann gelöscht werden.
FILE_READ_DATA	Aus der Datei können Daten gelesen werden.
FILE_READ_ATTRIBUTES	FileAttributes-Flags , wie unten beschrieben, können gelesen werden.
FILE_READ_EA	Erweiterte Attribute (EAs), die der Datei zugeordnet sind, können gelesen werden.
READ_CONTROL	Die Zugriffssteuerungsliste (Access Control List, ACL) und die Besitzinformationen, die der Datei zugeordnet sind, können gelesen werden.
FILE_WRITE_DATA	In die Datei können Daten geschrieben werden.
FILE_WRITE_ATTRIBUTES	FileAttributes-Flags können geschrieben werden.
FILE_WRITE_EA	EAs, die der Datei zugeordnet sind, können geschrieben werden.
FILE_APPEND_DATA	Daten können an die Datei angefügt werden.
WRITE_DAC	Die der Datei zugeordnete DACL (Discretionary Access Control List) kann geschrieben werden.
WRITE_OWNER	Besitzerinformationen, die der Datei zugeordnet sind, können geschrieben werden.
SYNCHRONIZE	Der Aufrufer kann den Abschluss eines E/A-Vorgangs synchronisieren, indem er darauf wartet, dass der zurückgegebene FileHandle-Wert auf den Signaled-Zustand festgelegt wird. Dieses Flag muss festgelegt werden, wenn das Flag CreateOptions FILE_SYNCHRONOUS_IO_ALERT oder FILE_SYNCHRONOUS_IO_NONALERT festgelegt ist.
FILE_EXECUTE	Daten können mithilfe der System paging-E/A aus der Datei in den Arbeitsspeicher eingelesen werden.

Alternativ können Sie für jedes Dateiobjekt, das kein Verzeichnis darstellt, eines oder mehrere der folgenden generischen ACCESS_MASK-Flags angeben. Die STANDARD_RIGHTS_XXX-Flags sind vordefinierte Systemwerte, die zum Erzwingen von Sicherheit für Systemobjekte verwendet werden. Sie können diese generischen Flags auch mit zusätzlichen Flags aus der vorherigen Tabelle kombinieren.

Gewünschter Zugriff auf Dateiwerte	Zuordnung zu DesiredAccess-Flags
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SYNCHRONIZE.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SYNCHRONIZE.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, FILE_READ_ATTRIBUTES, FILE_EXECUTE.

Für Verzeichnisse (das FILE_DIRECTORY_FILE CreateOptions-Flag festgelegt ist), können Sie eines oder mehrere der folgenden ACCESS_MASK-Flags angeben, die Sie auch mit allen kompatiblen Flags kombinieren können, die zuvor beschrieben wurden.

Gewünschter Zugriff auf Verzeichniswerte	Bedeutung
FILE_LIST_DIRECTORY	Dateien im Verzeichnis können aufgelistet werden.
FILE_TRAVERSE	Das Verzeichnis kann durchquert werden; Das heißt, es kann Teil des Pfadnamens einer Datei sein.

Die Flags FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE und FILE_APPEND_DATA DesiredAccess sind mit dem Erstellen oder Öffnen einer Verzeichnisdatei nicht kompatibel.

[in] ObjectAttributes

Zeiger auf eine OBJECT_ATTRIBUTES Struktur, die bereits von der InitializeObjectAttributes-Routine initialisiert wurde. Wenn der Aufrufer im Systemprozesskontext ausgeführt wird, kann dieser Parameter NULL sein. Andernfalls muss der Aufrufer das attribut OBJ_KERNEL_HANDLE im Aufruf auf InitializeObjectAttributes festlegen. Elemente dieser Struktur für ein Dateiobjekt umfassen Folgendes.

Mitglied	Wert
ULONG-Länge	Die Anzahl der Bytes der angegebenen ObjectAttributes-Daten . Dieser Wert muss mindestens `sizeof(OBJECT_ATTRIBUTES)`sein.
PUNICODE_STRING ObjectName	Zeiger auf eine gepufferte Unicode-Zeichenfolge, die den Namen der zu erstellenden oder zu öffnenden Datei enthält. Dieser Wert muss eine vollqualifizierte Dateispezifikation sein, es sei denn, es handelt sich um den Namen einer Datei relativ zum durch RootDirectory angegebenen Verzeichnis. Beispiel: "\Device\Floppy1\myfile.dat" oder "?? \B:\myfile.dat" kann die vollqualifizierte Dateispezifikation sein, sofern der Diskettenlaufwerktreiber und das überladene Dateisystem bereits geladen sind. (Hinweis: "??" ersetzt "\DosDevices" durch den Namen des Win32-Objektnamespace. "\DosDevices" funktioniert weiterhin, aber "??" wird vom Objekt-Manager schneller übersetzt.)
HANDLE RootDirectory	Optionales Handle für ein Verzeichnis, das durch einen vorherigen Aufruf von IoCreateFileEx abgerufen wurde. Wenn dieser Wert NULL ist, muss das ObjectName-Element eine vollqualifizierte Dateispezifikation sein, die den vollständigen Pfad zur Zieldatei enthält. Wenn dieser Wert nicht NULL ist, gibt das ObjectName-Element einen Dateinamen relativ zu diesem Verzeichnis an.
PSECURITY_DESCRIPTOR SecurityDescriptor	Optionaler Sicherheitsdeskriptor, der auf eine Datei angewendet werden soll. AcLs, die von einem solchen Sicherheitsdeskriptor angegeben werden, werden nur auf die Datei angewendet, wenn sie erstellt wird. Wenn der Wert NULL ist, wenn eine Datei erstellt wird, ist die in der Datei platzierte ACL dateisystemabhängig. Die meisten Dateisysteme geben einen Teil einer solchen ACL aus der übergeordneten Verzeichnisdatei in Kombination mit der Standard-ACL des Aufrufers weiter.
ULONG-Attribute	Ein Satz von Flags, der die Dateiobjektattribute steuert. Wenn der Aufrufer im Systemprozesskontext ausgeführt wird, kann dieser Parameter null sein. Andernfalls muss der Aufrufer das flag OBJ_KERNEL_HANDLE festlegen. Der Aufrufer kann optional auch das flag OBJ_CASE_INSENSITIVE festlegen, was angibt, dass name-lookup code die Groß-/Kleinschreibung von ObjectName ignorieren sollte, anstatt eine Suche nach exakter Übereinstimmung durchzuführen.

[out] IoStatusBlock

Zeiger auf eine Variable vom Typ IO_STATUS_BLOCK, die die endgültige Abschluss-status und Informationen zum angeforderten Vorgang empfängt. Bei der Rückgabe von IoCreateFileEx enthält der Information-Member der Variablen einen der folgenden Werte:

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Gibt optional die anfängliche Zuordnungsgröße in Byte für die Datei an. Ein Wert ungleich null hat keine Auswirkung, es sei denn, die Datei wird erstellt, überschrieben oder ersetzt.

[in] FileAttributes

Explizit angegebene Attribute werden nur angewendet, wenn die Datei erstellt, abgelöst oder in einigen Fällen überschrieben wird. Standardmäßig ist dieser Wert FILE_ATTRIBUTE_NORMAL, der von jedem anderen Flag oder einer Kombination (durch einen bitweisen OR-Vorgang) kompatibler Flags überschrieben werden kann. Mögliche FileAttributes-Flags umfassen Folgendes.

FileAttributes-Flags	Bedeutung
FILE_ATTRIBUTE_NORMAL	Eine Datei mit Standardattributen sollte erstellt werden.
FILE_ATTRIBUTE_READONLY	Eine schreibgeschützte Datei sollte erstellt werden.
FILE_ATTRIBUTE_HIDDEN	Eine ausgeblendete Datei sollte erstellt werden.
FILE_ATTRIBUTE_SYSTEM	Eine Systemdatei sollte erstellt werden.
FILE_ATTRIBUTE_ARCHIVE	Die Datei sollte so markiert werden, dass sie archiviert wird.
FILE_ATTRIBUTE_TEMPORARY	Eine temporäre Datei sollte erstellt werden.

[in] ShareAccess

Gibt den Typ des Freigabezugriffs auf die Datei an, den der Aufrufer als null oder 1 oder eine Kombination der folgenden Flags verwenden möchte. Legen Sie diesen Parameter auf Null fest, um exklusiven Zugriff anzufordern. Wenn das flag IO_IGNORE_SHARE_ACCESS_CHECK im Options-Parameter angegeben ist, ignoriert der E/A-Manager den ShareAccess-Parameter . Das Dateisystem kann jedoch weiterhin Zugriffsprüfungen durchführen. Daher ist es wichtig, den gewünschten Freigabemodus für diesen Parameter anzugeben, auch wenn Sie das flag IO_IGNORE_SHARE_ACCESS_CHECK verwenden. Geben Sie alle folgenden Freigabezugriffsflags an, um Fehler bei der Freigabeverletzung zu vermeiden.

ShareAccess-Flags	Bedeutung
FILE_SHARE_READ	Die Datei kann für den Lesezugriff durch die Dateierstellungsaufrufe anderer Threads geöffnet werden.
FILE_SHARE_WRITE	Die Datei kann für den Schreibzugriff durch die Dateierstellungsaufrufe anderer Threads geöffnet werden.
FILE_SHARE_DELETE	Die Datei kann für den Löschzugriff durch die Dateierstellungsaufrufe anderer Threads geöffnet werden.

Gerätetreiber und Zwischentreiber legen ShareAccess in der Regel auf Null fest, wodurch der Aufrufer exklusiven Zugriff auf die geöffnete Datei erhält.

[in] Disposition

Wert, der bestimmt, wie die Datei behandelt werden soll, wenn die Datei bereits vorhanden ist. Die Disposition kann eine der folgenden Sein:

Wert	Bedeutung
FILE_SUPERSEDE	Wenn die Datei bereits vorhanden ist, ersetzen Sie sie durch die angegebene Datei. Wenn sie nicht vorhanden ist, erstellen Sie die angegebene Datei.
FILE_CREATE	Wenn die Datei bereits vorhanden ist, schlägt die Anforderung fehl, und erstellen oder öffnen Sie die angegebene Datei nicht. Wenn sie nicht vorhanden ist, erstellen Sie die angegebene Datei.
FILE_OPEN	Wenn die Datei bereits vorhanden ist, öffnen Sie sie, anstatt eine neue Datei zu erstellen. Wenn sie nicht vorhanden ist, schlägt die Anforderung fehl, und erstellen Sie keine neue Datei.
FILE_OPEN_IF	Wenn die Datei bereits vorhanden ist, öffnen Sie sie. Wenn sie nicht vorhanden ist, erstellen Sie die angegebene Datei.
FILE_OVERWRITE	Wenn die Datei bereits vorhanden ist, öffnen Sie sie, und überschreiben Sie sie. Wenn sie nicht vorhanden ist, schlägt die Anforderung fehl.
FILE_OVERWRITE_IF	Wenn die Datei bereits vorhanden ist, öffnen Sie sie, und überschreiben Sie sie. Wenn sie nicht vorhanden ist, erstellen Sie die angegebene Datei.

[in] CreateOptions

Gibt die Optionen an, die beim Erstellen oder Öffnen der Datei angewendet werden sollen, als kompatible Kombination der folgenden Flags.

CreateOptions-Flag	Bedeutung
FILE_DIRECTORY_FILE (0x00000001)	Die Datei, die erstellt oder geöffnet wird, ist eine Verzeichnisdatei. Mit diesem Flag muss der Dispositionsparameter auf einen der FILE_CREATE, FILE_OPEN oder FILE_OPEN_IF festgelegt werden. CreateOptions-Flags , die mit diesem Flag kompatibel sind, sind wie folgt: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT und FILE_OPEN_BY_FILE_ID.
FILE_WRITE_THROUGH (0x00000002)	Systemdienste, Dateisysteme und Treiber, die Daten in die Datei schreiben, müssen die Daten tatsächlich in die Datei übertragen, bevor ein angeforderter Schreibvorgang als abgeschlossen betrachtet wird.
FILE_SEQUENTIAL_ONLY (0x00000004)	Alle Zugriffe auf die Datei erfolgen sequenziell.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	Die Datei kann nicht in den internen Puffern eines Treibers zwischengespeichert oder gepuffert werden. Dieses Flag ist mit dem DesiredAccess-FILE_APPEND_DATA-Flagnicht kompatibel.
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	Alle Vorgänge für die Datei werden synchron ausgeführt. Jede Wartezeit im Namen des Anrufers unterliegt einer vorzeitigen Beendigung von Warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionskontext verwaltet. Wenn dieses Flag festgelegt ist, muss auch das DesiredAccess SYNCHRONIZE-Flag festgelegt werden, damit der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	Alle Vorgänge für die Datei werden synchron ausgeführt. Wartezeiten im System, um E/A-Warteschlangen und -Abschluss zu synchronisieren, unterliegen keinen Warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionskontext verwaltet. Wenn dieses Flag festgelegt ist, muss auch das DesiredAccess SYNCHRONIZE-Flag festgelegt werden, damit der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet.
FILE_NON_DIRECTORY_FILE (0x00000040)	Die datei, die geöffnet wird, darf keine Verzeichnisdatei sein, andernfalls tritt bei diesem Aufruf ein Fehler auf. Das geöffnete Dateiobjekt kann eine Datendatei darstellen. ein logisches, virtuelles oder physisches Gerät; oder ein Volume.
FILE_CREATE_TREE_CONNECTION (0x00000080)	Erstellen Sie eine Strukturverbindung für diese Datei, um sie über das Netzwerk zu öffnen.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Schließen Sie diesen Vorgang sofort mit einem alternativen Erfolgscode ab, wenn die Zieldatei oplocked ist, anstatt den Thread des Aufrufers zu blockieren. Wenn die Datei oplocked ist, hat ein anderer Aufrufer bereits Zugriff auf die Datei über das Netzwerk.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Wenn die erweiterten Attribute für eine vorhandene Datei, die geöffnet wird, angeben, dass der Aufrufer erweiterte Attribute verstehen muss, um die Datei ordnungsgemäß zu interpretieren, schlägt diese Anforderung fehl, da der Aufrufer nicht versteht, wie mit erweiterten Attributen umgegangen werden soll.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Reserviert für die Systemnutzung; nicht verwenden.
FILE_RANDOM_ACCESS (0x00000800)	Zugriffe auf die Datei können zufällig erfolgen, sodass keine sequenziellen Read-Ahead-Vorgänge für die Datei von Dateisystemen oder dem Betriebssystem ausgeführt werden sollten.
FILE_DELETE_ON_CLOSE (0x00001000)	Löschen Sie die Datei, wenn das letzte Handle an FltClose übergeben wird.
FILE_OPEN_BY_FILE_ID (0x00002000)	Die Datei wird nach ID geöffnet. Der Dateiname enthält den Namen eines Geräts und eine 64-Bit-ID, die zum Öffnen der Datei verwendet werden soll.
FILE_OPEN_FOR_BACKUP_INTENT (0x000004000)	Die Datei wird zur Sicherungsabsicht geöffnet. Daher sollte das System bestimmte Zugriffsrechte überprüfen und dem Aufrufer die entsprechenden Zugriffe auf die Datei gewähren, bevor die Eingabe DesiredAccess mit dem Sicherheitsdeskriptor der Datei überprüft wird.
FILE_NO_COMPRESSION (0x00008000)	Unterdrücken der Vererbung von FILE_ATTRIBUTE_COMPRESSED aus dem übergeordneten Verzeichnis. Dies ermöglicht die Erstellung einer nicht komprimierten Datei in einem Verzeichnis, das als komprimiert markiert ist.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000)	Die Datei wird geöffnet, und eine opportunistische Sperre (Oplock) für die Datei wird als einzelner atomischer Vorgang angefordert. Das Dateisystem sucht nach Oplocks, bevor der Erstellungsvorgang ausgeführt wird, und der Erstellungsvorgang schlägt mit dem Rückgabecode STATUS_CANNOT_BREAK_OPLOCK fehl, wenn der Erstellungsvorgang einen vorhandenen Oplock unterbrechen würde. Dieses Flag ist in Windows 7, Windows Server 2008 R2 und höher unter Windows-Betriebssystemen verfügbar.
FILE_DISALLOW_EXCLUSIVE (0x00020000)	Wenn beim Öffnen einer vorhandenen Datei FILE_SHARE_READ nicht angegeben ist und dateisystemzugriffsprüfungen dem Aufrufer keinen Schreibzugriff auf die Datei gewähren würden, schlägt dieses Öffnen mit STATUS_ACCESS_DENIED fehl. Dies war das Standardverhalten vor Windows 7.
FILE_SESSION_AWARE (0x00040000)	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. Dieses Flag wird vor Windows Server 2012 nicht unterstützt.
FILE_RESERVE_OPFILTER (0x00100000)	Dieses Flag ermöglicht es einer Anwendung, eine oplock(opportunistische) Filtersperre anzufordern, um zu verhindern, dass andere Anwendungen Freigabeverletzungen erhalten. Wenn bereits geöffnete Handles vorhanden sind, schlägt die Erstellungsanforderung mit STATUS_OPLOCK_NOT_GRANTED fehl. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
FILE_OPEN_REPARSE_POINT (0x00200000)	Öffnen Sie eine Datei mit einem Analysepunkt, und umgehen Sie die normale Analysepunktverarbeitung für die Datei. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
FILE_OPEN_NO_RECALL (0x00400000)	Weist filter, die Offlinespeicher oder Virtualisierung durchführen, an, den Inhalt der Datei aufgrund dieses Öffnens nicht zurückzurufen.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000)	Dieses Flag weist das Dateisystem an, den Benutzer zu erfassen, der dem aufrufenden Thread zugeordnet ist. Alle nachfolgenden Aufrufe von FltQueryVolumeInformation oder ZwQueryVolumeInformationFile mithilfe des zurückgegebenen Handles gehen vom erfassten Benutzer und nicht vom aufrufenden Benutzer zu diesem Zeitpunkt aus, um den für den Aufrufer verfügbaren freien Speicherplatz zu berechnen. Dies gilt für die folgenden FsInformationClass-Werte: FileFsSizeInformation, FileFsFullSizeInformation und FileFsFullSizeInformationEx.

[in, optional] EaBuffer

Ein Zeiger auf eine vom Aufrufer bereitgestellte Variable vom Typ FILE_FULL_EA_INFORMATION , die ea-Informationen (Extended Attribute) enthält, die auf die Datei angewendet werden sollen. Für Geräte- und Zwischentreiber muss dieser Parameter NULL sein.

[in] EaLength

Länge von EaBuffer in Bytes. Für Gerätetreiber und Zwischentreiber muss dieser Parameter null sein.

[in] CreateFileType

Treiber müssen diesen Parameter auf CreateFileTypeNone festlegen.

[in, optional] InternalParameters

Treiber müssen diesen Parameter auf NULL festlegen.

[in] Options

Gibt Optionen an, die während der Generierung der Erstellungsanforderung verwendet werden sollen. Null oder mehr der folgenden Bitflagswerte können verwendet werden.

Optionsflag	Bedeutung
IO_FORCE_ACCESS_CHECK	Der E/A-Manager muss die Erstellungsanforderung anhand des Sicherheitsdeskriptors der Datei überprüfen. Weitere Informationen finden Sie in den Hinweisen.
IO_IGNORE_SHARE_ACCESS_CHECK	Der E/A-Manager sollte keine Freigabezugriffsprüfungen für das Dateiobjekt durchführen, nachdem es erstellt wurde. Möglicherweise führt das Dateisystem diese Überprüfungen jedoch weiterhin durch.
IO_STOP_ON_SYMLINK	Wenn beim Öffnen oder Erstellen der Datei eine Verbindung, eine symbolische Verknüpfung oder ein globaler Analysepunkt gefunden wird, gibt der E/A-Manager STATUS_STOPPED_ON_SYMLINK zurück. Darüber hinaus wird in IoStatusBlock-Information> eine REPARSE_DATA_BUFFER-Struktur zurückgegeben. Der Aufrufer ist für die Freigabe der REPARSE_DATA_BUFFER-Struktur verantwortlich.
IO_OPEN_TARGET_DIRECTORY	Öffnen Sie das übergeordnete Verzeichnis der Datei.

[in, optional] DriverContext

Ein optionaler Zeiger auf eine IO_DRIVER_CREATE_CONTEXT-Struktur , die zuvor von der IoInitializeDriverCreateContext-Routine initialisiert wurde. Die IO_DRIVER_CREATE_CONTEXT-Struktur kann verwendet werden, um zusätzliche Parameter an die Routinen IoCreateFileEx undFltCreateFileEx2 zu übergeben. Weitere Informationen finden Sie im abschnitt "Hinweise".

Rückgabewert

IoCreateFileEx gibt entweder STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. einen der folgenden.

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	IoCreateFileEx gibt diesen status Wert zurück, wenn der DriverContext-Parameter nicht NULL ist und das angegebene Geräteobjekt nicht an den Dateisystemtreiberstapel für das im Datei- oder Verzeichnisnamen angegebene Volume angefügt ist. Dieses Geräteobjekt wird vom DeviceObjectHint-Element der IO_DRIVER_CREATE_CONTEXT-Struktur angegeben. Weitere Informationen finden Sie unter IO_DRIVER_CREATE_CONTEXT.
STATUS_MOUNT_POINT_NOT_RESOLVED	IoCreateFileEx gibt diesen status Wert zurück, wenn der DriverContext-Parameter nicht NULL ist und wenn der Datei- oder Verzeichnisname einen Bereitstellungspunkt enthält, der in ein anderes Volume als das Volume aufgelöst wird, an das das angegebene Geräteobjekt angefügt ist. Dieses Geräteobjekt wird vom DeviceObjectHint-Element der IO_DRIVER_CREATE_CONTEXT-Struktur angegeben. Weitere Informationen finden Sie unter IO_DRIVER_CREATE_CONTEXT.
STATUS_OBJECT_PATH_SYNTAX_BAD	IoCreateFileEx gibt diesen status Wert zurück, wenn der ObjectAttributes-Parameter kein RootDirectory-Element enthielt, aber das ObjectName-Element in der OBJECT_ATTRIBUTES-Struktur eine leere Zeichenfolge war oder kein OBJECT_NAME_PATH_SEPARATOR Zeichen enthielt. Dies weist auf eine falsche Syntax für den Objektpfad hin.
STATUS_STOPPED_ON_SYMLINK	IoCreateFileEx gibt diesen status Wert zurück, wenn das Options-Parameterflag IO_STOP_ON_SYMLINK festgelegt ist und beim Öffnen oder Erstellen der Datei ein symbolischer Link gefunden wird.

Wenn die IoCreateFileEx-Routine einen Fehler status zurückgibt, kann der Aufrufer zusätzliche Informationen zur Fehlerursache finden, indem er den IoStatusBlock-Parameter überprüft.

IoCreateFileEx gibt möglicherweise STATUS_FILE_LOCK_CONFLICT als Rückgabewert oder im Status-Element der IO_STATUS_BLOCK-Struktur zurück, auf die der IoStatusBlock-Parameter verweist. Dies tritt nur auf, wenn die NTFS-Protokolldatei voll ist und ein Fehler auftritt, während IoCreateFileEx versucht, diese Situation zu behandeln.

Hinweise

Die IoCreateFileEx-Routine ähnelt sowohl der IoCreateFile-Routine als auch der IoCreateFileSpecifyDeviceObjectHint-Routine, bietet jedoch zusätzliche Funktionen, einschließlich Zugriff auf zusätzliche Create-Parameter (ECPs), Geräteobjekthinweise und Transaktionsinformationen über den DriverContext-Parameter der IoCreateFileEx-Routine. Weitere Informationen zu diesen strukturbasierten Parametern finden Sie unter IO_DRIVER_CREATE_CONTEXT.

Dateisystemfiltertreiber rufen IoCreateFileEx auf, um eine Erstellungsanforderung nur an ein angegebenes Geräteobjekt, die darunter angefügten Filter und das Dateisystem zu senden. Filter, die über dem angegebenen Geräteobjekt im Treiberstapel angefügt sind, empfangen die Erstellungsanforderung nicht. Wenn der DeviceObjectHint-Member der IO_DRIVER_CREATE_CONTEXT-Struktur (übergeben durch den DriverContext-Parameter ) jedoch NULL ist, wird die Anforderung an den Anfang des Stapels geleitet und von allen Filtern und dem Dateisystem empfangen.

Wenn die E/A-Anforderung nicht an den Anfang des Treiberstapels geleitet wird, d. h. wenn der DriverContext-Parameter nicht NULL ist und ein gültiges Geräteobjekt vom DeviceObjectHint-Element der IO_DRIVER_CREATE_CONTEXT-Struktur angegeben wird, gilt die folgende Einschränkung:

Wenn der Dateipfad, der an die IoCreateFileEx-Routine übergeben wird, einen Bereitstellungspunkt enthält, muss der Bereitstellungspunkt in dasselbe Volume aufgelöst werden, in dem sich die Datei oder das Verzeichnis befindet.

Das von IoCreateFileEx abgerufene Handle kann von nachfolgenden Aufrufen verwendet werden, um Daten in der Datei oder den Zustand oder die Attribute des Dateiobjekts zu bearbeiten. Jedes Handle, das von IoCreateFileEx abgerufen wird, muss schließlich durch Aufrufen von ZwClose freigegeben werden.

Es gibt zwei alternative Möglichkeiten, den Namen der Datei anzugeben, die mit IoCreateFileEx erstellt oder geöffnet werden soll:

Als vollqualifizierter Pfadname, der im ObjectName-Member des ObjectAttributes-Eingabeparameters angegeben wird.
Als Pfadname relativ zum Handle im RootDirectory-Member des ObjectAttributes-Eingabeparameters . (Dieses Handle kann eine Verzeichnisdatei darstellen.)

Treiberroutinen, die in einem anderen Prozesskontext als dem des Systemprozesses ausgeführt werden, müssen das attribut OBJ_KERNEL_HANDLE für den ObjectAttributes-Parameter von IoCreateFileEx festlegen. Dadurch wird die Verwendung des von IoCreateFileEx zurückgegebenen Handles auf Prozesse beschränkt, die im Kernelmodus ausgeführt werden. Andernfalls kann der Prozess, in dessen Kontext der Treiber ausgeführt wird, auf das Handle zugreifen. Treiber können InitializeObjectAttributes aufrufen, um das attribut OBJ_KERNEL_HANDLE festzulegen.

Bestimmte DesiredAccess-Flags und Kombinationen von Flags haben die folgenden Auswirkungen:

Damit ein Aufrufer eine E/A-Vervollständigung synchronisieren kann, indem er darauf wartet, dass der zurückgegebene FileHandle auf den Signalzustand festgelegt wird, muss das SYNCHRONIZE-Flag festgelegt werden. Andernfalls muss ein Aufrufer, der ein Geräte- oder Zwischentreiber ist, eine E/A-Vervollständigung mithilfe eines Ereignisobjekts synchronisieren.
Wenn nur die Flags FILE_APPEND_DATA und SYNCHRONIZE festgelegt sind, kann der Aufrufer nur an das Ende der Datei schreiben, und alle Offsetinformationen zu Schreibvorgängen in die Datei werden ignoriert. Die Datei wird jedoch automatisch erweitert, wenn dies für diese Art von Schreibvorgang erforderlich ist.
Das Festlegen des FILE_WRITE_DATA-Flags für eine Datei ermöglicht auch Schreibvorgänge über das Ende der Datei hinaus. Die Datei wird auch für diese Art von Schreibvorgang automatisch erweitert.
Wenn nur die Flags FILE_EXECUTE und SYNCHRONIZE festgelegt sind, kann der Aufrufer keine Daten in der Datei direkt mit dem zurückgegebenen FileHandle lesen oder schreiben. Das heißt, alle Vorgänge für die Datei erfolgen über den System-Pager als Reaktion auf Anweisungen und Datenzugriffe. Geräte- und Zwischentreiber sollten das FILE_EXECUTE-Flag in DesiredAccess nicht festlegen.

Der ShareAccess-Parameter bestimmt, ob separate Threads möglicherweise gleichzeitig auf dieselbe Datei zugreifen können. Sofern beide Dateiöffner über die Berechtigung verfügen, auf die angegebene Weise auf eine Datei zuzugreifen, kann die Datei erfolgreich geöffnet und freigegeben werden. Wenn der ursprüngliche Aufrufer von IoCreateFileEx keine FILE_SHARE_READ, FILE_SHARE_WRITE oder FILE_SHARE_DELETE angibt, können keine anderen Geöffneten Vorgänge für die Datei ausgeführt werden. Das heißt, der ursprüngliche Aufrufer erhält exklusiven Zugriff auf die Datei.

Damit eine freigegebene Datei erfolgreich geöffnet werden kann, muss der angeforderte DesiredAccess-Wert für die Datei sowohl mit den DesiredAccess - als auch mit den ShareAccess-Spezifikationen aller vorherigen offenen Anforderungen kompatibel sein, die noch nicht mit ZwClose veröffentlicht wurden. Das heißt, der DesiredAccess-Wert , der für IoCreateFileEx für eine bestimmte Datei angegeben wird, darf nicht mit den Zugriffen in Konflikt stehen, die andere Öffnende der Datei nicht zugelassen haben.

Wenn IO_IGNORE_SHARE_ACCESS_CHECK im Options-Parameter angegeben ist, ignoriert der E/A-Manager den ShareAccess-Parameter . Das Dateisystem kann jedoch weiterhin Zugriffsprüfungen durchführen. Daher ist es wichtig, den gewünschten Freigabemodus für den ShareAccess-Parameter anzugeben, auch wenn sie das flag IO_IGNORE_SHARE_ACCESS_CHECK verwenden.

Der Dispositionswert FILE_SUPERSEDE erfordert, dass der Aufrufer über DELETE-Zugriff auf ein vorhandenes Dateiobjekt verfügt. Wenn ja, wird diese Datei bei einem erfolgreichen Aufruf von IoCreateFileEx mit FILE_SUPERSEDE für eine vorhandene Datei effektiv gelöscht und dann neu erstellt. Dies impliziert, dass der Thread die Datei geöffnet hat, wenn die Datei bereits von einem anderen Thread geöffnet wurde, indem er einen ShareAccess-Parameter mit festgelegtem FILE_SHARE_DELETE-Flag angibt. Beachten Sie, dass diese Art von Disposition mit dem POSIX-Stil des Überschreibens von Dateien konsistent ist.

Die Dispositionswerte FILE_OVERWRITE_IF und FILE_SUPERSEDE sind ähnlich. Wenn IoCreateFileEx mit einer vorhandenen Datei und einem dieser Dispositionswerte aufgerufen wird, wird die Datei ersetzt.

Das Überschreiben einer Datei entspricht semantisch einem Ablösungsvorgang, mit Ausnahme von Folgenden:

Der Aufrufer muss über Schreibzugriff auf die Datei verfügen, anstatt den Zugriff zu löschen. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, die Datei mit dem in der ShareAccess-Eingabe festgelegten FILE_SHARE_WRITE-Flag geöffnet wurde.
Die angegebenen Dateiattribute werden logisch mit denen, die sich bereits in der Datei befinden, aufgehoben. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, ein nachfolgender Aufrufer von IoCreateFileEx vorhandene FileAttributes-Flags nicht deaktivieren kann, sondern zusätzliche Flags für dieselbe Datei aktivieren kann. Beachten Sie, dass diese Art des Überschreibens von Dateien mit MS-DOS, Windows 3.1 und OS/2 konsistent ist.

Der Wert createOptions FILE_DIRECTORY_FILE gibt an, dass die zu erstellende oder zu öffnende Datei eine Verzeichnisdatei ist. Wenn eine Verzeichnisdatei erstellt wird, erstellt das Dateisystem eine geeignete Struktur auf dem Datenträger, um ein leeres Verzeichnis für die Struktur auf dem Datenträger dieses bestimmten Dateisystems darzustellen. Wenn diese Option angegeben wurde und die zu öffnende Datei keine Verzeichnisdatei ist, oder wenn der Aufrufer einen inkonsistenten CreateOptions - oder Disposition-Wert angegeben hat, schlägt der Aufruf von IoCreateFileEx fehl.

Das Flag CreateOptions FILE_NO_INTERMEDIATE_BUFFERING verhindert, dass das Dateisystem im Namen des Aufrufers Zwischenpufferungen ausführt. Wenn Sie diesen Wert angeben, werden bestimmte Einschränkungen für die Parameter des Aufrufers auf die Zw.festgelegt. Dateiroutinen , einschließlich der folgenden:

Jedes optionale ByteOffset , das an ZwReadFile oder ZwWriteFile übergeben wird, muss ein integraler Wert (ganzzahliges Vielfaches) der Sektorgröße sein.
Die anZwReadFile oder ZwWriteFile übergebene Länge muss ein Integral der Sektorgröße sein. Beachten Sie, dass die Angabe eines Lesevorgangs für einen Puffer, dessen Länge genau der Sektorgröße entspricht, dazu führen kann, dass eine geringere Anzahl signifikanter Bytes an diesen Puffer übertragen wird, wenn das Ende der Datei während der Übertragung erreicht wurde.
Puffer müssen entsprechend der Ausrichtungsanforderung des zugrunde liegenden Geräts ausgerichtet werden. Diese Informationen können abgerufen werden, indem Sie IoCreateFileEx aufrufen, um ein Handle für das Dateiobjekt abzurufen, das das physische Gerät darstellt, und dann ZwQueryInformationFile mit diesem Handle aufrufen. Eine Liste der Systemwerte FILE_XXX_ALIGNMENT finden Sie unter DEVICE_OBJECT.
Aufrufe von ZwSetInformationFile mit dem FileInformationClass-Parameter , der auf FilePositionInformation festgelegt ist, müssen einen Offset angeben, der ein Integral der Sektorgröße ist.

Die sich gegenseitig ausschließenden CreateOptions-FILE_SYNCHRONOUS_IO_ALERT- und FILE_SYNCHRONOUS_IO_NONALERT-Flags geben an, dass alle E/A-Vorgänge für die Datei synchron sein sollen, solange sie über das Dateiobjekt erfolgen, auf das vom zurückgegebenen FileHandle verwiesen wird. Alle E/A-Vorgänge in einer solchen Datei werden über alle Threads serialisiert, indem das zurückgegebene Handle verwendet wird. Mit einem dieser CreateOptions-Werte muss das DesiredAccess SYNCHRONIZE-Flag festgelegt werden, damit der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet. Wenn einer dieser CreateOptions-Werte festgelegt ist, verwaltet der E/A-Manager den "Dateipositionskontext" für das Dateiobjekt, einen internen, aktuellen Dateipositionsoffset. Dieser Offset kann in Aufrufen von ZwReadFile und ZwWriteFile verwendet werden. Die Position kann auch durch Aufrufen von ZwQueryInformationFile abgefragt oder durch Aufrufen von ZwSetInformationFile festgelegt werden.

Wenn das Flag CreateOptions FILE_OPEN_REPARSE_POINT nicht angegeben ist und IoCreateFileEx versucht, eine Datei mit einem Analysepunkt zu öffnen, erfolgt die normale Analysepunktverarbeitung für die Datei. Wenn dagegen das flag FILE_OPEN_REPARSE_POINT angegeben ist, findet keine normale Analyseverarbeitung statt, und IoCreateFileEx versucht, die Analysepunktdatei direkt zu öffnen. In beiden Fällen gibt IoCreateFileEx STATUS_SUCCESS zurück, wenn der Öffnenvorgang erfolgreich war. Andernfalls gibt die Routine einen NTSTATUS-Fehlercode zurück. IoCreateFileEx gibt nie STATUS_REPARSE zurück.

Das Flag CreateOptions FILE_OPEN_REQUIRING_OPLOCK entfernt die Zeit zwischen dem Öffnen der Datei und dem Anfordern eines Oplocks, der es einem Drittanbieter möglicherweise ermöglichen könnte, die Datei zu öffnen und einen Freigabeverstoß zu erhalten. Eine Anwendung kann das FILE_OPEN_REQUIRING_OPLOCK-Flag auf IoCreateFileEx verwenden und dann einen beliebigen Oplock anfordern. Dadurch wird sichergestellt, dass ein Oplock-Besitzer über jede spätere offene Anforderung benachrichtigt wird, die einen Verstoß gegen die Freigabe verursacht.

Wenn in Windows 7 andere Handles für die Datei vorhanden sind, wenn eine Anwendung das flag FILE_OPEN_REQUIRING_OPLOCK verwendet, schlägt der Erstellungsvorgang mit STATUS_OPLOCK_NOT_GRANTED fehl. Diese Einschränkung ist ab Windows 8 nicht mehr vorhanden.

Wenn dieser Erstellungsvorgang einen oplock unterbrechen würde, der bereits für die Datei vorhanden ist, führt das Festlegen des FILE_OPEN_REQUIRING_OPLOCK-Flags dazu, dass der Erstellungsvorgang mit STATUS_CANNOT_BREAK_OPLOCK fehlschlägt. Der vorhandene Oplock wird durch diesen Erstellungsvorgang nicht unterbrochen.

Eine Anwendung, die dieses Flag verwendet, muss einen Oplock anfordern, nachdem dieser Aufruf erfolgreich war, oder alle späteren Versuche, die Datei zu öffnen, werden ohne den Vorteil der typischen Oplockverarbeitung blockiert. Wenn dieser Aufruf erfolgreich ist, aber die spätere oplock-Anforderung fehlschlägt, muss eine Anwendung, die dieses Flag verwendet, ihr Handle schließen, nachdem sie erkannt hat, dass die Oplock-Anforderung fehlgeschlagen ist.

Das FILE_OPEN_REQUIRING_OPLOCK-Flag ist in Windows 7, Windows Server 2008 R2 und späteren Windows-Betriebssystemen verfügbar. Die Microsoft-Dateisysteme, die dieses Flag implementieren, sind NTFS, FAT und exFAT.

Das CreateOptions-Flag FILE_RESERVE_OPFILTER ermöglicht es einer Anwendung, einen Oplock der Ebene 1, batch oder filter anzufordern, um zu verhindern, dass andere Anwendungen Freigabeverletzungen erhalten. FILE_RESERVE_OPFILTER ist jedoch nur für Filter oplocks praktisch nützlich. Um es verwenden zu können, müssen Sie die folgenden Schritte ausführen:

Stellen Sie eine Create-Anforderung mit CreateOptions von FILE_RESERVE_OPFILTER, DesiredAccess von genau FILE_READ_ATTRIBUTES und ShareAccess von genau FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Wenn bereits geöffnete Handles vorhanden sind, schlägt die Erstellungsanforderung mit STATUS_OPLOCK_NOT_GRANTED fehl, und auch der nächste angeforderte Oplock schlägt fehl.
- Wenn Sie mit mehr Zugriff oder weniger Freigabe öffnen, tritt auch ein Fehler von STATUS_OPLOCK_NOT_GRANTED auf.
Wenn die Erstellungsanforderung erfolgreich ist, fordern Sie einen Oplock an.
Öffnen Sie ein weiteres Handle für die Datei, um E/A-Vorgänge zu erledigen.

Schritt 3 macht dies nur für Filter oplocks praktisch. Das in Schritt 3 geöffnete Handle kann einen DesiredAccess-Wert aufweisen, der maximal FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONISIEREN | READ_CONTROL einen Filter oplock nicht zu unterbrechen. Ein DesiredAccess-Wert größer als FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE unterbricht einen Oplock der Ebene 1 oder batch und macht das FILE_RESERVE_OPFILTER Flag für diese Oplock-Typen unbrauchbar.

Wenn der Treiber bei Erstellungsanforderungen aus dem Benutzermodus IO_FORCE_ACCESS_CHECK im Options-Parameter von IoCreateFileEx festlegt, sollte er auch OBJ_FORCE_ACCESS_CHECK im ObjectAttributes-Parameter festlegen. Weitere Informationen zu diesem Flag finden Sie im Element Attributes von OBJECT_ATTRIBUTES.

NTFS ist das einzige Microsoft-Dateisystem, das FILE_RESERVE_OPFILTER implementiert.

IoCreateFileEx kann verwendet werden, um ein Handle für ein Volume abzurufen.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	ntddk.h (include Ntddk.h, Ntifs.h, FltKernel.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL