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:

Return codeDescription
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

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, KmdfIrql, KmdfIrql2, UsbKmdfIrql, UsbKmdfIrql2

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

Show: