USB descriptors

Classes
struct	libusb_device_descriptor
struct	libusb_endpoint_descriptor
struct	libusb_interface_descriptor
struct	libusb_interface
struct	libusb_config_descriptor
struct	libusb_ss_endpoint_companion_descriptor
struct	libusb_bos_dev_capability_descriptor
struct	libusb_bos_descriptor
struct	libusb_usb_2_0_extension_descriptor
struct	libusb_ss_usb_device_capability_descriptor
struct	libusb_container_id_descriptor

Enumerations
enum	libusb_class_code {   LIBUSB_CLASS_PER_INTERFACE = 0x00, LIBUSB_CLASS_AUDIO = 0x01, LIBUSB_CLASS_COMM = 0x02, LIBUSB_CLASS_HID = 0x03,   LIBUSB_CLASS_PHYSICAL = 0x05, LIBUSB_CLASS_IMAGE = 0x06, LIBUSB_CLASS_PTP = 0x06, LIBUSB_CLASS_PRINTER = 0x07,   LIBUSB_CLASS_MASS_STORAGE = 0x08, LIBUSB_CLASS_HUB = 0x09, LIBUSB_CLASS_DATA = 0x0a, LIBUSB_CLASS_SMART_CARD = 0x0b,   LIBUSB_CLASS_CONTENT_SECURITY = 0x0d, LIBUSB_CLASS_VIDEO = 0x0e, LIBUSB_CLASS_PERSONAL_HEALTHCARE = 0x0f, LIBUSB_CLASS_DIAGNOSTIC_DEVICE = 0xdc,   LIBUSB_CLASS_WIRELESS = 0xe0, LIBUSB_CLASS_APPLICATION = 0xfe, LIBUSB_CLASS_VENDOR_SPEC = 0xff }
enum	libusb_descriptor_type {   LIBUSB_DT_DEVICE = 0x01, LIBUSB_DT_CONFIG = 0x02, LIBUSB_DT_STRING = 0x03, LIBUSB_DT_INTERFACE = 0x04,   LIBUSB_DT_ENDPOINT = 0x05, LIBUSB_DT_BOS = 0x0f, LIBUSB_DT_DEVICE_CAPABILITY = 0x10, LIBUSB_DT_HID = 0x21,   LIBUSB_DT_REPORT = 0x22, LIBUSB_DT_PHYSICAL = 0x23, LIBUSB_DT_HUB = 0x29, LIBUSB_DT_SUPERSPEED_HUB = 0x2a,   LIBUSB_DT_SS_ENDPOINT_COMPANION = 0x30 }
enum	libusb_endpoint_direction { LIBUSB_ENDPOINT_OUT = 0x00, LIBUSB_ENDPOINT_IN = 0x80 }
enum	libusb_endpoint_transfer_type { LIBUSB_ENDPOINT_TRANSFER_TYPE_CONTROL = 0x0, LIBUSB_ENDPOINT_TRANSFER_TYPE_ISOCHRONOUS = 0x1, LIBUSB_ENDPOINT_TRANSFER_TYPE_BULK = 0x2, LIBUSB_ENDPOINT_TRANSFER_TYPE_INTERRUPT = 0x3 }
enum	libusb_iso_sync_type { LIBUSB_ISO_SYNC_TYPE_NONE = 0x0, LIBUSB_ISO_SYNC_TYPE_ASYNC = 0x1, LIBUSB_ISO_SYNC_TYPE_ADAPTIVE = 0x2, LIBUSB_ISO_SYNC_TYPE_SYNC = 0x3 }
enum	libusb_iso_usage_type { LIBUSB_ISO_USAGE_TYPE_DATA = 0x0, LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 0x1, LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 0x2 }
enum	libusb_supported_speed { LIBUSB_LOW_SPEED_OPERATION = (1 << 0), LIBUSB_FULL_SPEED_OPERATION = (1 << 1), LIBUSB_HIGH_SPEED_OPERATION = (1 << 2), LIBUSB_SUPER_SPEED_OPERATION = (1 << 3) }
enum	libusb_usb_2_0_extension_attributes { LIBUSB_BM_LPM_SUPPORT = (1 << 1) }
enum	libusb_ss_usb_device_capability_attributes { LIBUSB_BM_LTM_SUPPORT = (1 << 1) }
enum	libusb_bos_type { LIBUSB_BT_WIRELESS_USB_DEVICE_CAPABILITY = 0x01, LIBUSB_BT_USB_2_0_EXTENSION = 0x02, LIBUSB_BT_SS_USB_DEVICE_CAPABILITY = 0x03, LIBUSB_BT_CONTAINER_ID = 0x04 }

