WdfUsbInterfaceSelectSetting function (wdfusb.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfUsbInterfaceSelectSetting method selects a specified alternate setting for a specified USB interface.

Syntax

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

Parameters

[in] UsbInterface

A handle to a USB interface object that was obtained by calling WdfUsbTargetDeviceGetInterface.

[in, optional] PipesAttributes

A pointer to a WDF_OBJECT_ATTRIBUTES structure that specifies object attributes for pipe objects that the framework creates for the interface. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[in] Params

A pointer to a caller-supplied WDF_USB_INTERFACE_SELECT_SETTING_PARAMS structure that contains interface selection parameters.

Return value

WdfUsbInterfaceSelectSetting returns the I/O target's completion status value if the operation succeeds. Otherwise, this method can return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was detected.
STATUS_INSUFFICIENT_RESOURCES	There was insufficient memory to create a new pipe object.

For a list of other return values that the WdfUsbInterfaceSelectSetting method might return, see Framework Object Creation Errors.

This method also might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

After your driver calls WdfUsbTargetDeviceSelectConfig to select a configuration, the driver can call WdfUsbInterfaceSelectSetting to select an alternate setting for one of the device's interfaces.

Your driver can select an interface's alternate setting by specifying a USB interface descriptor or a URB, or by just providing an alternate setting for the interface. In all cases, the driver must provide a handle to an interface object.

If your driver just provides an alternate setting, the framework uses the interface object to determine the interface to which the setting belongs.

If your driver specifies an interface descriptor or a URB, the framework uses the interface that is specified in the descriptor or URB.

The framework creates a framework USB pipe object for each pipe that is associated with the interface, after deleting any pipe objects that the framework might have previously created for the interface. To obtain information about an interface's pipe objects, your driver can call WdfUsbInterfaceGetNumConfiguredPipes and WdfUsbInterfaceGetConfiguredPipe.

For more information about the WdfUsbInterfaceSelectSetting method and USB I/O targets, see USB I/O Targets.

Examples

The following code example initializes a WDF_OBJECT_ATTRIBUTES structure with attributes for the pipe objects that the framework will create. Then, the example initializes a WDF_USB_INTERFACE_SELECT_SETTING_PARAMS structure to specify alternate setting 1. Finally, the example calls WdfUsbInterfaceSelectSetting to select the alternate setting and create pipe objects for the interface's pipes.

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
                                      );

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.0
Minimum UMDF version	2.0
Header	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Share via