функция 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. Этот дескриптор необходимо указать в параметре 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, чтобы выбрать альтернативный параметр в интерфейсе.

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

После завершения запроса select-interface стек 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