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

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_HID = 0x21, LIBUSB_DT_REPORT = 0x22, LIBUSB_DT_PHYSICAL = 0x23,
  LIBUSB_DT_HUB = 0x29
}
 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. 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_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_HID 

HID descriptor.

LIBUSB_DT_REPORT 

HID report descriptor.

LIBUSB_DT_PHYSICAL 

Physical descriptor.

LIBUSB_DT_HUB 

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

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