GUsbDevice: GUsb Reference Manual

## GUsbDevice GUsbDevice — GLib device integration for libusb |

## Functions

GQuark | g_usb_device_error_quark ()
const gchar * | g_usb_device_get_platform_id ()
GUsbDevice * | g_usb_device_get_parent ()
GPtrArray * | g_usb_device_get_children ()
guint8 | g_usb_device_get_bus ()
guint8 | g_usb_device_get_address ()
guint8 | g_usb_device_get_port_number ()
guint16 | g_usb_device_get_vid ()
guint16 | g_usb_device_get_pid ()
guint16 | g_usb_device_get_release ()
guint16 | g_usb_device_get_spec ()
const gchar * | g_usb_device_get_vid_as_str ()
const gchar * | g_usb_device_get_pid_as_str ()
guint8 | g_usb_device_get_device_class ()
guint8 | g_usb_device_get_device_subclass ()
guint8 | g_usb_device_get_device_protocol ()
guint8 | g_usb_device_get_manufacturer_index ()
guint8 | g_usb_device_get_product_index ()
guint8 | g_usb_device_get_serial_number_index ()
guint8 | g_usb_device_get_custom_index ()
GUsbInterface * | g_usb_device_get_interface ()
GPtrArray * | g_usb_device_get_interfaces ()
gboolean | g_usb_device_open ()
gboolean | g_usb_device_close ()
gboolean | g_usb_device_reset ()
gint | g_usb_device_get_configuration ()
gboolean | g_usb_device_set_configuration ()
gboolean | g_usb_device_claim_interface ()
gboolean | g_usb_device_release_interface ()
gboolean | g_usb_device_set_interface_alt ()
gchar * | g_usb_device_get_string_descriptor ()
gboolean | g_usb_device_control_transfer ()
gboolean | g_usb_device_bulk_transfer ()
gboolean | g_usb_device_interrupt_transfer ()
void | g_usb_device_control_transfer_async ()
gssize | g_usb_device_control_transfer_finish ()
void | g_usb_device_bulk_transfer_async ()
gssize | g_usb_device_bulk_transfer_finish ()
void | g_usb_device_interrupt_transfer_async ()
gssize | g_usb_device_interrupt_transfer_finish ()

## Types and Values

#define | G_USB_DEVICE_ERROR
enum | GUsbDeviceDirection
enum | GUsbDeviceRequestType
enum | GUsbDeviceRecipient
enum | GUsbDeviceError
enum | GUsbDeviceClaimInterfaceFlags
enum | GUsbDeviceClassCode
struct | GUsbDevice
struct | GUsbDeviceClass
| GUsbDevicePrivate

## Description

This object is a thin glib wrapper around a libusb_device

## Functions

### g_usb_device_error_quark ()

    GQuark
    g_usb_device_error_quark (void);

#### Returns

Our personal error quark.

Since: 0.1.0

### g_usb_device_get_platform_id ()

    const gchar *
    g_usb_device_get_platform_id (GUsbDevice *device);

Gets the platform identifier for the device.

When the device is removed and then replugged, this value is not expected to be different.

#### Parameters

device | a GUsbDevice |

#### Returns

The platform ID, e.g. "usb:02:00:03:01"

Since: 0.1.1

### g_usb_device_get_parent ()

    GUsbDevice *
    g_usb_device_get_parent (GUsbDevice *device);

Gets the device parent if one exists.

#### Parameters

device | a GUsbDevice instance |

#### Returns

GUsbDevice or `NULL`.

[transfer full]

Since: 0.2.4

### g_usb_device_get_children ()

    GPtrArray *
    g_usb_device_get_children (GUsbDevice *device);

Gets the device children if any exist.

#### Parameters

device | a GUsbDevice instance |

#### Returns

an array of GUsbDevice.

[transfer full][element-type GUsbDevice]

Since: 0.2.4

### g_usb_device_get_bus ()

    guint8
    g_usb_device_get_bus (GUsbDevice *device);

