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 |
|---|---|
|
Un paramètre non valide a été détecté. |
|
Impossible d’allouer une mémoire tampon de mémoire. |
|
Le périphérique USB a retourné un descripteur non valide. |
|
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) |