Funzione WdfDeviceRetrieveDeviceInterfaceString (wdfdevice.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfDeviceRetrieveDeviceInterfaceString recupera il nome di collegamento simbolico assegnato al sistema operativo assegnato a un'interfaccia del dispositivo registrata 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 si chiama WdfDeviceCreateDeviceInterface.

[in] String

Handle per un oggetto stringa del framework. Il framework assegna la stringa Unicode del nome del collegamento simbolico all'oggetto string.

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 corrispondente alla stringa GUID e di riferimento specificata.
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.

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

Commenti

Per altre informazioni sulle interfacce del dispositivo, vedere Uso di interfacce dispositivo.

Esempio

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

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;
    }
}

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

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate

Condividi tramite