USB device driver programming reference
These programming elements are used by drivers for USB peripheral devices.
- Export functions for USB device drivers
- Callback functions for USB client drivers
- I/O control codes for USB device drivers
- Related topics
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.
|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.
|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.|
Reference information for KMDF and UMDF 2.0 client drivers. Starting in UMDF version 2.0, you can write a UMDF-based client driver in the C programming language that calls most KMDF methods. These methods are not supported in UMDF 2.0:
Reference information for user-mode client drivers that use UMDF interfaces versions 1.11 and earlier. The must be written by using the COM programming model.
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.
|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.|
The following functions have been deprecated. Do not use.
These are the callback routines that a USB client can implement.
In 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:
|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.|
Version 1 of the bus interface contains all of the version 0 routines and the following routine:
|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:
|EnumLogEntry||Not supported. Do not use.|
Version 3 of the bus interface contains all of the version 2 routines and the following routines:
|QueryBusTimeEx||This routine is not implemented.|
|QueryControllerType||Gets information about the USB host controller to which the USB device is attached.|
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:
|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.
Windows Driver Model (WDM) clients of the Universal Serial Bus (USB) driver stack communicate to the USB driver stack, by submitting an IRP with major code IRP_MJ_INTERNAL_DEVICE_CONTROL, and a minor code corresponding to an IOCTL value.
This topic provides a list the IOCTL values that client drivers can use. Kernel-mode I/O requests are for the exclusive use of client drivers. User-mode I/O requests can be used by client drivers and user-mode applications.
USB client drivers can receive or send any of the following I/O requests in kernel mode:
|IOCTL_INTERNAL_USB_CYCLE_PORT||Simulates a device unplug and replug on the port associated with the PDO.|
|IOCTL_INTERNAL_USB_GET_BUS_INFO||Queries the bus driver for certain bus information.|
|IOCTL_INTERNAL_USB_GET_CONTROLLER_NAME||Queries the bus driver for the device name of the USB host controller.|
|IOCTL_INTERNAL_USB_GET_DEVICE_CONFIG_INFO||Gets information about a USB device and the hub it is attached to.|
|IOCTL_INTERNAL_USB_GET_HUB_NAME||Retrieves the Unicode symbolic name for the target PDO if the PDO is for a hub.|
|IOCTL_INTERNAL_USB_GET_PORT_STATUS||Gets the status of the PDO.|
|IOCTL_INTERNAL_USB_GET_TOPOLOGY_ADDRESS||Retrieves information about the host controller the USB device is attached to, and the device's location in the USB device tree.|
|IOCTL_INTERNAL_USB_REGISTER_COMPOSITE_DEVICE||Registers the parent driver of a USB multi-function device (composite driver) with the underlying USB driver stack.|
|IOCTL_INTERNAL_USB_RESET_PORT||Reset the upstream port of the device it manages.|
|IOCTL_INTERNAL_USB_SUBMIT_IDLE_NOTIFICATION||Informs the USB bus driver that a device is idle and can be suspended.|
|IOCTL_INTERNAL_USB_SUBMIT_URB||Submit an URB to the bus driver.|
|IOCTL_INTERNAL_USB_UNREGISTER_COMPOSITE_DEVICE||Unregisters the parent driver of a USB multi-function device (composite driver) and releases all resources associated with registration.|
|IOCTL_INTERNAL_USB_REQUEST_REMOTE_WAKE_NOTIFICATION||Sent by the parent driver of a USB multi-function device (composite driver) to request remote wake-up notifications from a specific function in the device.|
The following I/O requests have been deprecated or reserved for internal use. USB client drivers must not use these I/O requests: