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

[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los controladores UMDF nuevos deben escribirse con UMDF 2. No se agregan nuevas características a UMDF 1 y hay compatibilidad limitada con UMDF 1 en versiones más recientes de Windows 10. Los controladores universales de Windows deben usar UMDF 2. Para obtener más información, consulta Introducción con UMDF.

El métodoCreateSymbolicLinkWithReferenceString crea un nombre de vínculo simbólico y, opcionalmente, una cadena de referencia para un dispositivo.

Sintaxis

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

Parámetros

[in] pSymbolicLink

Puntero a una cadena de caracteres terminada en NULL que se convierte en el nombre visible para el usuario del dispositivo. El nombre del vínculo simbólico debe estar en el espacio de nombres global DosDevices .

[in, optional] pReferenceString

Puntero a una cadena de caracteres terminada en NULL que Windows anexa al nombre del dispositivo cuando una aplicación usa el nombre simbólico que especifica el parámetro pSymbolicLink . Para obtener más información, vea la sección Comentarios que se muestra más adelante. Este parámetro es opcional y puede ser NULL.

Valor devuelto

CreateSymbolicLinkWithReferenceString devuelve S_OK si la operación se realiza correctamente. De lo contrario, el método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
E_INVALIDARG	El autor de la llamada especificó un valor no válido para un parámetro de entrada.
E_OUTOFMEMORY	Error en la asignación de memoria.

 

Este método puede devolver uno de los otros valores que contiene Winerror.h.

Comentarios

CreateSymbolicLinkWithReferenceString crea un nombre de vínculo simbólico y, opcionalmente, una cadena de referencia para el dispositivo que representa la interfaz IWDFDevice2 . Después de que un controlador llame a CreateSymbolicLinkWithReferenceString, las aplicaciones pueden usar el nombre simbólico del vínculo para acceder al dispositivo.

Supongamos que el nombre del dispositivo es "\Device\MyDevice". Puede crear un nombre de vínculo simbólico de "DeviceUserName" para el dispositivo especificando "L"DeviceUserName"" para el parámetro pSymbolicLink . Si especifica "L"Instance3"" para el parámetro pReferenceString , va a crear un vínculo simbólico a \Device\MyDevice\Instance3. Si una aplicación abre el dispositivo con el nombre de vínculo simbólico, el administrador de E/S abre \Device\MyDevice y crea un objeto de archivo WDM que contiene la cadena \Instance3 como nombre de archivo. El controlador basado en UMDF recibe un objeto de archivo creado por el marco, que también contiene la cadena \Instance3 como nombre de archivo (vea IWDFFile::RetrieveFileName).

Normalmente, en lugar de proporcionar vínculos simbólicos, los controladores basados en marcos proporcionan interfaces de dispositivo que las aplicaciones pueden usar para acceder a sus dispositivos.

Si el dispositivo se quita inesperadamente (se quita sorpresa), el marco quita el vínculo simbólico al dispositivo. A continuación, el controlador puede usar el nombre del vínculo simbólico para una nueva instancia del dispositivo.

Si no necesita agregar una cadena de referencia al nombre de vínculo simbólico del dispositivo, el controlador puede llamar a IWDFDevice::CreateSymbolicLink en lugar de CreateSymbolicLinkWithReferenceString.

Ejemplos

En la línea siguiente se define un prefijo de nombre de vínculo simbólico en el espacio de nombres global DosDevices .

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

En el ejemplo de código siguiente se crea una cadena de nombre simbólico, se obtiene la interfaz IWDFDevice2 y, a continuación, se llama a 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	Value
Finalización del soporte técnico	No disponible en UMDF 2.0 y versiones posteriores.
Plataforma de destino	Escritorio
Versión mínima de UMDF	1,9
Encabezado	wudfddi.h (incluya Wudfddi.h)
Archivo DLL	WUDFx.dll

Consulte también

IWDFDevice2

IWDFDevice::CreateSymbolicLink