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

Data Structures
struct	libusb_device_descriptor
	A structure representing the standard USB device descriptor. More...
struct	libusb_endpoint_descriptor
	A structure representing the standard USB endpoint descriptor. More...
struct	libusb_interface_descriptor
	A structure representing the standard USB interface descriptor. More...
struct	libusb_interface
	A collection of alternate settings for a particular USB interface. More...
struct	libusb_config_descriptor
	A structure representing the standard USB configuration descriptor. More...
struct	libusb_ss_endpoint_companion_descriptor
	A structure representing the superspeed endpoint companion descriptor. More...
struct	libusb_bos_dev_capability_descriptor
	A generic representation of a BOS Device Capability descriptor. More...
struct	libusb_bos_descriptor
	A structure representing the Binary Device Object Store (BOS) descriptor. More...
struct	libusb_usb_2_0_extension_descriptor
	A structure representing the USB 2.0 Extension descriptor This descriptor is documented in section 9.6.2.1 of the USB 3.0 specification. More...
struct	libusb_ss_usb_device_capability_descriptor
	A structure representing the SuperSpeed USB Device Capability descriptor This descriptor is documented in section 9.6.2.2 of the USB 3.0 specification. More...
struct	libusb_container_id_descriptor
	A structure representing the Container ID descriptor. More...

Enumerations
enum	libusb_class_code { LIBUSB_CLASS_PER_INTERFACE = 0, LIBUSB_CLASS_AUDIO = 1, LIBUSB_CLASS_COMM = 2, LIBUSB_CLASS_HID = 3, LIBUSB_CLASS_PHYSICAL = 5, LIBUSB_CLASS_PRINTER = 7, LIBUSB_CLASS_PTP = 6, LIBUSB_CLASS_IMAGE = 6, LIBUSB_CLASS_MASS_STORAGE = 8, LIBUSB_CLASS_HUB = 9, LIBUSB_CLASS_DATA = 10, 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 }
	Device and/or Interface Class codes. More...
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 }
	Descriptor types as defined by the USB specification. More...
enum	libusb_endpoint_direction { LIBUSB_ENDPOINT_IN = 0x80, LIBUSB_ENDPOINT_OUT = 0x00 }
	Endpoint direction. More...
enum	libusb_transfer_type { LIBUSB_TRANSFER_TYPE_CONTROL = 0, LIBUSB_TRANSFER_TYPE_ISOCHRONOUS = 1, LIBUSB_TRANSFER_TYPE_BULK = 2, LIBUSB_TRANSFER_TYPE_INTERRUPT = 3 }
	Endpoint transfer type. More...
enum	libusb_iso_sync_type { LIBUSB_ISO_SYNC_TYPE_NONE = 0, LIBUSB_ISO_SYNC_TYPE_ASYNC = 1, LIBUSB_ISO_SYNC_TYPE_ADAPTIVE = 2, LIBUSB_ISO_SYNC_TYPE_SYNC = 3 }
	Synchronization type for isochronous endpoints. More...
enum	libusb_iso_usage_type { LIBUSB_ISO_USAGE_TYPE_DATA = 0, LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 1, LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2 }
	Usage type for isochronous endpoints. More...

Functions
int	libusb_get_device_descriptor (libusb_device dev, struct libusb_device_descriptor desc)
	Get the USB device descriptor for a given device.
int	libusb_get_active_config_descriptor (libusb_device dev, struct libusb_config_descriptor *config)
	Get the USB configuration descriptor for the currently active configuration.
int	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.
int	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.
void	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().
int	libusb_get_ss_endpoint_companion_descriptor (struct 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)
void	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().
int	libusb_get_bos_descriptor (libusb_device_handle 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.
void	libusb_free_bos_descriptor (struct libusb_bos_descriptor *bos)
	Free a BOS descriptor obtained from libusb_get_bos_descriptor().
int	libusb_get_usb_2_0_extension_descriptor (struct 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.
void	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().
int	libusb_get_ss_usb_device_capability_descriptor (struct 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.
void	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().
int	libusb_get_container_id_descriptor (struct libusb_context ctx, struct libusb_bos_dev_capability_descriptor dev_cap, struct libusb_container_id_descriptor **container_id)
	Get a Container ID descriptor.
void	libusb_free_container_id_descriptor (struct libusb_container_id_descriptor *container_id)
	Free a Container ID descriptor obtained from libusb_get_container_id_descriptor().
int	libusb_get_string_descriptor_ascii (libusb_device_handle dev, uint8_t desc_index, unsigned char data, int length)
	Retrieve a string descriptor in C style ASCII.
static int	libusb_get_descriptor (libusb_device_handle dev, uint8_t desc_type, uint8_t desc_index, unsigned char data, int length)
	Retrieve a descriptor from the default control pipe.
static int	libusb_get_string_descriptor (libusb_device_handle dev, uint8_t desc_index, uint16_t langid, unsigned char data, int length)
	Retrieve a descriptor from a device.

Detailed Description

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

Enumeration Type Documentation

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_PRINTER	Printer class.
LIBUSB_CLASS_PTP	Image 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.

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.

enum libusb_endpoint_direction

Endpoint direction.

Values for bit 7 of the endpoint address scheme.

Enumerator:

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

enum libusb_transfer_type

Endpoint transfer type.

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

Enumerator:

LIBUSB_TRANSFER_TYPE_CONTROL	Control endpoint.
LIBUSB_TRANSFER_TYPE_ISOCHRONOUS	Isochronous endpoint.
LIBUSB_TRANSFER_TYPE_BULK	Bulk endpoint.
LIBUSB_TRANSFER_TYPE_INTERRUPT	Interrupt endpoint.

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.

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.

Function Documentation

int 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 libusbx-1.0.16, LIBUSBX_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

int 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

int 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()

int 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()

void 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

int libusb_get_ss_endpoint_companion_descriptor	(	struct 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

void 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

int libusb_get_bos_descriptor	(	libusb_device_handle *	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:

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

void 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

int libusb_get_usb_2_0_extension_descriptor	(	struct 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

void 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

int libusb_get_ss_usb_device_capability_descriptor	(	struct 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

void 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 USB 2.0 Extension descriptor to free

int libusb_get_container_id_descriptor	(	struct 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

void 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 USB 2.0 Extension descriptor to free

int libusb_get_string_descriptor_ascii	(	libusb_device_handle *	dev,
		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	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

static int libusb_get_descriptor	(	libusb_device_handle *	dev,
		uint8_t	desc_type,
		uint8_t	desc_index,
		unsigned char *	data,
		int	length
	)

inlinestatic

Retrieve a descriptor from the default control pipe.

This is a convenience function which formulates the appropriate control message to retrieve the descriptor.

Parameters:

dev	a device handle
desc_type	the descriptor type, see libusb_descriptor_type
desc_index	the index of the descriptor to retrieve
data	output buffer for descriptor
length	size of data buffer

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

static int libusb_get_string_descriptor	(	libusb_device_handle *	dev,
		uint8_t	desc_index,
		uint16_t	langid,
		unsigned char *	data,
		int	length
	)

inlinestatic

Retrieve a descriptor from a device.

This is a convenience function which formulates the appropriate control message to retrieve the descriptor. The string returned is Unicode, as detailed in the USB specifications.

Parameters:

dev	a device handle
desc_index	the index of the descriptor to retrieve
langid	the language ID for the string descriptor
data	output buffer for descriptor
length	size of data buffer

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

See also:: libusb_get_string_descriptor_ascii()

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation