Metodo IWDFDevice2::CreateSymbolicLinkWithReferenceString (wudfddi.h)

[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 metodoCreateSymbolicLinkWithReferenceString crea un nome di collegamento simbolico e, facoltativamente, una stringa di riferimento per un dispositivo

Sintassi

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

Parametri

[in] pSymbolicLink

Puntatore a una stringa di caratteri con terminazione NULL che diventa il nome visibile dall'utente del dispositivo. Il nome del collegamento simbolico deve trovarsi nello spazio dei nomi DosDevices globale.

[in, optional] pReferenceString

Puntatore a una stringa di caratteri con terminazione NULL che Windows aggiunge al nome del dispositivo quando un'applicazione usa il nome simbolico specificato dal parametro pSymbolicLink . Per ulteriori informazioni, vedere la sezione Osservazioni successiva. Questo parametro è facoltativo e può essere NULL.

Valore restituito

CreateSymbolicLinkWithReferenceString restituisce S_OK se l'operazione ha esito positivo. In caso contrario, il metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
E_INVALIDARG	Il chiamante ha specificato un valore non valido per un parametro di input.
E_OUTOFMEMORY	Allocazione di memoria non riuscita.

 

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

Commenti

CreateSymbolicLinkWithReferenceString crea un nome di collegamento simbolico e, facoltativamente, una stringa di riferimento per il dispositivo rappresentato dall'interfaccia IWDFDevice2 . Dopo che un driver chiama CreateSymbolicLinkWithReferenceString, le applicazioni possono usare il nome del collegamento simbolico per accedere al dispositivo.

Si supponga che il nome del dispositivo sia "\Device\MyDevice". È possibile creare un nome di collegamento simbolico "DeviceUserName" per il dispositivo specificando "L"DeviceUserName"" per il parametro pSymbolicLink . Se si specifica "L"Instance3"" per il parametro pReferenceString , si sta creando un collegamento simbolico a \Device\MyDevice\Instance3. Se un'applicazione apre il dispositivo usando il nome del collegamento simbolico, il gestore di I/O apre \Device\MyDevice e crea un oggetto file WDM che contiene la stringa \Instance3 come nome file. Il driver basato su UMDF riceve un oggetto file creato dal framework, che contiene anche la stringa \Instance3 come nome file (vedere IWDFFile::RetrieveFileName).

In genere, invece di fornire collegamenti simbolici, i driver basati su framework forniscono interfacce di dispositivo che le applicazioni possono usare per accedere ai dispositivi.

Se il dispositivo viene rimosso in modo imprevisto (rimosso a sorpresa), il framework rimuove il collegamento simbolico al dispositivo. Il driver può quindi usare il nome del collegamento simbolico per una nuova istanza del dispositivo.

Se non è necessario aggiungere una stringa di riferimento al nome del collegamento simbolico del dispositivo, il driver può chiamare IWDFDevice::CreateSymbolicLink anziché CreateSymbolicLinkWithReferenceString.

Esempio

La riga seguente definisce un prefisso del nome di collegamento simbolico nello spazio dei nomi DosDevices globale.

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

L'esempio di codice seguente crea una stringa di nome simbolico, ottiene l'interfaccia IWDFDevice2 e quindi chiama 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);
    }

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

IWDFDevice2

IWDFDevice::CreateSymbolicLink