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

  • Статья

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

Метод WdfUsbTargetDeviceSelectConfig выбирает конфигурацию USB для устройства или отменяет настройку устройства.

Синтаксис

NTSTATUS WdfUsbTargetDeviceSelectConfig(
  [in]           WDFUSBDEVICE                         UsbDevice,
  [in, optional] PWDF_OBJECT_ATTRIBUTES               PipeAttributes,
  [in, out]      PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
);

Параметры

[in] UsbDevice

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

[in, optional] PipeAttributes

Указатель на структуру, выделенную вызывающим объектом WDF_OBJECT_ATTRIBUTES , которая содержит атрибуты для новых объектов USB-канала платформы, создаваемых платформой для интерфейсов устройства. Для драйверов KMDF этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES. Драйверы UMDF должны задать для этого параметра значение NULL.

[in, out] Params

Указатель на выделенный вызывающим объектом WDF_USB_DEVICE_SELECT_CONFIG_PARAMS структуру, которую вызывающий объект и платформа используют для указания параметров конфигурации.

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

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

Код возврата Описание
STATUS_INVALID_PARAMETER
 Обнаружен недопустимый параметр.
STATUS_INFO_LENGTH_MISMATCH
 Неправильный элемент Sizeструктуры WDF_USB_DEVICE_SELECT_CONFIG_PARAMS , на которую указывает Params .
STATUS_INSUFFICIENT_RESOURCES
 Не удалось выделить буфер памяти.
STATUS_NOT_SUPPORTED
 Платформа возвращает это значение, если драйвер UMDF вызывает WdfUsbTargetDeviceSelectConfig с типом Params->, равным любому из следующих значений:
  • WdfUsbTargetDeviceSelectConfigTypeDeconfig
  • WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor
  • WdfUsbTargetDeviceSelectConfigTypeUrb
Дополнительные сведения см. в разделе WdfUsbTargetDeviceSelectConfigType.
 

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

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

Комментарии

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

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

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

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

Внимание!  

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

 

Примеры

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

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
NTSTATUS  status;

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(&configParams);

status = WdfUsbTargetDeviceSelectConfig(
                                        UsbDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &configParams
                                        );

В следующем примере кода выбирается конфигурация с несколькими интерфейсами, используя альтернативный нулевой параметр для всех интерфейсов. Этот пример применяется только к драйверам KMDF.

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
PWDF_USB_INTERFACE_SETTING_PAIR settingPairs;
UCHAR numInterfaces;
NTSTATUS  status;

numInterfaces = WdfUsbTargetDeviceGetNumInterfaces(UsbDevice);

settingPairs = ExAllocatePoolWithTag(
    PagedPool,
    sizeof(WDF_USB_INTERFACE_SETTING_PAIR) * numInterfaces,
    MY_DRIVER_TAG
);

if (settingPairs == NULL){
    return STATUS_INSUFFICIENT_RESOURCES;
}

for (interfaceIndex = 0; interfaceIndex < numInterfaces; interfaceIndex++) {
        
    settingPairs[interfaceIndex].UsbInterface = 
                                    WdfUsbTargetDeviceGetInterface(
                                        UsbDevice,
                                        interfaceIndex);

    // Select alternate setting zero on all interfaces.
       
    settingPairs[interfaceIndex].SettingIndex = 0;
}

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(
    &configParams,
    numInterfaces,
    settingPairs
);

status = WdfUsbTargetDeviceSelectConfig(
    UsbDevice,
    NULL,
    &configParams
);

if (!NT_SUCCESS(status)) {
    ExFreePoolWithTag(
        settingPairs,
        MY_DRIVER_TAG
    );
    return status;
}

Требования

Требование Значение
Целевая платформа Универсальное
Минимальная версия 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)

См. также раздел

WDF_OBJECT_ATTRIBUTES

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE

WdfUsbInterfaceGetConfiguredPipe

WdfUsbInterfaceGetNumConfiguredPipes

WdfUsbTargetDeviceCreateWithParameters