NtCreateFile-Funktion (winternl.h)

  • Artikel

Erstellt eine neue Datei oder ein neues Verzeichnis oder öffnet eine vorhandene Datei, ein vorhandenes Gerät, ein Verzeichnis oder ein Volume.

 

Diese Funktion ist der Benutzermodus, der der ZwCreateFile-Funktion entspricht, die im Windows Driver Kit (WDK) dokumentiert ist.

Syntax

__kernel_entry NTSTATUS NtCreateFile(
  [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              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in]           PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

Parameter

[out] FileHandle

Ein Zeiger auf eine Variable, die das Dateihandle empfängt, wenn der Aufruf erfolgreich ist.

[in] DesiredAccess

Der ACCESS_MASK Wert, der den Zugriff ausdrückt, den der Aufrufer für die Datei oder das Verzeichnis benötigt. Der Satz systemdefinierter DesiredAccess-Flags bestimmt die folgenden spezifischen Zugriffsrechte für Dateiobjekte.

Wert Bedeutung
DELETE
 Die Datei kann gelöscht werden.
FILE_READ_DATA
 Aus der Datei können Daten gelesen werden.
FILE_READ_ATTRIBUTES
 FileAttributes-Flags , die später beschrieben werden, können gelesen werden.
FILE_READ_EA
 Erweiterte Attribute, die der Datei zugeordnet sind, können gelesen werden. Dieses Flag ist für Geräte- und Zwischentreiber irrelevant.
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
 Der Datei zugeordnete erweiterte Attribute (EAs) können geschrieben werden. Dieses Flag ist für Geräte- und Zwischentreiber irrelevant.
FILE_APPEND_DATA
 Daten können an die Datei angefügt werden.
WRITE_DAC
 Die der Datei zugeordnete diskretionäre Zugriffssteuerungsliste (DACL) kann geschrieben werden.
WRITE_OWNER
 Besitzerinformationen, die der Datei zugeordnet sind, können geschrieben werden.
SYNCHRONIZE
 Das zurückgegebene FileHandle kann gewartet werden, um mit dem Abschluss eines E/A-Vorgangs zu synchronisieren. Wenn FileHandle nicht für synchrone E/A-Vorgänge geöffnet wurde, wird dieser Wert ignoriert.
FILE_EXECUTE
 Daten können mithilfe von System paging-E/A aus der Datei in den Arbeitsspeicher eingelesen werden. Dieses Flag ist für Geräte- und Zwischentreiber irrelevant.
 

Geben Sie beim Erstellen oder Öffnen eines Verzeichnisses keine FILE_READ_DATA ,FILE_WRITE_DATA, FILE_APPEND_DATA oder FILE_EXECUTE an.

Aufrufer von NtCreateFile können für jedes Dateiobjekt, das keine Verzeichnisdatei darstellt, eine oder eine Kombination der folgenden Angeben angeben, möglicherweise mithilfe eines bitweisen OR mit zusätzlichen kompatiblen Flags aus der vorherigen Liste der DesiredAccess-Flags .

Wert Bedeutung
FILE_GENERIC_READ
 STANDARD_RIGHTS_READ | FILE_READ_DATA | FILE_READ_ATTRIBUTES | FILE_READ_EA | SYNCHRONIZE
FILE_GENERIC_WRITE
 STANDARD_RIGHTS_WRITE | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES | FILE_WRITE_EA | FILE_APPEND_DATA | SYNCHRONIZE
FILE_GENERIC_EXECUTE
 STANDARD_RIGHTS_EXECUTE | FILE_READ_ATTRIBUTES | FILE_EXECUTE | SYNCHRONIZE
 

Der FILE_GENERIC_EXECUTE Wert ist für Geräte- und Zwischentreiber irrelevant.

Die STANDARD_RIGHTS_XXX sind vordefinierte Systemwerte, die zum Erzwingen der Sicherheit von Systemobjekten verwendet werden.

Um eine Verzeichnisdatei zu öffnen oder zu erstellen, können Aufrufer von NtCreateFile, wie auch mit dem CreateOptions-Parameter angegeben, eine oder eine Kombination aus den folgenden Angeben angeben, möglicherweise mithilfe eines bitweisen OR mit einem oder mehreren kompatiblen Flags aus der vorherigen Liste der DesiredAccess-Flags.

Wert Bedeutung
FILE_LIST_DIRECTORY
 Dateien im Verzeichnis können aufgelistet werden.
FILE_TRAVERSE
 Das Verzeichnis kann durchquert werden, d. h. es kann Teil des Pfadnamens einer Datei sein.

[in] ObjectAttributes

Ein Zeiger auf eine Struktur, die bereits mit InitializeObjectAttributes initialisiert wurde. Elemente dieser Struktur für ein Dateiobjekt umfassen Folgendes.

Wert Bedeutung
ULONG-Länge
 Gibt die Anzahl der Bytes der bereitgestellten ObjectAttributes-Daten an. Dieser Wert muss mindestens sizeof(OBJECT_ATTRIBUTES) sein.
HANDLE RootDirectory
 Gibt optional ein Handle für ein Verzeichnis an, das durch einen vorherigen Aufruf von NtCreateFile 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.
PUNICODE_STRING ObjectName
 Zeigt auf eine gepufferte Unicode-Zeichenfolge, die die zu erstellende oder zu öffnende Datei benennt. Dieser Wert muss eine vollqualifizierte Dateispezifikation oder der Name eines Geräteobjekts sein, es sei denn, es handelt sich um den Namen einer Datei relativ zum von RootDirectory angegebenen Verzeichnis. Beispiel: \Device\Floppy1\myfile.dat oder \?? \B:\myfile.dat kann die vollqualifizierte Dateispezifikation sein, vorausgesetzt, der Diskettentreiber und das überladene Dateisystem sind bereits geladen. Weitere Informationen finden Sie unter Dateinamen, Pfade und Namespaces.
ULONG-Attribute
 Ist eine Gruppe von Flags, die die Dateiobjektattribute steuert. Dieser Wert kann null oder OBJ_CASE_INSENSITIVE sein, was angibt, dass Name-Lookup-Code die Groß-/Kleinschreibung des ObjectName-Members ignorieren sollte, anstatt eine Suche nach exakter Übereinstimmung durchzuführen. Der Wert OBJ_INHERIT ist für Geräte- und Zwischentreiber irrelevant.
PSECURITY_DESCRIPTOR SecurityDescriptor
 Gibt optional einen Sicherheitsdeskriptor an, 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 beim Erstellen einer Datei NULL ist, ist die in der Datei platzierte ACL dateisystemabhängig. Die meisten Dateisysteme verteilen einen Teil einer solchen ACL aus der übergeordneten Verzeichnisdatei in Kombination mit der Standard-ACL des Aufrufers. Geräte- und Zwischentreiber können dieses Element auf NULL festlegen.
PSECURITY_QUALITY_OF_SERVICE SecurityQualityOfService
 Gibt die Zugriffsrechte an, die einem Server für den Sicherheitskontext des Clients erteilt werden sollen. Dieser Wert ist nur nicht NULL , wenn eine Verbindung mit einem geschützten Server hergestellt wird, sodass der Aufrufer steuern kann, welche Teile des Sicherheitskontexts des Aufrufers für den Server zur Verfügung gestellt werden und ob der Server die Identität des Aufrufers annehmen darf.

[out] IoStatusBlock

Ein Zeiger auf eine Variable, die die endgültige Vervollständigung status und Informationen zum angeforderten Vorgang empfängt. Wenn sie von NtCreateFile zurückgegeben wird, enthält das Information-Element einen der folgenden Werte:

  • FILE_CREATED
  • FILE_OPENED
  • FILE_OVERWRITTEN
  • FILE_SUPERSEDED
  • FILE_EXISTS
  • FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Die anfängliche Zuordnungsgröße in Bytes für die Datei. Ein Wert ohne Zero hat keine Auswirkung, es sei denn, die Datei wird erstellt, überschrieben oder ersetzt.

[in] FileAttributes

Die Dateiattribute. Explizit angegebene Attribute werden nur angewendet, wenn die Datei erstellt, ersetzt oder in einigen Fällen überschrieben wird. Standardmäßig ist dieser Wert ein FILE_ATTRIBUTE_NORMAL, der durch eine ORed-Kombination aus einem oder mehreren FILE_ATTRIBUTE_xxxx-Flags überschrieben werden kann, die in Wdm.h und NtDdk.h definiert sind. Eine Liste der Flags, die mit NtCreateFile verwendet werden können, finden Sie unter CreateFile.

[in] ShareAccess

Der Typ des Freigabezugriffs, den der Aufrufer in der Datei verwenden möchte, als Null oder als einer oder eine Kombination der folgenden Werte.

Wert Bedeutung
FILE_SHARE_READ
 Die Datei kann für den Lesezugriff durch Aufrufe anderer Threads an NtCreateFile geöffnet werden.
FILE_SHARE_WRITE
 Die Datei kann für den Schreibzugriff durch Aufrufe anderer Threads an NtCreateFile geöffnet werden.
FILE_SHARE_DELETE
 Die Datei kann für den Löschzugriff durch Aufrufe anderer Threads an NtCreateFile geöffnet werden.
 

Weitere Informationen finden Sie im Windows SDK.

[in] CreateDisposition

Gibt je nachdem, ob die Datei bereits vorhanden ist, als einen der folgenden Werte an, was zu tun ist.

Wert Bedeutung
FILE_SUPERSEDE
 Wenn die Datei bereits vorhanden ist, ersetzen Sie sie durch die angegebene Datei. Wenn dies nicht der Fall 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 dies nicht der Fall ist, erstellen Sie die angegebene Datei.
FILE_OPEN
 Wenn die Datei bereits vorhanden ist, öffnen Sie sie, anstatt eine neue Datei zu erstellen. Wenn dies nicht der Fall 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 dies nicht der Fall ist, erstellen Sie die angegebene Datei.
FILE_OVERWRITE
 Wenn die Datei bereits vorhanden ist, öffnen Sie sie, und überschreiben Sie sie. Wenn dies nicht der Fall ist, schlägt die Anforderung fehl.
FILE_OVERWRITE_IF
 Wenn die Datei bereits vorhanden ist, öffnen Sie sie, und überschreiben Sie sie. Wenn dies nicht der Fall ist, erstellen Sie die angegebene Datei.

[in] CreateOptions

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

Wert Bedeutung
FILE_DIRECTORY_FILE
 Die Datei, die erstellt oder geöffnet wird, ist eine Verzeichnisdatei. Mit diesem Flag muss der CreateDisposition-Parameter auf FILE_CREATE, FILE_OPEN oder FILE_OPEN_IF festgelegt werden. Mit diesem Flag enthalten andere kompatible CreateOptions-Flags nur Folgendes: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO _NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT und FILE_OPEN_BY_FILE_ID.
FILE_NON_DIRECTORY_FILE
 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, ein logisches, virtuelles oder physisches Gerät oder ein Volume darstellen.
FILE_WRITE_THROUGH
 Anwendungen, die Daten in die Datei schreiben, müssen die Daten tatsächlich in die Datei übertragen, bevor ein angeforderter Schreibvorgang als abgeschlossen betrachtet wird. Dieses Flag wird automatisch festgelegt, wenn das CreateOptions-Flag FILE_NO_INTERMEDIATE _BUFFERING festgelegt ist.
FILE_SEQUENTIAL_ONLY
 Alle Zugriffe auf die Datei erfolgen sequenziell.
FILE_RANDOM_ACCESS
 Zugriffe auf die Datei können zufällig erfolgen, sodass keine sequenziellen Read-Ahead-Vorgänge für die Datei von FSDs oder dem System ausgeführt werden sollten.
FILE_NO_INTERMEDIATE_BUFFERING
 Die Datei kann nicht in den internen Puffern eines Treibers zwischengespeichert oder gepuffert werden. Dieses Flag ist mit dem DesiredAccess-FILE_APPEND_DATA-Flag nicht kompatibel.
FILE_SYNCHRONOUS_IO_ALERT
 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 DesiredAccessSYNCHRONIZE-Flag festgelegt werden.
FILE_SYNCHRONOUS_IO_NONALERT
 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 DesiredAccessSYNCHRONIZE-Flag festgelegt werden.
FILE_CREATE_TREE_CONNECTION
 Erstellen Sie eine Strukturverbindung für diese Datei, um sie über das Netzwerk zu öffnen. Dieses Flag wird von Geräte- und Zwischentreibern nicht verwendet.
FILE_NO_EA_KNOWLEDGE
 Wenn die erweiterten Attribute für eine vorhandene Datei, die geöffnet wird, angeben, dass der Aufrufer EAs verstehen muss, um die Datei ordnungsgemäß zu interpretieren, schlägt diese Anforderung fehl, da der Aufrufer nicht versteht, wie mit EAs umgegangen werden soll. Dieses Flag ist für Geräte- und Zwischentreiber irrelevant.
FILE_OPEN_REPARSE_POINT
 Öffnen Sie eine Datei mit einem Analysepunkt, und umgehen Sie die normale Analysepunktverarbeitung für die Datei. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
FILE_DELETE_ON_CLOSE
 Löschen Sie die Datei, wenn das letzte Handle an NtClose übergeben wird. Wenn dieses Flag festgelegt ist, muss das DELETE-Flag im DesiredAccess-Parameter festgelegt werden.
FILE_OPEN_BY_FILE_ID
 Der durch den ObjectAttributes-Parameter angegebene Dateiname enthält die 8-Byte-Dateireferenznummer für die Datei. Diese Nummer wird von und spezifisch für das jeweilige Dateisystem zugewiesen. Wenn es sich bei der Datei um einen Analysepunkt handelt, enthält der Dateiname auch den Namen eines Geräts. Beachten Sie, dass das FAT-Dateisystem dieses Flag nicht unterstützt. Dieses Flag wird von Geräte- und Zwischentreibern nicht verwendet.
FILE_OPEN_FOR_BACKUP_INTENT
 Die Datei wird für die Sicherungsabsicht geöffnet. Daher sollte das System bestimmte Zugriffsrechte überprüfen und dem Aufrufer den entsprechenden Zugriff auf die Datei gewähren, bevor der DesiredAccess-Parameter mit dem Sicherheitsdeskriptor der Datei überprüft wird. Dieses Flag wird von Geräte- und Zwischentreibern nicht verwendet.
FILE_RESERVE_OPFILTER
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 Abschnitt mit Hinweisen.
FILE_OPEN_REQUIRING_OPLOCK
 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 es den Erstellungsvorgang ausführt. Die Erstellung schlägt mit einem Rückgabecode von STATUS_CANNOT_BREAK_OPLOCK fehl, wenn das Ergebnis einen vorhandenen Oplock unterbrechen würde. Weitere Informationen finden Sie im Abschnitt Hinweise. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieses Flag wird nicht unterstützt.

Dieses Flag wird in den folgenden Dateisystemen unterstützt: NTFS, FAT und exFAT.
FILE_COMPLETE_IF_OPLOCKED
 Schließen Sie diesen Vorgang sofort mit dem alternativen Erfolgscode STATUS_OPLOCK_BREAK_IN_PROGRESS ab, wenn die Zieldatei oplocked ist, anstatt den Thread des Aufrufers zu blockieren. Wenn die Datei oplocked ist, hat bereits ein anderer Aufrufer Zugriff auf die Datei. Dieses Flag wird von Geräte- und Zwischentreibern nicht verwendet.

[in] EaBuffer

Zeiger auf einen EA-Puffer, der zum Übergeben erweiterter Attribute verwendet wird.

Hinweis Einige Dateisysteme unterstützen möglicherweise keine EA-Puffer.
 

[in] EaLength

Länge des EA-Puffers.

Rückgabewert

NtCreateFile gibt entweder STATUS_SUCCESS oder einen entsprechenden Fehler status zurück. Wenn ein Fehler status zurückgegeben wird, kann der Aufrufer weitere Informationen zur Ursache des Fehlers finden, indem er den IoStatusBlock überprüft. Um diese Überprüfung zu vereinfachen, kann eine Anwendung die Makros NT_SUCCESS, NT_ERROR und NT_WARNING verwenden.

Hinweise

Das von NtCreateFile angegebene Handle kann von nachfolgenden Aufrufen verwendet werden, um Daten innerhalb der Datei oder des Zustands oder der Attribute des Dateiobjekts zu bearbeiten.

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

  • Als vollqualifizierter Pfadname, der im ObjectName-Member der Eingabe ObjectAttributes angegeben wird
  • Als Pfadname relativ zur Verzeichnisdatei, die durch das Handle im RootDirectory-Member der Eingabe ObjectAttributes dargestellt wird
Bestimmte DesiredAccess-Flags und Kombinationen von Flags haben die folgenden Auswirkungen:
  • Damit ein Aufrufer eine E/A-Vervollständigung synchronisieren kann, indem er auf das zurückgegebene FileHandle wartet, muss das SYNCHRONIZE-Flag festgelegt werden.
  • Das Übergeben einer Null an DesiredFlags ist ungültig.
  • 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 diesen 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 Schreibart automatisch erweitert.
  • Wenn nur die FILE_EXECUTE - und SYNCHRONIZE-Flags festgelegt sind, kann der Aufrufer keine Daten in der Datei direkt lesen oder schreiben, indem das zurückgegebene FileHandle verwendet wird. Das heißt, alle Vorgänge für die Datei erfolgen über den System pager als Reaktion auf Anweisungen und Datenzugriffe.
Der ShareAccess-Parameter bestimmt, ob separate Threads möglicherweise gleichzeitig auf dieselbe Datei zugreifen können. Vorausgesetzt, dass beide Dateiöffner über die Berechtigung verfügen, auf eine Datei auf die angegebene Weise zuzugreifen, kann die Datei erfolgreich geöffnet und freigegeben werden. Wenn der ursprüngliche Aufrufer von NtCreateFile nicht 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-Parameter für die Datei sowohl mit den DesiredAccess - als auch mit den ShareAccess-Spezifikationen aller vorherigen Öffnungen kompatibel sein, die noch nicht mit NtClose veröffentlicht wurden. Das heißt, der DesiredAccess-Parameter , der ntCreateFile für eine bestimmte Datei angegeben wird, darf nicht mit den Zugriffen in Konflikt stehen, die andere Öffnende der Datei nicht zugelassen haben.

Der CreateDisposition-WertFILE_SUPERSEDE erfordert, dass der Aufrufer über DELETE-Zugriff auf ein vorhandenes Dateiobjekt verfügt. Wenn ja, wird diese Datei durch einen erfolgreichen Aufruf von NtCreateFile mit FILE_SUPERSEDE für eine vorhandene Datei effektiv gelöscht und dann neu erstellt. Dies bedeutet, dass die Datei geöffnet wurde, wenn die Datei bereits von einem anderen Thread geöffnet wurde, indem sie einen ShareAccess-Parameter mit dem FILE_SHARE_DELETE-Flag festgelegt hat. Beachten Sie, dass diese Art von Disposition mit dem POSIX-Stil zum Überschreiben von Dateien konsistent ist. Die CreateDisposition-WerteFILE_OVERWRITE_IF und FILE_SUPERSEDE sind ähnlich. Wenn ZwCreateFile mit einer vorhandenen Datei und einem dieser CreateDisposition-Werte aufgerufen wird, wird die Datei ersetzt.

Das Überschreiben einer Datei entspricht semantisch einem Ablösevorgang, mit Ausnahme des Folgenden:

  • Der Aufrufer muss Schreibzugriff auf die Datei haben, anstatt den Zugriff zu löschen. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, die Datei mit dem imShareAccess-Parameter für 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 ein nachfolgender Aufrufer von NtCreateFile vorhandene FileAttributes-Flags nicht deaktivieren kann, wenn die Datei bereits von einem anderen Thread geöffnet wurde, aber zusätzliche Flags für dieselbe Datei aktivieren kann. Beachten Sie, dass diese Art des Überschreibens von Dateien mit den Betriebssystemen MS-DOS, Windows 3.1 und OS/2 konsistent ist.
Der Wert createOptionsFILE_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 des jeweiligen Dateisystems auf dem Datenträger darzustellen. Wenn diese Option angegeben wurde und die zu öffnende Datei keine Verzeichnisdatei ist, oder wenn der Aufrufer einen inkonsistenten CreateOptions - oder CreateDisposition-Wert angegeben hat, schlägt der Aufruf von NtCreateFile fehl.

Das Flag CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING verhindert, dass das Dateisystem im Auftrag des Aufrufers zwischenpuffert. Wenn Sie diesen Wert angeben, gelten bestimmte Einschränkungen für die Parameter des Aufrufers für andere NtXXXFile-Routinen , einschließlich der folgenden:

  • Jedes optionale ByteOffset , das an die NtReadFile- oder NtWriteFile-Funktion übergeben wird, muss ein Integral der Sektorgröße sein.
  • Die anNtReadFile oder NtWriteFile übergebene Länge muss ein Integral der Sektorgröße sein. Beachten Sie, dass das Angeben eines Lesevorgangs für einen Puffer, dessen Länge genau der Sektorgröße entspricht, dazu führen kann, dass eine geringere Anzahl wichtiger 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 angepasst werden. Diese Informationen können abgerufen werden, indem Sie NtCreateFile aufrufen, um ein Handle für das Dateiobjekt abzurufen, das das physische Gerät darstellt, und dann NtQueryInformationFile mit diesem Handle aufrufen. Eine Liste der Systemwerte FILE_XXX_ALIGNMENT finden Sie in der Windows SDK-Dokumentation.
  • Aufrufe von NtSetInformationFile , bei denen der FileInformationClass-Parameter auf FilePositionInformation festgelegt ist, müssen einen Offset angeben, der ein Integral der Sektorgröße ist.
Die CreateOptions-FILE_SYNCHRONOUS_IO_ALERT- und FILE_SYNCHRONOUS_IO_NONALERT-Flags, die sich gegenseitig ausschließen, wie ihre Namen vermuten lassen, 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 mithilfe des zurückgegebenen Handles über alle Threads serialisiert. Bei einer dieser CreateOptions muss das DesiredAccessSYNCHRONIZE-Flag festgelegt werden, damit der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet. Wenn eines dieser CreateOptions-Elemente festgelegt ist, verwaltet der E/A-Manager den Dateipositionskontext für das Dateiobjekt, einen internen, aktuellen Dateipositionsoffset. Dieser Offset kann in Aufrufen von NtReadFile und NtWriteFile verwendet werden. Seine Position kann auch mit NtQueryInformationFile und NtSetInformationFile abgefragt oder festgelegt werden.

Wenn der CreateOptions-Parameter das flag FILE_OPEN_REPARSE_POINT angibt und NtCreateFile eine Datei mit einem Analysepunkt öffnet, wird die normale Reparseverarbeitung nicht ausgeführt, und NtCreateFile versucht, die Analysepunktdatei direkt zu öffnen. Wenn das FILE_OPEN_REPARSE_POINT-Flag nicht angegeben ist, erfolgt die normale Analysepunktverarbeitung für die Datei. In beiden Fällen gibt NtCreateFileSTATUS_SUCCESS zurück, wenn der geöffnete Vorgang erfolgreich war. andernfalls ein Fehlercode. Die NtCreateFile-Funktion gibt nie STATUS_REPARSE zurück.

Das FILE_OPEN_REQUIRING_OPLOCK Flag des CreateOptions-Parameters beseitigt die Zeit zwischen dem Öffnen der Datei und dem Anfordern eines Oplocks, der möglicherweise einem Drittanbieter das Öffnen der Datei ermöglichen könnte, was zu einer Freigabeverletzung führen würde. Eine Anwendung kann das FILE_OPEN_REQUIRING_OPLOCK-Flag mit NtCreateFile verwenden und dann einen beliebigen Oplock anfordern. Dadurch wird sichergestellt, dass ein Oplock-Besitzer über jede nachfolgende offene Anforderung benachrichtigt wird, die eine Freigabeverletzung verursacht.

Wenn in Windows 7 andere Handles für die Datei vorhanden sind, wenn eine Anwendung dieses Flag 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 unterbricht, der bereits in der 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, da sonst alle nachfolgenden Versuche zum Öffnen der Datei ohne den Vorteil der normalen oplock-Verarbeitung blockiert werden. Wenn dieser Aufruf erfolgreich ist, aber die nachfolgende 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.

Hinweis Das FILE_OPEN_REQUIRING_OPLOCK-Flag ist unter Windows 7, Windows Server 2008 R2 und höher für die folgenden Dateisysteme verfügbar: NTFS, FAT und exFAT.
 

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

  1. Stellen Sie eine Create-Anforderung mit CreateOptions von FILE_RESERVE_OPFILTER, DesiredAccess von genau FILE_READ_ATTRIBUTES und ShareAccess genau (FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)aus. Mögliche Fehler sind wie folgt:
    • 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 als FILE_READ_ATTRIBUTES oder weniger Freigabe (FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)öffnen, schlägt die Anforderung mit STATUS_OPLOCK_NOT_GRANTED fehl.
  2. Wenn die Erstellungsanforderung erfolgreich ist, fordern Sie einen oplock an.
  3. Ö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. Der in Schritt 3 geöffnete Handle kann über einen DesiredAccess-Wert verfügen, der ein Maximum von (FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL) enthält und trotzdem keinen Filter-Oplock unterbricht. Ein DesiredAccess größer als (FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE) unterbricht jedoch einen Level 1- oder Batch-Oplock und macht das FILE_RESERVE_OPFILTER Flag für diese Oplock-Typen nutzlos.

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

Weitere Informationen zu oplocks finden Sie unter Oplock Semantics.

Beachten Sie, dass die WDK-Headerdatei NtDef.h für viele Konstantendefinitionen sowie für das Makro InitializeObjectAttributes erforderlich ist. Sie können auch die Funktionen LoadLibrary und GetProcAddress verwenden, um eine dynamische Verknüpfung mit NtDll.dll.

Anforderungen

Anforderung Wert
Zielplattform Windows
Kopfzeile winternl.h
Bibliothek ntdll.lib
DLL ntdll.dll