Funzione IoEnumerateDeviceObjectList (ntifs.h)

Articolo
03/08/2023

La routine IoEnumerateDeviceObjectList enumera l'elenco di oggetti del dispositivo di un driver.

Sintassi

NTSTATUS IoEnumerateDeviceObjectList(
  [in]  PDRIVER_OBJECT DriverObject,
  [out] PDEVICE_OBJECT *DeviceObjectList,
  [in]  ULONG          DeviceObjectListSize,
  [out] PULONG         ActualNumberDeviceObjects
);

Parametri

[in] DriverObject

Puntatore all'oggetto driver per il driver.

[out] DeviceObjectList

Puntatore a una matrice allocata dal chiamante che riceve i puntatori a oggetti del dispositivo. Questa matrice deve essere allocata dal pool non a pagina. Questo parametro può essere NULL. Vedere la sezione Osservazioni.

[in] DeviceObjectListSize

Dimensioni, in byte, della matrice DeviceObjectList . Questo parametro può essere zero. Vedere la sezione Osservazioni.

[out] ActualNumberDeviceObjects

Numero effettivo di oggetti dispositivo trovati nell'elenco di oggetti dispositivo dell'oggetto driver. Si noti che se la matrice in DeviceObjectList è troppo piccola, il numero di puntatori a oggetti dispositivo copiati nella matrice sarà minore di ActualNumberDeviceObjects.

Valore restituito

IoEnumerateDeviceObjectList restituisce un codice NTSTATUS, ad esempio uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	La chiamata a IoEnumerateDeviceObjectList è stata completata correttamente.
STATUS_BUFFER_TOO_SMALL	La matrice in DeviceObjectList è troppo piccola per contenere l'intero elenco di oggetti del dispositivo. In questo caso, IoEnumerateDeviceObjectList copia il maggior numero possibile di puntatori a oggetti dispositivo nella matrice.

Commenti

Un driver di filtro del file system chiama IoEnumerateDeviceObjectList per enumerare:

Gli oggetti del dispositivo creati. Questa operazione viene comunemente eseguita quando il driver sta preparando a scaricare. Si noti che un driver di filtro non può essere scaricato in modo sicuro da un sistema in esecuzione. Per altre informazioni, vedere ZwUnloadDriver.
Gli oggetti dispositivo creati dal file system di base, quindi il filtro conosce il numero di volumi a cui può essere collegato.

IoEnumerateDeviceObjectList restituisce tutti gli oggetti dispositivo creati dal driver di filtro. Ciò include oggetti dispositivo di controllo (CDO) e oggetti dispositivo volume (VDOs). I due tipi di oggetti dispositivo possono essere distinti dal fatto che, per convenzione, i CDO sono denominati e i VDO non sono.

In quest'ultimo caso, il driver di filtro chiama in genere IoEnumerateDeviceObjectList due volte: una volta per ottenere il numero di oggetti dispositivo nell'elenco e una volta per ottenere l'elenco degli oggetti del dispositivo stesso. Nella prima chiamata, il chiamante deve impostare il parametro DeviceObjectList su NULL e DeviceObjectListSize su zero. Nella seconda chiamata , DeviceObjectList deve contenere un puntatore a una matrice puntatore di dimensioni appropriate e DeviceObjectListSize deve contenere le dimensioni, in byte, di tale matrice.

IoEnumerateDeviceObjectList incrementa il conteggio dei riferimenti su ogni oggetto dispositivo nell'elenco a cui punta deviceObjectList. Pertanto, ogni chiamata riuscita a IoEnumerateDeviceObjectList deve essere corrispondente a una chiamata successiva a ObDereferenceObject per ogni oggetto dispositivo nell'elenco. La mancata operazione impedisce al sistema di liberare o eliminare questi oggetti dispositivo a causa di un numero di riferimenti in sospeso.

Requisiti

Requisito	Valore
Client minimo supportato	Aggiornamento cumulativo di Windows 2000 SP4; Windows XP
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL