Função IoGetDeviceInterfaces (wdm.h)

Artigo
03/01/2024

A rotina IoGetDeviceInterfaces retorna uma lista de instâncias de interface do dispositivo de uma classe de interface de dispositivo específica (como todos os dispositivos no sistema que dão suporte a uma interface HID).

Sintaxe

NTSTATUS IoGetDeviceInterfaces(
  [in]           const GUID     *InterfaceClassGuid,
  [in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
  [in]           ULONG          Flags,
  [out]          PZZWSTR        *SymbolicLinkList
);

Parâmetros

[in] InterfaceClassGuid

Ponteiro para um GUID de classe que especifica a classe de interface do dispositivo. Os GUIDs de uma classe devem estar em um arquivo de cabeçalho específico do dispositivo.

[in, optional] PhysicalDeviceObject

Ponteiro para um PDO opcional que restringe a pesquisa apenas às instâncias de interface do dispositivo do dispositivo representado pelo PDO.

[in] Flags

Especifica sinalizadores que modificam a pesquisa de interfaces de dispositivo. Apenas um sinalizador está definido no momento e é descrito na tabela a seguir.

Sinalizador	Significado
DEVICE_INTERFACE_INCLUDE_NONACTIVE	Retornar instâncias de interface do dispositivo desabilitadas, além de instâncias de interface habilitadas.

Ao pesquisar um dispositivo que dê suporte a uma classe de interface específica, o chamador requer uma instância de interface habilitada e, portanto, não define o sinalizador DEVICE_INTERFACE_INCLUDE_NONACTIVE.

Um driver normalmente define o sinalizador DEVICE_INTERFACE_INCLUDE_NONACTIVE para localizar instâncias de interface desabilitadas que o driver deve habilitar. Por exemplo, o instalador de classe para o dispositivo pode ter sido direcionado pelo arquivo INF para registrar uma ou mais instâncias de interface para o dispositivo. As instâncias de interface seriam registradas, mas não poderão ser usadas até que sejam habilitadas pelo driver (usando IoSetDeviceInterfaceState). Para restringir a lista de instâncias de interface retornadas apenas às expostas por um determinado dispositivo, um driver pode especificar um PhysicalDeviceObject.

[out] SymbolicLinkList

Um ponteiro para um ponteiro de caractere largo no qual a rotina, se bem-sucedida, grava o endereço base de um buffer que contém uma lista de cadeias de caracteres Unicode. Essas cadeias de caracteres são nomes de link simbólicos que identificam as instâncias de interface do dispositivo que correspondem aos critérios de pesquisa. Cada cadeia de caracteres Unicode na lista é terminada em nulo; o final da lista inteira é marcado por um caractere nulo adicional. A rotina aloca o buffer para essas cadeias de caracteres da memória paginada do sistema. O chamador é responsável por liberar o buffer (chamando a rotina ExFreePool ) quando ele não for mais necessário.

Se nenhuma instância de interface do dispositivo corresponder aos critérios de pesquisa, essa rotina retornará STATUS_SUCCESS e a cadeia de caracteres conterá um único caractere NULL.

Retornar valor

IoGetDeviceInterfaces retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Possíveis valores retornados por erro incluem o seguinte.

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	Possivelmente indica que PhysicalDeviceObject não era um ponteiro PDO válido.

Comentários

IoGetDeviceInterfaces retorna uma lista de instâncias de interface do dispositivo que correspondem aos critérios de pesquisa. Um componente do modo kernel normalmente chama essa rotina para obter uma lista de todas as instâncias de interface do dispositivo habilitadas de uma classe de interface de dispositivo específica. Esse componente pode obter um ponteiro para o objeto de arquivo e/ou o objeto de dispositivo para uma interface chamando a rotina IoGetDeviceObjectPointer ou ZwCreateFile . O ponteiro do objeto do dispositivo retornado por IoGetDeviceObjectPointer aponta para a parte superior da pilha do dispositivo e pode ser usado em chamadas para a rotina IoCallDriver .

Se houver uma interface padrão para a classe de interface do dispositivo solicitada, ela será listada primeiro em SymbolicLinkList. As interfaces padrão podem ser definidas pelo modo de usuário, mas não pelo modo kernel.

O formato de um nome de link simbólico é opaco; o chamador não deve tentar analisar um nome de link simbólico.

Links simbólicos para instâncias de interface do dispositivo podem ser usados entre inicializações do sistema.

Para ser notificado quando instâncias de interface de dispositivo adicionais de uma classe específica estiverem habilitadas no sistema, registre-se para notificação de uma alteração de classe de dispositivo chamando a rotina IoRegisterPlugPlayNotification .

Os chamadores de IoGetDeviceInterfaces devem estar em execução em IRQL = PASSIVE_LEVEL no contexto de um thread do sistema.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 2000.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
Regras de conformidade da DDI	HwStorPortProhibitedDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)