WdfUsbTargetDeviceQueryString, fonction (wdfusb.h)

Article
07/16/2024

[S’applique à KMDF et UMDF]

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

[in, optional] Request

Handle vers un objet de requête de framework. Ce paramètre est facultatif et peut être NULL. Pour plus d’informations, consultez la section Remarques suivante.

[in, optional] RequestOptions

Pointeur vers une structure WDF_REQUEST_SEND_OPTIONS allouée par l’appelant qui spécifie les options de la requête. Ce pointeur est facultatif et peut être NULL. Pour plus d’informations, consultez la section Remarques suivante.

[out, optional] String

Pointeur vers une mémoire tampon allouée par 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 est NULL, WdfUsbTargetDeviceQueryString retourne la taille de mémoire tampon requise (autrement dit, le nombre requis de caractères Unicode) à l’emplacement vers lequel NumCharacters pointe.

[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 retourne, 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 chaîne tampon 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_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

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

Retourner le code	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	Impossible d’allouer une mémoire tampon 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

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

Définissez le pointeur string sur NULL, afin que WdfUsbTargetDeviceQueryString retourne la taille de mémoire tampon requise dans l’adresse vers laquelle les NumCharacters points de paramètre.
Allouez de l’espace tampon pour contenir le nombre de caractères Unicode figurant dans la chaîne demandée. Par exemple, un pilote peut appeler ExAllocatePoolWithTag pour allouer une mémoire tampon, ou appeler WdfMemoryCreate pour créer un objet mémoire de framework.
Appelez à nouveau WdfUsbTargetDeviceQueryString, en définissant à nouveau la valeur chaîne sur un pointeur vers la nouvelle mémoire tampon et en définissant NumCharacters à la longueur de la mémoire tampon (autrement dit, le nombre de caractères Unicode, et non la longueur d’octet).

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 de NULL nonpour le paramètre requête de , 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 requête de requête de chaîne. Si le pilote spécifie une valeur NULL pour requête, 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 nonNULL ou une NULLDemander paramètre. 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 WdfUsbTargetDeviceQueryString pour obtenir à nouveau la chaîne de nom du 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;
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
                                       );

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’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)