WdfUsbTargetDeviceQueryString, fonction (wdfusb.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetDeviceQueryString récupère la chaîne Unicode associée à une valeur d’index de descripteur et de périphérique USB spécifiée.

Syntaxe

NTSTATUS WdfUsbTargetDeviceQueryString(
  [in]            WDFUSBDEVICE              UsbDevice,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PUSHORT                   String,
  [in, out]       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] Request

Handle pour un objet de requête d’infrastructure. Ce paramètre est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] RequestOptions

Pointeur vers une structure de WDF_REQUEST_SEND_OPTIONS allouée par l’appelant qui spécifie des options pour la demande. Ce pointeur est facultatif et peut être NULL. Pour plus d'informations, consultez la section Notes qui suit.

[out, optional] String

Pointeur vers une mémoire tampon allouée à l’appelant qui reçoit la chaîne Unicode demandée. La chaîne est terminée par NULL uniquement si l’appareil fournit une chaîne terminée par NULL. Si ce pointeur a la valeur NULL, WdfUsbTargetDeviceQueryString retourne la taille de mémoire tampon requise (c’est-à-dire le nombre requis de caractères Unicode) à l’emplacement vers lequel pointe NumCharacters .

[in, out] NumCharacters

Pointeur vers une variable allouée par l’appelant. L’appelant fournit le nombre de caractères Unicode que la mémoire tampon peut contenir. Lorsque WdfUsbTargetDeviceQueryString est retourné, la variable reçoit le nombre de caractères (y compris le terminateur NULL, s’il est fourni) qui se trouvent dans la chaîne Unicode que la mémoire tampon de chaîne reçoit.

[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

WdfUsbTargetDeviceQueryString 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.
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

Les pilotes doivent appeler WdfUsbTargetDeviceQueryString deux fois, en procédant comme suit :

Définissez le pointeur string sur NULL, de sorte que WdfUsbTargetDeviceQueryString retourne la taille de mémoire tampon requise dans l’adresse vers laquelle pointe le paramètre NumCharacters .
Allouez de l’espace tampon pour contenir le nombre de caractères Unicode qui se trouvent dans la chaîne demandée. Par exemple, un pilote peut appeler ExAllocatePoolWithTag pour allouer une mémoire tampon, ou il peut appeler WdfMemoryCreate pour créer un objet de mémoire du framework.
Appelez WdfUsbTargetDeviceQueryString à nouveau, en définissant la valeur String sur un pointeur vers la nouvelle mémoire tampon et en définissant NumCharacters sur la longueur de la mémoire tampon (c’est-à-dire le nombre de caractères Unicode, et non la longueur d’octets).

WdfUsbTargetDeviceQueryString localise le descripteur de chaîne USB spécifié et copie la chaîne Unicode du descripteur dans la mémoire tampon fournie.

Si votre pilote spécifie une valeur non NULL pour le paramètre Request , l’infrastructure utilise l’objet de requête spécifié, et un autre thread de pilote peut appeler WdfRequestCancelSentRequest, si nécessaire, pour tenter d’annuler la demande de requête de chaîne. Si le pilote spécifie une valeur NULL pour Request, l’infrastructure utilise un objet de requête interne que le pilote ne peut pas annuler.

Votre pilote peut spécifier un paramètre RequestOptions non NULL, que le pilote fournisse un paramètre non NULL ou un paramètre de requêteNULL. Vous pouvez, par exemple, utiliser le paramètre RequestOptions pour spécifier une valeur de délai d’attente.

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

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

Exemples

L’exemple de code suivant appelle WdfUsbTargetDeviceQueryString pour obtenir la taille de mémoire tampon requise, appelle WdfMemoryCreate pour créer un objet mémoire et une mémoire tampon, puis appelle À nouveau WdfUsbTargetDeviceQueryString pour obtenir la chaîne de nom du fabricant, en anglais (0x0409), à partir d’un descripteur de périphérique USB. (Le pilote a précédemment stocké le descripteur dans l’espace contextuel défini par le pilote.)

PMY_DEVICE_CONTEXT  myDeviceContext;
USHORT  numCharacters;
PUSHORT  stringBuf;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       NULL,
                                       &numCharacters,
                                       myDeviceContext->UsbDeviceDescr.iManufacturer,
                                       0x0409
                                       );

ntStatus = WdfMemoryCreate(
                           WDF_NO_OBJECT_ATTRIBUTES,
                           NonPagedPool,
                           POOL_TAG,
                           numCharacters * sizeof(WCHAR),
                           &memoryHandle,
                           (PVOID)&stringBuf
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}
status = WdfUsbTargetDeviceQueryString(
                                       myDeviceContext->UsbTargetDevice,
                                       NULL,
                                       NULL,
                                       stringBuf,
                                       &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)