Funzione IoEnumerateDeviceObjectList (ntifs.h)
La routine IoEnumerateDeviceObjectList enumera l'elenco di oggetti dispositivo di un driver.
NTSTATUS IoEnumerateDeviceObjectList(
[in] PDRIVER_OBJECT DriverObject,
[out] PDEVICE_OBJECT *DeviceObjectList,
[in] ULONG DeviceObjectListSize,
[out] PULONG ActualNumberDeviceObjects
);
[in] DriverObject
Puntatore all'oggetto driver per il driver.
[out] DeviceObjectList
Puntatore a una matrice allocata dal chiamante che riceve i puntatori agli oggetti dispositivo. Questa matrice deve essere allocata dal pool non di paging. 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.
IoEnumerateDeviceObjectList restituisce un codice NTSTATUS, ad esempio uno dei valori seguenti:
| Codice restituito | Descrizione |
|---|---|
| STATUS_SUCCESS | La chiamata a IoEnumerateDeviceObjectList 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. |
Un driver di filtro del file system chiama IoEnumerateDeviceObjectList per enumerare:
Oggetti dispositivo creati. Questa operazione viene in genere eseguita quando il driver si prepara 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, in modo che il filtro conosca il numero di volumi a cui può collegarsi.
IoEnumerateDeviceObjectList restituisce tutti gli oggetti dispositivo creati dal driver di filtro. Sono inclusi gli oggetti dispositivo di controllo (CDO) e gli oggetti dispositivo del volume (VDO). I due tipi di oggetti dispositivo possono essere distinti dal fatto che, per convenzione, i CDO sono denominati e gli oggetti VDO non sono.
Nel secondo 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 di oggetti 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 di puntatori di dimensioni appropriate e DeviceObjectListSize deve contenere le dimensioni, in byte, di tale matrice.
IoEnumerateDeviceObjectList incrementa il conteggio dei riferimenti per ogni oggetto dispositivo nell'elenco a cui punta DeviceObjectList. Pertanto, ogni chiamata riuscita a IoEnumerateDeviceObjectList deve essere confrontata con una chiamata successiva a ObDereferenceObject per ogni oggetto dispositivo nell'elenco. In caso contrario, impedisce al sistema di liberare o eliminare questi oggetti dispositivo a causa di un conteggio dei riferimenti in sospeso.
| 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 |