Gets the USB bus number for the device.

#### Parameters

device | a GUsbDevice |

#### Returns

The 8-bit bus number

Since: 0.1.0

### g_usb_device_get_address ()

    guint8
    g_usb_device_get_address (GUsbDevice *device);

Gets the USB address for the device.

#### Parameters

device | a GUsbDevice |

#### Returns

The 8-bit address

Since: 0.1.0

### g_usb_device_get_port_number ()

    guint8
    g_usb_device_get_port_number (GUsbDevice *device);

Gets the USB port number for the device.

#### Parameters

device | a GUsbDevice |

#### Returns

The 8-bit port number

Since: 0.2.4

### g_usb_device_get_vid ()

    guint16
    g_usb_device_get_vid (GUsbDevice *device);

Gets the vendor ID for the device.

#### Parameters

device | a GUsbDevice |

#### Returns

an ID.

Since: 0.1.0

### g_usb_device_get_pid ()

    guint16
    g_usb_device_get_pid (GUsbDevice *device);

Gets the product ID for the device.

#### Parameters

device | a GUsbDevice |

#### Returns

an ID.

Since: 0.1.0

### g_usb_device_get_release ()

    guint16
    g_usb_device_get_release (GUsbDevice *device);

Gets the BCD firmware version number for the device.

#### Parameters

device | a GUsbDevice |

#### Returns

a version number in BCD format.

Since: 0.2.8

### g_usb_device_get_spec ()

    guint16
    g_usb_device_get_spec (GUsbDevice *device);

Gets the BCD specification revision for the device. For example, `0x0110` indicates USB 1.1 and 0x0320 indicates USB 3.2

#### Parameters

device | a GUsbDevice |

#### Returns

a specification revision in BCD format.

Since: 0.3.1

### g_usb_device_get_vid_as_str ()

    const gchar *
    g_usb_device_get_vid_as_str (GUsbDevice *device);

Gets the vendor ID for the device as a string.

#### Parameters

device | a GUsbDevice |

#### Returns

an string ID, or `NULL` if not available.

Since: 0.2.4

### g_usb_device_get_pid_as_str ()

    const gchar *
    g_usb_device_get_pid_as_str (GUsbDevice *device);

Gets the product ID for the device as a string.

#### Parameters

device | a GUsbDevice |

#### Returns

an string ID, or `NULL` if not available.

Since: 0.2.4

### g_usb_device_get_device_class ()

    guint8
    g_usb_device_get_device_class (GUsbDevice *device);

Gets the device class, typically a GUsbDeviceClassCode.

#### Parameters

device | a GUsbDevice |

#### Returns

a device class number, e.g. 0x09 is a USB hub.

Since: 0.1.7

### g_usb_device_get_device_subclass ()

    guint8
    g_usb_device_get_device_subclass (GUsbDevice *device);

Gets the device subclass qualified by the class number. See `g_usb_device_get_device_class()`.

#### Parameters

device | a GUsbDevice |

#### Returns

a device subclass number.

Since: 0.2.4

### g_usb_device_get_device_protocol ()

    guint8
    g_usb_device_get_device_protocol (GUsbDevice *device);

Gets the device protocol qualified by the class and subclass numbers. See `g_usb_device_get_device_class()` and `g_usb_device_get_device_subclass()`.

#### Parameters

device | a GUsbDevice |

#### Returns

a device protocol number.

Since: 0.2.4

### g_usb_device_get_manufacturer_index ()

    guint8
    g_usb_device_get_manufacturer_index (GUsbDevice *device);

Gets the index for the Manufacturer string descriptor.

#### Parameters

device | a GUsbDevice |

#### Returns

a string descriptor index.

Since: 0.1.0

### g_usb_device_get_product_index ()

    guint8
    g_usb_device_get_product_index (GUsbDevice *device);

Gets the index for the Product string descriptor.

#### Parameters

device | a GUsbDevice |

#### Returns

a string descriptor index.

Since: 0.1.0

