Função IoGetDeviceInterfaceAlias (wdm.h)

Artigo
02/07/2025

A rotina IoGetDeviceInterfaceAlias retorna a interface do dispositivo de alias da instância de interface do dispositivo especificada, se o alias existir.

Sintaxe

NTSTATUS IoGetDeviceInterfaceAlias(
  [in]  PUNICODE_STRING SymbolicLinkName,
  [in]  const GUID      *AliasInterfaceClassGuid,
  [out] PUNICODE_STRING AliasSymbolicLinkName
);

Parâmetros

[in] SymbolicLinkName

Ponteiro para o nome da instância da interface do dispositivo para a qual recuperar um alias. O chamador normalmente recebeu essa cadeia de caracteres de uma chamada para IoGetDeviceInterfaces ou em uma estrutura de notificação PnP.

[in] AliasInterfaceClassGuid

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

[out] AliasSymbolicLinkName

Especifica um ponteiro para uma cadeia de caracteres NULL Unicode. No retorno bem-sucedido, AliasSymbolicLinkName.buffer aponta para uma cadeia de caracteres que contém o nome do alias. O chamador deve liberar a cadeia de caracteres Unicode com rtlFreeUnicodeString quando ela não for mais necessária.

Valor de retorno

IoGetDeviceInterfaceAlias retornará STATUS_SUCCESS se a chamada tiver sido bem-sucedida. Os valores de retorno de erro possíveis são descritos a seguir.

Código de retorno	Descrição
STATUS_OBJECT_NAME_NOT_FOUND	Possivelmente indica que não há nenhum alias da classe de interface especificada.
STATUS_OBJECT_PATH_NOT_FOUND	Possivelmente indica que não há nenhum alias da classe de interface especificada.
STATUS_INVALID_HANDLE	Possivelmente indica um SymbolicLinkName inválido ou um AliasClassGuidinválido.

Observações

As interfaces de dispositivo serão consideradas aliases se forem expostas pelo mesmo dispositivo subjacente e tiverem cadeias de caracteres de referência de interface idênticas, mas forem de classes de interface diferentes.

O parâmetro SymbolicLinkName especifica uma instância de interface do dispositivo para um dispositivo específico, pertencente a uma classe de interface específica, com uma cadeia de caracteres de referência específica. IoGetDeviceInterfaceAlias retorna outra instância de interface do dispositivo para o mesmo dispositivo e cadeia de caracteres de referência, mas de uma classe de interface diferente, se existir.

Por exemplo, o driver de função para um volume tolerante a falhas pode registrar e definir duas interfaces de dispositivo, uma da classe de interface de volume tolerante a falhas e uma da classe de interface de volume. Outro driver poderia chamar IoGetDeviceInterfaceAlias com o link simbólico para uma das interfaces e perguntar se a outra interface existe especificando sua classe de interface.

Duas interfaces de dispositivo com cadeias de referência null são aliases se forem expostas pelo mesmo dispositivo subjacente e tiverem GUIDs de classe de interface diferentes.

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

Requisitos

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

Consulte também

IoRegisterDeviceInterface

rtlFreeUnicodeString

Partilhar via