WdfUsbTargetDeviceFormatRequestForString, fonction (wdfusb.h)

Article
08/08/2023

[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 pour un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.

[in] Request

Handle pour un objet de requête d’infrastructure.

[in] Memory

Handle pour un objet de mémoire d’infrastructure.

[in, optional] Offset

Pointeur vers une structure de WDFMEMORY_OFFSET allouée par l’appelant qui fournit des valeurs facultatives de décalage d’octets 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 a la valeur 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_DESCRIPTOR ou USB_INTERFACE_DESCRIPTOR .

[in, optional] LangID

Identificateur de langue. La chaîne 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

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

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

Une fois que WdfUsbTargetDeviceFormatRequestForString est retourné, le pilote doit appeler WdfRequestSend pour envoyer la demande. Une fois WdfRequestSend retourné, le pilote peut passer le handle mémoire à 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 descripteurs d’objet à WdfUsbTargetDeviceFormatRequestForString. Ensuite, l’exemple définit une fonction de rappel CompletionRoutine pour la requête et envoie la demande à 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;
}

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	<=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)