функция USBD_SelectInterfaceUrbAllocateAndBuild (usbdlib.h)

Статья
08/07/2023

Подпрограмма USBD_SelectInterfaceUrbAllocateAndBuild выделяет и форматирует структуру URB, необходимую для запроса на выбор интерфейса или изменение альтернативного параметра.

Синтаксис

NTSTATUS USBD_SelectInterfaceUrbAllocateAndBuild(
  [in]  USBD_HANDLE                USBDHandle,
  [in]  USBD_CONFIGURATION_HANDLE  ConfigurationHandle,
        PUSBD_INTERFACE_LIST_ENTRY InterfaceListEntry,
  [out] PURB                       *Urb
);

Параметры

[in] USBDHandle

UsbD-дескриптор, полученный драйвером клиента в предыдущем вызове подпрограммы USBD_CreateHandle.

[in] ConfigurationHandle

Дескриптор, возвращаемый стеком USB-драйвера в UrbSelectConfiguration.ConfigurationHandle член структуры URB, после завершения запроса на выборку конфигурации стека драйверов.

InterfaceListEntry

Указатель на структуру, выделенную вызывающим объектом USBD_INTERFACE_LIST_ENTRY. Дополнительные сведения см. в разделе "Примечания".

[out] Urb

Указатель на структуру URB, которая получает URB, выделенную USBD_SelectInterfaceUrbAllocateAndBuild. Драйвер клиента должен освободить URB после завершения использования драйвера, вызвав USBD_UrbFree.

Возвращаемое значение

Подпрограмма возвращает код NTSTATUS. Возможные значения включают, но не ограничены, коды состояния, перечисленные в следующей таблице.

Возвращаемый код	Описание
STATUS_SUCCESS	Обычный вызов выполнен успешно.
STATUS_INVALID_PARAMETER	Вызывающий объект передал значение NULL в любом из параметров.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти для завершения вызова.

Замечания

Драйвер клиента должен вызвать подпрограмму USBD_SelectInterfaceUrbAllocateAndBuild после выбора конфигурации на устройстве. После завершения запроса на выборку конфигурации драйвер клиента получает дескриптор конфигурации в UrbSelectConfiguration.ConfigurationHandle член URB. Этот дескриптор должен быть указан в параметре ConfigurationHandle ConfigurationHandleUSBD_SelectInterfaceUrbAllocateAndBuild.

Драйвер клиента вызывает USBD_SelectInterfaceUrbAllocateAndBuild выделить и создать URB для запроса на выборку интерфейса, чтобы изменить альтернативный параметр интерфейса в выбранной конфигурации. В вызове USBD_SelectInterfaceUrbAllocateAndBuildдрайвер клиента должен выделить и указать указатель на структуру USBD_INTERFACE_LIST_ENTRY. Драйвер клиента должен задать элементы структуры следующим образом:

Элемент interfaceDescriptor должен указывать на структуру USB_INTERFACE_DESCRIPTOR, содержащую дескриптор интерфейса с альтернативным параметром для выбора. Дескриптор интерфейса был получен в предыдущем запросе, чтобы получить дескриптор конфигурации и связанные интерфейсы и дескрипторы конечных точек.
Элемент интерфейса должен иметь значение NULL.

USBD_SelectInterfaceUrbAllocateAndBuild выделяет структуру URB и заполняет ее сведениями о указанном параметре интерфейса и конечных точках. Подпрограмма также выделяет USBD_INTERFACE_INFORMATION структуру. Элементы структуры (кроме сведений о канале) заполняются на основе указанного дескриптора интерфейса. USBD_SelectInterfaceUrbAllocateAndBuild задает элемент интерфейса USBD_INTERFACE_LIST_ENTRY адресом USBD_INTERFACE_INFORMATION в URB. Драйвер клиента может отправить этот URB в стек USB-драйверов, чтобы выбрать альтернативный параметр в интерфейсе.

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

После завершения запроса на выборку интерфейс стек usb-драйверов заполняет USBD_INTERFACE_INFORMATION сведениями о каналах, открытых для конечных точек, определенных в выбранном альтернативном параметре. Драйвер клиента может получить эти дескрипторы канала, проверяя массив, на который указывает каналы член USBD_INTERFACE_INFORMATION, и хранить дескриптор для будущих запросов на передачу данных.

Драйвер клиента может повторно использовать URB, выделенный USBD_SelectInterfaceUrbAllocateAndBuild только для другого запроса интерфейса выбора для того же альтернативного параметра. Драйвер клиента не должен повторно использовать URB для любого другого типа запроса или для другого запроса интерфейса выбора для другого альтернативного параметра. Вместо выделения нового URB повторное использованием существующего URB является предпочтительным подходом в определенных сценариях. Рассмотрим USB-звуковое устройство с интерфейсом с двумя альтернативными параметрами, определенными для двух требований к пропускной способности. Параметр 0 определен для нулевой пропускной способности; Параметр 1 определяется для использования определенного объема пропускной способности. Драйвер клиента хочет часто переключаться между двумя параметрами в зависимости от того, используется ли устройство. Чтобы реализовать этот сценарий, драйвер клиента может выделить два URI для запросов на выборку, по одному на параметр. Драйвер клиента может использовать (и повторно использовать) URB для запроса на выборку интерфейса, чтобы выбрать параметр 1 при отправке звуков на устройство. Чтобы сохранить пропускную способность при отсутствии звуков, драйвер клиента может использовать (и повторно использовать) другой URB для переключения на параметр 0. Эта реализация запрещает драйверу клиента выделять URI для каждого из этих запросов интерфейса выбора, каждый раз, когда драйверу нужно изменить параметр.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Требуется WDK для Windows 8. Предназначено для Windows Vista и более поздних версий операционной системы Windows.
целевая платформа	Настольный
заголовка	usbdlib.h
библиотеки	Usbdex.lib
IRQL	DISPATCH_LEVEL

См. также

USBD_CreateHandle

USBD_SelectConfigUrbAllocateAndBuild

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