Freigeben über

NtCreateFile-Funktion (winternl.h)

  • Artikel

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

 

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

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 Typ des Zugriffs 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
 Daten können aus der Datei 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 Kennzeichen ist für Geräte- und Zwischentreiber irrelevant.
READ_CONTROL
 Die Zugriffssteuerungsliste (Access Control List, ACL) und besitzerinformationen, die der Datei zugeordnet sind, können gelesen werden.
FILE_WRITE_DATA
 Daten können in die Datei geschrieben werden.
FILE_WRITE_ATTRIBUTES
 FileAttributes Flags können geschrieben werden.
FILE_WRITE_EA
 Erweiterte Attribute (EAs), die der Datei zugeordnet sind, können geschrieben werden. Dieses Kennzeichen ist für Geräte- und Zwischentreiber irrelevant.
FILE_APPEND_DATA
 Daten können an die Datei angefügt werden.
WRITE_DAC
 Die mit der Datei verknüpfte diskretionäre Zugriffssteuerungsliste (ACCESS Control List, DACL) kann geschrieben werden.
WRITE_OWNER
 Besitzerinformationen, die der Datei zugeordnet sind, können geschrieben werden.
SYNCHRONISIEREN
 Die zurückgegebene FileHandle- kann mit dem Abschluss eines E/A-Vorgangs auf die Synchronisierung gewartet werden. Wenn FileHandle- nicht für synchrone E/A geöffnet wurde, wird dieser Wert ignoriert.
FILE_EXECUTE
 Daten können aus der Datei mithilfe von System-Auslagerungs-E/A in den Arbeitsspeicher gelesen werden. Dieses Kennzeichen ist für Geräte- und Zwischentreiber irrelevant.
 

Geben Sie beim Erstellen oder Öffnen eines Verzeichnisses nicht FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATAoder FILE_EXECUTE an.

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

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 auf Systemobjekten verwendet werden.

Um eine Verzeichnisdatei zu öffnen oder zu erstellen, wie auch mit dem CreateOptions Parameter angegeben, können Aufrufer von NtCreateFile- eine oder eine Kombination der folgenden angeben, möglicherweise eine bitweise ODER mit mindestens einem kompatiblen Flag aus der vorherigen DesiredAccess Flags-Liste.

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

[in] ObjectAttributes

Ein Zeiger auf eine Struktur, die bereits mit InitializeObjectAttributesinitialisiert wurde. Elemente dieser Struktur für ein Dateiobjekt enthalten Folgendes.

Wert Bedeutung
ULONG Length
 Gibt die Anzahl der Bytes von ObjectAttributes bereitgestellten 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 NtCreateFileabgerufen wird. Wenn dieser Wert NULL-ist, muss der ObjectName Member eine vollqualifizierte Dateispezifikation sein, die den vollständigen Pfad zur Zieldatei enthält. Wenn dieser Wert nichtNULL-ist, gibt das element ObjectName einen Dateinamen relativ zu diesem Verzeichnis an.
PUNICODE_STRING ObjectName-
 Verweist auf eine gepufferte Unicode-Zeichenfolge, die die zu erstellende oder geöffnete 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 verzeichnis, das durch RootDirectoryangegeben wird. Beispiel: \Device\Floppy1\myfile.dat oder \?? \B:\myfile.dat könnte die vollqualifizierte Dateispezifikation sein, vorausgesetzt, der Diskettentreiber und das Überladen des Dateisystems sind bereits geladen. Weitere Informationen finden Sie unter Dateinamen, Pfade und Namespaces.
