Função WdfDeviceRetrieveDeviceInterfaceString (wdfdevice.h)

Artigo
07/02/2025

[Aplica-se a KMDF e UMDF]

O método WdfDeviceRetrieveDeviceInterfaceString recupera o nome de link simbólico que o sistema operacional atribuiu a uma interface de dispositivo que o driver registrou para um dispositivo especificado.

Sintaxe

NTSTATUS WdfDeviceRetrieveDeviceInterfaceString(
  [in]           WDFDEVICE        Device,
  [in]           const GUID       *InterfaceClassGUID,
  [in, optional] PCUNICODE_STRING ReferenceString,
  [in]           WDFSTRING        String
);

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] InterfaceClassGUID

Um ponteiro para um GUID que identifica a classe de interface do dispositivo.

[in, optional] ReferenceString

Um ponteiro para uma estrutura UNICODE_STRING que descreve uma cadeia de caracteres de referência para a interface do dispositivo. Esse parâmetro é opcional e pode ser NULL se o driver não especificou uma cadeia de caracteres de referência quando chamou WdfDeviceCreateDeviceInterface.

[in] String

Um identificador para um objeto de cadeia de caracteres da estrutura . A estrutura atribuirá a cadeia de caracteres Unicode do nome de link simbólico ao objeto de cadeia de caracteres.

Valor de retorno

WdfDeviceRetrieveDeviceInterfaceString retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, o método poderá retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceRetrieveDeviceInterfaceString não foi chamado em IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi especificado.
STATUS_INVALID_DEVICE_REQUEST	O objeto de dispositivo especificado foi inicializado por WdfControlDeviceInitAllocate.
STATUS_OBJECT_NAME_NOT_FOUND	Não foi possível encontrar uma interface de dispositivo que corresponda ao GUID especificado e à cadeia de caracteres de referência.
STATUS_INVALID_DEVICE_STATE	O driver chamado WdfDeviceCreateDeviceInterface mas o sistema ainda não atribuiu um nome de link simbólico à interface do dispositivo.

WdfDeviceRetrieveDeviceInterfaceString também pode retornar outros valores NTSTATUS.

Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.

Observações

Para obter mais informações sobre interfaces de dispositivo, consulte Usando interfaces de dispositivo.

Exemplos

O exemplo de código a seguir cria um objeto de cadeia de caracteres e, em seguida, recupera o nome de link simbólico de uma interface de dispositivo especificada.

NTSTATUS status;
WDFSTRING string;

status = WdfStringCreate(
                         NULL,
                         WDF_NO_OBJECT_ATTRIBUTES,
                         &string
                         );
if (NT_SUCCESS(status)) {
    status = WdfDeviceRetrieveDeviceInterfaceString(
                         Device,
                         &GUID_DEVINTERFACE_DDI_TEST1,
                         NULL,
                         string
                         );
    if (!NT_SUCCESS(status)) {
        return status;
    }
}

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
versão mínima do UMDF	2.0
cabeçalho	wdfdevice.h (inclua Wdf.h)
biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Consulte também

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate

Compartilhar via