WdfUsbTargetDeviceAllocAndQueryString, fonction (wdfusb.h)

[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 de descripteur spécifiées.

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 vers un objet périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.

[in, optional] StringMemoryAttributes

Pointeur vers une structure WDF_OBJECT_ATTRIBUTES allouée par l’appelant qui contient des attributs fournis par l’appelant pour le nouvel objet 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 avoir la valeur 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 est 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 de retour

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.

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

Remarques

La méthode WdfUsbTargetDeviceAllocAndQueryString , que votre pilote doit appeler 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 transmettre 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 aux États-Unis (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

   
Plateforme cible Universal
Version KMDF minimale 1.0
Version UMDF minimale 2,0
En-tête wdfusb.h (include 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)

Voir aussi

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceQueryString