Funzione IoGetDeviceDirectory (wdm.h)

Articolo
08/08/2023

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 particolare istanza del dispositivo. Non deve essere NULL.

[_In_] DirectoryType

Valore di tipo _DEVICE_DIRECTORY_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 alla directory del dispositivo richiesta. Il chiamante non deve passare NULL.

Valore restituito

Restituisce un valore NTSTATUS appropriato. I valori possibili sono:

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; I flag non sono 0; Reserved non è NULL.

Commenti

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 fornisce un handle per la directory radice, il nome dell'oggetto deve essere relativo all'oggetto (nel caso dei file, la directory), rappresentato dall'handle.

Al termine della chiamata IoGetDeviceDirectory , usare l'handle ricevuto come directory radice nel OBJECT_ATTRIBUTES che si passa a 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.