Functions
int API_EXPORTED	libusb_get_device_descriptor (libusb_device *dev, struct libusb_device_descriptor *desc)
int API_EXPORTED	libusb_get_active_config_descriptor (libusb_device *dev, struct libusb_config_descriptor **config)
int API_EXPORTED	libusb_get_config_descriptor (libusb_device *dev, uint8_t config_index, struct libusb_config_descriptor **config)
int API_EXPORTED	libusb_get_config_descriptor_by_value (libusb_device *dev, uint8_t bConfigurationValue, struct libusb_config_descriptor **config)
void API_EXPORTED	libusb_free_config_descriptor (struct libusb_config_descriptor *config)
int API_EXPORTED	libusb_get_ss_endpoint_companion_descriptor (libusb_context *ctx, const struct libusb_endpoint_descriptor *endpoint, struct libusb_ss_endpoint_companion_descriptor **ep_comp)
void API_EXPORTED	libusb_free_ss_endpoint_companion_descriptor (struct libusb_ss_endpoint_companion_descriptor *ep_comp)
int API_EXPORTED	libusb_get_bos_descriptor (libusb_device_handle *dev_handle, struct libusb_bos_descriptor **bos)
void API_EXPORTED	libusb_free_bos_descriptor (struct libusb_bos_descriptor *bos)
int API_EXPORTED	libusb_get_usb_2_0_extension_descriptor (libusb_context *ctx, struct libusb_bos_dev_capability_descriptor *dev_cap, struct libusb_usb_2_0_extension_descriptor **usb_2_0_extension)
void API_EXPORTED	libusb_free_usb_2_0_extension_descriptor (struct libusb_usb_2_0_extension_descriptor *usb_2_0_extension)
int API_EXPORTED	libusb_get_ss_usb_device_capability_descriptor (libusb_context *ctx, struct libusb_bos_dev_capability_descriptor *dev_cap, struct libusb_ss_usb_device_capability_descriptor **ss_usb_device_cap)
void API_EXPORTED	libusb_free_ss_usb_device_capability_descriptor (struct libusb_ss_usb_device_capability_descriptor *ss_usb_device_cap)
int API_EXPORTED	libusb_get_container_id_descriptor (libusb_context *ctx, struct libusb_bos_dev_capability_descriptor *dev_cap, struct libusb_container_id_descriptor **container_id)
void API_EXPORTED	libusb_free_container_id_descriptor (struct libusb_container_id_descriptor *container_id)
int API_EXPORTED	libusb_get_string_descriptor_ascii (libusb_device_handle *dev_handle, uint8_t desc_index, unsigned char *data, int length)

Detailed Description

This page details how to examine the various standard USB descriptors for detected devices

Enumeration Type Documentation

libusb_bos_type

enum libusb_bos_type

USB capability types

Enumerator
LIBUSB_BT_WIRELESS_USB_DEVICE_CAPABILITY	Wireless USB device capability
LIBUSB_BT_USB_2_0_EXTENSION	USB 2.0 extensions
LIBUSB_BT_SS_USB_DEVICE_CAPABILITY	SuperSpeed USB device capability
LIBUSB_BT_CONTAINER_ID	Container ID type

libusb_class_code

enum libusb_class_code

Device and/or Interface Class codes

Enumerator
LIBUSB_CLASS_PER_INTERFACE	In the context of a device descriptor, this bDeviceClass value indicates that each interface specifies its own class information and all interfaces operate independently.
LIBUSB_CLASS_AUDIO	Audio class
LIBUSB_CLASS_COMM	Communications class
LIBUSB_CLASS_HID	Human Interface Device class
LIBUSB_CLASS_PHYSICAL	Physical
LIBUSB_CLASS_IMAGE	Image class
LIBUSB_CLASS_PRINTER	Printer class
LIBUSB_CLASS_MASS_STORAGE	Mass storage class
LIBUSB_CLASS_HUB	Hub class
LIBUSB_CLASS_DATA	Data class
LIBUSB_CLASS_SMART_CARD	Smart Card
LIBUSB_CLASS_CONTENT_SECURITY	Content Security
LIBUSB_CLASS_VIDEO	Video
LIBUSB_CLASS_PERSONAL_HEALTHCARE	Personal Healthcare
LIBUSB_CLASS_DIAGNOSTIC_DEVICE	Diagnostic Device
LIBUSB_CLASS_WIRELESS	Wireless class
LIBUSB_CLASS_APPLICATION	Application class
LIBUSB_CLASS_VENDOR_SPEC	Class is vendor-specific

libusb_descriptor_type

enum libusb_descriptor_type

Descriptor types as defined by the USB specification.

Enumerator
LIBUSB_DT_DEVICE	Device descriptor. See libusb_device_descriptor.
LIBUSB_DT_CONFIG	Configuration descriptor. See libusb_config_descriptor.
LIBUSB_DT_STRING	String descriptor
LIBUSB_DT_INTERFACE	Interface descriptor. See libusb_interface_descriptor.
LIBUSB_DT_ENDPOINT	Endpoint descriptor. See libusb_endpoint_descriptor.
LIBUSB_DT_BOS	BOS descriptor
LIBUSB_DT_DEVICE_CAPABILITY	Device Capability descriptor
LIBUSB_DT_HID	HID descriptor
LIBUSB_DT_REPORT	HID report descriptor
LIBUSB_DT_PHYSICAL	Physical descriptor
LIBUSB_DT_HUB	Hub descriptor
LIBUSB_DT_SUPERSPEED_HUB	SuperSpeed Hub descriptor
LIBUSB_DT_SS_ENDPOINT_COMPANION	SuperSpeed Endpoint Companion descriptor

libusb_endpoint_direction

enum libusb_endpoint_direction

Endpoint direction. Values for bit 7 of the endpoint address scheme.

Enumerator
LIBUSB_ENDPOINT_OUT	Out: host-to-device
LIBUSB_ENDPOINT_IN	In: device-to-host

libusb_endpoint_transfer_type

enum libusb_endpoint_transfer_type

Endpoint transfer type. Values for bits 0:1 of the endpoint attributes field.

Enumerator
LIBUSB_ENDPOINT_TRANSFER_TYPE_CONTROL	Control endpoint
LIBUSB_ENDPOINT_TRANSFER_TYPE_ISOCHRONOUS	Isochronous endpoint
LIBUSB_ENDPOINT_TRANSFER_TYPE_BULK	Bulk endpoint
LIBUSB_ENDPOINT_TRANSFER_TYPE_INTERRUPT	Interrupt endpoint

libusb_iso_sync_type

enum libusb_iso_sync_type

Synchronization type for isochronous endpoints. Values for bits 2:3 of the bmAttributes field in libusb_endpoint_descriptor.

Enumerator
LIBUSB_ISO_SYNC_TYPE_NONE	No synchronization
LIBUSB_ISO_SYNC_TYPE_ASYNC	Asynchronous
LIBUSB_ISO_SYNC_TYPE_ADAPTIVE	Adaptive
LIBUSB_ISO_SYNC_TYPE_SYNC	Synchronous

libusb_iso_usage_type

enum libusb_iso_usage_type

Usage type for isochronous endpoints. Values for bits 4:5 of the bmAttributes field in libusb_endpoint_descriptor.

Enumerator
LIBUSB_ISO_USAGE_TYPE_DATA	Data endpoint
LIBUSB_ISO_USAGE_TYPE_FEEDBACK	Feedback endpoint
LIBUSB_ISO_USAGE_TYPE_IMPLICIT	Implicit feedback Data endpoint

libusb_ss_usb_device_capability_attributes

enum libusb_ss_usb_device_capability_attributes

Masks for the bits of the bmAttributes field field of the SuperSpeed USB Device Capability descriptor.

Enumerator
LIBUSB_BM_LTM_SUPPORT	Supports Latency Tolerance Messages (LTM)

libusb_supported_speed

enum libusb_supported_speed

Supported speeds (wSpeedSupported) bitfield. Indicates what speeds the device supports.

Enumerator
LIBUSB_LOW_SPEED_OPERATION	Low speed operation supported (1.5MBit/s).
LIBUSB_FULL_SPEED_OPERATION	Full speed operation supported (12MBit/s).
LIBUSB_HIGH_SPEED_OPERATION	High speed operation supported (480MBit/s).
LIBUSB_SUPER_SPEED_OPERATION	Superspeed operation supported (5000MBit/s).

libusb_usb_2_0_extension_attributes

enum libusb_usb_2_0_extension_attributes

Masks for the bits of the bmAttributes field of the USB 2.0 Extension descriptor.

Enumerator
LIBUSB_BM_LPM_SUPPORT	Supports Link Power Management (LPM)

Function Documentation

libusb_free_bos_descriptor()

void API_EXPORTED libusb_free_bos_descriptor

(

struct libusb_bos_descriptor *

bos

)

Free a BOS descriptor obtained from libusb_get_bos_descriptor(). It is safe to call this function with a NULL bos parameter, in which case the function simply returns.

Parameters

bos	the BOS descriptor to free

libusb_free_config_descriptor()

void API_EXPORTED libusb_free_config_descriptor

(

struct libusb_config_descriptor *

config

)

Free a configuration descriptor obtained from libusb_get_active_config_descriptor() or libusb_get_config_descriptor(). It is safe to call this function with a NULL config parameter, in which case the function simply returns.

Parameters

config

the configuration descriptor to free

libusb_free_container_id_descriptor()

void API_EXPORTED libusb_free_container_id_descriptor

(

struct libusb_container_id_descriptor *

container_id

)

Free a Container ID descriptor obtained from libusb_get_container_id_descriptor(). It is safe to call this function with a NULL container_id parameter, in which case the function simply returns.

Parameters

container_id

the Container ID descriptor to free

libusb_free_ss_endpoint_companion_descriptor()

void API_EXPORTED libusb_free_ss_endpoint_companion_descriptor

(

struct libusb_ss_endpoint_companion_descriptor *

ep_comp

)

Free a superspeed endpoint companion descriptor obtained from libusb_get_ss_endpoint_companion_descriptor(). It is safe to call this function with a NULL ep_comp parameter, in which case the function simply returns.

Parameters

ep_comp

the superspeed endpoint companion descriptor to free

libusb_free_ss_usb_device_capability_descriptor()

void API_EXPORTED libusb_free_ss_usb_device_capability_descriptor

(

struct libusb_ss_usb_device_capability_descriptor *

ss_usb_device_cap

)

Free a SuperSpeed USB Device Capability descriptor obtained from libusb_get_ss_usb_device_capability_descriptor(). It is safe to call this function with a NULL ss_usb_device_cap parameter, in which case the function simply returns.

Parameters

ss_usb_device_cap

the SuperSpeed USB Device Capability descriptor to free

libusb_free_usb_2_0_extension_descriptor()

void API_EXPORTED libusb_free_usb_2_0_extension_descriptor

(

struct libusb_usb_2_0_extension_descriptor *

usb_2_0_extension

)

Free a USB 2.0 Extension descriptor obtained from libusb_get_usb_2_0_extension_descriptor(). It is safe to call this function with a NULL usb_2_0_extension parameter, in which case the function simply returns.

Parameters

usb_2_0_extension

the USB 2.0 Extension descriptor to free

libusb_get_active_config_descriptor()

int API_EXPORTED libusb_get_active_config_descriptor	(	libusb_device *	dev,
		struct libusb_config_descriptor **	config
	)

Get the USB configuration descriptor for the currently active configuration. This is a non-blocking function which does not involve any requests being sent to the device.

Parameters

dev	a device
config	output location for the USB configuration descriptor. Only valid if 0 was returned. Must be freed with libusb_free_config_descriptor() after use.

Returns

0 on success

LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state

another LIBUSB_ERROR code on error

See also

libusb_get_config_descriptor

libusb_get_bos_descriptor()

int API_EXPORTED libusb_get_bos_descriptor	(	libusb_device_handle *	dev_handle,
		struct libusb_bos_descriptor **	bos
	)

Get a Binary Object Store (BOS) descriptor This is a BLOCKING function, which will send requests to the device.

Parameters

dev_handle	the handle of an open libusb device
bos	output location for the BOS descriptor. Only valid if 0 was returned. Must be freed with libusb_free_bos_descriptor() after use.

Returns

0 on success

LIBUSB_ERROR_NOT_FOUND if the device doesn't have a BOS descriptor

another LIBUSB_ERROR code on error

libusb_get_config_descriptor()

int API_EXPORTED libusb_get_config_descriptor	(	libusb_device *	dev,
		uint8_t	config_index,
		struct libusb_config_descriptor **	config
	)

Get a USB configuration descriptor based on its index. This is a non-blocking function which does not involve any requests being sent to the device.

Parameters

dev	a device
config_index	the index of the configuration you wish to retrieve
config	output location for the USB configuration descriptor. Only valid if 0 was returned. Must be freed with libusb_free_config_descriptor() after use.

Returns

0 on success

LIBUSB_ERROR_NOT_FOUND if the configuration does not exist

another LIBUSB_ERROR code on error

See also

libusb_get_active_config_descriptor()

libusb_get_config_descriptor_by_value()

libusb_get_config_descriptor_by_value()

int API_EXPORTED libusb_get_config_descriptor_by_value	(	libusb_device *	dev,
		uint8_t	bConfigurationValue,
		struct libusb_config_descriptor **	config
	)

Get a USB configuration descriptor with a specific bConfigurationValue. This is a non-blocking function which does not involve any requests being sent to the device.

Parameters

dev	a device
bConfigurationValue	the bConfigurationValue of the configuration you wish to retrieve
config	output location for the USB configuration descriptor. Only valid if 0 was returned. Must be freed with libusb_free_config_descriptor() after use.

Returns

0 on success

LIBUSB_ERROR_NOT_FOUND if the configuration does not exist

another LIBUSB_ERROR code on error

See also

libusb_get_active_config_descriptor()

libusb_get_config_descriptor()

libusb_get_container_id_descriptor()

int API_EXPORTED libusb_get_container_id_descriptor	(	libusb_context *	ctx,
		struct libusb_bos_dev_capability_descriptor *	dev_cap,
		struct libusb_container_id_descriptor **	container_id
	)

Get a Container ID descriptor

Parameters

ctx	the context to operate on, or NULL for the default context
dev_cap	Device Capability descriptor with a bDevCapabilityType of libusb_capability_type::LIBUSB_BT_CONTAINER_ID LIBUSB_BT_CONTAINER_ID
container_id	output location for the Container ID descriptor. Only valid if 0 was returned. Must be freed with libusb_free_container_id_descriptor() after use.

Returns

0 on success

a LIBUSB_ERROR code on error

libusb_get_device_descriptor()

int API_EXPORTED libusb_get_device_descriptor	(	libusb_device *	dev,
		struct libusb_device_descriptor *	desc
	)

Get the USB device descriptor for a given device.

This is a non-blocking function; the device descriptor is cached in memory.

Note since libusb-1.0.16, LIBUSB_API_VERSION >= 0x01000102, this function always succeeds.

Parameters

dev	the device
desc	output location for the descriptor data

Returns

0 on success or a LIBUSB_ERROR code on failure

libusb_get_ss_endpoint_companion_descriptor()

int API_EXPORTED libusb_get_ss_endpoint_companion_descriptor	(	libusb_context *	ctx,
		const struct libusb_endpoint_descriptor *	endpoint,
		struct libusb_ss_endpoint_companion_descriptor **	ep_comp
	)

Get an endpoints superspeed endpoint companion descriptor (if any)

Parameters

ctx	the context to operate on, or NULL for the default context
endpoint	endpoint descriptor from which to get the superspeed endpoint companion descriptor
ep_comp	output location for the superspeed endpoint companion descriptor. Only valid if 0 was returned. Must be freed with libusb_free_ss_endpoint_companion_descriptor() after use.

Returns

0 on success

LIBUSB_ERROR_NOT_FOUND if the configuration does not exist

another LIBUSB_ERROR code on error

libusb_get_ss_usb_device_capability_descriptor()

int API_EXPORTED libusb_get_ss_usb_device_capability_descriptor	(	libusb_context *	ctx,
		struct libusb_bos_dev_capability_descriptor *	dev_cap,
		struct libusb_ss_usb_device_capability_descriptor **	ss_usb_device_cap
	)

Get a SuperSpeed USB Device Capability descriptor

Parameters

ctx	the context to operate on, or NULL for the default context
dev_cap	Device Capability descriptor with a bDevCapabilityType of libusb_capability_type::LIBUSB_BT_SS_USB_DEVICE_CAPABILITY LIBUSB_BT_SS_USB_DEVICE_CAPABILITY
ss_usb_device_cap	output location for the SuperSpeed USB Device Capability descriptor. Only valid if 0 was returned. Must be freed with libusb_free_ss_usb_device_capability_descriptor() after use.

Returns

0 on success

a LIBUSB_ERROR code on error

libusb_get_string_descriptor_ascii()

int API_EXPORTED libusb_get_string_descriptor_ascii	(	libusb_device_handle *	dev_handle,
		uint8_t	desc_index,
		unsigned char *	data,
		int	length
	)

Retrieve a string descriptor in C style ASCII.

Wrapper around libusb_get_string_descriptor(). Uses the first language supported by the device.

Parameters

dev_handle	a device handle
desc_index	the index of the descriptor to retrieve
data	output buffer for ASCII string descriptor
length	size of data buffer

Returns

number of bytes returned in data, or LIBUSB_ERROR code on failure

libusb_get_usb_2_0_extension_descriptor()

int API_EXPORTED libusb_get_usb_2_0_extension_descriptor	(	libusb_context *	ctx,
		struct libusb_bos_dev_capability_descriptor *	dev_cap,
		struct libusb_usb_2_0_extension_descriptor **	usb_2_0_extension
	)

Get an USB 2.0 Extension descriptor

Parameters

ctx	the context to operate on, or NULL for the default context
dev_cap	Device Capability descriptor with a bDevCapabilityType of libusb_capability_type::LIBUSB_BT_USB_2_0_EXTENSION LIBUSB_BT_USB_2_0_EXTENSION
usb_2_0_extension	output location for the USB 2.0 Extension descriptor. Only valid if 0 was returned. Must be freed with libusb_free_usb_2_0_extension_descriptor() after use.

Returns

0 on success

a LIBUSB_ERROR code on error