Função WdfDeviceRetrieveDeviceInterfaceString (wdfdevice.h)

  • Artigo

[Aplica-se a KMDF e UMDF]

O método WdfDeviceRetrieveDeviceInterfaceString recupera o nome de link simbólico atribuído ao sistema operacional 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 de estrutura. A estrutura atribuirá a cadeia de caracteres Unicode do nome de link simbólico ao objeto de cadeia de caracteres.

Retornar valor

WdfDeviceRetrieveDeviceInterfaceString retorna 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.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

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 simbólico do link de uma interface do 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
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)

Confira também

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate