WdfDeviceRetrieveDeviceInterfaceString-Funktion (wdfdevice.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfDeviceRetrieveDeviceInterfaceString Methode ruft den symbolischen Verknüpfungsnamen 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 zu einem 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 Referenzzeichenfolge für die Geräteschnittstelle beschreibt. Dieser Parameter ist optional und kann NULL- werden, wenn der Treiber beim Aufrufen WdfDeviceCreateDeviceInterfacekeine Verweiszeichenfolge angegeben hat.

[in] String

Ein Handle für ein Framework-Zeichenfolgenobjekt. Das Framework weist die Unicode-Zeichenfolge des symbolischen Verknüpfungsnamens dem Zeichenfolgenobjekt 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	Es wurde ein ungültiger Parameter angegeben.
STATUS_INVALID_DEVICE_REQUEST	Das angegebene Geräteobjekt wurde durch WdfControlDeviceInitAllocateinitialisiert.
STATUS_OBJECT_NAME_NOT_FOUND	Es wurde keine Geräteschnittstelle gefunden, die der angegebenen GUID entspricht, und eine Referenzzeichenfolge wurde nicht gefunden.
STATUS_INVALID_DEVICE_STATE	Der Treiber namens WdfDeviceCreateDeviceInterface, das System hat der Geräteschnittstelle jedoch noch keinen symbolischen Verknüpfungsnamen zugewiesen.

WdfDeviceRetrieveDeviceInterfaceString- können auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

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

Beispiele

Im folgenden Codebeispiel wird ein Zeichenfolgenobjekt erstellt und anschließend 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-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfdevice.h (einschließen Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Siehe auch

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface-

WdfStringCreate-

Freigeben über