Funzione WdfDeviceRetrieveDeviceInterfaceString (wdfdevice.h)

Articolo
02/07/2025

[Si applica a KMDF e UMDF]

Il metodo WdfDeviceRetrieveDeviceInterfaceString recupera il nome simbolico del collegamento assegnato dal sistema operativo a un'interfaccia del dispositivo registrata dal driver per un dispositivo specificato.

Sintassi

NTSTATUS WdfDeviceRetrieveDeviceInterfaceString(
  [in]           WDFDEVICE        Device,
  [in]           const GUID       *InterfaceClassGUID,
  [in, optional] PCUNICODE_STRING ReferenceString,
  [in]           WDFSTRING        String
);

Parametri

[in] Device

Handle per un oggetto dispositivo framework.

[in] InterfaceClassGUID

Puntatore a un GUID che identifica la classe dell'interfaccia del dispositivo.

[in, optional] ReferenceString

Puntatore a una struttura UNICODE_STRING che descrive una stringa di riferimento per l'interfaccia del dispositivo. Questo parametro è facoltativo e può essere NULL se il driver non ha specificato una stringa di riferimento quando ha chiamato WdfDeviceCreateDeviceInterface.

[in] String

Handle per un oggetto stringa framework. Il framework assegnerà la stringa Unicode del nome di collegamento simbolico all'oggetto stringa.

Valore restituito

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

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceRetrieveDeviceInterfaceString non è stato chiamato in IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido.
STATUS_INVALID_DEVICE_REQUEST	L'oggetto dispositivo specificato è stato inizializzato da WdfControlDeviceInitAllocate.
STATUS_OBJECT_NAME_NOT_FOUND	Impossibile trovare un'interfaccia del dispositivo che corrisponde al GUID specificato e alla stringa di riferimento.
STATUS_INVALID_DEVICE_STATE	Il driver denominato WdfDeviceCreateDeviceInterface, ma il sistema non ha ancora assegnato un nome di collegamento simbolico all'interfaccia del dispositivo.

WdfDeviceRetrieveDeviceInterfaceString potrebbe restituire anche altri valori NTSTATUS .

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Osservazioni

Per altre informazioni sulle interfacce dei dispositivi, vedere Using Device Interfaces.For more information about device interfaces, see Using Device Interfaces.

Esempi

Nell'esempio di codice seguente viene creato un oggetto stringa e quindi viene recuperato il nome di collegamento simbolico di un'interfaccia dispositivo specificata.

NTSTATUS status;
WDFSTRING string;

status = WdfStringCreate(
                         NULL,
                         WDF_NO_OBJECT_ATTRIBUTES,
                         &string
                         );
if (NT_SUCCESS(status)) {
    status = WdfDeviceRetrieveDeviceInterfaceString(
                         Device,
                         &GUID_DEVINTERFACE_DDI_TEST1,
                         NULL,
                         string
                         );
    if (!NT_SUCCESS(status)) {
        return status;
    }
}

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	2.0
intestazione	wdfdevice.h (include Wdf.h)
libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedere anche

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreare

Condividi tramite