IoGetDeviceDirectory-Funktion (wdm.h)

Artikel
02/27/2024

Gibt ein Handle für ein Verzeichnis auf dem Datenträger zurück, in dem Treiber Dateien speichern können. Die Dateien in diesem Verzeichnis gelten für ein bestimmtes Gerät instance.

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 objekt des physischen Geräts, das im Gerätestapel eines bestimmten Geräts instance abgefragt wird. Darf nicht NULL sein.

[_In_] DirectoryType

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

[_In_] Flags

Muss den Wert 0 (null) haben.

[_In_] Reserved

Reserviert. Muss NULL sein.

[_Out_] DeviceDirectoryHandle

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

Rückgabewert

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

Fehlercode	BESCHREIBUNG
STATUS_SUCCESS	Der Aufruf öffnete erfolgreich ein Handle für das angeforderte Geräteverzeichnis.
STATUS_INVALID_PARAMETER	Ein Eingabewert für diese Funktion ist ungültig. Beispielsweise ist PhysicalDeviceObject oder DeviceDirectoryHandle NULL. Flags ist nicht 0; Reserviert ist nicht NULL.

Hinweise

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 , um auf Dateien zuzugreifen bzw. diese zu erstellen. 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 bereitstellen, muss der Objektname relativ zum Objekt (im Fall von Dateien das Verzeichnis) sein, das das Handle darstellt.

Nachdem der IoGetDeviceDirectory-Aufruf erfolgreich war, 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 das empfangene 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.