структура _URB_BULK_OR_INTERRUPT_TRANSFER (usb.h)

Статья
08/07/2023

Структура _URB_BULK_OR_INTERRUPT_TRANSFER используется драйверами USB-клиента для отправки или получения данных по массовому каналу или в канале прерывания.

Синтаксис

struct _URB_BULK_OR_INTERRUPT_TRANSFER {
  struct _URB_HEADER   Hdr;
  USBD_PIPE_HANDLE     PipeHandle;
  ULONG                TransferFlags;
  ULONG                TransferBufferLength;
  PVOID                TransferBuffer;
  PMDL                 TransferBufferMDL;
  struct _URB          *UrbLink;
  struct _URB_HCD_AREA hca;
};

Члены

Hdr

Указатель на структуру _URB_HEADER , указывающую сведения о заголовке URB. Функция Hdr.Function должна быть URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER, а hdr.Length должна иметь значение sizeof(_URB_BULK_OR_INTERRUPT_TRANSFER).

PipeHandle

Указывает непрозрачный дескриптор для канала массовых операций или прерываний. Драйвер хост-контроллера возвращает этот дескриптор, когда драйвер клиента выбирает конфигурацию устройства с urb типа URB_FUNCTION_SELECT_CONFIGURATION или когда драйвер клиента изменяет параметры для интерфейса с URB типа URB_FUNCTION_SELECT_INTERFACE.

TransferFlags

Задает ноль, единицу или сочетание следующих флагов:

Значение	Значение
USBD_TRANSFER_DIRECTION_IN	Задано для запроса данных с устройства. Для передачи данных на устройство этот флаг должен быть снят.
USBD_TRANSFER_DIRECTION_OUT	Задано для передачи данных на устройство. Установка этого флага эквивалентна снятию флага USBD_TRANSFER_DIRECTION_IN.
USBD_SHORT_TRANSFER_OK	Параметр указывает контроллеру узла не возвращать ошибку при получении пакета от устройства, который короче максимального размера пакета для конечной точки. Максимальный размер пакета для конечной точки указывается в элементе wMaxPacketSize структуры USB_ENDPOINT_DESCRIPTOR (дескриптор конечной точки). Когда контроллер узла получает пакет, короче , чем wMaxPacketSize , на массовой конечной точке или в конечной точке прерывания, контроллер узла немедленно прекращает запрашивать данные из конечной точки и завершает передачу. Если флаг USBD_SHORT_TRANSFER_OK не задан, контроллер узла завершает передачу с ошибкой. Этот флаг не следует устанавливать, если не задано USBD_TRANSFER_DIRECTION_IN. Примечание На контроллерах узла EHCI USBD_SHORT_TRANSFER_OK игнорируются для конечных точек массовых операций и прерываний. Передача коротких пакетов на контроллеры EHCI не приводит к возникновению ошибки. На контроллерах узла UHCI и OHCI, если USBD_SHORT_TRANSFER_OK не задан для массовой передачи или прерывания, короткая передача пакетов останавливает конечную точку и возвращается код ошибки для передачи. Драйвер клиента должен возобновить работу конечной точки, отправив запрос URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL перед отправкой запроса на передачу в конечную точку.

Значение

USBD_TRANSFER_DIRECTION_IN

Задано для запроса данных с устройства. Для передачи данных на устройство этот флаг должен быть снят.

USBD_TRANSFER_DIRECTION_OUT

Задано для передачи данных на устройство. Установка этого флага эквивалентна снятию флага USBD_TRANSFER_DIRECTION_IN.

USBD_SHORT_TRANSFER_OK

Параметр указывает контроллеру узла не возвращать ошибку при получении пакета от устройства, который короче максимального размера пакета для конечной точки. Максимальный размер пакета для конечной точки указывается в элементе wMaxPacketSize структуры USB_ENDPOINT_DESCRIPTOR (дескриптор конечной точки). Когда контроллер узла получает пакет, короче , чем wMaxPacketSize , на массовой конечной точке или в конечной точке прерывания, контроллер узла немедленно прекращает запрашивать данные из конечной точки и завершает передачу. Если флаг USBD_SHORT_TRANSFER_OK не задан, контроллер узла завершает передачу с ошибкой.

Этот флаг не следует устанавливать, если не задано USBD_TRANSFER_DIRECTION_IN. Примечание На контроллерах узла EHCI USBD_SHORT_TRANSFER_OK игнорируются для конечных точек массовых операций и прерываний. Передача коротких пакетов на контроллеры EHCI не приводит к возникновению ошибки.

На контроллерах узла UHCI и OHCI, если USBD_SHORT_TRANSFER_OK не задан для массовой передачи или прерывания, короткая передача пакетов останавливает конечную точку и возвращается код ошибки для передачи. Драйвер клиента должен возобновить работу конечной точки, отправив запрос URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL перед отправкой запроса на передачу в конечную точку.

TransferBufferLength

Указывает длину (в байтах) буфера, указанного в TransferBuffer или описанного в разделе TransferBufferMDL. Драйвер хост-контроллера возвращает количество байтов, отправленных или считываемых из канала в этом элементе.

TransferBuffer

Указатель на резидентный буфер для передачи или имеет значение NULL , если MDL предоставляется в TransferBufferMDL. Содержимое этого буфера зависит от значения Параметра TransferFlags. Если указан USBD_TRANSFER_DIRECTION_IN этот буфер будет содержать данные, считанные с устройства при возврате из драйвера контроллера узла. В противном случае этот буфер содержит предоставленные драйвером данные для передачи на устройство.

TransferBufferMDL

Указатель на MDL, описывающий резидентный буфер, или имеет значение NULL , если буфер предоставлен в TransferBuffer. Содержимое буфера зависит от значения Параметра TransferFlags. Если указан USBD_TRANSFER_DIRECTION_IN, описанный буфер будет содержать данные, считываемые с устройства при возвращении из драйвера контроллера узла. В противном случае буфер содержит предоставленные драйвером данные для передачи на устройство. Этот MDL-файл должен быть выделен из непагрегированного пула.

UrbLink

Зарезервировано. Не используется.

hca

Зарезервировано. Не используется.

Драйверы могут использовать процедуру службы UsbBuildInterruptOrBulkTransferRequest для форматирования этого URB. Буферы, указанные в TransferBuffer или описанные в TransferBufferMDL , должны быть непередаваемыми.

В URB параметры TransferBuffer и TransferBufferMDL могут одновременно иметь значения, отличные от NULL. В этом случае буфер передачи и MDL, указывающие на TransferBuffer и TransferBufferMDL , должны указывать на один и тот же буфер.

Драйвер шины USB обрабатывает этот URB на DISPATCH_LEVEL.

Зарезервированные элементы этой структуры должны рассматриваться как непрозрачные и зарезервированы для использования системой.