A cross-platform user library to access USB devices
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,
  LIBUSB_TRANSFER_TYPE_BULK_STREAM = 4
}
 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. More...
 
int libusb_get_active_config_descriptor (libusb_device *dev, struct libusb_config_descriptor **config)
 Get the USB configuration descriptor for the currently active configuration. More...
 
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. More...
 
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. More...
 
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(). More...
 
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) More...
 
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(). More...
 
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. More...
 
void libusb_free_bos_descriptor (struct libusb_bos_descriptor *bos)
 Free a BOS descriptor obtained from libusb_get_bos_descriptor(). More...
 
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. More...
 
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(). More...
 
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. More...
 
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(). More...
 
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. More...
 
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(). More...
 
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. More...
 
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. More...
 
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. More...
 

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.

LIBUSB_TRANSFER_TYPE_BULK_STREAM 

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