IoCreateFileSpecifyDeviceObjectHint-Funktion (ntddk.h)

Artikel
03/08/2023

Die IoCreateFileSpecifyDeviceObjectHint-Routine wird von Dateisystemfiltertreibern verwendet, um eine Erstellungsanforderung nur an die Filter unterhalb eines angegebenen Geräteobjekts und an das Dateisystem zu senden.

Syntax

NTSTATUS IoCreateFileSpecifyDeviceObjectHint(
  [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] PVOID              DeviceObject
);

Parameter

[out] FileHandle

Ein Zeiger auf eine Variable, die ein Handle für das Dateiobjekt empfängt, wenn dieser Aufruf erfolgreich ist.

[in] DesiredAccess

Eine Bitmaske von Flags, die den Typ des Zugriffs angeben, den der Aufrufer auf die Datei oder das Verzeichnis benötigt. Der Satz systemdefinierter DesiredAccess-Flags bestimmt die folgenden spezifischen Zugriffsrechte für Dateiobjekte.

DesiredAccess-Flags	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 (EA), 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	Erweiterte Attribute, 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 diskretionäre Zugriffssteuerungsliste (DACL) 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 Signalzustand festgelegt wird. Dieses Flag muss festgelegt werden, wenn das CreateOptions-FILE_SYNCHRONOUS_IO_ALERT - oder FILE_SYNCHRONOUS_IO_NONALERT-Flag festgelegt ist.
FILE_EXECUTE	Daten können mithilfe von System paging-E/A aus der Datei in den Arbeitsspeicher eingelesen werden.

Aufrufer von IoCreateFileSpecifyDeviceObjectHint können für jedes Dateiobjekt, das keine Verzeichnisdatei darstellt, eine oder eine Kombination aus den folgenden, möglicherweise ORed mit zusätzlichen kompatiblen Flags aus der vorherigen Liste derDesiredAccess-Flags angeben:

DesiredAccess to file values	Zuordnung zu DesiredAccess-Flags
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA und SYNCHRONIZE.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA und SYNCHRONIZE.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, SYNCHRONISIEREN, FILE_READ_ATTRIBUTES und FILE_EXECUTE.

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

Wenn das FILE_DIRECTORY_FILE CreateOptions-Flag festgelegt ist, können Aufrufer von IoCreateFileSpecifyDeviceObjectHint eine oder eine Kombination aus den folgenden angeben, möglicherweise ORed mit einem oder mehreren kompatiblen Flags aus der vorherigen Liste derDesiredAccess-Flags .

DesiredAccess to directory values	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.

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

Ein 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 (ObjectAttributes) NULL sein. Andernfalls muss der Aufrufer das attribut OBJ_KERNEL_HANDLE im Aufruf der InitializeObjectAttributes-Routine festlegen. Zu den Elementen der OBJECT_ATTRIBUTES-Struktur für ein Dateiobjekt gehören folgendes.

Mitglied	Wert
ULONGLength	Gibt die Anzahl der Bytes der bereitgestellten ObjectAttributes-Daten an. Dieser Wert muss mindestens sizeof(OBJECT_ATTRIBUTES) sein.
PUNICODE_STRING ObjectName	Ein Zeiger auf eine gepufferte Unicode-Zeichenfolge mit dem Namen der zu erstellenden oder zu öffnenden Datei. Dieser Wert muss eine vollqualifizierte Dateispezifikation sein, es sei denn, es handelt sich um den Namen einer Datei relativ zu dem durch 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. (Beachten Sie, dass \?? \DosDevices als Name des Win32-Objektnamespaces ersetzt. \DosDevices funktioniert weiterhin, aber \?? wird vom Objekt-Manager schneller übersetzt.)
HANDLERootDirectory	Gibt optional ein Handle für ein Verzeichnis an, das durch einen vorherigen Aufruf von IoCreateFileSpecifyDeviceObjectHint 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	Gibt optional einen Sicherheitsdeskriptor an, der auf eine Datei angewendet werden soll. AcLs, die durch einen 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.
ULONGAttributes	Eine Reihe von Flags, die die Dateiobjektattribute steuern. Wenn der Aufrufer im Systemprozesskontext ausgeführt wird, kann dieser Parameter 0 sein. Andernfalls muss der Aufrufer das flag OBJ_KERNEL_HANDLE festlegen. Der Aufrufer kann auch optional das OBJ_CASE_INSENSITIVE-Flag festlegen, das angibt, dass name-lookup code die Groß-/Kleinschreibung von ObjectName ignorieren soll, anstatt eine Suche nach exakter Übereinstimmung durchzuführen.

