Método IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink (wudfddi.h)
[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los nuevos controladores UMDF deben escribirse mediante 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 a UMDF.]
El método RetrieveSymbolicLink recupera el nombre simbólico del vínculo asignado al sistema operativo 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 un cadena de caracteres Unicode terminadanull 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 pSymbolicLink apunta. En la salida, la ubicación recibe la longitud, en caracteres, del nombre simbólico del vínculo, incluido el null carácter de terminación.
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 |
|---|---|
|
El búfer al que pSymbolicLink apunta a es demasiado pequeño. En este caso, el marco almacena el tamaño de búfer necesario en la ubicación a la que pdwSymbolicLinkLengthInChars apunta. |
Este método podría devolver uno de los otros valores que contiene Winerror.h.
Observaciones
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:
- Establezca el parámetro pSymbolicLink en NULL y llame a RetrieveSymbolicLink. La ubicación que pdwSymbolicLinkLengthInChars apunta a recibir el número de caracteres que contiene el nombre del vínculo simbólico.
- Asigne un búfer lo suficientemente grande como para recibir el nombre del vínculo simbólico.
- Llame de nuevo a RetrieveSymbolicLink y establezca el parámetro pSymbolicLink en la dirección del búfer asignado.
Ejemplos
En el ejemplo de código siguiente se muestra cómo la función de devolución de llamada IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival función de devolución de llamada puede determinar la longitud del nombre del vínculo simbólico de la interfaz de 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 | Valor |
|---|---|
| fin del soporte técnico | No disponible en UMDF 2.0 y versiones posteriores. |
| de la plataforma de destino de | Escritorio |
| versión mínima de UMDF | 1.9 |
| encabezado de | wudfddi.h (incluya Wudfddi.h) |
| DLL de | WUDFx.dll |