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

Статья
08/08/2023

[Применяется только к KMDF]

Метод WdfUsbTargetDeviceCreateUrb выделяет блок запросов USB (URB).

Синтаксис

NTSTATUS WdfUsbTargetDeviceCreateUrb(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]           WDFMEMORY              *UrbMemory,
  [out, optional] PURB                   *Urb
);

Параметры

[in] UsbDevice

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

[in, optional] Attributes

Указатель на структуру WDF_OBJECT_ATTRIBUTES , предоставляемую вызывающим объектом, которая содержит атрибуты для нового объекта памяти. Если драйвер предоставляет этот параметр, элемент ParentObject структуры должен быть объектом USB-устройства (WDFUSBDEVICE) или объектом запроса (WDFREQUEST), созданным платформой, или любым объектом, цепочка родителей которого приводит к одному из этих типов. Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[out] UrbMemory

Указатель на расположение типа WDFMEMORY, которое получает дескриптор объекта памяти платформы.

[out, optional] Urb

Указатель на структуру URB, которая получает адрес только что выделенного URB. Этот параметр является необязательным и может иметь значение NULL.

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

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INVALID_DEVICE_STATE	Драйвер не указал версию контракта клиента при вызове WDF_USB_DEVICE_CREATE_CONFIG_INIT.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти для создания нового URB.

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

Перед вызовом WdfUsbTargetDeviceCreateUrb драйвер должен вызвать WdfUsbTargetDeviceCreateWithParameters. В случае успешного выполнения WdfUsbTargetDeviceCreateUrb возвращает дескриптор в объект памяти платформы, описывающий только что выделенный URB. Как правило, драйвер вызывает WdfUsbTargetDeviceCreateUrb из обработчика запроса.

Драйвер может вызвать WdfUsbTargetDeviceCreateUrb , чтобы выделить структуру URB перед вызовом WdfUsbTargetDeviceFormatRequestForUrb.

WdfUsbTargetDeviceCreateUrb аналогично WdfMemoryCreate. Оба метода выделяют объект памяти платформы, и оба метода также предоставляют возможность получения буфера (в данном случае URB), связанного с объектом памяти. В обоих случаях вызывающий объект также может получить буфер позже, вызвав WdfMemoryGetBuffer.

Если драйвер предоставляет параметр Urb при вызове WdfUsbTargetDeviceCreateUrb, вы можете отформатировать URB вручную или путем вызова подпрограмм UsbBuildXxx.

Объект памяти и его буфер удаляются при удалении родительского объекта. Драйвер также может удалить объект памяти и его буфер, вызвав WdfObjectDelete.

Примеры

В следующем примере кода объявляется объект памяти платформы. В примере вызывается WdfUsbTargetDeviceCreateUrb для выделения блока запросов USB, а затем вызывается WdfUsbTargetDeviceFormatRequestForUrb для форматирования запроса, использующего содержимое структуры URB. Наконец, в примере регистрируется функция обратного вызова CompletionRoutine и отправляется запрос целевому объекту ввода-вывода.

WDFMEMORY memory;
PURB urb = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = UsbDevice;

status = WdfUsbTargetDeviceCreateUrb(
    pDevContext->WdfUsbTargetDevice,
    &objectAttribs,
    &memory,
    &urb);

status = WdfUsbTargetDeviceFormatRequestForUrb(
    deviceContext->WdfUsbTargetDevice,
    request,
    memory,
    NULL);

WdfRequestSetCompletionRoutine(
    request,
    MyCompletionRoutine,
    NULL);

if (!WdfRequestSend(
        request,
        WdfUsbTargetDeviceGetIoTarget(UsbDevice),
        NULL)) {
    status = WdfRequestGetStatus(request);
}

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Целевая платформа	Универсальное
Минимальная версия KMDF	1.11
Верхняя часть	wdfusb.h (включая Wdfusb.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки платформы).
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf)

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

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb

Поделиться через