WdfDeviceRetrieveDeviceInterfaceString, fonction (wdfdevice.h)

Article
02/07/2025

[S’applique à KMDF et UMDF]

La méthode WdfDeviceRetrieveDeviceInterfaceString récupère le nom de lien symbolique attribué par le système d’exploitation à une interface de périphérique que le pilote a inscrit 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 vers 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 vers un objet de chaîne d’infrastructure . L’infrastructure affecte la chaîne Unicode du nom de lien symbolique à l’objet chaîne.

Valeur de retour

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

Retourner le code	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 spécifié et à la chaîne de référence 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 .

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

Pour plus d’informations sur les interfaces d’appareil, consultez Using Device Interfaces.

Exemples

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

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

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’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