Função SetupDiGetDeviceInterfaceAlias (setupapi.h)

A função SetupDiGetDeviceInterfaceAlias retorna um alias de uma interface de dispositivo especificada.

Sintaxe

WINSETUPAPI BOOL SetupDiGetDeviceInterfaceAlias(
  [in]  HDEVINFO                  DeviceInfoSet,
  [in]  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  [in]  const GUID                *AliasInterfaceClassGuid,
  [out] PSP_DEVICE_INTERFACE_DATA AliasDeviceInterfaceData
);

Parâmetros

[in] DeviceInfoSet

Um ponteiro para o conjunto de informações do dispositivo que contém a interface do dispositivo para a qual recuperar um alias. Esse identificador normalmente é retornado por SetupDiGetClassDevs.

[in] DeviceInterfaceData

Um ponteiro para uma estrutura SP_DEVICE_INTERFACE_DATA que especifica a interface do dispositivo em DeviceInfoSet para a qual recuperar um alias. Normalmente, esse ponteiro é retornado por SetupDiEnumDeviceInterfaces.

[in] AliasInterfaceClassGuid

Um ponteiro para um GUID que especifica a classe de interface do alias a ser recuperado.

[out] AliasDeviceInterfaceData

Um ponteiro para um buffer alocado pelo chamador que contém, no retorno bem-sucedido, uma estrutura de SP_DEVICE_INTERFACE_DATA concluída que identifica o alias solicitado. O chamador deve definir AliasDeviceInterfaceData.cbSize como sizeof(SP_DEVICE_INTERFACE_DATA) antes de chamar essa função.

Retornar valor

SetupDiGetDeviceInterfaceAlias retornará TRUE se a função for concluída sem erro. Se a função for concluída com um erro, FALSE será retornado e o código de erro para a falha poderá ser recuperado chamando GetLastError.

Possíveis erros retornados por GetLastError são listados na tabela a seguir.

Código de retorno	Descrição
ERROR_INVALID_PARAMETER	DispositivoInfoSet inválido ou parâmetro DeviceInterfaceData inválido.
ERROR_NO_SUCH_INTERFACE_DEVICE	Não há nenhum alias da classe AliasInterfaceClassGuid para a interface do dispositivo especificada.
ERROR_INVALID_USER_BUFFER	Buffer AliasDeviceInterfaceData inválido.

Comentários

As interfaces de dispositivo são consideradas aliases se forem de classes de interface diferentes, mas tiverem suporte no mesmo dispositivo e tiverem cadeias de caracteres de referência idênticas.

SetupDiGetDeviceInterfaceAlias pode ser usado para localizar um dispositivo que expõe mais de uma interface. Por exemplo, considere um disco que pode fazer parte de um volume tolerante a falhas e pode conter dados criptografados. O driver de função para o dispositivo de disco pode registrar uma interface de volume tolerante a falhas e uma interface de volume criptografado. Essas interfaces são aliases de interface do dispositivo se o driver de função as registrar com cadeias de caracteres de referência idênticas e se referirem ao mesmo dispositivo. (As cadeias de caracteres de referência provavelmente serão NULL e, portanto, são iguais.)

Para localizar um dispositivo de várias interfaces, primeiro localize todos os dispositivos disponíveis que expõem uma das interfaces, como a interface de volume tolerante a falhas, usando SetupDiGetClassDevs e SetupDiEnumDeviceInterfaces. Em seguida, passe um dispositivo com a primeira interface (volume tolerante a falhas) para SetupDiGetDeviceInterfaceAlias e solicite um alias da outra classe de interface (encrypted-volume).

Se o alias solicitado existir, mas o buffer AliasDeviceInterfaceData fornecido pelo chamador for inválido, essa função adicionará com êxito o elemento de interface do dispositivo a DevInfoSet , mas retornará FALSE para o valor retornado. Nesse caso, GetLastError retorna ERROR_INVALID_USER_BUFFER.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Microsoft Windows 2000 e versões posteriores do Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	setupapi.h (inclua Setupapi.h)
Biblioteca	Setupapi.lib
DLL	Setupapi.dll

Confira também

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs