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 de 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 ê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_DESCRIPTORou 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 :

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 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 (0x0409), à partir d’un descripteur d’appareil 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
                                        );

Exigences

Voir aussi

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceQueryString