WdfUsbInterfaceSelectSetting method

[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

UsbInterface [in]

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

PipesAttributes [in, optional]

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.

Params [in]

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:

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

See also

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT

WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE

WDF_USB_INTERFACE_SELECT_SETTING_PARAMS

WDF_USB_INTERFACE_SELECT_SETTING_PARAMS_INIT_SETTING

WdfUsbInterfaceGetConfiguredPipe

WdfUsbInterfaceGetNumConfiguredPipes

WdfUsbTargetDeviceGetInterface

WdfUsbTargetDeviceSelectConfig

Send comments about this topic to Microsoft