Функция WdfUsbInterfaceSelectSetting (wdfusb.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Метод WdfUsbInterfaceSelectSetting выбирает указанный альтернативный параметр для указанного ИНТЕРФЕЙСА USB.

Синтаксис

NTSTATUS WdfUsbInterfaceSelectSetting(
  [in]           WDFUSBINTERFACE                          UsbInterface,
  [in, optional] PWDF_OBJECT_ATTRIBUTES                   PipesAttributes,
  [in]           PWDF_USB_INTERFACE_SELECT_SETTING_PARAMS Params
);

Параметры

[in] UsbInterface

Дескриптор объекта интерфейса USB, полученный путем вызова WdfUsbTargetDeviceGetInterface.

[in, optional] PipesAttributes

Указатель на структуру WDF_OBJECT_ATTRIBUTES , указывающую атрибуты объекта для объектов канала, создаваемых платформой для интерфейса. Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[in] Params

Указатель на предоставленную вызывающей WDF_USB_INTERFACE_SELECT_SETTING_PARAMS структуру, содержащую параметры выбора интерфейса.

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

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти для создания нового объекта канала.

Список других возвращаемых значений, которые может возвращать метод WdfUsbInterfaceSelectSetting , см. в разделе Ошибки создания объекта платформы.

Этот метод также может возвращать другие значения NTSTATUS.

Ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

После того как драйвер вызывает WdfUsbTargetDeviceSelectConfig для выбора конфигурации, драйвер может вызвать WdfUsbInterfaceSelectSetting , чтобы выбрать альтернативный параметр для одного из интерфейсов устройства.

Драйвер может выбрать альтернативный параметр интерфейса, указав дескриптор интерфейса USB или URB или просто указав альтернативный параметр для интерфейса. Во всех случаях драйвер должен предоставить дескриптор для объекта интерфейса.

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

Если драйвер задает дескриптор интерфейса или URB, платформа использует интерфейс, указанный в дескрипторе или URB.

Платформа создает объект USB-канала платформы для каждого канала, связанного с интерфейсом, после удаления всех объектов канала, которые платформа могла ранее создать для интерфейса. Чтобы получить сведения об объектах канала интерфейса, драйвер может вызвать WdfUsbInterfaceGetNumConfiguredPipes и WdfUsbInterfaceGetConfiguredPipe.

Дополнительные сведения о методе WdfUsbInterfaceSelectSetting и целевых объектах USB-ввода-вывода см. в разделе Usb I/O Targets.

Примеры

В следующем примере кода инициализируется структура WDF_OBJECT_ATTRIBUTES с атрибутами для объектов канала, создаваемых платформой. Затем в примере инициализируется структура WDF_USB_INTERFACE_SELECT_SETTING_PARAMS для указания альтернативного параметра 1. Наконец, в примере вызывается метод WdfUsbInterfaceSelectSetting для выбора альтернативного параметра и создания объектов канала для каналов интерфейса.

WDF_OBJECT_ATTRIBUTES  pipesAttributes;
WDF_USB_INTERFACE_SELECT_SETTING_PARAMS  selectSettingParams;
NTSTATUS  Status;

WDF_OBJECT_ATTRIBUTES_INIT(&pipesAttributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &pipesAttributes,
                                       MY_PIPE_CONTEXT
                                       );

WDF_USB_INTERFACE_SELECT_SETTING_PARAMS_INIT_SETTING(
                                      &selectSettingParams,
                                      1
                                      );

Status = WdfUsbInterfaceSelectSetting(
                                      UsbInterface,
                                      &pipesAttributes,
                                      &selectSettingParams
                                      );

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfusb.h (включая Wdfusb.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)