Funzione IoGetDeviceDirectory (wdm.h)

Articolo
02/07/2025

Restituisce un handle a una directory su disco, in cui i driver possono archiviare i file. I file in tale directory si applicano a un'istanza del dispositivo specifica.

Sintassi

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

Parametri

[_In_] PhysicalDeviceObject

Puntatore all'oggetto dispositivo fisico sottoposto a query nello stack di dispositivi di una determinata istanza del dispositivo. Non deve essere NULL.

[_In_] DirectoryType

Valore _DEVICE_DIRECTORY_TYPE-type che indica il tipo di directory richiesta.

[_In_] Flags

Deve essere 0.

[_In_] Reserved

Riservato. Deve essere NULL.

[_Out_] DeviceDirectoryHandle

Puntatore a una variabile che riceve un handle nella directory del dispositivo richiesta. Il chiamante non deve passare NULL.

Valore restituito

Restituisce un valore NTSTATUS appropriato . I valori possibili includono:

Codice di errore	Descrizione
STATUS_SUCCESS	La chiamata ha aperto correttamente un handle alla directory del dispositivo richiesta.
STATUS_INVALID_PARAMETER	Un valore di input per questa funzione non è valido. Ad esempio, PhysicalDeviceObject o DeviceDirectoryHandle è NULL; flag non è 0; riservato non è NULL.

Osservazioni

Se IoGetDeviceDirectory viene chiamato prima dell'avvio dei dischi e dei volumi necessari, la funzione non apre un handle e restituisce un errore.

I driver usano in genere ZwOpenFile e ZwCreateFile per accedere/creare file. Uno dei parametri per tali funzioni è una struttura OBJECT_ATTRIBUTES, che contiene il nome dell'oggetto e una directory radice. Se la directory radice è NULL, il nome dell'oggetto deve essere un percorso completo. Tuttavia, se si specifica un handle per la directory radice, il nome dell'oggetto deve essere relativo all'oggetto (nel caso di file, la directory), rappresentato dall'handle.

Dopo che la chiamata IoGetDeviceDirectory ha esito positivo, usare l'handle ricevuto come directory radice nel OBJECT_ATTRIBUTES passato a un ZwOpenFile e ZwCreateFile.

Il driver deve chiamare ZwClose per chiudere l'handle ricevuto quando l'accesso non è più necessario.

I chiamanti di IoGetDeviceDirectory devono essere in esecuzione in IRQL = PASSIVE_LEVEL nel contesto di un thread di sistema.