WdfDeviceRetrieveDeviceInterfaceString-Funktion (wdfdevice.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfDeviceRetrieveDeviceInterfaceString-Methode ruft den symbolischen Linknamen ab, den das Betriebssystem einer Geräteschnittstelle zugewiesen hat, die der Treiber für ein angegebenes Gerät registriert hat.

Syntax

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

Parameter

[in] Device

Ein Handle für ein Framework-Geräteobjekt.

[in] InterfaceClassGUID

Ein Zeiger auf eine GUID, die die Geräteschnittstellenklasse identifiziert.

[in, optional] ReferenceString

Ein Zeiger auf eine UNICODE_STRING Struktur, die eine Verweiszeichenfolge für die Geräteschnittstelle beschreibt. Dieser Parameter ist optional und kann NULL sein, wenn der Treiber beim Aufrufen von WdfDeviceCreateDeviceInterface keine Verweiszeichenfolge angegeben hat.

[in] String

Ein Handle für ein Frameworkzeichenfolgenobjekt. Das Framework weist dem Zeichenfolgenobjekt die Unicode-Zeichenfolge des symbolischen Linknamens zu.

Rückgabewert

WdfDeviceRetrieveDeviceInterfaceString gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceRetrieveDeviceInterfaceString wurde bei IRQL = PASSIVE_LEVEL nicht aufgerufen.
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde angegeben.
STATUS_INVALID_DEVICE_REQUEST	Das angegebene Geräteobjekt wurde von WdfControlDeviceInitAllocate initialisiert.
STATUS_OBJECT_NAME_NOT_FOUND	Eine Geräteschnittstelle, die der angegebenen GUID und der angegebenen Verweiszeichenfolge entspricht, konnte nicht gefunden werden.
STATUS_INVALID_DEVICE_STATE	Der Treiber namens WdfDeviceCreateDeviceInterface , aber das System hat der Geräteschnittstelle noch keinen symbolischen Linknamen zugewiesen.

WdfDeviceRetrieveDeviceInterfaceString gibt möglicherweise auch andere NTSTATUS-Werte zurück.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Weitere Informationen zu Geräteschnittstellen finden Sie unter Verwenden von Geräteschnittstellen.

Beispiele

Im folgenden Codebeispiel wird ein Zeichenfolgenobjekt erstellt und dann der symbolische Linkname einer angegebenen Geräteschnittstelle abgerufen.

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

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfdevice.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate

Freigeben über