USB descriptors

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_association_descriptor
	A structure representing the standard USB interface association descriptor. More...
struct	libusb_interface_association_descriptor_array
	Structure containing an array of 0 or more interface association descriptors. 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_ssplus_sublink_attribute
	Expose libusb_ssplus_usb_device_capability_descriptor::sublinkSpeedAttributes. More...
struct	libusb_ssplus_usb_device_capability_descriptor
	A structure representing the SuperSpeedPlus descriptor This descriptor is documented in section 9.6.2.5 of the USB 3.1 specification. More...
struct	libusb_container_id_descriptor
	A structure representing the Container ID descriptor. More...
struct	libusb_platform_descriptor
	A structure representing a Platform descriptor. More...

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_MISCELLANEOUS = 0xef , 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_INTERFACE_ASSOCIATION = 0x0b , 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_OUT = 0x00 , LIBUSB_ENDPOINT_IN = 0x80 }
	Endpoint direction. More...
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 }
	Endpoint transfer type. More...
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 }
	Synchronization type for isochronous endpoints. More...
enum	libusb_iso_usage_type { LIBUSB_ISO_USAGE_TYPE_DATA = 0x0 , LIBUSB_ISO_USAGE_TYPE_FEEDBACK = 0x1 , LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 0x2 }
	Usage type for isochronous endpoints. More...
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) }
	Supported speeds (wSpeedSupported) bitfield. More...
enum	libusb_usb_2_0_extension_attributes { LIBUSB_BM_LPM_SUPPORT = (1 << 1) }
	Masks for the bits of the bmAttributes field of the USB 2.0 Extension descriptor. More...
enum	libusb_ss_usb_device_capability_attributes { LIBUSB_BM_LTM_SUPPORT = (1 << 1) }
	Masks for the bits of the bmAttributes field field of the SuperSpeed USB Device Capability descriptor. More...
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 ,   LIBUSB_BT_PLATFORM_DESCRIPTOR = 0x05 , LIBUSB_BT_SUPERSPEED_PLUS_CAPABILITY = 0x0A }
	USB capability types. More...
enum	libusb_superspeedplus_sublink_attribute_sublink_type { LIBUSB_SSPLUS_ATTR_TYPE_SYM = 0 , LIBUSB_SSPLUS_ATTR_TYPE_ASYM = 1 }
	enum used in libusb_ssplus_sublink_attribute
enum	libusb_superspeedplus_sublink_attribute_sublink_direction { LIBUSB_SSPLUS_ATTR_DIR_RX = 0 , LIBUSB_SSPLUS_ATTR_DIR_TX = 1 }
	enum used in libusb_ssplus_sublink_attribute
enum	libusb_superspeedplus_sublink_attribute_exponent { LIBUSB_SSPLUS_ATTR_EXP_BPS = 0 , LIBUSB_SSPLUS_ATTR_EXP_KBS = 1 , LIBUSB_SSPLUS_ATTR_EXP_MBS = 2 , LIBUSB_SSPLUS_ATTR_EXP_GBS = 3 }
	enum used in libusb_ssplus_sublink_attribute Bit = Bits per second Kb = Kbps Mb = Mbps Gb = Gbps
enum	libusb_superspeedplus_sublink_attribute_link_protocol { LIBUSB_SSPLUS_ATTR_PROT_SS = 0 , LIBUSB_SSPLUS_ATTR_PROT_SSPLUS = 1 }
	enum used in libusb_ssplus_sublink_attribute

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 (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 *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.
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 (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 (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.
int	libusb_get_ssplus_usb_device_capability_descriptor (libusb_context *ctx, struct libusb_bos_dev_capability_descriptor *dev_cap, struct libusb_ssplus_usb_device_capability_descriptor **ssplus_usb_device_cap)
	Get a SuperSpeedPlus USB Device Capability descriptor.
void	libusb_free_ssplus_usb_device_capability_descriptor (struct libusb_ssplus_usb_device_capability_descriptor *ssplus_usb_device_cap)
	Free a SuperSpeedPlus USB Device Capability descriptor obtained from libusb_get_ssplus_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 (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_platform_descriptor (libusb_context *ctx, struct libusb_bos_dev_capability_descriptor *dev_cap, struct libusb_platform_descriptor **platform_descriptor)
	Get a platform descriptor.
void	libusb_free_platform_descriptor (struct libusb_platform_descriptor *platform_descriptor)
	Free a platform descriptor obtained from libusb_get_platform_descriptor().
int	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.
int	libusb_get_interface_association_descriptors (libusb_device *dev, uint8_t config_index, struct libusb_interface_association_descriptor_array **iad_array)
	Get an array of interface association descriptors (IAD) for a given configuration.
int	libusb_get_active_interface_association_descriptors (libusb_device *dev, struct libusb_interface_association_descriptor_array **iad_array)
	Get an array of interface association descriptors (IAD) for the currently active configuration.
void	libusb_free_interface_association_descriptors (struct libusb_interface_association_descriptor_array *iad_array)
	Free an array of interface association descriptors (IADs) obtained from libusb_get_interface_association_descriptors() or libusb_get_active_interface_association_descriptors().
static int	libusb_get_descriptor (libusb_device_handle *dev_handle, 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_handle, 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

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_MISCELLANEOUS	Miscellaneous 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_INTERFACE_ASSOCIATION	Interface Association Descriptor. See libusb_interface_association_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_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)

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_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_BT_PLATFORM_DESCRIPTOR	Platform descriptor.
LIBUSB_BT_SUPERSPEED_PLUS_CAPABILITY	SuperSpeedPlus device capability.

Function Documentation

libusb_get_device_descriptor()

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 libusb-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

libusb_get_active_config_descriptor()

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

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

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

libusb_free_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

libusb_get_ss_endpoint_companion_descriptor()

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

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

libusb_get_bos_descriptor()

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

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

libusb_get_usb_2_0_extension_descriptor()

int 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_bos_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

libusb_free_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().

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

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

int libusb_get_ssplus_usb_device_capability_descriptor	(	libusb_context *	ctx,
		struct libusb_bos_dev_capability_descriptor *	dev_cap,
		struct libusb_ssplus_usb_device_capability_descriptor **	ssplus_usb_device_cap
	)

Get a SuperSpeedPlus USB Device Capability descriptor.

Since version 1.0.28, LIBUSB_API_VERSION >= 0x0100010B

Parameters

ctx	the context to operate on, or NULL for the default context
dev_cap	Device Capability descriptor with a bDevCapabilityType of libusb_bos_type::LIBUSB_BT_SUPERSPEED_PLUS_CAPABILITY LIBUSB_BT_SUPERSPEED_PLUS_CAPABILITY
ssplus_usb_device_cap	output location for the SuperSpeedPlus USB Device Capability descriptor. Only valid if 0 was returned. Must be freed with libusb_free_ssplus_usb_device_capability_descriptor() after use.

Returns

0 on success

a LIBUSB_ERROR code on error

libusb_free_ssplus_usb_device_capability_descriptor()

void libusb_free_ssplus_usb_device_capability_descriptor

(

struct libusb_ssplus_usb_device_capability_descriptor *

ssplus_usb_device_cap

)

Free a SuperSpeedPlus USB Device Capability descriptor obtained from libusb_get_ssplus_usb_device_capability_descriptor().

It is safe to call this function with a NULL ssplus_usb_device_cap parameter, in which case the function simply returns.

Since version 1.0.28, LIBUSB_API_VERSION >= 0x0100010B

Parameters

ssplus_usb_device_cap

the SuperSpeedPlus USB Device Capability descriptor to free

libusb_free_ss_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().

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

int 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_bos_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_free_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().

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

int libusb_get_platform_descriptor	(	libusb_context *	ctx,
		struct libusb_bos_dev_capability_descriptor *	dev_cap,
		struct libusb_platform_descriptor **	platform_descriptor
	)

Get a platform descriptor.

Since version 1.0.27, LIBUSB_API_VERSION >= 0x0100010A

Parameters

ctx	the context to operate on, or NULL for the default context
dev_cap	Device Capability descriptor with a bDevCapabilityType of libusb_bos_type::LIBUSB_BT_PLATFORM_DESCRIPTOR LIBUSB_BT_PLATFORM_DESCRIPTOR
platform_descriptor	output location for the Platform descriptor. Only valid if 0 was returned. Must be freed with libusb_free_platform_descriptor() after use.

Returns

0 on success

a LIBUSB_ERROR code on error

libusb_free_platform_descriptor()

void libusb_free_platform_descriptor

(

struct libusb_platform_descriptor *

platform_descriptor

)

Free a platform descriptor obtained from libusb_get_platform_descriptor().

It is safe to call this function with a NULL platform_descriptor parameter, in which case the function simply returns.

Parameters

platform_descriptor

the Platform descriptor to free

libusb_get_string_descriptor_ascii()

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

int libusb_get_interface_association_descriptors	(	libusb_device *	dev,
		uint8_t	config_index,
		struct libusb_interface_association_descriptor_array **	iad_array
	)

Get an array of interface association descriptors (IAD) for a given configuration.

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 the IADs for.
iad_array	output location for the array of IADs. Only valid if 0 was returned. Must be freed with libusb_free_interface_association_descriptors() after use. It's possible that a given configuration contains no IADs. In this case the iad_array is still output, but will have 'length' field set to 0, and iad field set to NULL.

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

libusb_get_active_interface_association_descriptors()

int libusb_get_active_interface_association_descriptors	(	libusb_device *	dev,
		struct libusb_interface_association_descriptor_array **	iad_array
	)

Get an array of interface association descriptors (IAD) 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
iad_array	output location for the array of IADs. Only valid if 0 was returned. Must be freed with libusb_free_interface_association_descriptors() after use. It's possible that a given configuration contains no IADs. In this case the iad_array is still output, but will have 'length' field set to 0, and iad field set to NULL.

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_interface_association_descriptors

libusb_free_interface_association_descriptors()

void libusb_free_interface_association_descriptors

(

struct libusb_interface_association_descriptor_array *

iad_array

)

Free an array of interface association descriptors (IADs) obtained from libusb_get_interface_association_descriptors() or libusb_get_active_interface_association_descriptors().

It is safe to call this function with a NULL iad_array parameter, in which case the function simply returns.

Parameters

iad_array

the IAD array to free

libusb_get_descriptor()

static int libusb_get_descriptor ( libusb_device_handle *  dev_handle, 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_handle	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

libusb_get_string_descriptor()

static int libusb_get_string_descriptor ( libusb_device_handle *  dev_handle, 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_handle	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()