ULONG-Attribute
 Ist eine Reihe von Flags, die die Dateiobjektattribute steuern. Dieser Wert kann null oder OBJ_CASE_INSENSITIVEsein, was angibt, dass der Name-Nachschlagecode die Groß-/Kleinschreibung des ObjectName Members ignorieren sollte, anstatt eine Suche mit 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 durch einen solchen Sicherheitsdeskriptor angegeben werden, werden nur dann 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 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 ein Server dem Sicherheitskontext des Clients zugewiesen werden soll. Dieser Wert ist nichtNULL- nur, wenn eine Verbindung mit einem geschützten Server hergestellt wird, sodass der Aufrufer steuern kann, welche Teile des Sicherheitskontexts des Aufrufers dem 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 den endgültigen Abschlussstatus und Informationen zum angeforderten Vorgang empfängt. Bei rückgabe von NtCreateFileenthält das Information Member 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 Byte für die Datei. Ein Wert ungleich Null hat keine Auswirkung, es sei denn, die Datei wird erstellt, überschrieben oder abgelöst.

[in] FileAttributes

Die Dateiattribute. Explizit angegebene Attribute werden nur angewendet, wenn die Datei erstellt, abgelöst oder in einigen Fällen überschrieben wird. Dieser Wert ist standardmäßig eine FILE_ATTRIBUTE_NORMAL, die durch eine ORed-Kombination aus einer 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 eine 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 NtCreateFilegeöffnet werden.
FILE_SHARE_DELETE
 Die Datei kann für den Löschzugriff durch Aufrufe anderer Threads an NtCreateFilegeöffnet werden.
 

Weitere Informationen finden Sie im Windows SDK.

[in] CreateDisposition

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

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, schlagen Sie 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 Beim Erstellen oder Öffnen der Datei anzuwendenden Optionen als kompatible Kombination der folgenden Flags.

Wert Bedeutung
FILE_DIRECTORY_FILE
 Die zu erstellende oder geöffnete Datei ist eine Verzeichnisdatei. Mit dieser Kennzeichnung muss der parameter CreateDisposition auf FILE_CREATE, FILE_OPENoder FILE_OPEN_IFfestgelegt werden. Mit dieser Kennzeichnung sind andere kompatible CreateOptions- Flags nur folgende: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO _NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENTund FILE_OPEN_BY_FILE_ID.
FILE_NON_DIRECTORY_FILE
 Die geöffnete Datei darf keine Verzeichnisdatei sein, oder dieser Aufruf schlägt fehl. 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-attribut festgelegt ist, FILE_NO_INTERMEDIATE _BUFFERING festgelegt ist.
FILE_SEQUENTIAL_ONLY
 Alle Zugriffe auf die Datei sind sequenziell.
FILE_RANDOM_ACCESS
 Der Zugriff auf die Datei kann zufällig sein, sodass keine sequenziellen Lese-/Vorlesevorgänge für die Datei durch FSDs oder das System ausgeführt werden sollten.
FILE_NO_INTERMEDIATE_BUFFERING
 Die Datei kann nicht zwischengespeichert oder in den internen Puffern eines Treibers gepuffert werden. Dieses Flag ist nicht mit dem DesiredAccessFILE_APPEND_DATA Flag kompatibel.
FILE_SYNCHRONOUS_IO_ALERT
 Alle Vorgänge in der Datei werden synchron ausgeführt. Jede Wartezeit im Auftrag des Anrufers unterliegt einer vorzeitigen Kündigung durch Warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionskontext aufrecht erhält. Wenn dieses Kennzeichen festgelegt ist, muss auch das flag DesiredAccessSYNCHRONIZE Flag festgelegt werden.
FILE_SYNCHRONOUS_IO_NONALERT
 Alle Vorgänge in der Datei werden synchron ausgeführt. Wartezeiten im System, um die E/A-Warteschlange zu synchronisieren und den Abschluss zu vervollständigen, unterliegen nicht warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionskontext aufrecht erhält. Wenn dieses Kennzeichen festgelegt ist, muss auch das flag DesiredAccessSYNCHRONIZE Flag festgelegt werden.
FILE_CREATE_TREE_CONNECTION
 Erstellen Sie eine Strukturverbindung für diese Datei, um sie über das Netzwerk zu öffnen. Dieses Kennzeichen wird nicht von Geräte- und Zwischentreibern 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 es mit EAs umgeht. Dieses Kennzeichen 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 "Hinweise".
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 parameter DesiredAccess festgelegt werden.
FILE_OPEN_BY_FILE_ID
 Der Dateiname, der durch den parameter ObjectAttributes angegeben wird, enthält die 8-Byte-Dateireferenznummer für die Datei. Diese Nummer wird dem jeweiligen Dateisystem zugewiesen und spezifisch. Wenn die Datei ein Analysepunkt ist, enthält der Dateiname auch den Namen eines Geräts. Beachten Sie, dass das FAT-Dateisystem dieses Flag nicht unterstützt. Dieses Kennzeichen wird nicht von Geräte- und Zwischentreibern verwendet.
FILE_OPEN_FOR_BACKUP_INTENT
 Die Datei wird zur Sicherung geöffnet. Daher sollte das System nach bestimmten Zugriffsrechten suchen und dem Aufrufer den entsprechenden Zugriff auf die Datei gewähren, bevor der parameter DesiredAccess für den Sicherheitsdeskriptor der Datei überprüft wird. Dieses Kennzeichen wird von Geräte- und Zwischentreibern nicht verwendet.
FILE_RESERVE_OPFILTER
Mit dieser Kennzeichnung kann eine Anwendung eine opportunistische Filtersperre (oplock) anfordern, um zu verhindern, dass andere Anwendungen Verstöße gegen die Freigabe erhalten. Wenn bereits geöffnete Handles vorhanden sind, schlägt die Erstellungsanforderung mit STATUS_OPLOCK_NOT_GRANTEDfehl. Weitere Informationen finden Sie im Abschnitt "Hinweise".
FILE_OPEN_REQUIRING_OPLOCK
 Die Datei wird geöffnet, und eine opportunistische Sperre (Oplock) auf der Datei wird als einzelner atomischer Vorgang angefordert. Das Dateisystem sucht nach Oplocks, bevor er den Erstellungsvorgang ausführt, und schlägt die Erstellung mit einem Rückgabecode von STATUS_CANNOT_BREAK_OPLOCK fehl, wenn das Ergebnis ein vorhandenes 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 für die folgenden Dateisysteme unterstützt: NTFS, FAT und exFAT.
FILE_COMPLETE_IF_OPLOCKED
 Schließen Sie diesen Vorgang sofort mit einem alternativen Erfolgscode von STATUS_OPLOCK_BREAK_IN_PROGRESS ab, wenn die Zieldatei oplocked ist, anstatt den Thread des Aufrufers zu blockieren. Wenn die Datei oplockedist, hat ein anderer Aufrufer bereits Zugriff auf die Datei. Dieses Kennzeichen wird nicht von Geräte- und Zwischentreibern 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 geeigneten Fehlerstatus zurück. Wenn ein Fehlerstatus zurückgegeben wird, kann der Aufrufer weitere Informationen zur Ursache des Fehlers finden, indem er die IoStatusBlock-überprüft. Um diese Überprüfung zu vereinfachen, kann eine Anwendung die makros NT_SUCCESS, NT_ERRORund NT_WARNING verwenden.

Bemerkungen

Das Handle, das von NtCreateFileangegeben wird, kann von nachfolgenden Aufrufen zum Bearbeiten von Daten innerhalb der Datei oder des Zustands oder der Attribute des Dateiobjekts verwendet werden.

Es gibt zwei alternative Möglichkeiten, den Namen der zu erstellenden oder geöffneten Datei mit NtCreateFile-anzugeben:

  • Als vollqualifizierter Pfadname, der im ObjectName Member der Eingabe ObjectAttributes-
  • 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 folgende Auswirkungen:
  • Damit ein Aufrufer einen E/A-Abschluss synchronisieren kann, indem auf das zurückgegebene FileHandle-gewartet wird, muss das flag SYNCHRONIZE festgelegt werden.
  • Das Übergeben einer Null an DesiredFlags ist ungültig.
  • Wenn nur die FILE_APPEND_DATA und SYNCHRONIZE Flags 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 bei Bedarf automatisch für diesen Schreibvorgangstyp erweitert.
  • Das Festlegen des FILE_WRITE_DATA Flags für eine Datei ermöglicht auch das Auftreten von Schreibvorgängen über das Ende der Datei hinaus. Die Datei wird für diesen Schreibtyp 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 die zurückgegebene FileHandle-verwendet wird, d. h., alle Vorgänge der Datei erfolgen über den System-Pager als Reaktion auf Anweisungen und Datenzugriffe.
