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

Статья
02/07/2025

[Применимо к 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	Элемент размераWDF_USB_DEVICE_SELECT_CONFIG_PARAMS структуры WDF_USB_DEVICE_SELECT_CONFIG_PARAMS, к которому указывает парамс.
STATUS_INSUFFICIENT_RESOURCES	Не удалось выделить буфер памяти.
STATUS_NOT_SUPPORTED	Платформа возвращает это значение, если драйвер UMDF вызывает WdfUsbTargetDeviceSelectConfig с Params->Type для любого из следующих значений: WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb Дополнительные сведения см. в WdfUsbTargetDeviceSelectConfigType.

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

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

Замечания

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

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

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

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

осторожность

Вы можете использовать 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 (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)