USB Routines

The topics in this section describe the four types of routines exposed by the Microsoft-provided USB driver stack.

Routines for USB Client Drivers
Bus Driver Interface Routines for USB Client Drivers
Generic Parent Driver Routines
WinUSB Functions
USB Device Redirection Routines
Deprecated Routines
Related topics

Routines for USB Client Drivers

This section lists the routines that a Windows Driver Model (WDM)-based USB client driver can call to communicate with the Microsoft-provided USB driver stack.

The following table lists the routines that are available in Windows Driver Kit (WDK) for Windows 8. These routines are defined in Usbdlib.h and the client driver requires the Usbdex.lib library. The library gets loaded and statically linked to the client driver module when it is built. A client driver that calls these routines can run on Windows Vista and later versions of Windows.

Routine	Description
USBD_AssignUrbToIoStackLocation	Associate an URB that is allocated by USBD_UrbAllocate, USBD_SelectConfigUrbAllocateAndBuild, or USBD_SelectInterfaceUrbAllocateAndBuild, with the IRP.
USBD_CreateHandle	Registers a client driver with the underlying USB driver stack.
USBD_CloseHandle	Closes a USBD handle obtained in a previous call to USBD_CreateHandle.
USBD_IsInterfaceVersionSupported	Checks whether the underlying USB driver stack supports a particular USBD interface version.
USBD_IsochUrbAllocate	Allocates and formats an URB structure for an isochronous transfer request.
USBD_QueryUsbCapability	Determine whether the underlying USB driver stack support a specific capability.
USBD_SelectConfigUrbAllocateAndBuild	Allocates and formats a URB structure that is required to select a configuration for a USB device.
USBD_SelectInterfaceUrbAllocateAndBuild	Allocates and formats a URB structure that is required to select an interface for a USB device.
USBD_UrbAllocate	Allocates an URB structure for a request.
USBD_UrbFree	Releases the URB that is allocated by USBD_UrbAllocate, USBD_SelectConfigUrbAllocateAndBuild, or USBD_SelectInterfaceUrbAllocateAndBuild.

The following table lists routines that are available in Windows Vista and later versions of the operating system.

Routine	Description
GET_ISO_URB_SIZE	Returns the number of bytes required to hold an isochronous transfer request.
GET_SELECT_CONFIGURATION_REQUEST_SIZE	Returns the number of bytes required to create a select-configuration URB.
GET_SELECT_INTERFACE_REQUEST_SIZE	Returns the number of bytes required to create a select-interface URB.
GET_USBD_INTERFACE_SIZE	Returns the number of bytes required to hold a USBD_INTERFACE_INFORMATION interface descriptor with its associated endpoint descriptors.
UsbBuildFeatureRequest	Formats an URB with the parameters necessary to request that a feature be turned on or off on a USB device.
UsbBuildGetDescriptorRequest	Formats an URB with the parameters necessary to obtain descriptor information from the host controller driver (HCD).
UsbBuildGetStatusRequest	Formats an URB to obtain status from a device, interface, endpoint, or other device-defined target on a USB device.
UsbBuildInterruptOrBulkTransferRequest	Formats an URB to send or receive data on a bulk pipe, or to receive data from an interrupt pipe.
UsbBuildOpenStaticStreamsRequest	Formats an URB structure to open streams in a specific bulk endpoint.
UsbBuildOsFeatureDescriptorRequest	Formats an URB to request a Microsoft OS feature descriptor.
UsbBuildSelectConfigurationRequest	Formats an URB with the parameters necessary to select a configuration on a USB device.
UsbBuildSelectInterfaceRequest	Formats an URB with the parameters necessary to select an alternate setting for an interface on a USB device.
UsbBuildVendorRequest	Formats an URB to send a vendor or class-specific command to a USB device, interface, endpoint, or other device-defined target.
USBD_CreateConfigurationRequestEx	Allocates and formats an URB to select a configuration for a USB device.
USBD_GetInterfaceLength	Obtains the length of a given interface descriptor, including the length of all endpoint descriptors contained within the interface.
USBD_GetPdoRegistryParameter	Retrieves the value from the specified key in the USB device's hardware registry.
USBD_ParseConfigurationDescriptorEx	Searches a given configuration descriptor and returns a pointer to an interface that matches the given search criteria.
USBD_ParseDescriptors	Searches a given configuration descriptor and returns a pointer to the first descriptor that matches the search criteria.
USBD_ValidateConfigurationDescriptor	Validates all descriptors returned by a device in its response to a configuration descriptor request.

Bus Driver Interface Routines for USB Client Drivers

In Windows XP, Windows Vista, and Windows 7, instead of linking directly to Usbd.sys, a USB client driver can query the USB bus driver for an interface. The client driver can then call the following routines associated with the bus driver interface.

Version 0 of the bus interface contains the following routines:

Routine	Description
InterfaceDereference	Decrements the number of references to the interface.
InterfaceReference	Increments the reference count to the interface.
GetUSBDIVersion	Gets the USB interface version number and the version number of the USB specification that defines the interface, along with information about host controller capabilities.
QueryBusInformation	Gets information about the bus.
QueryBusTime	Gets the current 32-bit USB frame number.
SubmitIsoOutUrb	Not implemented.

Version 1 of the bus interface contains all of the version 0 routines and the following routine:

Routine	Description
IsDeviceHighSpeed	Returns TRUE if the device is operating at high speed.

Version 2 of the bus interface contains all of the version 1 routines and the following routines:

Routine	Description
EnumLogEntry	Not supported. Do not use.

Version 3 of the bus interface contains all of the version 2 routines and the following routines:

Routine	Description
QueryBusTimeEx	This routine is not implemented.
QueryControllerType	Gets information about the USB host controller to which the USB device is attached.

Generic Parent Driver Routines

In Windows Vista, the USB Generic Parent Driver (Usbccgp.sys) can query vendor-supplied filter drivers for an interface. Vendor-supplied filter drivers can provide the USBC_DEVICE_CONFIGURATION_INTERFACE_V1 structure to assist the generic parent driver in defining interface collections. The members of this structure point to several callback routines that are implemented by the filter driver. These implementations are used by the generic parent driver while enumerating the interface collections. Version 0 of the generic parent interface calls the following routines:

Routine	Description
InterfaceDereference	Decrements the number of references to the interface.
InterfaceReference	Increments the reference count to the interface.
USBC_START_DEVICE_CALLBACK	Allows a USB client driver to provide a custom definition of the interface collections on a device.

For information about the callback routine mechanism, see Customizing Enumeration of Interface Collections for Composite Devices.

WinUSB Functions

This section describes the following functions, exposed by Winusb.dll, which user-mode client drivers and applications can use to communicate with USB devices.

Note WinUSB functions require Windows XP or later. You can use these functions in your C/C++ application to communicate with your USB device. Microsoft does not provide a managed API for WinUSB.

Routine	Description
WinUsb_AbortPipe	Aborts all of the pending transfers for a pipe.
WinUsb_ControlTransfer	Transmits control data over a default control endpoint.
WinUsb_FlushPipe	Discards any data that is cached in a pipe.
WinUsb_Free	Releases all of the resources that WinUsb_Initialize allocated.
WinUsb_GetAdjustedFrameNumber	Computes what the current USB frame number should be based on the frame number value and timestamp.
WinUsb_GetAssociatedInterface	Retrieves a handle for an associated interface.
WinUsb_GetCurrentAlternateSetting	Gets the current alternate interface setting for an interface.
WinUsb_GetCurrentFrameNumber	Gets the current frame number for the bus.
WinUsb_GetDescriptor	Gets the requested descriptor.
WinUsb_GetOverlappedResult	Retrieves the results of an overlapped operation on the specified file.
WinUsb_GetPipePolicy	Gets the policy for a specific pipe (endpoint).
WinUsb_GetPowerPolicy	Gets the power policy for a device.
WinUsb_Initialize	Creates a WinUSB handle for the device specified by a file handle.
WinUsb_QueryDeviceInformation	Retrieves information about the physical device that is associated with a WinUSB handle.
WinUsb_QueryInterfaceSettings	Retrieves the interface descriptor for the specified alternate interface settings for a particular interface handle.
WinUsb_QueryPipe	Retrieves information about a pipe that is associated with an interface.
WinUsb_ReadIsochPipeAsap	Reads data from an isochronous OUT endpoint.
WinUsb_ReadPipe	Reads data from the specified pipe.
WinUsb_RegisterIsochBuffer	Registers a buffer to be used for isochronous transfers.
WinUsb_ResetPipe	Resets the data toggle and clears the stall condition on a pipe.
WinUsb_ReadIsochPipe	Reads data from an isochronous OUT endpoint.
WinUsb_SetCurrentAlternateSetting	Sets the alternate setting of an interface.
WinUsb_SetPipePolicy	Sets the policy for a specific pipe (endpoint).
WinUsb_SetPowerPolicy	Sets the power policy for a device.
WinUsb_UnregisterIsochBuffer	Releases all of the resources that previously allocated. This is a synchronous operation.
WinUsb_WriteIsochPipeAsap	Writes the contents of a buffer to an isochronous OUT endpoint.
WinUsb_WriteIsochPipe	Writes the contents of a caller-supplied buffer to an isochronous OUT endpoint, starting on a specified frame number.
WinUsb_WritePipe	Writes data to a pipe.

USB Device Redirection Routines

USB Device Redirection is controlled by the Redirection Policy Manager (RPM). RPM is a kernel-mode export driver that is available in Windows 7. By using RPM, third-party developers can load an alternate driver in place of the original USB device driver. RPM abstracts the redirection functionality provided by Microsoft. One of the clients for RPM is a Windows Virtual PC, a client virtualization solution for Windows 7.

For more information, see USB Device Redirection.

Routine	Description
RPMGetAvailableDevices	Returns a list of the attached USB devices (except hubs and HIDs).
RPMLoadAlternateDriverForDevice	Loads the client-specified alternate driver for a device that is connected on a particular hub and connection index.
RPMRegisterAlternateDriver	Enables a client application to register itself in order to perform driver redirection operations for a USB device.
RPMUnloadAlternateDriverForDevice	Unloads the client-specified registered driver for a device that is connected on a particular hub and connection index.
RPMUnregisterAlternateDriver	Allows a previously registered client to unregister itself.

Deprecated Routines

The following routines have been deprecated. Do not use.