USB descriptors

Overview

This page details how to examine the various standard USB descriptors for detected devices. More…

// enums

enum libusb_class_code;
enum libusb_descriptor_type;
enum libusb_endpoint_direction;
enum libusb_iso_sync_type;
enum libusb_iso_usage_type;
enum libusb_transfer_type;

// structs

struct libusb_bos_descriptor;
struct libusb_bos_dev_capability_descriptor;
struct libusb_config_descriptor;
struct libusb_container_id_descriptor;
struct libusb_device_descriptor;
struct libusb_endpoint_descriptor;
struct libusb_interface;
struct libusb_interface_descriptor;
struct libusb_ss_endpoint_companion_descriptor;
struct libusb_ss_usb_device_capability_descriptor;
struct libusb_usb_2_0_extension_descriptor;

// global functions

int
libusb_get_device_descriptor(
    libusb_device* dev,
    struct libusb_device_descriptor* desc
);

int
libusb_get_active_config_descriptor(
    libusb_device* dev,
    struct libusb_config_descriptor** config
);

int
libusb_get_config_descriptor(
    libusb_device* dev,
    uint8_t config_index,
    struct libusb_config_descriptor** config
);

int
libusb_get_config_descriptor_by_value(
    libusb_device* dev,
    uint8_t bConfigurationValue,
    struct libusb_config_descriptor** config
);

void
libusb_free_config_descriptor(struct libusb_config_descriptor* config);

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

void
libusb_free_ss_endpoint_companion_descriptor(struct libusb_ss_endpoint_companion_descriptor* ep_comp);

int
libusb_get_bos_descriptor(
    libusb_device_handle* dev_handle,
    struct libusb_bos_descriptor** bos
);

void
libusb_free_bos_descriptor(struct libusb_bos_descriptor* bos);

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

void
libusb_free_usb_2_0_extension_descriptor(struct libusb_usb_2_0_extension_descriptor* usb_2_0_extension);

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

void
libusb_free_ss_usb_device_capability_descriptor(struct libusb_ss_usb_device_capability_descriptor* ss_usb_device_cap);

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

void
libusb_free_container_id_descriptor(struct libusb_container_id_descriptor* container_id);

int
libusb_get_string_descriptor_ascii(
    libusb_device_handle* dev_handle,
    uint8_t desc_index,
    unsigned char* data,
    int length
);

static
int
libusb_get_descriptor(
    libusb_device_handle* dev_handle,
    uint8_t desc_type,
    uint8_t desc_index,
    unsigned char* data,
    int length
);

static
int
libusb_get_string_descriptor(
    libusb_device_handle* dev_handle,
    uint8_t desc_index,
    uint16_t langid,
    unsigned char* data,
    int length
);

Detailed Documentation

This page details how to examine the various standard USB descriptors for detected devices.

Global Functions

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:

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

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

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

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

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

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:

ctx	the context to operate on, or NULL for the default context
dev_cap	Device Capability descriptor with a bDevCapabilityType of libusb_capability_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

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

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:

ctx	the context to operate on, or NULL for the default context
dev_cap	Device Capability descriptor with a bDevCapabilityType of libusb_capability_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

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

ctx	the context to operate on, or NULL for the default context
dev_cap	Device Capability descriptor with a bDevCapabilityType of libusb_capability_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

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 USB 2.0 Extension descriptor to free

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

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.

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

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.

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