WdfDeviceRetrieveDeviceInterfaceString, fonction (wdfdevice.h)

Article
02/27/2024

[S’applique à KMDF et UMDF]

La méthode WdfDeviceRetrieveDeviceInterfaceString récupère le nom de lien symbolique que le système d’exploitation a attribué à une interface d’appareil que le pilote a inscrite pour un appareil spécifié.

Syntaxe

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

Paramètres

[in] Device

Handle d’un objet d’appareil framework.

[in] InterfaceClassGUID

Pointeur vers un GUID qui identifie la classe d’interface d’appareil.

[in, optional] ReferenceString

Pointeur vers une structure UNICODE_STRING qui décrit une chaîne de référence pour l’interface de l’appareil. Ce paramètre est facultatif et peut être NULL si le pilote n’a pas spécifié de chaîne de référence lorsqu’il a appelé WdfDeviceCreateDeviceInterface.

[in] String

Handle d’un objet de chaîne de framework. L’infrastructure affecte la chaîne Unicode du nom de lien symbolique à l’objet string.

Valeur retournée

WdfDeviceRetrieveDeviceInterfaceString retourne STATUS_SUCCESS si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceRetrieveDeviceInterfaceString n’a pas été appelé à IRQL = PASSIVE_LEVEL.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été spécifié.
STATUS_INVALID_DEVICE_REQUEST	L’objet d’appareil spécifié a été initialisé par WdfControlDeviceInitAllocate.
STATUS_OBJECT_NAME_NOT_FOUND	Une interface d’appareil qui correspond au GUID et à la chaîne de référence spécifiés est introuvable.
STATUS_INVALID_DEVICE_STATE	Le pilote appelé WdfDeviceCreateDeviceInterface , mais le système n’a pas encore attribué de nom de lien symbolique à l’interface de l’appareil.

WdfDeviceRetrieveDeviceInterfaceString peut également retourner d’autres valeurs NTSTATUS.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Pour plus d’informations sur les interfaces d’appareil, consultez Utilisation d’interfaces d’appareil.

Exemples

L’exemple de code suivant crée un objet string, puis récupère le nom de lien symbolique d’une interface d’appareil spécifiée.

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

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfdevice.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

UNICODE_STRING

WdfControlDeviceInitAllocate

WdfDeviceCreateDeviceInterface

WdfStringCreate

Partager via