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

Статья
02/26/2024

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

Синтаксис

struct _URB_HEADER {
  USHORT      Length;
  USHORT      Function;
  USBD_STATUS Status;
  PVOID       UsbdDeviceHandle;
  ULONG       UsbdFlags;
};

Члены

Length

Указывает длину URB в байтах. Для запросов URB, использующих структуры данных, отличные от _URB_HEADER, для этого элемента должна быть задана длина всей структуры запроса URB, а не размер _URB_HEADER.

Function

Задает числовой код, указывающий запрошенную операцию для этого URB. Необходимо задать одно из следующих значений:

URB_FUNCTION_SELECT_CONFIGURATION

Указывает драйверу контроллера узла, что требуется выбрать конфигурацию. Если задано значение , urb используется с URB_SELECT_CONFIGURATION в качестве структуры данных.

URB_FUNCTION_SELECT_INTERFACE

Указывает драйверу контроллера узла, что для интерфейса выбирается альтернативный параметр интерфейса. Если задано значение , urb используется с _URB_SELECT_INTERFACE в качестве структуры данных.

URB_FUNCTION_ABORT_PIPE

Указывает, что все невыполненные запросы для канала должны быть отменены. Если задано значение , urb используется с _URB_PIPE_REQUEST в качестве структуры данных. Этот запрос общего назначения позволяет клиенту отменить все ожидающие передачи для указанного канала. Состояние канала и состояние конечной точки не затрагиваются. Запрос на прерывание может завершиться до завершения всех невыполненных запросов. Не предполагайте, что выполнение запроса прерывания подразумевает завершение всех остальных невыполненных запросов.

URB_FUNCTION_TAKE_FRAME_LENGTH_CONTROL

Эта функция URB является нерекомендуемой в операционных системах Windows 2000 и более поздних версий и не поддерживается корпорацией Майкрософт. Не используйте. Если указать эту функцию с запросом URB, запрос завершится ошибкой и система сообщит об ошибке.

URB_FUNCTION_RELEASE_FRAME_LENGTH_CONTROL

URB_FUNCTION_GET_FRAME_LENGTH

Эта функция URB является нерекомендуемой в операционных системах Windows 2000 и более поздних версий и не поддерживается корпорацией Майкрософт. Не используйте. Если вы используете эту функцию с запросом URB, запрос завершится ошибкой и система сообщит об ошибке.

URB_FUNCTION_SET_FRAME_LENGTH

Эта функция URB является нерекомендуемой в операционных системах Windows 2000 и более поздних версий и не поддерживается корпорацией Майкрософт. Не используйте. Если вы используете его с запросом URB, запрос завершится ошибкой, и система сообщит об ошибке.

URB_FUNCTION_GET_CURRENT_FRAME_NUMBER

Запрашивает текущий номер кадра из драйвера контроллера узла. Если задано значение , urb используется с _URB_GET_CURRENT_FRAME_NUMBER в качестве структуры данных.

URB_FUNCTION_CONTROL_TRANSFER

Передает данные в управляющий канал или из нее. Если задано значение , urb используется с _URB_CONTROL_TRANSFER в качестве структуры данных.

URB_FUNCTION_CONTROL_TRANSFER_EX

Передает данные в управляющий канал или из нее без ограничения времени, заданного значением времени ожидания. Если задано значение , urb используется с URB_CONTROL_TRANSFER_EX в качестве структуры данных.

Доступно в Операционных системах Windows Vista и более поздних версий.

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER

Передает данные из массового канала или канала прерывания или в массовый канал. Если задано значение , urb используется с _URB_BULK_OR_INTERRUPT_TRANSFER в качестве структуры данных.

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER_USING_CHAINED_MDL

Передает данные в массовый канал или канал прерывания и из нее с помощью цепочек MDL. Если задано значение , urb используется с _URB_BULK_OR_INTERRUPT_TRANSFER в качестве структуры данных. Драйвер клиента должен задать для члена TransferBufferMDL первую структуру MDL в цепочке, содержащей буфер передачи. Стек драйверов USB игнорирует элемент TransferBuffer при обработке этого URB.

Доступно в Windows 8. Сведения об использовании цепочек многомерных выражений см. в статье How to Send Chained MDLs(>How to Send Chained MDLs).

URB_FUNCTION_ISOCH_TRANSFER

Передает данные в изохронный канал или из нее. Если задано значение , urb используется с _URB_ISOCH_TRANSFER в качестве структуры данных.

