WdfUsbTargetDeviceFormatRequestForString, fonction (wdfusb.h)

Article
02/07/2025

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetDeviceFormatRequestForString génère une requête pour le descripteur de chaîne USB associé à la valeur d’index de chaîne d’un périphérique USB.

Syntaxe

NTSTATUS WdfUsbTargetDeviceFormatRequestForString(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         Memory,
  [in, optional] PWDFMEMORY_OFFSET Offset,
  [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] Request

Handle vers un objet de requête de framework.

[in] Memory

Handle vers un objet de mémoire de framework.

[in, optional] Offset

Pointeur vers une structure WDFMEMORY_OFFSET allouée par l’appelant qui fournit des valeurs facultatives de décalage d’octet et de longueur. L’infrastructure utilise ces valeurs pour déterminer l’adresse et la longueur de début, dans la mémoire tampon de sortie, pour stocker le descripteur de chaîne. Si ce pointeur est NULL, le descripteur est stocké au début de la mémoire tampon de sortie et la longueur de chaîne maximale est la longueur de la mémoire tampon.

[in] StringIndex

Valeur d’index qui identifie la chaîne. 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 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

WdfUsbTargetDeviceFormatRequestForString 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	Le nombre d’octets de la mémoire tampon n’était pas un nombre pair.
STATUS_INSUFFICIENT_RESOURCES	Il y avait une mémoire insuffisante.
STATUS_INTEGER_OVERFLOW	Le décalage spécifié par offset n’était pas valide.

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

Une fois WdfUsbTargetDeviceFormatRequestForString retourne, le pilote doit appeler WdfRequestSend pour envoyer la requête. Une fois WdfRequestSend retourné, le pilote peut passer le handle Memory à WdfMemoryGetBuffer pour obtenir un pointeur vers la mémoire tampon. La mémoire tampon contient une structure USB_STRING_DESCRIPTOR qui décrit le descripteur de chaîne.

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

Exemples

L’exemple de code suivant crée un objet de requête et un objet mémoire, et transmet les handles d’objet à WdfUsbTargetDeviceFormatRequestForString. Ensuite, l’exemple définit une fonction de rappel CompletionRoutine pour la requête et envoie la requête à une cible d’E/S.

NTSTATUS status;
PDEVICE_CONTEXT deviceContext = GetDeviceContext(device);
WDFREQUEST request;
WDFMEMORY memHandle;
WDF_OBJECT_ATTRIBUTES attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

status = WdfRequestCreate(
    &attributes,
    WdfUsbTargetDeviceGetIoTarget(deviceContext->UsbTargetDevice),
    &request);

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfMemoryCreate(
    WDF_NO_OBJECT_ATTRIBUTES,
    NonPagedPool,
    0,
    STR_DESC_STRING_SIZE,
    &memHandle,
    NULL);
if (!NT_SUCCESS(status)) {
    WdfObjectDelete(request);
    return status;
}

status = WdfUsbTargetDeviceFormatRequestForString(
    deviceContext->UsbTargetDevice,
    request,
    memHandle,
    NULL,
    deviceContext->UsbDeviceDescr.iManufacturer,
    0x0409);

if (NT_SUCCESS(status)) {
    WdfRequestSetCompletionRoutine(
        request,
        MyCompletionRoutine,
        NULL);

    if (WdfRequestSend(
            request,
            WdfUsbTargetDeviceGetIoTarget(deviceContext->UsbTargetDevice),
            NULL)) {
        status = STATUS_PENDING;
    }
    
}
else {
    WdfObjectDelete(memHandle);
    WdfObjectDelete(request);
    return status;
}

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	<=DISPATCH_LEVEL
règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)