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

Статья
02/07/2025

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

Синтаксис

struct _URB_CONTROL_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;
  UCHAR                SetupPacket[8];
};

Члены

Hdr

Указатель на структуру _URB_HEADER, указывающую сведения о заголовке URB. hdr.Function должен быть URB_FUNCTION_CONTROL_TRANSFER, а hdr.Length должны быть sizeof(_URB_CONTROL_TRANSFER).

PipeHandle

Дескриптор для канала управления.

Если целевой объект является конечной точкой управления по умолчанию, PipeHandle должен быть null. В этом случае TransferFlags должен содержать флаг USBD_DEFAULT_PIPE_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	Устанавливается, чтобы контроллер узла не возвращал ошибку при получении пакета от устройства, которое меньше максимального размера пакета для конечной точки. Максимальный размер пакета для конечной точки сообщается в bMaxPacketSize0 член структуры USB_DEVICE_DESCRIPTOR (дескриптор устройства) для конечной точки управления по умолчанию. Для конечной точки управления, отличной от по умолчанию, максимальный размер пакета устанавливается в wMaxPacketSize член структуры USB_ENDPOINT_DESCRIPTOR (дескриптор конечной точки). Когда контроллер узла получает пакет, длина которого короче wMaxPacketSize в конечной точке элемента управления, поведение выполняется следующим образом в зависимости от типа контроллера узла: На контроллерах узла EHCI контроллер узла немедленно переходит к этапу состояния передачи элемента управления. Передача завершается успешно, независимо от того, задана ли USBD_SHORT_TRANSFER_OK. В контроллерах узла UHCI и OHCI, если USBD_SHORT_TRANSFER_OK задано, контроллер узла переходит к этапу состояния. Если USBD_SHORT_TRANSFER_OK не задано, контроллер узла отказывается от этапов передачи данных и состояния элемента управления, а передача завершается ошибкой.
USBD_DEFAULT_PIPE_TRANSFER	Устанавливается для направления контроллера узла для передачи элемента управления на канале управления по умолчанию. Это позволяет вызывающему объекту отправлять команды в канал управления по умолчанию без явного указания дескриптора канала.

TransferBufferLength

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

TransferBuffer

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

TransferBufferMDL

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

UrbLink

Скрытный. Не используйте.

hca

Скрытный. Не используйте.

SetupPacket[8]

Задает пакет установки usb-запроса. Формат пакета установки USB-запроса находится в спецификации USB-ядра.

Замечания

Структура URB_CONTROL_TRANSFER_EX идентична URB_CONTROL_TRANSFER, за исключением того, что она предоставляет значение времени ожидания в поле Timeout.

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