IoGetDeviceDirectory-Funktion (wdm.h)

Artikel
02/07/2025

Gibt ein Handle zu einem Verzeichnis auf dem Datenträger zurück, in dem Treiber Dateien speichern können. Die Dateien in diesem Verzeichnis gelten für eine bestimmte Geräteinstanz.

Syntax

NTSTATUS IoGetDeviceDirectory(
  [_In_]  PDEVICE_OBJECT        PhysicalDeviceObject,
  [_In_]  DEVICE_DIRECTORY_TYPE DirectoryType,
  [_In_]  ULONG                 Flags,
  [_In_]  PVOID                 Reserved,
  [_Out_] PHANDLE               DeviceDirectoryHandle
);

Parameter

[_In_] PhysicalDeviceObject

Ein Zeiger auf das physische Geräteobjekt, im Gerätestapel einer bestimmten Geräteinstanz abgefragt werden. Darf nicht NULL sein.

[_In_] DirectoryType

Ein _DEVICE_DIRECTORY_TYPE-type-Wert, der den Typ des angeforderten Verzeichnisses angibt.

[_In_] Flags

Muss 0 sein.

[_In_] Reserved

Reserviert. Muss NULL sein.

[_Out_] DeviceDirectoryHandle

Ein Zeiger auf eine Variable, die ein HANDLE an das angeforderte Geräteverzeichnis empfängt. Der Aufrufer darf null nicht übergeben.

Rückgabewert

Gibt einen geeigneten NTSTATUS-Wertzurück. Mögliche Werte sind:

Fehlercode	Beschreibung
STATUS_SUCCESS	Der Aufruf hat erfolgreich ein Handle für das angeforderte Geräteverzeichnis geöffnet.
STATUS_INVALID_PARAMETER	Ein Eingabewert für diese Funktion ist ungültig. Beispielsweise ist PhysicalDeviceObject oder DeviceDirectoryHandle- NULL; Flags ist nicht 0; Reservierte ist nicht NULL.

Bemerkungen

Wenn IoGetDeviceDirectory- aufgerufen wird, bevor die erforderlichen Datenträger und Volumes gestartet wurden, öffnet die Funktion kein Handle und gibt einen Fehler zurück.

Treiber verwenden in der Regel ZwOpenFile- und ZwCreateFile- für den Zugriff auf/das Erstellen von Dateien. Einer der Parameter für diese Funktionen ist eine OBJECT_ATTRIBUTES Struktur, die den Objektnamen und ein Stammverzeichnis enthält. Wenn das Stammverzeichnis NULL ist, muss der Objektname ein vollqualifizierter Pfad sein. Wenn Sie jedoch ein Handle für das Stammverzeichnis angeben, muss der Objektname relativ zum Objekt (im Fall von Dateien, dem Verzeichnis) sein, das das Handle darstellt.

Nachdem der IoGetDevice Directory-Aufruf erfolgreich ausgeführt wurde, verwenden Sie das empfangene HANDLE als Stammverzeichnis in der OBJECT_ATTRIBUTES, die Sie an eine ZwOpenFile- und ZwCreateFileübergeben.

Der Treiber muss ZwClose- aufrufen, um den empfangenen Handle zu schließen, wenn kein Zugriff mehr erforderlich ist.

Aufrufer von IoGetDeviceDirectory- müssen unter IRQL = PASSIVE_LEVEL im Kontext eines Systemthreads ausgeführt werden.