[out] IoStatusBlock

Ein Zeiger auf eine IO_STATUS_BLOCK-Struktur, die die endgültige Vervollständigung status und Informationen zum angeforderten Vorgang empfängt. Beim Zurückgeben von IoCreateFileSpecifyDeviceObjectHint 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

Gibt optional die anfängliche Zuordnungsgröße in Bytes für die Datei an. Ein Wert ohne Zero 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, ersetzt oder in einigen Fällen überschrieben wird. Standardmäßig ist dieser Wert FILE_ATTRIBUTE_NORMAL, der von jedem anderen Flag oder einer ORed-Kombination kompatibler Flags überschrieben werden kann. Mögliche FileAttributes-Flags :

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

[in] ShareAccess

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

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

[in] Disposition

Gibt einen Wert an, der die auszuführende Aktion bestimmt, je nachdem, ob die Datei bereits vorhanden ist. Der Wert kann einer der folgenden Werte sein.

Dispositionswerte	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

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

CreateOptions-Flags	Bedeutung
FILE_DIRECTORY_FILE	Die datei, die erstellt oder geöffnet wird, ist eine Verzeichnisdatei. Wenn dieses Flag festgelegt ist, muss der Dispositionsparameter auf einen der FILE_CREATE, FILE_OPEN oder FILE_OPEN_IF festgelegt werden. Dieses Flag ist mit den folgenden CreateOptions-Flags kompatibel: 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 geöffnete Datei darf keine Verzeichnisdatei sein, andernfalls tritt bei diesem Aufruf ein Fehler auf. Das geöffnete Dateiobjekt muss eine Datendatei darstellen.
FILE_WRITE_THROUGH	Systemdienste, FSDs 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	Alle Zugriffe auf die Datei erfolgen sequenziell.
FILE_RANDOM_ACCESS	Zugriffe auf die Datei können zufällig erfolgen, sodass keine sequenziellen Lesevorgänge für die Datei durch FSDs oder das 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 der vorzeitigen Beendigung von Warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionskontext behält. Wenn dieses Flag festgelegt ist, muss auch das DesiredAccess SYNCHRONIZE-Flag festgelegt werden.
FILE_SYNCHRONOUS_IO_NONALERT	Alle Vorgänge für die Datei werden synchron ausgeführt. Wartezeiten, die im System vorhanden sind, um E/A-Warteschlangen und Vervollständigung zu synchronisieren, unterliegen keine Warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionskontext behält. Wenn dieses Flag festgelegt ist, muss auch das DesiredAccess SYNCHRONIZE-Flag festgelegt werden.
FILE_CREATE_TREE_CONNECTION	Erstellen Sie eine Strukturverbindung für diese Datei, um sie über das Netzwerk zu öffnen.
FILE_COMPLETE_IF_OPLOCKED	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 über das Netzwerk Zugriff auf die Datei.
FILE_NO_EA_KNOWLEDGE	Wenn die erweiterten Attribute einer vorhandenen Datei, die geöffnet wird, darauf hinweisen, 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.
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 weiter unten im Abschnitt Hinweise .
FILE_DELETE_ON_CLOSE	Löschen Sie die Datei, wenn das letzte Handle an ZwClose übergeben wird.
FILE_OPEN_BY_FILE_ID	Der im ObjectAttributes-Parameter angegebene Dateiname enthält die 8-Byte-Dateireferenznummer für die Datei. Diese Nummer wird vom Dateisystem zugewiesen und ist dateisystemspezifisch. Wenn es sich bei der Datei um einen Analysepunkt handelt, enthält der Dateiname auch den Namen eines Geräts. Hinweis: Das FAT-Dateisystem unterstützt FILE_OPEN_BY_FILE_ID nicht.
FILE_OPEN_FOR_BACKUP_INTENT	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_OPEN_REQUIRING_OPLOCK	Die Datei wird geöffnet, und eine opportunistische Sperre (Oplock) für die Datei wird als einzelner atomarer Vorgang angefordert. Das Dateisystem überprüft auf Oplocks, bevor es den Erstellungsvorgang ausführt, und der Erstellungsvorgang schlägt mit einem Rückgabecode von STATUS_CANNOT_BREAK_OPLOCK fehl, wenn die Erstellung einen vorhandenen Oplock unterbrechen würde.
FILE_RESERVE_OPFILTER	Dieses Flag ermöglicht es einer Anwendung, eine opportunistische Filtersperre (oplock) 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".

