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

Macros
#define	LIBUSB_DEVICE_STRING_BYTES_MAX (384U)
	The maximum length for a device string descriptor in UTF-8.

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_AUDIO_VIDEO = 0x10 , LIBUSB_CLASS_BILLBOARD = 0x11 , LIBUSB_CLASS_TYPE_C_BRIDGE = 0x12 , LIBUSB_CLASS_BULK_DISPLAY_PROTOCOL = 0x13 , LIBUSB_CLASS_MCTP = 0x14 , LIBUSB_CLASS_I3C = 0x3c , 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
enum	libusb_device_string_type { LIBUSB_DEVICE_STRING_MANUFACTURER , LIBUSB_DEVICE_STRING_PRODUCT , LIBUSB_DEVICE_STRING_SERIAL_NUMBER , LIBUSB_DEVICE_STRING_COUNT }
	The device string type.

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().
int	libusb_get_device_string (libusb_device dev, enum libusb_device_string_type string_type, char data, int length)
	Retrieve a device string without needing to open the device.
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.

Macro Definition Documentation

◆ LIBUSB_DEVICE_STRING_BYTES_MAX

#define LIBUSB_DEVICE_STRING_BYTES_MAX (384U)

The maximum length for a device string descriptor in UTF-8.

255 max descriptor length with 2 byte header => 253 bytes UTF-16LE, no null termination (USB 2.0 9.6.7) => 126.5 codepoints => 126 * 3 + 1 => 382 bytes

Stay with 256 * 2/3 = 384 to be safe.

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_AUDIO_VIDEO	Audio & Video.
LIBUSB_CLASS_BILLBOARD	Billboard.
LIBUSB_CLASS_TYPE_C_BRIDGE	Interface class.
LIBUSB_CLASS_BULK_DISPLAY_PROTOCOL	Bulk display.
LIBUSB_CLASS_MCTP	MCTP.
LIBUSB_CLASS_I3C	I3C.
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_device_string()

int libusb_get_device_string	(	libusb_device *	dev,
		enum libusb_device_string_type	string_type,
		char *	data,
		int	length )

Retrieve a device string without needing to open the device.

Since version v1.0.30 LIBUSB_API_VERSION >= 0x0100010C

Parameters

dev	the target device
string_type	the string type to retrieve
data	the data buffer for the UTF-8 encoded string.
length	the size of the data buffer in bytes. USB string descriptors cannot be longer than LIBUSB_DEVICE_STRING_BYTES_MAX.

Returns: a negative error code or the actual string length in bytes including the null terminator.

See also: libusb_get_string_descriptor(); libusb_get_string_descriptor_ascii()

This function works when the device is still closed since it relies on the operating system to provide the string. The operating system normally reads and caches the common string descriptors during USB enumeration.

Since the USB string descriptor could be processed by the OS, this function returns a UTF-8 encoded string.

The string will be returned untranslated or in the default OS language when supported by the OS and USB device.

One way to call this function is using a buffer on the stack:

char buffer[LIBUSB_DEVICE_STRING_BYTES_MAX];
int ret = libusb_get_device_string(dev, LIBUSB_DEVICE_STRING_SERIAL_NUMBER, buffer, sizeof(buffer));
if (ret < 0) {
    // handle error
}

This function is commonly used to get the serial number to allow for device selection before opening the selected device.

◆ libusb_get_descriptor()

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

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

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ LIBUSB_DEVICE_STRING_BYTES_MAX

Enumeration Type Documentation

◆ libusb_class_code

◆ libusb_descriptor_type

◆ libusb_endpoint_direction

◆ libusb_endpoint_transfer_type

◆ libusb_iso_sync_type

◆ libusb_iso_usage_type

◆ libusb_supported_speed

◆ libusb_usb_2_0_extension_attributes

◆ libusb_ss_usb_device_capability_attributes

◆ libusb_bos_type

Function Documentation

◆ libusb_get_device_descriptor()

◆ libusb_get_active_config_descriptor()

◆ libusb_get_config_descriptor()

◆ libusb_get_config_descriptor_by_value()

◆ libusb_free_config_descriptor()

◆ libusb_get_ss_endpoint_companion_descriptor()

◆ libusb_free_ss_endpoint_companion_descriptor()

◆ libusb_get_bos_descriptor()

◆ libusb_free_bos_descriptor()

◆ libusb_get_usb_2_0_extension_descriptor()

◆ libusb_free_usb_2_0_extension_descriptor()

◆ libusb_get_ss_usb_device_capability_descriptor()

◆ libusb_get_ssplus_usb_device_capability_descriptor()

◆ libusb_free_ssplus_usb_device_capability_descriptor()

◆ libusb_free_ss_usb_device_capability_descriptor()

◆ libusb_get_container_id_descriptor()

◆ libusb_free_container_id_descriptor()

◆ libusb_get_platform_descriptor()

◆ libusb_free_platform_descriptor()

◆ libusb_get_string_descriptor_ascii()

◆ libusb_get_interface_association_descriptors()

◆ libusb_get_active_interface_association_descriptors()

◆ libusb_free_interface_association_descriptors()

◆ libusb_get_device_string()

◆ libusb_get_descriptor()

◆ libusb_get_string_descriptor()