Função IoEnumerateDeviceObjectList (ntifs.h)
A rotina de IoEnumerateDeviceObjectList enumera a lista de objetos do dispositivo de um driver.
Sintaxe
NTSTATUS IoEnumerateDeviceObjectList(
[in] PDRIVER_OBJECT DriverObject,
[out] PDEVICE_OBJECT *DeviceObjectList,
[in] ULONG DeviceObjectListSize,
[out] PULONG ActualNumberDeviceObjects
);
Parâmetros
[in] DriverObject
Um ponteiro para o objeto driver para o driver.
[out] DeviceObjectList
Um ponteiro para uma matriz alocada por chamador que recebe os ponteiros de objeto do dispositivo. Essa matriz deve ser alocada do pool nãopagado. Esse parâmetro pode ser NULL. Consulte Comentários.
[in] DeviceObjectListSize
Tamanho, em bytes, da matriz DeviceObjectList. Esse parâmetro pode ser zero. Consulte Comentários.
[out] ActualNumberDeviceObjects
Número real de objetos de dispositivo encontrados na lista de objetos do dispositivo do objeto de driver. Observe que se a matriz em DeviceObjectList for muito pequena, o número de ponteiros de objeto do dispositivo copiados para a matriz será menor que ActualNumberDeviceObjects.
Valor de retorno
IoEnumerateDeviceObjectList retorna um código NTSTATUS, como um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
| STATUS_SUCCESS | A chamada para IoEnumerateDeviceObjectList concluída com êxito. |
| STATUS_BUFFER_TOO_SMALL | A matriz em DeviceObjectList é muito pequena para manter toda a lista de objetos do dispositivo. Nesse caso, IoEnumerateDeviceObjectList copia o máximo possível de ponteiros de objeto do dispositivo para a matriz. |
Observações
Um driver de filtro do sistema de arquivos chama IoEnumerateDeviceObjectList para enumerar:
Os objetos do dispositivo que ele criou. Isso geralmente é feito quando o driver está se preparando para descarregar. Observe que um driver de filtro não pode ser descarregado com segurança de um sistema em execução. Para obter mais informações, consulte ZwUnloadDriver .
Os objetos de dispositivo criados pelo sistema de arquivos base, para que o filtro saiba o número de volumes aos quais ele pode anexar.
IoEnumerateDeviceObjectList retorna todos os objetos de dispositivo criados pelo driver de filtro. Isso inclui CDOs (objetos de dispositivo de controle), bem como VDOs (objetos de dispositivo de volume). Os dois tipos de objetos de dispositivo podem ser distinguidos pelo fato de que, por convenção, os CDOs são nomeados e os VDOs não são.
No último caso, o driver de filtro normalmente chama IoEnumerateDeviceObjectList duas vezes: uma vez para obter o número de objetos de dispositivo na lista e uma vez para obter a própria lista de objetos do dispositivo. Na primeira chamada, o chamador deve definir o parâmetro DeviceObjectList como NULL e DeviceObjectListSize como zero. Na segunda chamada, DeviceObjectList deve conter um ponteiro para uma matriz de ponteiro de tamanho adequado e DeviceObjectListSize deve conter o tamanho, em bytes, dessa matriz.
IoEnumerateDeviceObjectList incrementa a contagem de referência em cada objeto de dispositivo na lista apontada por DeviceObjectList. Portanto, cada chamada bem-sucedida para IoEnumerateDeviceObjectList deve ser correspondida por uma chamada subsequente para ObDereferenceObject para cada objeto de dispositivo na lista. A falha ao fazer isso impede que o sistema libere ou exclua esses objetos de dispositivo devido a uma contagem de referência pendente.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Pacote cumulativo de atualizações do Windows 2000 SP4; Windows XP |
| da Plataforma de Destino | Universal |
| cabeçalho | ntifs.h (inclua Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |