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

2025-02-07

Структура _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

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

Доступно в Windows 8. Сведения об использовании цепочек многомерных выражений см. в статье Отправке сетевых многомерных выражений">Отправке цепочки многомерных выражений.

URB_FUNCTION_ISOCH_TRANSFER

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

URB_FUNCTION_ISOCH_TRANSFER_USING_CHAINED_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 функцию. Так как некоторые несоответствующие устройства не поддерживают эту функцию, корпорация Майкрософт предоставляет два дополнительных URI: 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

Извлекает дескриптор компонента Microsoft OS из 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 используется для предоставления общих сведений о каждом запросе к драйверу контроллера узла.

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