Функция WdfUsbTargetDeviceFormatRequestForString (wdfusb.h)

[Применимо к KMDF и UMDF]

Метод WdfUsbTargetDeviceFormatRequestForString создает запрос на дескриптор строки USB, связанный со значением индекса строки USB-устройства.

Синтаксис

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

Параметры

[in] UsbDevice

Дескриптор объекта USB-устройства, полученный при предыдущем вызове WdfUsbTargetDeviceCreateWithParameters.

[in] Request

Дескриптор объекта запроса платформы.

[in] Memory

Дескриптор объекта памяти платформы.

[in, optional] Offset

Указатель на структуру, выделенную вызывающим объектом WDFMEMORY_OFFSET , которая предоставляет необязательные значения смещения и длины байтов. Платформа использует эти значения для определения начального адреса и длины в выходном буфере для хранения дескриптора строки. Если этот указатель имеет значение NULL, дескриптор хранится в начале выходного буфера, а максимальная длина строки равна длине буфера.

[in] StringIndex

Значение индекса, определяющее строку. Это значение индекса получается из структуры USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR или USB_INTERFACE_DESCRIPTOR .

[in, optional] LangID

Идентификатор языка. Строка будет получена для языка, указанного этим идентификатором. Сведения о получении поддерживаемых языковых идентификаторов устройства см. в спецификации USB.

Возвращаемое значение

WdfUsbTargetDeviceFormatRequestForString возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Комментарии

После возврата WdfUsbTargetDeviceFormatRequestForString драйвер должен вызвать WdfRequestSend для отправки запроса. После возврата WdfRequestSend драйвер может передать дескриптор памятив WdfMemoryGetBuffer , чтобы получить указатель на буфер памяти. Буфер будет содержать структуру USB_STRING_DESCRIPTOR , описывающую дескриптор строки.

Дополнительные сведения о методе WdfUsbTargetDeviceFormatRequestForString и целевых объектах ввода-вывода USB см. в разделе Usb I/O Targets.

Примеры

В следующем примере кода создается объект запроса и объект памяти, а дескрипторы объектов передаются в WdfUsbTargetDeviceFormatRequestForString. Затем в примере задается функция обратного вызова CompletionRoutine для запроса и отправляется запрос в целевой объект ввода-вывода.

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

Требования

См. также раздел

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

USB_STRING_DESCRIPTOR

WDFMEMORY_OFFSET

WdfMemoryGetBuffer

WdfRequestSend

WdfRequestSetCompletionRoutine

WdfUsbTargetDeviceAllocAndQueryString

WdfUsbTargetDeviceCreateWithParameters