WdfUsbTargetDeviceAllocAndQueryString, fonction (wdfusb.h)

Article
03/01/2024

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetDeviceAllocAndQueryString alloue une mémoire tampon, puis récupère la chaîne Unicode associée à un périphérique USB et à une valeur d’index descripteur spécifiés.

Syntaxe

NTSTATUS WdfUsbTargetDeviceAllocAndQueryString(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES StringMemoryAttributes,
  [out]           WDFMEMORY              *StringMemory,
  [out, optional] PUSHORT                NumCharacters,
  [in]            UCHAR                  StringIndex,
  [in, optional]  USHORT                 LangID
);

Paramètres

[in] UsbDevice

Handle pour un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.

[in, optional] StringMemoryAttributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES allouée à l’appelant qui contient des attributs fournis par l’appelant pour le nouvel objet de mémoire. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out] StringMemory

Pointeur vers un emplacement qui reçoit un handle vers l’objet mémoire qui contient la chaîne Unicode. La chaîne est terminée par NULL uniquement si l’appareil fournit une chaîne terminée par NULL.

[out, optional] NumCharacters

Pointeur vers un emplacement qui reçoit le nombre de caractères contenus dans le descripteur de chaîne. Si la chaîne Unicode est terminée par null, ce nombre inclut le caractère NULL. Ce paramètre est facultatif et peut être NULL.

[in] StringIndex

Valeur d’index qui identifie la chaîne Unicode. Cette valeur d’index est obtenue à partir d’une structure USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR ou USB_INTERFACE_DESCRIPTOR .

[in, optional] LangID

Identificateur de langue. La chaîne Unicode sera récupérée pour la langue spécifiée par cet identificateur. Pour plus d’informations sur l’obtention des identificateurs de langue pris en charge d’un appareil, consultez la spécification USB.

Valeur retournée

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

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer une mémoire tampon de mémoire.
STATUS_DEVICE_DATA_ERROR	Le périphérique USB a retourné un descripteur non valide.
STATUS_BUFFER_OVERFLOW	La mémoire tampon fournie était trop petite.

Cette méthode 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

La méthode WdfUsbTargetDeviceAllocAndQueryString , que votre pilote n’a besoin d’appeler qu’une seule fois pour obtenir un descripteur de chaîne, est une alternative à la méthode WdfUsbTargetDeviceQueryString , qui doit être appelée deux fois pour obtenir une chaîne.

La méthode localise le descripteur de chaîne USB spécifié, copie la chaîne Unicode du descripteur dans un objet mémoire et retourne un handle à l’objet mémoire.

Après avoir appelé WdfUsbTargetDeviceAllocAndQueryString, votre pilote peut passer le handle StringMemory à WdfMemoryGetBuffer pour accéder au contenu de l’objet mémoire.

Pour plus d’informations sur les descripteurs de chaîne USB, consultez la spécification USB.

Pour plus d’informations sur la méthode WdfUsbTargetDeviceAllocAndQueryString et les cibles d’E/S USB, consultez Cibles d’E/S USB.

Exemples

L’exemple de code suivant appelle WdfUsbTargetDeviceAllocAndQueryString pour obtenir la chaîne de nom d’un fabricant, en anglais usa (0x0409), à partir d’un descripteur de périphérique USB. (Le pilote a précédemment stocké le descripteur dans l’espace de contexte défini par le pilote.)

PMY_DEVICE_CONTEXT  myDeviceContext;
WDFMEMORY  memoryHandle;
USHORT  numCharacters;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceAllocAndQueryString(
                                        myDeviceContext->UsbTargetDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &memoryHandle,
                                        &numCharacters,
                                        myDeviceContext->UsbDeviceDescr.iManufacturer,
                                        0x0409
                                        );

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfusb.h (inclure Wdfusb.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), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)