Compartilhar via

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

  • Artigo

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Drivers universais do Windows devem usar UMDF 2. Para obter mais informações, consulte Introdução com 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 terminada em nulo que representa o nome simbólico do link. Defina esse ponteiro como 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 de terminação NULL .

Retornar valor

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 para o qual 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.

Comentários

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:

  1. Defina o parâmetro pSymbolicLink como NULL e chame RetrieveSymbolicLink. O local para o qual pdwSymbolicLinkLengthInChars aponta recebe o número de caracteres que o nome simbólico do link contém.
  2. Aloque um buffer grande o suficiente para receber o nome simbólico do link.
  3. Chame RetrieveSymbolicLink novamente e defina o parâmetro pSymbolicLink como o endereço do buffer alocado.
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 a função de retorno de chamada IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival de um driver 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.
Plataforma de Destino Área de Trabalho
Versão mínima do UMDF 1,9
Cabeçalho wudfddi.h (include Wudfddi.h)
DLL WUDFx.dll

Confira também

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize::GetInterfaceGuid