Método IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink (wudfddi.h)

Artigo
02/07/2025

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui o UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum recurso novo está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução aoda UMDF .]

O método RetrieveSymbolicLink recupera o nome de link simbólico que o sistema operacional atribuiu a uma interface do dispositivo .

Sintaxe

HRESULT RetrieveSymbolicLink(
  [out, optional] PWSTR pSymbolicLink,
  [in, out]       DWORD *pdwSymbolicLinkLengthInChars
);

Parâmetros

[out, optional] pSymbolicLink

Um ponteiro para um buffer que recebe uma cadeia de caracteres Unicode nula que representa o nome do link simbólico. Defina esse ponteiro para NULL para obter o tamanho do buffer necessário.

[in, out] pdwSymbolicLinkLengthInChars

Um ponteiro para um local alocado pelo chamador. Na entrada, esse local deve conter o comprimento fornecido pelo chamador do buffer para o qual pSymbolicLink aponta. Na saída, o local recebe o comprimento, em caracteres, do nome do link simbólico, incluindo o caractere NULL terminação.

Valor de retorno

RetrieveSymbolicLink retornará S_OK se a operação for bem-sucedida. Caso contrário, o método poderá retornar o seguinte valor:

Código de retorno	Descrição
E_NOT_SUFFICIENT_BUFFER	O buffer que pSymbolicLink aponta é muito pequeno. Nesse caso, a estrutura armazena o tamanho do buffer necessário no local para o qual pdwSymbolicLinkLengthInChars aponta.

Esse método pode retornar um dos outros valores que Winerror.h contém.

Observações

O nome do link simbólico pode incluir um caractere de barra invertida () acrescentado, seguido por uma cadeia de caracteres de referência específica da instância.

Normalmente, o driver deve chamar RetrieveSymbolicLink duas vezes, da seguinte maneira:

Defina o parâmetro pSymbolicLink para NULL e chame RetrieveSymbolicLink. O local que pdwSymbolicLinkLengthInChars aponta para receber o número de caracteres que o nome do link simbólico contém.
Aloque um buffer grande o suficiente para receber o nome do link simbólico.
Chame RetrieveSymbolicLink novamente e defina o parâmetro pSymbolicLink para o endereço do buffer que você alocou.

Para obter mais informações sobre o método RetrieveSymbolicLink, consulte Usando interfaces de dispositivo em drivers baseados em UMDF.

Exemplos

O exemplo de código a seguir mostra como o de um driver IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival função de retorno de chamada pode determinar o comprimento do nome simbólico do link da interface do dispositivo, alocar um buffer para o nome e, em seguida, recuperar o nome.

void 
STDMETHODCALLTYPE
CMyDevice::OnRemoteInterfaceArrival(
    __in IWDFRemoteInterfaceInitialize  *FxRemoteInterfaceInit
    )
{
    HRESULT hr;
    INT BufferSize;
    hr= FxRemoteInterfaceInit->RetrieveSymbolicLink(NULL,
                                                    &BufferSize);
    if (FAILED(hr)) goto Error;
    hr = FxDriver->CreateWdfMemory(BufferSize, 
                                   NULL, 
                                   FxRemoteInterface, 
                                   &FxSymLinkBuffer);
    if (FAILED(hr)) goto Error;
    hr= FxRemoteInterfaceInit->RetrieveSymbolicLink(FxSymLinkBuffer->GetDataBuffer(NULL),
                                                    &BufferSize);
    if (FAILED(hr)) goto Error;
...
Error:
...
}

Requisitos

Requisito	Valor
fim do suporte	Indisponível no UMDF 2.0 e posterior.
da Plataforma de Destino	Área de trabalho
versão mínima do UMDF	1.9
cabeçalho	wudfddi.h (inclua Wudfddi.h)
de DLL	WUDFx.dll

Consulte também

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize::GetInterfaceGuid

Compartilhar via