WdfUsbTargetDeviceFormatRequestForString function (wdfusb.h)

[Applies to KMDF and UMDF]

The WdfUsbTargetDeviceFormatRequestForString method builds a request for the USB string descriptor that is associated with a USB device's string index value.

Syntax

NTSTATUS WdfUsbTargetDeviceFormatRequestForString(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         Memory,
  [in, optional] PWDFMEMORY_OFFSET Offset,
  [in]           UCHAR             StringIndex,
  [in, optional] USHORT            LangID
);

Parameters

[in] UsbDevice

A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreateWithParameters.

[in] Request

A handle to a framework request object.

[in] Memory

A handle to a framework memory object.

[in, optional] Offset

A pointer to a caller-allocated WDFMEMORY_OFFSET structure that supplies optional byte offset and length values. The framework uses these values to determine the beginning address and length, within the output buffer, for storing the string descriptor. If this pointer is NULL, the descriptor is stored at the beginning of the output buffer, and the maximum string length is the buffer length.

[in] StringIndex

An index value that identifies the string. This index value is obtained from a USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR, or USB_INTERFACE_DESCRIPTOR structure.

[in, optional] LangID

A language identifier. The string will be retrieved for the language that this identifier specifies. For information about obtaining a device's supported language identifiers, see the USB specification.

Return value

WdfUsbTargetDeviceFormatRequestForString returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return one of the following values:

This method also might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

After WdfUsbTargetDeviceFormatRequestForString returns, the driver must call WdfRequestSend to send the request. After WdfRequestSend returns, the driver can pass the Memory handle to WdfMemoryGetBuffer to obtain a pointer to the memory buffer. The buffer will contain a USB_STRING_DESCRIPTOR structure that describes the string descriptor.

For more information about the WdfUsbTargetDeviceFormatRequestForString method and USB I/O targets, see USB I/O Targets.

Examples

The following code example creates a request object and a memory object, and it passes the object handles to WdfUsbTargetDeviceFormatRequestForString. Then, the example sets a CompletionRoutine callback function for the request and sends the request to an I/O target.

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;
}

Requirements

See also

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

USB_STRING_DESCRIPTOR

WDFMEMORY_OFFSET

WdfMemoryGetBuffer

WdfRequestSend

WdfRequestSetCompletionRoutine

WdfUsbTargetDeviceAllocAndQueryString

WdfUsbTargetDeviceCreateWithParameters