Metodo IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink (wudfddi.h)

Articolo
03/05/2024

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre info, vedi Introduzione con UMDF.]

Il metodo RetrieveSymbolicLink recupera il nome del collegamento simbolico assegnato al sistema operativo a un'interfaccia del dispositivo.

Sintassi

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

Parametri

[out, optional] pSymbolicLink

Puntatore a un buffer che riceve una stringa di caratteri Unicode con terminazione Null che rappresenta il nome del collegamento simbolico. Impostare questo puntatore su NULL per ottenere le dimensioni del buffer necessarie.

[in, out] pdwSymbolicLinkLengthInChars

Puntatore a una posizione allocata dal chiamante. In input, questa posizione deve contenere la lunghezza specificata dal chiamante del buffer a cui punta pSymbolicLink . Nell'output, la posizione riceve la lunghezza, in caratteri, del nome del collegamento simbolico, incluso il carattere di terminazione NULL .

Valore restituito

RetrieveSymbolicLink restituisce S_OK se l'operazione ha esito positivo. In caso contrario, il metodo potrebbe restituire il valore seguente:

Codice restituito	Descrizione
E_NOT_SUFFICIENT_BUFFER	Il buffer a cui punta pSymbolicLink è troppo piccolo. In questo caso, il framework archivia le dimensioni del buffer necessarie nel percorso a cui punta pdwSymbolicLinkLengthInChars .

Questo metodo potrebbe restituire uno degli altri valori contenuti da Winerror.h.

Commenti

Il nome del collegamento simbolico può includere un carattere barra rovesciata () accodato, seguito da una stringa di riferimento specifica dell'istanza.

In genere, il driver deve chiamare RetrieveSymbolicLink due volte, come indicato di seguito:

Impostare il parametro pSymbolicLink su NULL e chiamare RetrieveSymbolicLink. Il percorso che pdwSymbolicLinkLengthInChars punta a riceve il numero di caratteri contenuti dal nome del collegamento simbolico.
Allocare un buffer di dimensioni sufficienti per ricevere il nome del collegamento simbolico.
Chiamare di nuovo RetrieveSymbolicLink e impostare il parametro pSymbolicLink sull'indirizzo del buffer allocato.

Per altre informazioni sul metodo RetrieveSymbolicLink , vedere Using Device Interfaces in UMDF-based Drivers.For more information about the RetrieveSymbolicLink method, see Using Device Interfaces in UMDF-based Drivers.

Esempio

Nell'esempio di codice seguente viene illustrato come la funzione di callback IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival può determinare la lunghezza del nome del collegamento simbolico dell'interfaccia del dispositivo, allocare un buffer per il nome e quindi recuperare il nome.

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:
...
}

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1,9
Intestazione	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Vedi anche

IWDFRemoteInterfaceInitialize

IWDFRemoteInterfaceInitialize::GetInterfaceGuid

Condividi tramite