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

Статья
08/08/2023

[Относится только к 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. В примере определяется количество байтов, необходимых для хранения изохронного запроса на передачу, а затем вручную настраивается заголовок 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 (включая Wdfusb.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки Платформы).
IRQL	<=DISPATCH_LEVEL
Правила соответствия DDI	DriverCreate(kmdf)

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

WdfUsbTargetDeviceCreateUrb

WdfUsbTargetDeviceCreateWithParameters

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