Função WdfDeviceCreateSymbolicLink (wdfdevice.h)

  • Artigo

[Aplica-se a KMDF e UMDF]

O método WdfDeviceCreateSymbolicLink cria um link simbólico para um dispositivo especificado.

Sintaxe

NTSTATUS WdfDeviceCreateSymbolicLink(
  [in] WDFDEVICE        Device,
  [in] PCUNICODE_STRING SymbolicLinkName
);

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] SymbolicLinkName

Um ponteiro para uma estrutura UNICODE_STRING que contém um nome visível pelo usuário para o dispositivo.

Retornar valor

Se a operação for bem-sucedida, o WdfDeviceCreateSymbolicLink retornará STATUS_SUCCCESS. Os valores retornados adicionais incluem:

Código de retorno Descrição
STATUS_INSUFFICIENT_RESOURCES
 O sistema não pode alocar espaço para armazenar o nome do dispositivo.
 

O método pode retornar outros valores NTSTATUS.

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

Comentários

Se um driver criar um link simbólico para um dispositivo, os aplicativos poderão usar o nome simbólico do link para acessar o dispositivo. 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.

Exemplos

O exemplo de código a seguir de um driver KMDF cria um nome de dispositivo MS-DOS que um aplicativo pode usar para acessar um dispositivo.

#define DOS_DEVICE_NAME  L"\\DosDevices\\MyDevice"
DECLARE_CONST_UNICODE_STRING(dosDeviceName, DOS_DEVICE_NAME);
NTSTATUS  status;

status = WdfDeviceCreateSymbolicLink(
                                     controlDevice,
                                     &dosDeviceName
                                     );
if (!NT_SUCCESS(status)) {
    goto Error;
}

Um driver UMDF deve fornecer um nome de link simbólico no namespace global DosDevices , como ilustra o exemplo de código a seguir.

#define DOS_DEVICE_NAME  L"\\DosDevices\\Global\\MyDevice"
DECLARE_CONST_UNICODE_STRING(dosDeviceName, DOS_DEVICE_NAME);
NTSTATUS  status;

status = WdfDeviceCreateSymbolicLink(
                                     controlDevice,
                                     &dosDeviceName
                                     );
if (!NT_SUCCESS(status)) {
    goto Error;
}

Para obter informações sobre namespaces \DosDevices globais e locais, consulte Nomes de dispositivo MS-DOS locais e globais.

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