WdfUsbTargetDeviceFormatRequestForString, fonction (wdfusb.h)

[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 :

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

Voir aussi

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

USB_STRING_DESCRIPTOR

WDFMEMORY_OFFSET

WdfMemoryGetBuffer

WdfRequestSend

WdfRequestSetCompletionRoutine

WdfUsbTargetDeviceAllocAndQueryString

WdfUsbTargetDeviceCreateWithParameters