Método IWDFDevice2::CreateSymbolicLinkWithReferenceString (wudfddi.h)

[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. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]

O métodoCreateSymbolicLinkWithReferenceString cria um nome de link simbólico e, opcionalmente, uma cadeia de caracteres de referência para um dispositivo

Sintaxe

HRESULT CreateSymbolicLinkWithReferenceString(
  [in]           PCWSTR pSymbolicLink,
  [in, optional] PCWSTR pReferenceString
);

Parâmetros

[in] pSymbolicLink

Um ponteiro para uma cadeia de caracteres terminada em NULL que se torna o nome visível pelo usuário do dispositivo. O nome do link simbólico deve estar no namespace global DosDevices .

[in, optional] pReferenceString

Um ponteiro para uma cadeia de caracteres terminada em NULL que o Windows acrescenta ao nome do dispositivo quando um aplicativo usa o nome simbólico especificado pelo parâmetro pSymbolicLink . Para obter mais informações, consulte a seção Comentários a seguir. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

CreateSymbolicLinkWithReferenceString retornará S_OK 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
E_INVALIDARG	O chamador especificou um valor inválido para um parâmetro de entrada.
E_OUTOFMEMORY	Falha na alocação de memória.

 

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

Comentários

CreateSymbolicLinkWithReferenceString cria um nome de link simbólico e, opcionalmente, uma cadeia de caracteres de referência, para o dispositivo que a interface IWDFDevice2 representa. Depois que um driver chama CreateSymbolicLinkWithReferenceString, os aplicativos podem usar o nome simbólico do link para acessar o dispositivo.

Suponha que o nome do dispositivo seja "\Device\MyDevice". Você pode criar um nome de link simbólico de "DeviceUserName" para seu dispositivo especificando "L"DeviceUserName"" para o parâmetro pSymbolicLink . Se você especificar "L"Instance3"" para o parâmetro pReferenceString , você está criando um link simbólico para \Device\MyDevice\Instance3. Se um aplicativo abrir o dispositivo usando o nome do link simbólico, o gerenciador de E/S abrirá \Device\MyDevice e criará um objeto de arquivo WDM que contém a cadeia de caracteres \Instance3 como o nome do arquivo. O driver baseado em UMDF recebe um objeto de arquivo criado pela estrutura, que também contém a cadeia de caracteres \Instance3 como o nome do arquivo (consulte IWDFFile::RetrieveFileName).

Normalmente, em vez de fornecer links simbólicos, os drivers baseados em estrutura fornecem interfaces de dispositivo que os aplicativos podem usar para acessar seus dispositivos.

Se o dispositivo for removido inesperadamente (removido de surpresa), a estrutura removerá o link simbólico para o dispositivo. Em seguida, o driver pode usar o nome do link simbólico para uma nova instância do dispositivo.

Se você não precisar adicionar uma cadeia de caracteres de referência ao nome simbólico do link do dispositivo, o driver poderá chamar IWDFDevice::CreateSymbolicLink em vez de CreateSymbolicLinkWithReferenceString.

Exemplos

A linha a seguir define um prefixo simbólico de nome de link no namespace global DosDevices .

#define SYMBOLIC_LINK_NAME_PREFIX   L"\\DosDevices\\Global\\"

O exemplo de código a seguir cria uma cadeia de caracteres de nome simbólica, obtém a interface IWDFDevice2 e chama CreateSymbolicLinkWithReferenceString.

    IWDFDevice2 *pDevice2 = NULL;
    HRESULT hr;

    //
    // Create symbolic link name string.
    //
    hr = StringCchPrintf(portFullName,
                         portFullNameLength,
                         L"%ws%ws",
                         SYMBOLIC_LINK_NAME_PREFIX,
                         portName);
    if (FAILED(hr))
    {
        goto Exit;
    }

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pDevice2);
    if (SUCCEEDED(hr)) 
    {
    hr = pDevice2->CreateSymbolicLinkWithReferenceString(portFullName,
                                                         portCountString);
    if (FAILED(hr))
        {
            goto Exit;
        }
        SAFE_RELEASE(pDevice2);
    }

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 (inclua Wudfddi.h)
DLL	WUDFx.dll

Confira também

IWDFDevice2

IWDFDevice::CreateSymbolicLink