USB配置初始化和激活

USB配置结构:

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS

The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure specifies USB device configuration parameters.

typedef struct _WDF_USB_DEVICE_SELECT_CONFIG_PARAMS {
      ULONG      Size;
      WdfUsbTargetDeviceSelectConfigType      Type;
      union {
        struct {
          PUSB_CONFIGURATION_DESCRIPTOR      ConfigurationDescriptor;
          PUSB_INTERFACE_DESCRIPTOR*      InterfaceDescriptors;
          ULONG NumInterfaceDescriptors;
        } Descriptor;
        struct {
          PURB      Urb;
        } Urb;
        struct {
          UCHAR      NumberConfiguredPipes;
          WDFUSBINTERFACE      ConfiguredUsbInterface;
        } SingleInterface;
        struct {
          UCHAR      NumberInterfaces;
          PWDF_USB_INTERFACE_SETTING_PAIR      Pairs;
          UCHAR      NumberOfConfiguredInterfaces;
        } MultiInterface;
      } Types;
} WDF_USB_DEVICE_SELECT_CONFIG_PARAMS, *PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS;

Members
Size 
The size, in bytes, of this structure. 
Type 
A WdfUsbTargetDeviceSelectConfigType-typed value that either specifies the type of configuration that is being selected or indicates that the current configuration is being deconfigured. 
Types.Descriptor.ConfigurationDescriptor 
If the driver sets the Type member to WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor, this member contains a driver-supplied pointer to a USB_CONFIGURATION_DESCRIPTOR structure that specifies a configuration descriptor. If this pointer is NULL, the framework uses the device's first configuration. 
Types.Descriptor.InterfaceDescriptors 
If the driver sets Type to WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor, this member contains a driver-supplied pointer to an array of USB_INTERFACE_DESCRIPTOR structures that represent the interfaces to select for the configuration. 
Types.Descriptor.NumInterfaceDescriptors 
If the driver sets Type to WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor, this member contains the number of elements that are in the interface array that Types.Descriptor.InterfaceDescriptors points to. 
Types.Urb.Urb 
If the driver sets Type to WdfUsbTargetDeviceSelectConfigTypeUrb, this member specifies a driver-initialized URB structure that the framework uses to configure the device. 
Types.SingleInterface.NumberConfiguredPipes 
If the driver sets Type to WdfUsbTargetDeviceSelectConfigTypeSingleInterface, the framework provides the number of pipes that are configured for the interface. 
Types.SingleInterface.ConfiguredUsbInterface 
If the driver sets Type to WdfUsbTargetDeviceSelectConfigTypeSingleInterface, the framework provides a handle to a USB interface object that represents the configured interface. 
Types.MultiInterface.NumberInterfaces 
If the driver sets Type to WdfUsbTargetDeviceSelectConfigTypeInterfacesPairs, this member specifies the number of elements that are in the Types.MultiInterface.Pairs array. 
Types.MultiInterface.Pairs 
If the driver sets Type to WdfUsbTargetDeviceSelectConfigTypeInterfacesPairs, this member specifies a pointer to an array of WDF_USB_INTERFACE_SETTING_PAIR structures that identify the interfaces to select. 
Types.MultiInterface.NumberOfConfiguredInterfaces 
If the driver sets Type to WdfUsbTargetDeviceSelectConfigTypeInterfacesPairs or WdfUsbTargetDeviceSelectConfigTypeMultiInterface, the framework provides the number if interfaces that are configured for the device. 
Comments
The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure is used as input to WdfUsbTargetDeviceSelectConfig.
To initialize a WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure, use 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
If the driver sets the Type member to WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor, it can change the USB device configuration. All other values use the current USB device configuration.
Requirements
Versions: The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure is available in version 1.0 and later versions of KMDF.
Headers: Declared in Wdfusb.h. Include Wdfusb.h.

USB配置初化:
WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_DECONFIG
 
 
The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_DECONFIG function initializes a WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure so that a driver can deconfigure a USB device.
VOID
      WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_DECONFIG(
        OUT PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS  Params
        );

Parameters
Params 
A pointer to a driver-allocated WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure. 
Return Value
None
Comments
The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_DECONFIG function zeros the WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure and sets the Size member to the size of the structure. It also sets the Type member to WdfUsbTargetDeviceSelectConfigTypeDeconfig.
WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE
 
 
The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE function initializes a WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure so that a driver can configure a device to use a single, specified interface.
VOID
      WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(
        OUT PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS  Params
        );

Parameters
Params 
A pointer to a driver-allocated WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure. 
Return Value
None
Comments
Your driver can use the WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE function to select a configuration if the device interface is specified by a handle to USB interface objects.
Your driver can use this function only if your device has just one USB interface.
The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE function zeros the WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure and sets the Size member to the size of the structure. It also sets the Type member to WdfUsbTargetDeviceSelectConfigTypeSingleInterface.
WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES
 
 
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.
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
Params 
A pointer to a driver-allocated WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure. 
NumberInterfaces 
The number of elements in the SettingPairs array. If SettingPairs is not NULL, this parameter must be greater than zero. 
SettingPairs 
An array of WDF_USB_INTERFACE_SETTING_PAIR structures. This parameter is optional and can be NULL. 

Return Value
None
Comments
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 the SettingPairs parameter is not NULL, this function sets the Type member to WdfUsbTargetDeviceSelectConfigTypeInterfacesPairs. Otherwise, WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES sets the Type member to WdfUsbTargetDeviceSelectConfigTypeMultiInterface.
WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_INTERFACES_DESCRIPTORS
 
 
The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_INTERFACES_DESCRIPTORS function initializes a WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure so that a driver can specify a configuration by using USB descriptors.
VOID
      WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_INTERFACES_DESCRIPTORS(
        OUT PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS  Params,
        IN PUSB_CONFIGURATION_DESCRIPTOR  ConfigDescriptor,
        IN PUSB_INTERFACE_DESCRIPTOR*  InterfaceDescriptors,
        IN ULONG  NumInterfaceDescriptors
        )

Parameters
Params 
A pointer to a driver-allocated WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure. 
ConfigDescriptor 
A pointer to a USB_CONFIGURATION_DESCRIPTOR structure. 
InterfaceDescriptors 
A pointer to an array of USB_INTERFACE_DESCRIPTOR structures. 
NumInterfaceDescriptors 
The number of elements that is in the InterfaceDescriptors array. 
Return Value
None
Comments
The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_INTERFACES_DESCRIPTORS function zeros the WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure and sets the Size member to the size of the structure. It also sets the Type member to WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor.
This function uses the ConfigDescriptor, InterfaceDescriptors, and NumInterfaceDescriptors parameters to set the structure's Types.Descriptor union members.
WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_URB
 
 
The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_USB function initializes a WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure so that a driver can specify a configuration by using a URB.
VOID FORCEINLINE
      WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_URB(
        OUT PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS  Params,
        IN PURB  Urb
        );

Parameters
Params 
A pointer to the driver's WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure. 
Urb 
A pointer to a URB structure. 
Return Value
None
Comments
The WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_URB function zeros the WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure and sets the Size member to the size of the structure. It also sets the Type member to WdfUsbTargetDeviceSelectConfigTypeUrb and sets the Types.Urb.Urb member to the Urb pointer.
USB配置激活:
WdfUsbTargetDeviceSelectConfig
 
 
The WdfUsbTargetDeviceSelectConfig method selects a USB configuration for a device, or it deconfigures the device.
NTSTATUS
      WdfUsbTargetDeviceSelectConfig(
        IN WDFUSBDEVICE  UsbDevice,
        IN OPTIONAL PWDF_OBJECT_ATTRIBUTES  PipeAttributes,
        IN OUT PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS  Params
        );

Parameters
UsbDevice 
A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreate. 
PipeAttributes 
A pointer to a caller-allocated WDF_OBJECT_ATTRIBUTES structure that contains attributes for new framework USB pipe objects that the framework creates for the device's interfaces. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES. 
Params 
A pointer to a caller-allocated WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure that the caller and the framework use to specify configuration parameters. 
Return Value
WdfUsbTargetDeviceSelectConfig returns the I/O target's completion status value if the operation succeeds. Otherwise, this method can return one of the following values:
STATUS_INVALID_PARAMETER 
An invalid parameter was detected. 
STATUS_INFO_LENGTH_MISMATCH 
The Size member of the WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure that Params points to was incorrect. 
STATUS_INSUFFICIENT_RESOURCES 
A memory buffer could not be allocated. 
 
This method might also return other NTSTATUS values.
A bug check occurs if a driver-supplied object handle is invalid.
 
Comments
Your driver can select a device configuration by using a WDF_USB_DEVICE_SELECT_CONFIG_PARAMS structure to specify USB descriptors, a URB, or handles to framework USB interface objects.
The framework creates a framework USB pipe object for each pipe that is associated with each interface in the configuration, after deleting any pipe objects that the framework might have previously created for the configuration. The framework uses alternate setting zero for each interface, unless the driver specifies a different alternate setting.
To obtain information about an interface's pipe objects, the driver can call WdfUsbInterfaceGetNumConfiguredPipes and WdfUsbInterfaceGetConfiguredPipe.
For more information about the WdfUsbTargetDeviceSelectConfig method and USB I/O targets, see USB I/O Targets.