Der parameter ShareAccess bestimmt, ob separate Threads gleichzeitig auf dieselbe Datei zugreifen können. Sofern 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_WRITEoder FILE_SHARE_DELETEangibt, können keine anderen Geöffneten Vorgänge für die Datei ausgeführt werden; d. h., 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 mit der Datei kompatibel sein, sowohl mit der DesiredAccess- als auch mit ShareAccess- Spezifikationen aller vorherigen Öffnen, die noch nicht mit NtClose-veröffentlicht wurden. Das heißt, der DesiredAccess Parameter, der für NtCreateFile- für eine bestimmte Datei angegeben wurde, darf nicht mit den Zugriffen in Konflikt stehen, die andere Öffnende der Datei nicht zugelassen haben.

Der CreateDisposition-wertFILE_SUPERSEDE erfordert, dass der Aufrufer DELETE Zugriff auf ein vorhandenes Dateiobjekt hat. Wenn ja, wird ein erfolgreicher Aufruf von NtCreateFile mit FILE_SUPERSEDE für eine vorhandene Datei effektiv gelöscht und anschließend erneut erstellt. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, die Datei durch Angeben eines ShareAccess--Parameters mit dem FILE_SHARE_DELETE Flagsatz geöffnet wurde. Beachten Sie, dass diese Art von Löschung mit dem POSIX-Stil des Überschreibens von Dateien konsistent ist. Die CreateDisposition- Werte FILE_OVERWRITE_IF und FILE_SUPERSEDE ähneln. Wenn ZwCreateFile- mit einer vorhandenen Datei aufgerufen wird und einer dieser CreateDisposition--Werte, wird die Datei ersetzt.

Das Überschreiben einer Datei entspricht semantisch einem Supersede-Vorgang, mit Ausnahme der folgenden Aktionen:

  • 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 FILE_SHARE_WRITE Flag geöffnet wurde, das im Eingabeparameter ShareAccess festgelegt ist.
  • Die angegebenen Dateiattribute werden logisch mit den bereits in der Datei gespeicherten Attributen versehen. Dies bedeutet, dass, wenn die Datei bereits von einem anderen Thread geöffnet wurde, ein nachfolgender Aufrufer von NtCreateFile vorhandene FileAttributes Flags nicht deaktivieren kann, aber 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 Betriebssystemen/2 konsistent ist.
Der wert CreateOptionsFILE_DIRECTORY_FILE gibt an, dass die zu erstellende oder geöffnete 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 eine inkonsistente CreateOptions- oder CreateDisposition--Wert angegeben hat, schlägt der Aufruf von NtCreateFile fehl.

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

  • Alle optionalen ByteOffset-, die an die NtReadFile- oder NtWriteFile--Funktion übergeben werden, muss ein Integral der Sektorgröße sein.
  • Die Length-, die an NtReadFile oder NtWriteFileübergeben wurde, muss ein integraler Bestandteil der Sektorgröße sein. Beachten Sie, dass das Angeben eines Lesevorgangs an einen Puffer, dessen Länge genau die Sektorgröße ist, zu einer geringeren Anzahl signifikanter Bytes führen kann, die an diesen Puffer übertragen werden, 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 anschließend NtQueryInformationFile mit diesem Handle aufrufen. Eine Liste der System-FILE_XXX-_ALIGNMENT-Werte finden Sie in der Windows SDK-Dokumentation.
  • Aufrufe an NtSetInformationFile mit dem parameter FileInformationClass auf FilePositionInformation festgelegt müssen einen Offset angeben, der ein integraler Bereich der Sektorgröße ist.
