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

Статья
02/07/2025

[Применимо только к 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 (include Wdfusb.h)
библиотеки	Wdf01000.sys (см. управление версиями библиотеки Платформы).)
IRQL	<=DISPATCH_LEVEL
правил соответствия DDI	DriverCreate(kmdf)

См. также

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb

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