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_PRINTER = 7, LIBUSB_CLASS_PTP = 6, LIBUSB_CLASS_MASS_STORAGE = 8, LIBUSB_CLASS_HUB = 9,
  LIBUSB_CLASS_DATA = 10, 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.
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_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_PRINTER  Printer dclass.
LIBUSB_CLASS_PTP  Picture transfer protocol class.
LIBUSB_CLASS_MASS_STORAGE  Mass storage class.
LIBUSB_CLASS_HUB  Hub class.
LIBUSB_CLASS_DATA  Data class.
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:
dev the device
desc output 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:
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

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

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

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

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:
dev 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

static int libusb_get_descriptor ( libusb_device_handle dev,
uint8_t  desc_type,
uint8_t  desc_index,
unsigned char *  data,
int  length 
) [inline, static]

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

static int libusb_get_string_descriptor ( libusb_device_handle dev,
uint8_t  desc_index,
uint16_t  langid,
unsigned char *  data,
int  length 
) [inline, static]

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


Generated on Thu Oct 14 14:56:35 2010 for libusb by  doxygen 1.5.9