### g_usb_device_get_serial_number_index ()

    guint8
    g_usb_device_get_serial_number_index (GUsbDevice *device);

Gets the index for the Serial Number string descriptor.

#### Parameters

device | a GUsbDevice |

#### Returns

a string descriptor index.

Since: 0.1.0

### g_usb_device_get_custom_index ()

    guint8
    g_usb_device_get_custom_index (GUsbDevice *device,
                                   guint8 class_id,
                                   guint8 subclass_id,
                                   guint8 protocol_id,
                                   GError **error);

Gets the string index from the vendor class interface descriptor.

#### Parameters

device | a GUsbDevice |
class_id | a device class, e.g. 0xff for VENDOR |
subclass_id | a device subclass |
protocol_id | a protocol number |
error | a GError, or `NULL` |

#### Returns

a non-zero index, or 0x00 for failure

Since: 0.2.5

### g_usb_device_get_interface ()

    GUsbInterface *
    g_usb_device_get_interface (GUsbDevice *device,
                                guint8 class_id,
                                guint8 subclass_id,
                                guint8 protocol_id,
                                GError **error);

Gets the first interface that matches the vendor class interface descriptor. If you want to find all the interfaces that match (there may be other 'alternate' interfaces you have to use `g_usb_device_get_interfaces()` and check each one manally.

#### Parameters

device | a GUsbDevice |
class_id | a device class, e.g. 0xff for VENDOR |
subclass_id | a device subclass |
protocol_id | a protocol number |
error | a GError, or `NULL` |

#### Returns

a GUsbInterface or `NULL` for not found.

[transfer full]

Since: 0.2.8

### g_usb_device_get_interfaces ()

    GPtrArray *
    g_usb_device_get_interfaces (GUsbDevice *device,
                                 GError **error);

Gets all the interfaces exported by the device.

#### Parameters

device | a GUsbDevice |
error | a GError, or `NULL` |

#### Returns

an array of interfaces or `NULL` for error.

[transfer container][element-type GUsbInterface]

Since: 0.2.8

### g_usb_device_open ()

    gboolean
    g_usb_device_open (GUsbDevice *device,
                       GError **error);

Opens the device for use.

Warning: this function is synchronous.

#### Parameters

device | a GUsbDevice |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success

Since: 0.1.0

### g_usb_device_close ()

    gboolean
    g_usb_device_close (GUsbDevice *device,
                        GError **error);

Closes the device when it is no longer required.

#### Parameters

device | a GUsbDevice |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success

### g_usb_device_reset ()

    gboolean
    g_usb_device_reset (GUsbDevice *device,
                        GError **error);

Perform a USB port reset to reinitialize a device.

If the reset succeeds, the device will appear to disconnected and reconnected. This means the `device` will no longer be valid and should be closed and rediscovered.

This is a blocking function which usually incurs a noticeable delay.

#### Parameters

device | a GUsbDevice |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success

### g_usb_device_get_configuration ()

    gint
    g_usb_device_get_configuration (GUsbDevice *device,
                                    GError **error);

Get the bConfigurationValue for the active configuration of the device.

Warning: this function is synchronous.

#### Parameters

device | a GUsbDevice |
error | a GError, or `NULL` |

#### Returns

The bConfigurationValue of the active config, or -1 on error

Since: 0.1.0

### g_usb_device_set_configuration ()

    gboolean
    g_usb_device_set_configuration (GUsbDevice *device,
                                    gint configuration,
                                    GError **error);

Set the active bConfigurationValue for the device.

Warning: this function is synchronous.

#### Parameters

device | a GUsbDevice |
configuration | the configuration value to set |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success

Since: 0.1.0

### g_usb_device_claim_interface ()

    gboolean
    g_usb_device_claim_interface (GUsbDevice *device,
                                  gint interface,
                                  GUsbDeviceClaimInterfaceFlags flags,
                                  GError **error);

Claim an interface of the device.

#### Parameters

device | a GUsbDevice |
interface | bInterfaceNumber of the interface you wish to claim |
flags | GUsbDeviceClaimInterfaceFlags |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success

Since: 0.1.0

### g_usb_device_release_interface ()

    gboolean
    g_usb_device_release_interface (GUsbDevice *device,
                                    gint interface,
                                    GUsbDeviceClaimInterfaceFlags flags,
                                    GError **error);

Release an interface of the device.

#### Parameters

device | a GUsbDevice |
interface | bInterfaceNumber of the interface you wish to release |
flags | GUsbDeviceClaimInterfaceFlags |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success

Since: 0.1.0

### g_usb_device_set_interface_alt ()

    gboolean
    g_usb_device_set_interface_alt (GUsbDevice *device,
                                    gint interface,
                                    guint8 alt,
                                    GError **error);

Sets an alternate setting on an interface.

#### Parameters

device | a GUsbDevice |
interface | bInterfaceNumber of the interface you wish to release |
alt | alternative setting number |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success

Since: 0.2.8

### g_usb_device_get_string_descriptor ()

    gchar *
    g_usb_device_get_string_descriptor (GUsbDevice *device,
                                        guint8 desc_index,
                                        GError **error);

Get a string descriptor from the device. The returned string should be freed with `g_free()` when no longer needed.

#### Parameters

desc_index | the index for the string descriptor to retrieve |
error | a GError, or `NULL` |

#### Returns

a newly-allocated string holding the descriptor, or NULL on error.

Since: 0.1.0

### g_usb_device_control_transfer ()

    gboolean
    g_usb_device_control_transfer (GUsbDevice *device,
                                   GUsbDeviceDirection direction,
                                   GUsbDeviceRequestType request_type,
                                   GUsbDeviceRecipient recipient,
                                   guint8 request,
                                   guint16 value,
                                   guint16 idx,
                                   guint8 *data,
                                   gsize length,
                                   gsize *actual_length,
                                   guint timeout,
                                   GCancellable *cancellable,
                                   GError **error);

Perform a USB control transfer.

Warning: this function is synchronous, and cannot be cancelled.

#### Parameters

device | a GUsbDevice |
request_type | the request type field for the setup packet |
request | the request field for the setup packet |
value | the value field for the setup packet |
idx | the index field for the setup packet |
data | a suitably-sized data buffer for either input or output. | [array length=length]
length | the length field for the setup packet. |
actual_length | the actual number of bytes sent, or `NULL`. | [out][optional]
timeout | timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0. |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success

Since: 0.1.0

### g_usb_device_bulk_transfer ()

    gboolean
    g_usb_device_bulk_transfer (GUsbDevice *device,
                                guint8 endpoint,
                                guint8 *data,
                                gsize length,
                                gsize *actual_length,
                                guint timeout,
                                GCancellable *cancellable,
                                GError **error);

Perform a USB bulk transfer.

Warning: this function is synchronous, and cannot be cancelled.

#### Parameters

device | a GUsbDevice |
endpoint | the address of a valid endpoint to communicate with |
data | a suitably-sized data buffer for either input or output. | [array length=length]
length | the length field for the setup packet. |
actual_length | the actual number of bytes sent, or `NULL`. | [out][optional]
timeout | timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0. |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success

Since: 0.1.0

### g_usb_device_interrupt_transfer ()

    gboolean
    g_usb_device_interrupt_transfer (GUsbDevice *device,
                                     guint8 endpoint,
                                     guint8 *data,
                                     gsize length,
                                     gsize *actual_length,
                                     guint timeout,
                                     GCancellable *cancellable,
                                     GError **error);

Perform a USB interrupt transfer.

Warning: this function is synchronous, and cannot be cancelled.

#### Parameters

device | a GUsbDevice |
endpoint | the address of a valid endpoint to communicate with |
data | a suitably-sized data buffer for either input or output. | [array length=length]
length | the length field for the setup packet. |
actual_length | the actual number of bytes sent, or `NULL`. | [out][optional]
timeout | timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0. |
cancellable | a GCancellable, or `NULL` |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success

Since: 0.1.0

### g_usb_device_control_transfer_async ()

    void
    g_usb_device_control_transfer_async (GUsbDevice *device,
                                         GUsbDeviceDirection direction,
                                         GUsbDeviceRequestType request_type,
                                         GUsbDeviceRecipient recipient,
                                         guint8 request,
                                         guint16 value,
                                         guint16 idx,
                                         guint8 *data,
                                         gsize length,
                                         guint timeout,
                                         GCancellable *cancellable,
                                         GAsyncReadyCallback callback,
                                         gpointer user_data);

Do an async control transfer

#### Parameters

device | a GUsbDevice |
data | a suitably-sized data buffer for either input or output. | [array length=length]
length | the length field for the setup packet. |
timeout | timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0. |
cancellable | a GCancellable, or `NULL` |
callback | the function to run on completion |
user_data | the data to pass to `callback` |

Since: 0.1.0

### g_usb_device_control_transfer_finish ()

    gssize
    g_usb_device_control_transfer_finish (GUsbDevice *device,
                                          GAsyncResult *res,
                                          GError **error);

Gets the result from the asynchronous function.

#### Parameters

device | a GUsbDevice instance. |
res | the GAsyncResult |
error | A GError or `NULL` |

#### Returns

the actual number of bytes sent, or -1 on error.

Since: 0.1.0

### g_usb_device_bulk_transfer_async ()

    void
    g_usb_device_bulk_transfer_async (GUsbDevice *device,
                                      guint8 endpoint,
                                      guint8 *data,
                                      gsize length,
                                      guint timeout,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Do an async bulk transfer

#### Parameters

device | a GUsbDevice instance. |
endpoint | the address of a valid endpoint to communicate with |
data | a suitably-sized data buffer for either input or output. | [array length=length]
length | the length field for the setup packet. |
timeout | timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0. |
cancellable | a GCancellable, or `NULL` |
callback | the function to run on completion |
user_data | the data to pass to `callback` |

Since: 0.1.0

### g_usb_device_bulk_transfer_finish ()

    gssize
    g_usb_device_bulk_transfer_finish (GUsbDevice *device,
                                       GAsyncResult *res,
                                       GError **error);

Gets the result from the asynchronous function.

#### Parameters

device | a GUsbDevice instance. |
res | the GAsyncResult |
error | A GError or `NULL` |

#### Returns

the actual number of bytes sent, or -1 on error.

Since: 0.1.0

### g_usb_device_interrupt_transfer_async ()

    void
    g_usb_device_interrupt_transfer_async (GUsbDevice *device,
                                           guint8 endpoint,
                                           guint8 *data,
                                           gsize length,
                                           guint timeout,
                                           GCancellable *cancellable,
                                           GAsyncReadyCallback callback,
                                           gpointer user_data);

Do an async interrupt transfer

#### Parameters

device | a GUsbDevice instance. |
endpoint | the address of a valid endpoint to communicate with |
data | a suitably-sized data buffer for either input or output. | [array length=length]
length | the length field for the setup packet. |
timeout | timeout timeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use 0. |
cancellable | a GCancellable, or `NULL` |
callback | the function to run on completion |
user_data | the data to pass to `callback` |

Since: 0.1.0

### g_usb_device_interrupt_transfer_finish ()

    gssize
    g_usb_device_interrupt_transfer_finish
                                   (GUsbDevice *device,
                                    GAsyncResult *res,
                                    GError **error);

Gets the result from the asynchronous function.

#### Parameters

device | a GUsbDevice instance. |
res | the GAsyncResult |
error | A GError or `NULL` |

#### Returns

the actual number of bytes sent, or -1 on error.

Since: 0.1.0

## Types and Values

### G_USB_DEVICE_ERROR

    #define G_USB_DEVICE_ERROR		(g_usb_device_error_quark ())

### enum GUsbDeviceDirection

The message direction.

#### Members

G_USB_DEVICE_DIRECTION_DEVICE_TO_HOST |  |
G_USB_DEVICE_DIRECTION_HOST_TO_DEVICE |  |

### enum GUsbDeviceRequestType

The message request type.

#### Members

G_USB_DEVICE_REQUEST_TYPE_STANDARD |  |
G_USB_DEVICE_REQUEST_TYPE_CLASS |  |
G_USB_DEVICE_REQUEST_TYPE_VENDOR |  |
G_USB_DEVICE_REQUEST_TYPE_RESERVED |  |

### enum GUsbDeviceRecipient

The message recipient.

#### Members

G_USB_DEVICE_RECIPIENT_DEVICE |  |
G_USB_DEVICE_RECIPIENT_INTERFACE |  |
G_USB_DEVICE_RECIPIENT_ENDPOINT |  |
G_USB_DEVICE_RECIPIENT_OTHER |  |

### enum GUsbDeviceError

The error code.

#### Members

G_USB_DEVICE_ERROR_INTERNAL |  |
G_USB_DEVICE_ERROR_IO |  |
G_USB_DEVICE_ERROR_TIMED_OUT |  |
G_USB_DEVICE_ERROR_NOT_SUPPORTED |  |
G_USB_DEVICE_ERROR_NO_DEVICE |  |
G_USB_DEVICE_ERROR_NOT_OPEN |  |
G_USB_DEVICE_ERROR_ALREADY_OPEN |  |
G_USB_DEVICE_ERROR_CANCELLED |  |
G_USB_DEVICE_ERROR_FAILED |  |
G_USB_DEVICE_ERROR_PERMISSION_DENIED |  |
G_USB_DEVICE_ERROR_LAST |  |

### enum GUsbDeviceClaimInterfaceFlags

Flags for the g_usb_device_claim_interface and g_usb_device_release_interface methods flags parameters.

#### Members

G_USB_DEVICE_CLAIM_INTERFACE_NONE |  |
G_USB_DEVICE_CLAIM_INTERFACE_BIND_KERNEL_DRIVER |  |

### enum GUsbDeviceClassCode

The USB device class.

#### Members

G_USB_DEVICE_CLASS_INTERFACE_DESC |  |
G_USB_DEVICE_CLASS_AUDIO |  |
G_USB_DEVICE_CLASS_COMMUNICATIONS |  |
G_USB_DEVICE_CLASS_HID |  |
G_USB_DEVICE_CLASS_PHYSICAL |  |
G_USB_DEVICE_CLASS_IMAGE |  |
G_USB_DEVICE_CLASS_PRINTER |  |
G_USB_DEVICE_CLASS_MASS_STORAGE |  |
G_USB_DEVICE_CLASS_HUB |  |
G_USB_DEVICE_CLASS_CDC_DATA |  |
G_USB_DEVICE_CLASS_SMART_CARD |  |
G_USB_DEVICE_CLASS_CONTENT_SECURITY |  |
G_USB_DEVICE_CLASS_VIDEO |  |
G_USB_DEVICE_CLASS_PERSONAL_HEALTHCARE |  |
G_USB_DEVICE_CLASS_AUDIO_VIDEO |  |
G_USB_DEVICE_CLASS_BILLBOARD |  |
G_USB_DEVICE_CLASS_DIAGNOSTIC |  |
G_USB_DEVICE_CLASS_WIRELESS_CONTROLLER |  |
G_USB_DEVICE_CLASS_MISCELLANEOUS |  |
G_USB_DEVICE_CLASS_APPLICATION_SPECIFIC |  |
G_USB_DEVICE_CLASS_VENDOR_SPECIFIC |  |

### struct GUsbDevice

    struct GUsbDevice {
    	 GObject			 parent;
    	 GUsbDevicePrivate		*priv;
    };

### struct GUsbDeviceClass

    struct GUsbDeviceClass {
    	GObjectClass			 parent_class;
    };

### GUsbDevicePrivate

    typedef struct _GUsbDevicePrivate GUsbDevicePrivate;

Private GUsbDevice data