Funzione WdfDeviceCreateSymbolicLink (wdfdevice.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfDeviceCreateSymbolicLink crea un collegamento simbolico a un dispositivo specificato.

Sintassi

NTSTATUS WdfDeviceCreateSymbolicLink(
  [in] WDFDEVICE        Device,
  [in] PCUNICODE_STRING SymbolicLinkName
);

Parametri

[in] Device

Handle per un oggetto dispositivo framework.

[in] SymbolicLinkName

Puntatore a una struttura UNICODE_STRING contenente un nome visibile dall'utente per il dispositivo.

Valore restituito

Se l'operazione ha esito positivo, WdfDeviceCreateSymbolicLink restituisce STATUS_SUCCCESS. I valori restituiti aggiuntivi includono:

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	Il sistema non può allocare spazio per archiviare il nome del dispositivo.

Il metodo potrebbe restituire altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Se un driver crea un collegamento simbolico per un dispositivo, le applicazioni possono usare il nome di collegamento simbolico per accedere al dispositivo. In genere, anziché fornire collegamenti simbolici , i driver basati su framework forniscono interfacce di dispositivo che le applicazioni possono usare per accedere ai propri 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.

Esempio

L'esempio di codice seguente da un driver KMDF crea un nome di dispositivo MS-DOS che un'applicazione può usare per accedere a un dispositivo.

#define DOS_DEVICE_NAME  L"\\DosDevices\\MyDevice"
DECLARE_CONST_UNICODE_STRING(dosDeviceName, DOS_DEVICE_NAME);
NTSTATUS  status;

status = WdfDeviceCreateSymbolicLink(
                                     controlDevice,
                                     &dosDeviceName
                                     );
if (!NT_SUCCESS(status)) {
    goto Error;
}

Un driver UMDF deve fornire un nome di collegamento simbolico nello spazio dei nomi DosDevices globale, come illustrato nell'esempio di codice seguente.

#define DOS_DEVICE_NAME  L"\\DosDevices\\Global\\MyDevice"
DECLARE_CONST_UNICODE_STRING(dosDeviceName, DOS_DEVICE_NAME);
NTSTATUS  status;

status = WdfDeviceCreateSymbolicLink(
                                     controlDevice,
                                     &dosDeviceName
                                     );
if (!NT_SUCCESS(status)) {
    goto Error;
}

Per informazioni sugli spazi dei nomi globale e locale \DosDevices , vedere Nomi dei dispositivi MS-DOS locali e globali.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfdevice.h (includere Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedi anche

UNICODE_STRING

Condividi tramite