[in, optional] EaBuffer

Ein Zeiger auf einen vom Aufrufer bereitgestellten FILE_FULL_EA_INFORMATION strukturierten Puffer, der Informationen zum erweiterten Attribut (Extended Attribute, EA) enthält, die auf die Datei angewendet werden sollen.

[in] EaLength

Die Länge von EaBuffer in Bytes.

[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 Erstellung der Erstellungsanforderung verwendet werden sollen. In der folgenden Tabelle sind die verfügbaren Optionen aufgelistet.

Optionsflags	Bedeutung
IO_FORCE_ACCESS_CHECK	Gibt an, dass der E/A-Manager die Erstellungsanforderung anhand der Sicherheitsbeschreibung der Datei überprüfen muss.
IO_IGNORE_SHARE_ACCESS_CHECK	Gibt an, dass der E/A-Manager keine Freigabezugriffsprüfungen für das Dateiobjekt durchführen soll, nachdem es erstellt wurde. Möglicherweise führt das Dateisystem diese Überprüfungen jedoch weiterhin durch.

[in, optional] DeviceObject

Ein Zeiger auf das Geräteobjekt, an das die Erstellungsanforderung gesendet werden soll. Das Geräteobjekt muss ein Filter- oder Dateisystemgeräteobjekt im Dateisystemtreiberstapel für das Volume sein, auf dem sich die Datei oder das Verzeichnis befindet. Dieser Parameter ist optional und kann NULL sein. Wenn dieser Parameter NULL ist, wird die Anforderung an das Geräteobjekt am oberen Rand des Treiberstapels gesendet.

Rückgabewert

IoCreateFileSpecifyDeviceObjectHint gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Wert zurück, z. B. einen der folgenden:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	Das angegebene DeviceObject wird nicht an den Dateisystemtreiberstapel für das volume angefügt, das im Datei- oder Verzeichnisnamen angegeben ist. Dieser Fehler kann auch auftreten, wenn der Name einen anderen Analysepunkt als einen Bereitstellungspunkt enthält.
STATUS_MOUNT_POINT_NOT_RESOLVED	Der Datei- oder Verzeichnisname enthält einen Bereitstellungspunkt, der in ein anderes Volume als das Volume aufgelöst wird, an das das angegebene DeviceObject angefügt ist.
STATUS_OBJECT_PATH_SYNTAX_BAD

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

Hinweise

Diese Routine wird von Dateisystemfiltertreibern verwendet, um eine Erstellungsanforderung nur an die Filter unterhalb eines angegebenen Geräteobjekts und an das Dateisystem zu senden. Filter, die über dem angegebenen Geräteobjekt im Treiberstapel angefügt werden, erhalten die Erstellungsanforderung nicht.

Die Windows Vista IoCreateFileEx-Routine ähnelt der IoCreateFileSpecifyDeviceObjectHint-Routine , bietet jedoch eine größere Funktionalität als die IoCreateFileSpecifyDeviceObjectHint-Routine , einschließlich des Zugriffs auf zusätzliche Erstellungsparameter (ECPs) und Transaktionsinformationen.

Wenn Sie die IoCreateFileEx-Routine anstelle der IoCreateFileSpecifyDeviceObjectHint-Routine verwenden, beachten Sie, dass der DriverContext-Parameter der IoCreateFileSpecifyDeviceObjectHint-Routine in das DeviceObjectHint-Element der IO_DRIVER_CREATE_CONTEXT-Struktur verschoben wurde. Die IO_DRIVER_CREATE_CONTEXT-Struktur wird über den DriverContext-Parameter an die IoCreateFileEx-Routine übergeben.

Dateisystemfiltertreiber rufen IoCreateFileSpecifyDeviceObjectHint 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. Gleiches gilt für alle Bereinigungs- oder Schließenanforderungen für das Dateiobjekt, das von IoCreateFileSpecifyDeviceObjectHint erstellt wird.

Es gibt zwei alternative Möglichkeiten, den Namen der Datei anzugeben, die mit IoCreateFileSpecifyDeviceObjectHint 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

Jedes Handle, das aus IoCreateFileSpecifyDeviceObjectHint abgerufen wird, muss schließlich durch Aufrufen von ZwClose freigegeben werden.

Treiberroutinen, die in einem anderen Prozesskontext als dem des Systemprozesses ausgeführt werden, müssen das OBJ_KERNEL_HANDLE-Attribut für den ObjectAttributes-Parameter von IoCreateFileSpecifyDeviceObjectHint festlegen. Dadurch wird die Verwendung des von IoCreateFileSpecifyDeviceObjectHint zurückgegebenen Handle auf Prozesse eingeschränkt, die im Kernelmodus ausgeführt werden. Andernfalls kann der Prozess, in dessen Kontext der Treiber ausgeführt wird, auf das Handle zugreifen.

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

Damit ein Aufrufer eine E/A-Vervollständigung synchronisieren kann, indem er wartet, bis das zurückgegebene FileHandle auf den Signalzustand festgelegt wird, muss das SYNC-Flag festgelegt werden.
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 Flags FILE_EXECUTE und SYNCHRONIZE festgelegt sind, kann der Aufrufer keine Daten in der Datei direkt lesen oder schreiben, indem er die zurückgegebene FileHandle verwendet. 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 IoCreateFileSpecifyDeviceObjectHint 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 für die Datei sowohl mit den DesiredAccess - als auch mit den ShareAccess-Spezifikationen aller vorherigen Öffnungen kompatibel sein, die noch nicht mit ZwClose veröffentlicht wurden. Das heißt, der DesiredAccess , der in IoCreateFileSpecifyDeviceObjectHint 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 führt jedoch möglicherweise weiterhin Zugriffsprüfungen durch. Daher ist es wichtig, den freigabemodus anzugeben, den Sie für den ShareAccess-Parameter wünschen, 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 durch einen erfolgreichen Aufruf von IoCreateFileSpecifyDeviceObjectHint 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 ein ShareAccess-Parameter mit dem FILE_SHARE_DELETE-Flag festgelegt wurde. Beachten Sie, dass diese Art von Disposition mit dem POSIX-Stil zum Überschreiben von Dateien konsistent ist.

Die Dispositionswerte FILE_OVERWRITE_IF und FILE_SUPERSEDE sind ähnlich. Wenn IoCreateFileSpecifyDeviceObjectHint mit einer vorhandenen Datei und einem dieser Dispositionswerte 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 in der Eingabe ShareAccess 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 IoCreateFileSpecifyDeviceObjectHint vorhandene FileAttributes-Flags nicht deaktivieren kann, aber zusätzliche Flags für dieselbe Datei aktivieren kann, wenn die Datei bereits von einem anderen Thread geöffnet wurde.

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 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 Disposition-Wert angegeben hat, schlägt der Aufruf von IoCreateFileSpecifyDeviceObjectHint fehl.

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

Jeder Byteoffsetwert , der an ZwReadFile oder ZwWriteFile übergeben wird, muss ein Vielfaches der Sektorgröße des zugrunde liegenden Geräts sein.
Die Länge , die an ZwReadFile oder ZwWriteFile übergeben wird, muss ein Vielfaches 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 ausgerichtet werden. Diese Informationen können abgerufen werden, indem Sie IoCreateFileSpecifyDeviceObjectHint 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 , bei denen der FileInformationClass-Parameter auf FilePositionInformation festgelegt ist, müssen einen Offset angeben, der ein Vielfaches der Sektorgröße ist.

Die sich gegenseitig ausschließenden CreateOptions-FILE_SYNCHRONOUS_IO_ALERT und FILE_SYNCHRONOUS_IO_NONALERT 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 DesiredAccess SYNCHRONIZE-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 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 IoCreateFileSpecifyDeviceObjectHint versucht, eine Datei mit einem Analysepunkt zu öffnen, erfolgt die normale Analysepunktverarbeitung für die Datei. Wenn hingegen das flag FILE_OPEN_REPARSE_POINT angegeben ist, wird die normale Reparseverarbeitung nicht ausgeführt, und IoCreateFileSpecifyDeviceObjectHint versucht, die Analysepunktdatei direkt zu öffnen. In beiden Fällen gibt IoCreateFileSpecifyDeviceObjectHint STATUS_SUCCESS zurück, wenn der geöffnete Vorgang erfolgreich war. Andernfalls gibt die Routine einen NTSTATUS-Fehlercode zurück. IoCreateFileSpecifyDeviceObjectHint gibt nie STATUS_REPARSE zurück.

Das Flag CreateOptions FILE_OPEN_REQUIRING_OPLOCK beseitigt die Zeit zwischen dem Öffnen der Datei und der Anforderung eines Oplocks, der es einem Drittanbieter möglicherweise ermöglichen könnte, die Datei zu öffnen und eine Freigabeverletzung zu erhalten. Eine Anwendung kann das FILE_OPEN_REQUIRING_OPLOCK-Flag für IoCreateFileSpecifyDeviceObjectHint verwenden und dann einen beliebigen Oplock anfordern. Dadurch wird sichergestellt, dass ein Oplock-Besitzer über jede spätere offene Anforderung benachrichtigt wird, die eine Freigabeverletzung 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 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, sonst werden alle späteren Versuche, die Datei zu öffnen, ohne den Vorteil der typischen Oplock-Verarbeitung 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 bei der oplock-Anforderung ein Fehler aufgetreten ist.

Das FILE_OPEN_REQUIRING_OPLOCK-Flag ist unter Windows 7, Windows Server 2008 R2 und höheren Windows-Betriebssystemen verfügbar. Die Microsoft-Dateisysteme, die dieses Flag in Windows 7 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 zu verwenden, 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 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 ein DesiredAccess-Element enthalten, das maximal FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONISIEREN | READ_CONTROL und trotzdem keinen Filter oplock unterbrechen. Ein DesiredAccess 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 nutzlos.

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

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

Wenn der An IoCreateFileSpecifyDeviceObjectHint übergebene Dateinamenpfad einen Analysepunkt enthält, muss der Analysepunkt in dasselbe Volume aufgelöst werden, in dem sich die Datei oder das Verzeichnis befindet. Andernfalls wird entweder der Fehler STATUS_INVALID_DEVICE_OBJECT_PARAMETER oder STATUS_MOUNT_POINT_NOT_RESOLVED zurückgegeben.

Anforderungen

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