WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES function (wdfusb.h)

Article
10/21/2021

[Applies to KMDF and UMDF]

The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES function initializes a WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure so that a driver can configure a device to use multiple interfaces.

Syntax

void WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(
  [in, out]      PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params,
  [in, optional] UCHAR                                NumberInterfaces,
  [in, optional] PWDF_USB_INTERFACE_SETTING_PAIR      SettingPairs
);

Parameters

[in, out] Params

A pointer to a driver-allocated WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure.

[in, optional] NumberInterfaces

The number of elements in the SettingPairs array. If SettingPairs is not NULL, this parameter must be greater than zero.

[in, optional] SettingPairs

An array of WDF_USB_INTERFACE_SETTING_PAIR structures. This parameter is optional and can be NULL.

Return value

None

Remarks

Your driver can use the WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES function to select a configuration if the device interfaces are specified by handles to USB interface objects.

Your driver can use this function if your device has one or more USB interfaces.

The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES function zeros the WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure and sets the Size member to the size of the structure.

If either numInterfaces or SettingPairs is NULL, WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES sets the Type member to WdfUsbTargetDeviceSelectConfigTypeMultiInterface. In this case, the framework determines the number of interfaces you have and enables alternate setting zero on each. Use this setting if you would like to default to alternate setting zero on all interfaces.

If the numInterfaces parameter and the SettingPairs parameter are both not NULL, this function sets the Type member of the WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure to WdfUsbTargetDeviceSelectConfigTypeInterfacesPairs. In this case, you can specify an alternate setting on any of the interfaces.

To initialize a WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure, the driver must call one of the following functions:

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_DECONFIG
WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE
WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES
WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_INTERFACES_DESCRIPTORS
WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_URB

Examples

The following code example calls either WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE or WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES, based on the number of interfaces that the device configuration supports. Then, the example calls WdfUsbTargetDeviceSelectConfig to select a configuration.

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS params;
PWDF_USB_INTERFACE_SETTING_PAIR settingPairs;
UCHAR numInterfaces;

numInterfaces = WdfUsbTargetDeviceGetNumInterfaces(UsbDevice);

if (numInterfaces == 1){
    WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(&params);
}
else {
    settingPairs = ExAllocatePoolWithTag(
                        PagedPool,
                        sizeof(WDF_USB_INTERFACE_SETTING_PAIR) * numInterfaces,
                        MEM_TAG
                        );
    if (settingPairs == NULL){
        return STATUS_INSUFFICIENT_RESOURCES;
    }

 //
 // Call driver-defined routine to populate the
    // WDF_USB_INTERFACE_SETTING_PAIR structures 
 // that ExAllocatePoolWithTag allocated.
 //
    InitSettingPairs(
                     UsbDevice,
                     settingPairs,
                     numInterfaces
                     );

    WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(
                    &params,
                    numInterfaces,
                    settingPairs
                    );
}
status = WdfUsbTargetDeviceSelectConfig(
                                        UsbDevice,
                                        NULL,
                                        &params
                                        );
if (!NT_SUCCESS(status)) {
    return status;
}

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfusb.h (include Wdfusb.h)