Função IoEnumerateDeviceObjectList (ntifs.h)

Artigo
02/26/2024

A rotina IoEnumerateDeviceObjectList enumera a lista de objetos de 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 de driver para o driver.

[out] DeviceObjectList

Um ponteiro para uma matriz alocada pelo chamador que recebe os ponteiros de objeto do dispositivo. Essa matriz deve ser alocada do pool nãopagado. Este parâmetro pode ser NULL. Consulte Observações.

[in] DeviceObjectListSize

Tamanho, em bytes, da matriz DeviceObjectList . Esse parâmetro pode ser zero. Consulte Observações.

[out] ActualNumberDeviceObjects

Número real de objetos de dispositivo encontrados na lista de objetos de dispositivo do objeto de driver. Observe que, se a matriz em DeviceObjectList for muito pequena, o número de ponteiros de objeto de dispositivo copiados para a matriz será menor que ActualNumberDeviceObjects.

Retornar valor

IoEnumerateDeviceObjectList retorna um código NTSTATUS, como um dos seguintes valores:

Código de retorno	Descrição
STATUS_SUCCESS	A chamada para IoEnumerateDeviceObjectList foi 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 de dispositivo para a matriz.

Comentários

Um driver de filtro do sistema de arquivos chama IoEnumerateDeviceObjectList para enumerar:

Os objetos de 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 diferenciados 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 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 apropriado, 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. Não fazer isso impede que o sistema libere ou exclua esses objetos de dispositivo devido a uma contagem de referência pendente.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Pacote cumulativo de atualizações do Windows 2000 SP4; Windows XP
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL