USB device driver macros

The following table contains macros for drivers for USB peripheral devices.

MacroDeclared inDescription
GET_ISO_URB_SIZE

usbdlib.h

The GET_ISO_URB_SIZE macro returns the number of bytes required to hold an isochronous transfer request.

NumberOfPackets [in]

ULONG

Specifies the number of isochronous transfer packets that will be part of the transfer request.

Return value

ULONG

GET_ISO_URB_SIZE returns the number of bytes required to hold an isochronous request with the given NumberOfPackets.

GET_SELECT_CONFIGURATION_REQUEST_SIZE

usbdlib.h

The GET_SELECT_CONFIGURATION_REQUEST_SIZE macro returns the number of bytes required to create a select-configuration URB.

TotalInterfaces [in]

ULONG

Specifies how many interfaces the configuration has.

TotalPipes [in]

ULONG

Specifies how many endpoints (pipes) the configuration has.

Return value

ULONG

GET_SELECT_CONFIGURATION_REQUEST_SIZE returns the number of bytes required to hold a select-configuration request with the given number of pipes and interfaces.

GET_SELECT_INTERFACE_REQUEST_SIZE

usbdlib.h

The GET_SELECT_INTERFACE_REQUEST_SIZE macro returns the number of bytes required to create a select-interface URB.

TotalPipes [in]

ULONG

Specifies the total number of endpoints (pipes) the interface has.

Return value

ULONG

GET_SELECT_INTERFACE_REQUEST_SIZE returns the number of bytes required to hold an URB to select a new setting for an interface with the given number of pipes.

GET_USBD_INTERFACE_SIZE

usbdlib.h

The GET_USBD_INTERFACE_SIZE macro returns the number of bytes required to hold a USBD_INTERFACE_INFORMATION interface descriptor with its associated endpoint descriptors.

TotalEndpoints [in]

ULONG

Specifies the total number of endpoints (pipes) the interface has.

Return value

ULONG

GET_USBD_INTERFACE_SIZE returns the number of bytes required to hold a USBD_INTERFACE_INFORMATION structure describing the interface and a USBD_PIPE_INFORMATION structure for each endpoint in the interface.

UsbBuildFeatureRequest

usbdlib.h

The UsbBuildFeatureRequest macro formats an URB with the parameters necessary to request that a feature be turned on or off on a USB device.

Urb [in, out]

PURB

Pointer to an URB to be formatted as a feature request to a device.

Op [in]

USHORT

Specifies one of the following operation codes:

URB_FUNCTION_SET_FEATURE_TO_DEVICE

Sets a USB-defined feature, specified by FeatureSelector, on a device.

URB_FUNCTION_SET_FEATURE_TO_INTERFACE

Sets a USB-defined feature, specified by FeatureSelector, on an interface for a device.

URB_FUNCTION_SET_FEATURE_TO_ENDPOINT

Sets a USB-defined feature, specified by FeatureSelector, on an endpoint for an interface on a USB device.

URB_FUNCTION_SET_FEATURE_TO_OTHER

Sets a USB-defined feature, specified by FeatureSelector, on a device-defined target on a USB device.

URB_FUNCTION_CLEAR_FEATURE_TO_DEVICE

Clears a USB-defined feature, specified by FeatureSelector, on a device.

URB_FUNCTION_CLEAR_FEATURE_TO_INTERFACE

Clears a USB-defined feature, specified by FeatureSelector, on an interface for a device.

URB_FUNCTION_CLEAR_FEATURE_TO_ENDPOINT

Clears a USB-defined feature, specified by FeatureSelector, on an endpoint, for an interface, on a USB device.

URB_FUNCTION_CLEAR_FEATURE_TO_OTHER

Clears a USB-defined feature, specified by FeatureSelector, on a device-defined target on a USB device.

FeatureSelector [in]

USHORT

Specifies the USB-defined feature code that should be set or cleared on the target as specified by Op.

Index [in]

USHORT

For a feature request for an endpoint or interface, specifies the index of the endpoint or interface within the configuration descriptor. For the device, this must be zero.

Link [in]

PURB

Reserved. Must be set to NULL.

Return value

void

This macro does not return a value.

UsbBuildGetDescriptorRequest

usbdlib.h

The UsbBuildGetDescriptorRequest macro formats an URB with the parameters necessary to obtain descriptor information from the host controller driver (HCD).

Urb [in, out]

PURB

Pointer to an URB to be formatted for a get descriptor request to the HCD. The caller must allocate nonpaged pool for this URB.

Length [in]

USHORT

Specifies the size, in bytes, of the URB.

DescriptorType [in]

UCHAR

Specifies one of the following values:

USB_DEVICE_DESCRIPTOR_TYPE

USB_CONFIGURATION_DESCRIPTOR_TYPE

USB_STRING_DESCRIPTOR_TYPE

Index [in]

UCHAR

Specifies the device-defined index of the descriptor that is to be retrieved.

LanguageId [in]

USHORT

Specifies the language ID of the descriptor to be retrieved when USB_STRING_DESCRIPTOR_TYPE is set in DescriptorType. This parameter must be zero for any other value in DescriptorType.

TransferBuffer [in, optional]

PVOID

Pointer to a resident buffer to receive the descriptor data or is NULL if an MDL is supplied in TransferBufferMDL.

TransferBufferMDL [in, optional]

PMDL

Pointer to an MDL that describes a resident buffer to receive the descriptor data or is NULL if a buffer is supplied in TransferBuffer.

TransferBufferLength [in]

ULONG

Specifies the length of the buffer specified in TransferBuffer or described in TransferBufferMDL.

Link [in]

PURB

Reserved. Must be set to NULL.

Return value

void

This macro does not return a value.

This macro is defined in usblib.h. When USB_CONFIGURATION_DESCRIPTOR_TYPE is specified for DescriptorType, all interface, endpoint, class-specific, and vendor-specific descriptors for the configuration also are retrieved. The caller must allocate a buffer large enough to hold all of this information or the data is truncated without error.

UsbBuildOsFeatureDescriptorRequest

usbdlib.h

The UsbBuildOsFeatureDescriptorRequest macro formats an URB to request a Microsoft OS feature descriptor.

Urb [in, out]

PURB

Pointer to a caller-allocated URB structure to be formatted as a request for a Microsoft OS feature descriptor.

Length [in]

USHORT

Specifies the size, in bytes, of the URB structure.

Interface [in]

UCHAR

Specifies the interface number for the requested Microsoft OS feature descriptor.

Index [in]

USHORT

Specifies the index number of the requested Microsoft OS feature descriptor.

TransferBuffer [in, optional]

PVOID

Pointer to a resident buffer that receives the descriptor data. If an MDL is supplied in TransferBufferMDL, then TransferBuffer is NULL.

TransferBufferMDL [in, optional]

PMDL

Pointer to an MDL that describes a resident buffer that receives the descriptor. If a buffer is supplied in TransferBuffer, then TransferBufferMDL is NULL. The MDL must be allocated from nonpaged pool.

TransferBufferLength [in]

ULONG

Specifies the length, in bytes, of the buffer specified in TransferBuffer or TransferBufferMDL.

Return value

void

This macro does not return a value.

UsbBuildSelectConfigurationRequest

usbdlib.h

The UsbBuildSelectConfigurationRequest macro formats an URB with the parameters necessary to select a configuration on a USB device.

Urb [in]

PURB

Pointer to an URB to be formatted as a select configuration request.

Length [in]

USHORT

Specifies the size, in bytes, of the URB.

ConfigurationDescriptor [in]

PUSB_CONFIGURATION_DESCRIPTOR

Pointer to an initialized USB configuration descriptor that identifies the configuration to be set on the device. If NULL, the device will be set into its unconfigured state.

Return value

void

This macro does not return a value.

UsbBuildSelectInterfaceRequest

usbdlib.h

The UsbBuildSelectInterfaceRequest macro formats an URB with the parameters necessary to select an alternate setting for an interface on a USB device.

Urb [in]

PURB

Pointer to an URB that is to be formatted as a select-interface request.

Length [in]

USHORT

Specifies the size, in bytes, of the URB. The URB_FUNCTION_SELECT_INTERFACE URB has a variable length. Clients can use the GET_SELECT_INTERFACE_REQUEST_SIZE macro to determine the URB length.

ConfigurationHandle [in]

USBD_CONFIGURATION_HANDLE

Specifies the handle for this interface returned by the HCD when a configuration was selected.

InterfaceNumber [in]

UCHAR

Is the device-defined identifier for this interface specified in the descriptor for this interface.

AlternateSetting [in]

UCHAR

Is the device-defined identifier of the alternate setting that this interface should now use.

Return value

void

This macro does not return a value.

UsbBuildVendorRequest

usbdlib.h

The UsbBuildVendorRequest macro formats an URB to send a vendor or class-specific command to a USB device, interface, endpoint, or other device-defined target.

Urb [in]

PURB

Pointer to an URB that is to be formatted as a vendor or class request.

Function [in]

USHORT

Must be set to one of the following values:

URB_FUNCTION_VENDOR_DEVICE

Indicates the URB is a vendor-defined request for a USB device.

URB_FUNCTION_VENDOR_INTERFACE

Indicates the URB is a vendor-defined request for an interface on a USB device.

URB_FUNCTION_VENDOR_ENDPOINT

Indicates the URB is a vendor-defined request for an endpoint, in an interface, on a USB device.

URB_FUNCTION_VENDOR_OTHER

Indicates the URB is a vendor-defined request for a device-defined target.

URB_FUNCTION_CLASS_DEVICE

Indicates the URB is a USB-defined class request for a USB device.

URB_FUNCTION_CLASS_INTERFACE

Indicates the URB is a USB-defined class request for an interface on a USB device.

URB_FUNCTION_CLASS_ENDPOINT

Indicates the URB is a USB-defined class request for an endpoint, in an interface, on a USB device.

URB_FUNCTION_CLASS_OTHER

Indicates the URB is a USB-defined class request for a device-defined target.

Length [in]

USHORT

Specifies the length, in bytes, of the URB.

TransferFlags [in]

ULONG

Specifies zero, one, or a combination of the following flags:

USBD_TRANSFER_DIRECTION_IN

Is set to request data from a device. To transfer data to a device, this flag must be clear.

USBD_SHORT_TRANSFER_OK

Can be used if USBD_TRANSFER_DIRECTION_IN is set. If set, directs the HCD not to return an error if a packet is received from the device that is shorter than the maximum packet size for the endpoint. Otherwise, a short request returns an error condition.

ReservedBits [in]

UCHAR

Specifies a value, from 4 to 31 inclusive, that becomes part of the request type code in the USB-defined setup packet. This value is defined by USB for a class request or the vendor for a vendor request.

Request [in]

UCHAR

Specifies the USB or vendor-defined request code for the device, interface, endpoint, or other device-defined target.

Value [in]

USHORT

Is a value, specific to Request, that becomes part of the USB-defined setup packet for the target. This value is defined by the creator of the code used in Request.

Index [in]

USHORT

Specifies the device-defined identifier if the request is for an endpoint, interface, or device-defined target. Otherwise, Index must be zero.

TransferBuffer [in, optional]

PVOID

Pointer to a resident buffer for the transfer or is NULL if an MDL is supplied in TransferBufferMDL. The contents of this buffer depend on the value of TransferFlags. If USBD_TRANSFER_DIRECTION_IN is specified, this buffer will contain data read from the device on return from the HCD. Otherwise, this buffer contains driver-supplied data to be transferred to the device.

TransferBufferMDL [in, optional]

PMDL

Pointer to an MDL that describes a resident buffer or is NULL if a buffer is supplied in TransferBuffer. The contents of the buffer depend on the value of TransferFlags. If USBD_TRANSFER_DIRECTION_IN is specified, the described buffer will contain data read from the device on return from the HCD. Otherwise, the buffer contains driver-supplied data to be transferred to the device. The MDL must be allocated from nonpaged pool.

TransferBufferLength [in]

ULONG

Specifies the length, in bytes, of the buffer specified in TransferBuffer or described in TransferBufferMDL.

Link [in]

PURB

Reserved. Must be set to NULL.

Return value

void

This macro does not return a value.

 

Related topics

URB
USBD_INTERFACE_INFORMATION
USBD_PIPE_INFORMATION

 

 

Send comments about this topic to Microsoft

Show: