eXpand your USB potential
Data Structures | Enumerations | Functions
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_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

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.

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.

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.

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.

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.

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 libusb-1.0.16, LIBUSB_API_VERSION >= 0x01000102, this function always succeeds.

Parameters:
devthe device
descoutput 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:
deva device
configoutput 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:
deva device
config_indexthe index of the configuration you wish to retrieve
configoutput 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:
deva device
bConfigurationValuethe bConfigurationValue of the configuration you wish to retrieve
configoutput 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:
configthe 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:
ctxthe context to operate on, or NULL for the default context
endpointendpoint descriptor from which to get the superspeed endpoint companion descriptor
ep_compoutput 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_compthe 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:
handlethe handle of an open libusb device
bosoutput 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:
bosthe 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:
ctxthe context to operate on, or NULL for the default context
dev_capDevice Capability descriptor with a bDevCapabilityType of libusb_capability_type::LIBUSB_BT_USB_2_0_EXTENSION LIBUSB_BT_USB_2_0_EXTENSION
usb_2_0_extensionoutput 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_extensionthe 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:
ctxthe context to operate on, or NULL for the default context
dev_capDevice Capability descriptor with a bDevCapabilityType of libusb_capability_type::LIBUSB_BT_SS_USB_DEVICE_CAPABILITY LIBUSB_BT_SS_USB_DEVICE_CAPABILITY
ss_usb_device_capoutput 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_capthe 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:
ctxthe context to operate on, or NULL for the default context
dev_capDevice Capability descriptor with a bDevCapabilityType of libusb_capability_type::LIBUSB_BT_CONTAINER_ID LIBUSB_BT_CONTAINER_ID
container_idoutput 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_idthe 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:
deva device handle
desc_indexthe index of the descriptor to retrieve
dataoutput buffer for ASCII string descriptor
lengthsize 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:
deva device handle
desc_typethe descriptor type, see libusb_descriptor_type
desc_indexthe index of the descriptor to retrieve
dataoutput buffer for descriptor
lengthsize 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:
deva device handle
desc_indexthe index of the descriptor to retrieve
langidthe language ID for the string descriptor
dataoutput buffer for descriptor
lengthsize of data buffer
Returns:
number of bytes returned in data, or LIBUSB_ERROR code on failure
See also:
libusb_get_string_descriptor_ascii()