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

  • Artículo

[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étodo RetrieveSymbolicLink recupera el nombre del vínculo simbólico que el sistema operativo asignó a una interfaz de dispositivo.

Sintaxis

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

Parámetros

[out, optional] pSymbolicLink

Puntero a un búfer que recibe una cadena de caracteres Unicode terminada en null que representa el nombre del vínculo simbólico. Establezca este puntero en NULL para obtener el tamaño de búfer necesario.

[in, out] pdwSymbolicLinkLengthInChars

Puntero a una ubicación asignada por el autor de la llamada. En la entrada, esta ubicación debe contener la longitud proporcionada por el autor de la llamada del búfer a la que apunta pSymbolicLink . En la salida, la ubicación recibe la longitud, en caracteres, del nombre del vínculo simbólico, incluido el carácter de terminación NULL .

Valor devuelto

RetrieveSymbolicLink devuelve S_OK si la operación se realiza correctamente. De lo contrario, el método podría devolver el siguiente valor:

Código devuelto Descripción
E_NOT_SUFFICIENT_BUFFER
 El búfer al que apunta pSymbolicLink es demasiado pequeño. En este caso, el marco almacena el tamaño de búfer necesario en la ubicación a la que apunta pdwSymbolicLinkLengthInChars .
 

Este método podría devolver uno de los otros valores que contiene Winerror.h.

Comentarios

El nombre del vínculo simbólico puede incluir un carácter de barra diagonal inversa anexada (), seguido de una cadena de referencia específica de la instancia.

Normalmente, el controlador debe llamar a RetrieveSymbolicLink dos veces, como se indica a continuación:

  1. Establezca el parámetro pSymbolicLink en NULL y llame a RetrieveSymbolicLink. La ubicación a la que apunta pdwSymbolicLinkLengthInChars recibe el número de caracteres que contiene el nombre del vínculo simbólico.
  2. Asigne un búfer lo suficientemente grande como para recibir el nombre del vínculo simbólico.
  3. Vuelva a llamar a RetrieveSymbolicLink y establezca el parámetro pSymbolicLink en la dirección del búfer que asignó.
Para obtener más información sobre el método RetrieveSymbolicLink , consulte Uso de interfaces de dispositivo en controladores basados en UMDF.

Ejemplos

En el ejemplo de código siguiente se muestra cómo la función de devolución de llamada IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival puede determinar la longitud del nombre del vínculo simbólico de la interfaz del dispositivo, asignar un búfer para el nombre y, a continuación, recuperar el nombre.

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 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

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize::GetInterfaceGuid