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

Статья
02/07/2025

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

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

Синтаксис

NTSTATUS WdfUsbTargetDeviceCreateIsochUrb(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]            ULONG                  NumberOfIsochPackets,
  [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.

[in] NumberOfIsochPackets

Указывает количество изохронных пакетов, для которых система выделяет память в URB.

[out] UrbMemory

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

[out, optional] Urb

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

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

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

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

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

Замечания

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

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

Как правило, драйвер вызывает WdfUsbTargetDeviceCreateIsochUrb из обработчика запросов .

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

Дополнительные сведения см. в разделе "Примечания" WdfUsbTargetDeviceCreateUrb.

Примеры

Следующий пример кода основан на подпрограмме PerformIsochTransfer в примере драйвера Isorwr. В примере вызывается WdfUsbTargetDeviceCreateIsochUrb для выделения блока usb-запроса изохронного usb-запроса. В примере определяется количество байтов, необходимых для хранения запроса на передачу изохронных данных, а затем вручную настраивает заголовок URB и изохронные пакеты в URB. На этом этапе драйвер может вызывать WdfUsbTargetPipeFormatRequestForUrb, как показано в примере WdfUsbTargetDeviceCreateUrb.


USBD_PIPE_HANDLE usbdPipeHandle;
ULONG numPackets = UserBufferLength/TransferSizePerFrame;
ULONG urbSize;
PURB urb;  
WDFMEMORY memory;

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

status = WdfUsbTargetDeviceCreateIsochUrb(
                                     pDevContext->WdfUsbTargetDevice,  
                                     &objectAttribs,  
                                     0, 
                                     numPackets, 
                                     &memory,  
                                     NULL  
                                     ); 
 
urb = WdfMemoryGetBuffer(urbMemory, &urbSize); 
urbSize = GET_ISO_URB_SIZE(numPackets);  

usbdPipeHandle = WdfUsbTargetPipeWdmGetPipeHandle(pipe);
urb->UrbIsochronousTransfer.Hdr.Length = GET_ISO_URB_SIZE(numPackets);  
urb->UrbIsochronousTransfer.Hdr.Function = URB_FUNCTION_ISOCH_TRANSFER;  
urb->UrbIsochronousTransfer.PipeHandle = usbdPipeHandle; 

for (packetId = 0; packetId < numberOfPackets; packetId++) {

     Urb-> UrbIsochronousTransfer.IsoPacket[packetId].Offset = xxx;
     Urb-> UrbIsochronousTransfer.IsoPacket[packetId].YYY = yyy;
}

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista
целевая платформа	Всеобщий
минимальная версия KMDF	1.11
заголовка	wdfusb.h (include Wdfusb.h)
библиотеки	Wdf01000.sys (см. управление версиями библиотеки Платформы).)
IRQL	<=DISPATCH_LEVEL
правил соответствия DDI	DriverCreate(kmdf)

См. также

WdfUsbTargetDeviceCreateUrb

WdfUsbTargetDeviceCreateWithParameters

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