URB_FUNCTION_ISOCH_TRANSFER_USING_CHAINED_MDL

Передает данные в изохронный канал или из нее с помощью цепочек MDL. Если задано значение , urb используется с _URB_ISOCH_TRANSFER в качестве структуры данных. Драйвер клиента должен задать для члена TransferBufferMDL первый MDL в цепочке, содержащей буфер передачи. Стек драйверов USB игнорирует элемент TransferBuffer при обработке этого URB.

URB_FUNCTION_RESET_PIPE

См. URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL.

URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL

Сбрасывает указанный канал. Если этот параметр задан, этот URB используется с _URB_PIPE_REQUEST.

Примечание

Эта URB заменяет URB_FUNCTION_RESET_PIPE.

Водитель автобуса выполняет три задачи в ответ на этот URB:

Во-первых, для всех каналов, кроме изохронных, эта URB отправляет CLEAR_FEATURE запрос на очистку функции ENDPOINT_HALT устройства.

Во-вторых, драйвер шины USB сбрасывает переключатель данных на стороне узла в соответствии со спецификацией USB. USB-устройство должно сбросить переключатель данных на стороне устройства, когда водитель шины очищает ENDPOINT_HALT функцию. Так как некоторые несоответствующие устройства не поддерживают эту функцию, корпорация Майкрософт предоставляет два дополнительных urb: URB_FUNCTION_SYNC_CLEAR_STALL и URB_FUNCTION_SYNC_RESET_PIPE. Они позволяют клиентским драйверам очищать ENDPOINT_HALT функцию на устройстве или сбрасывать канал на стороне узла соответственно, не влияя на переключатель данных на стороне узла. Если устройство не сбрасывает переключатель данных, когда это необходимо, драйвер клиента может компенсировать этот дефект, не сбрасывая переключатель данных на стороне узла. Если переключатель данных сбрасывается на стороне узла, но не на стороне устройства, пакеты будут выходить из последовательности, и устройство может удалить пакеты.

В-третьих, после успешного сброса канала водитель автобуса возобновляет передачи с помощью следующей очереди URB.

После сброса канала переносы возобновляются со следующей очередью URB.

Нет необходимости очищать условие остановки в канале управления по умолчанию. Канал управления по умолчанию всегда должен принимать пакеты установки, поэтому в случае остановки стек USB автоматически очистит условие остановки. Драйверу клиента не нужно предпринимать никаких специальных действий для очистки условия остановки в канале по умолчанию.

Все передачи должны быть прерваны или отменены перед попыткой сброса канала.

Эта urb должна быть отправлена по адресу PASSIVE_LEVEL.

URB_FUNCTION_SYNC_RESET_PIPE

Очищает условие остановки на стороне узла канала. Если задано значение , эта URB используется с _URB_PIPE_REQUEST в качестве структуры данных.

Эта URB позволяет клиенту очистить остановленное состояние канала без сброса переключателя данных и без очистки условия остановки конечной точки (ENDPOINT_HALT функции). Чтобы очистить условие остановки в канале, сбросить переключатель данных на стороне узла и очистить зависание на устройстве с помощью одной операции, используйте URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL.

Следующие коды состояния важны и имеют указанное значение:

USBD_STATUS_INVALID_PIPE_HANDLE

Недопустимый объект PipeHandle

USBD_STATUS_ERROR_BUSY

Конечная точка имеет активные передачи, ожидающие.

Все передачи должны быть прерваны или отменены перед попыткой сброса канала.

Эта URB должна быть отправлена по адресу PASSIVE_LEVEL.

Доступно в Операционных системах Windows XP и более поздних версий.

URB_FUNCTION_SYNC_CLEAR_STALL

Очищает условие остановки в конечной точке. Для всех каналов, кроме изохронных, этот URB отправляет CLEAR_FEATURE запрос на очистку функции ENDPOINT_HALT устройства. Однако, в отличие от функции RB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL, эта функция URB не сбрасывает переключатель данных на стороне узла канала. Спецификация USB требует, чтобы устройства сбрасывали переключатель данных на стороне устройства после того, как клиент очистит функцию ENDPOINT_HALT устройства, но некоторые несоответствующие устройства сбрасывают переключатель данных должным образом. Клиентские драйверы, управляющие такими устройствами, могут компенсировать этот дефект, очищая условие остановки непосредственно с помощью URB_FUNCTION_SYNC_CLEAR_STALL вместо сброса канала с помощью URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL. URB_FUNCTION_SYNC_CLEAR_STALL очищает состояние остановки на устройстве без сброса переключателя данных на стороне узла. Это не позволяет устройству, не соответствующему требованиям, интерпретировать следующий пакет как повторную передачу и удалить пакет.

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

Эта функция URB должна быть отправлена по адресу PASSIVE_LEVEL

Доступно в Операционных системах Windows XP и более поздних версий.

URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE

Извлекает дескриптор устройства с определенного USB-устройства. Если этот параметр задан, urb используется с _URB_CONTROL_DESCRIPTOR_REQUEST в качестве структуры данных.

URB_FUNCTION_GET_DESCRIPTOR_FROM_ENDPOINT

Извлекает дескриптор из конечной точки в интерфейсе USB-устройства. Если этот параметр задан, urb используется с _URB_CONTROL_DESCRIPTOR_REQUEST в качестве структуры данных.

URB_FUNCTION_SET_DESCRIPTOR_TO_DEVICE

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

URB_FUNCTION_SET_DESCRIPTOR_TO_ENDPOINT

Задает дескриптор конечной точки в конечной точке для интерфейса. Если этот параметр задан, urb используется с _URB_CONTROL_DESCRIPTOR_REQUEST в качестве структуры данных.

URB_FUNCTION_SET_FEATURE_TO_DEVICE

Задает функцию, определяемую USB, на устройстве. Если этот параметр задан, urb используется с _URB_CONTROL_FEATURE_REQUEST в качестве структуры данных.

URB_FUNCTION_SET_FEATURE_TO_INTERFACE

Задает определяемую USB функцию в интерфейсе устройства. Если этот параметр задан, urb используется с _URB_CONTROL_FEATURE_REQUEST в качестве структуры данных.

URB_FUNCTION_SET_FEATURE_TO_ENDPOINT

Задает функцию, определяемую USB, в конечной точке для интерфейса на USB-устройстве. Если этот параметр задан, urb используется с _URB_CONTROL_FEATURE_REQUEST в качестве структуры данных.

URB_FUNCTION_SET_FEATURE_TO_OTHER

Задает функцию, определяемую USB, в целевом объекте, определяемом устройством на USB-устройстве. Если этот параметр задан, urb используется с _URB_CONTROL_FEATURE_REQUEST в качестве структуры данных.

URB_FUNCTION_CLEAR_FEATURE_TO_DEVICE

Очищает определяемую USB функцию на устройстве. Если этот параметр задан, urb используется с _URB_CONTROL_FEATURE_REQUEST в качестве структуры данных.

URB_FUNCTION_CLEAR_FEATURE_TO_INTERFACE

Очищает определяемую USB-функцию в интерфейсе устройства. Если этот параметр задан, urb используется с _URB_CONTROL_FEATURE_REQUEST в качестве структуры данных.

URB_FUNCTION_CLEAR_FEATURE_TO_ENDPOINT

Очищает определяемую USB-функцию в конечной точке для интерфейса на USB-устройстве. Если этот параметр задан, urb используется с _URB_CONTROL_FEATURE_REQUEST в качестве структуры данных.

URB_FUNCTION_CLEAR_FEATURE_TO_OTHER

Очищает определяемую USB-функцию в целевом объекте, определенном устройством на USB-устройстве. Если этот параметр задан, urb используется с _URB_CONTROL_FEATURE_REQUEST в качестве структуры данных.

URB_FUNCTION_GET_STATUS_FROM_DEVICE

Извлекает состояние с USB-устройства. Если этот параметр задан, URB используется с _URB_CONTROL_GET_STATUS_REQUEST в качестве структуры данных.

URB_FUNCTION_GET_STATUS_FROM_INTERFACE

Извлекает состояние из интерфейса НА USB-устройстве. Если этот параметр задан, URB используется с _URB_CONTROL_GET_STATUS_REQUEST в качестве структуры данных.

URB_FUNCTION_GET_STATUS_FROM_ENDPOINT

Извлекает состояние из конечной точки для интерфейса на USB-устройстве. Если этот параметр задан, URB используется с _URB_CONTROL_GET_STATUS_REQUEST в качестве структуры данных.

URB_FUNCTION_GET_STATUS_FROM_OTHER

Извлекает состояние из определенного устройством целевого объекта на USB-устройстве. Если этот параметр задан, URB используется с _URB_CONTROL_GET_STATUS_REQUEST в качестве структуры данных.

URB_FUNCTION_VENDOR_DEVICE

Отправляет команду конкретного поставщика на USB-устройство. Если этот параметр задан, URB используется с _URB_CONTROL_VENDOR_OR_CLASS_REQUEST в качестве структуры данных.

URB_FUNCTION_VENDOR_INTERFACE

Отправляет команду для конкретного поставщика для интерфейса на USB-устройстве. Если этот параметр задан, URB используется с _URB_CONTROL_VENDOR_OR_CLASS_REQUEST в качестве структуры данных.

URB_FUNCTION_VENDOR_ENDPOINT

Отправляет команду конкретного поставщика для конечной точки в интерфейсе на USB-устройстве. Если этот параметр задан, URB используется с _URB_CONTROL_VENDOR_OR_CLASS_REQUEST в качестве структуры данных.

URB_FUNCTION_VENDOR_OTHER

Отправляет команду конкретного поставщика в определенный устройством целевой объект на USB-устройстве. Если этот параметр задан, URB используется с _URB_CONTROL_VENDOR_OR_CLASS_REQUEST в качестве структуры данных.

URB_FUNCTION_CLASS_DEVICE

Отправляет определяемую USB команду класса на USB-устройство. Если этот параметр задан, URB используется с _URB_CONTROL_VENDOR_OR_CLASS_REQUEST в качестве структуры данных.

URB_FUNCTION_CLASS_INTERFACE

Отправляет определяемую USB команду класса в интерфейс НА USB-устройстве. Если этот параметр задан, URB используется с _URB_CONTROL_VENDOR_OR_CLASS_REQUEST в качестве структуры данных.

URB_FUNCTION_CLASS_ENDPOINT

Отправляет определяемую USB команду класса в конечную точку в интерфейсе на USB-устройстве. Если этот параметр задан, URB используется с _URB_CONTROL_VENDOR_OR_CLASS_REQUEST в качестве структуры данных.

URB_FUNCTION_CLASS_OTHER

Отправляет команду класса, определяемую USB, в целевой объект, определенный устройством на USB-устройстве. Если этот параметр задан, URB используется с _URB_CONTROL_VENDOR_OR_CLASS_REQUEST в качестве структуры данных.

URB_FUNCTION_GET_CONFIGURATION

Извлекает текущую конфигурацию на USB-устройстве. Если этот параметр задан, urb используется с _URB_CONTROL_GET_CONFIGURATION_REQUEST в качестве структуры данных.

URB_FUNCTION_GET_INTERFACE

Извлекает текущие параметры интерфейса на USB-устройстве. Если этот параметр задан, URB используется с _URB_CONTROL_GET_INTERFACE_REQUEST в качестве структуры данных.

Доступно в Windows 2000, Windows Vista и более поздних операционных системах. Недоступно в Windows XP.

URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE

Извлекает дескриптор из интерфейса USB-устройства. Если задано значение , urb используется с _URB_CONTROL_DESCRIPTOR_REQUEST в качестве структуры данных.

URB_FUNCTION_SET_DESCRIPTOR_TO_INTERFACE

Задает дескриптор для интерфейса на USB-устройстве. Если задано значение , urb используется с _URB_CONTROL_DESCRIPTOR_REQUEST в качестве структуры данных.

URB_FUNCTION_GET_MS_FEATURE_DESCRIPTOR

Извлекает дескриптор компонента ОС Майкрософт из USB-устройства или интерфейса на USB-устройстве. Если этот параметр задан, urb используется с _URB_OS_FEATURE_DESCRIPTOR_REQUEST в качестве структуры данных.

Доступно в операционных системах Windows XP и более поздних версий.

URB_FUNCTION_OPEN_STATIC_STREAMS

Открывает потоки в указанной массовой конечной точке. Если задано значение , urb используется с _URB_OPEN_STATIC_STREAMS в качестве структуры данных.

Доступно в Windows 8. Сведения о форматировании URB для запроса открытого потока см. в статье Открытие и закрытие статических потоков в конечной точке массовой передачи USB.

URB_FUNCTION_CLOSE_STATIC_STREAMS

Закрывает все открытые потоки в указанной конечной точке массовых операций. Если задано значение , urb используется с _URB_PIPE_REQUEST в качестве структуры данных.

Status

Содержит код USBD_STATUS_XXX при возвращении из драйвера контроллера узла.

UsbdDeviceHandle

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

UsbdFlags

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

Структура _URB_HEADER является членом всех USB-запросов, входящих в структуру URB. Структура _URB_HEADER используется для предоставления общих сведений о каждом запросе к драйверу контроллера узла.

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