Die CreateOptionsFILE_SYNCHRONOUS_IO_ALERT und FILE_SYNCHRONOUS_IO_NONALERT Flags, die sich gegenseitig ausschließen, wie ihre Namen vorschlagen, geben an, dass alle E/A-Vorgänge in der Datei synchron sein sollen, solange sie über das dateiobjekt auftreten, das durch die zurückgegebene FileHandle-bezeichnet wird. Alle E/A-Vorgänge in einer solchen Datei werden über alle Threads serialisiert, indem das zurückgegebene Handle verwendet wird. Mit einer dieser CreateOptionsmuss das DesiredAccessSYNCHRONIZE Flag festgelegt werden, damit der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet. Mit einer dieser CreateOptions festgelegt, verwaltet der E/A-Manager den "Dateipositionskontext" für das Dateiobjekt, einen internen, aktuellen Dateipositionsversatz. Dieser Offset kann in Aufrufen von NtReadFile- und NtWriteFile-verwendet werden. Seine Position kann auch mit NtQueryInformationFile und NtSetInformationFileabgefragt oder festgelegt werden.

Wenn der CreateOptions Parameter das flag FILE_OPEN_REPARSE_POINT angibt und NtCreateFile eine Datei mit einem Analysepunkt öffnet, tritt keine normale Analyseverarbeitung auf 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. Wenn der Öffnenvorgang erfolgreich war, gibt NtCreateFile in beiden Fällen STATUS_SUCCESSzurück; andernfalls ein Fehlercode. Die NtCreateFile--Funktion gibt nie STATUS_REPARSEzurück.

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

Wenn in Windows 7 andere Handles in der Datei vorhanden sind, wenn eine Anwendung dieses Flag verwendet, schlägt der Erstellungsvorgang mit STATUS_OPLOCK_NOT_GRANTEDfehl. 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_OPLOCKfehlschlä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 nachfolgenden Versuche zum Öffnen der Datei werden ohne den Vorteil der normalen Oplock-Verarbeitung blockiert. Wenn dieser Aufruf erfolgreich ausgeführt wird, aber die nachfolgende Oplock-Anforderung fehlschlägt, muss eine Anwendung, die dieses Flag verwendet, sein Handle schließen, nachdem erkannt wird, dass die Oplock-Anforderung fehlgeschlagen ist.

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

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

  1. Stellen Sie eine Create-Anforderung mit CreateOptions von FILE_RESERVE_OPFILTER, DesiredAccess genau FILE_READ_ATTRIBUTESaus, und ShareAccess- genau (FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE). Mögliche Fehler sind wie folgt:
    • Wenn bereits geöffnete Handles vorhanden sind, schlägt die Erstellungsanforderung mit STATUS_OPLOCK_NOT_GRANTEDfehl, und der nächste angeforderte Oplock schlägt ebenfalls fehl.
    • Wenn Sie mehr Zugriff als FILE_READ_ATTRIBUTES oder weniger Freigabe als (FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)öffnen, schlägt die Anforderung mit STATUS_OPLOCK_NOT_GRANTEDfehl.
  2. Wenn die Erstellungsanforderung erfolgreich ist, fordern Sie ein Oplock an.
  3. Öffnen Sie ein weiteres Handle für die Datei, um E/A zu erledigen.
Schritt 3 macht dies nur für Filter oplocks praktisch. Der in Schritt 3 geöffnete Handle kann eine DesiredAccess- aufweisen, die maximal (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. Jedes DesiredAccess- größer als (FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE) unterbricht jedoch einen Oplock der Ebene 1 oder batch und macht das FILE_RESERVE_OPFILTER Flag für diese Oplock-Typen nutzlos.

NTFS ist das einzige Microsoft-Dateisystem, das FILE_RESERVE_OPFILTERimplementiert.

Weitere Informationen zu Oplocks finden Sie unter Oplock Semantics.

Beachten Sie, dass die WDK-Headerdatei NtDef.h für viele Konstantendefinitionen sowie das InitializeObjectAttributes Makros erforderlich ist. Sie können auch die funktionen LoadLibrary und GetProcAddress verwenden, um dynamisch mit NtDll.dllzu verknüpfen.

Anforderungen

Anforderung Wert
Zielplattform- Fenster
Header- winternl.h
Library ntdll.lib
DLL- ntdll.dll