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

Статья
02/07/2025

[Применимо к 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, см. в ошибок создания объектов Framework.

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

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

Замечания

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

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

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

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

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

Дополнительные сведения о методе WdfUsbInterfaceSelectSetting и целевых объектах ввода-вывода USB см. в целевых объектов usb-ввода-вывода.

Примеры

В следующем примере кода инициализируется структура 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 (include 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)