GUsb Reference Manual: GUsbDevice

## GUsbDevice GUsbDevice — GLib device integration for libusb |

## Functions

GQuark | g_usb_device_error_quark ()
const gchar * | g_usb_device_get_platform_id ()
guint8 | g_usb_device_get_bus ()
guint8 | g_usb_device_get_address ()
guint16 | g_usb_device_get_vid ()
guint16 | g_usb_device_get_pid ()
guint8 | g_usb_device_get_device_class ()
guint8 | g_usb_device_get_manufacturer_index ()
guint8 | g_usb_device_get_product_index ()
guint8 | g_usb_device_get_serial_number_index ()
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 ()
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 ()

## Properties

GUsbContext * | context | Write / Construct Only
gpointer | libusb-device | Read / Write / Construct Only
gchar * | platform-id | Write / Construct Only

## Types and Values

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

## Object Hierarchy

        GObject
        ╰── GUsbDevice

## 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. On Linux, this is the full sysfs path of the device

#### Parameters

device | a GUsbDevice |

#### Returns

The platform ID, or `NULL`

Since 0.1.1

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

    guint8
    g_usb_device_get_device_class (GUsbDevice *device);

Gets the device class.

#### Parameters

device | a GUsbDevice |

#### Returns

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

Since 0.1.7

### 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_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_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 retreive |
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` |
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` |
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` |
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_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_BIND_KERNEL_DRIVER |  |

### struct GUsbDevice

    struct GUsbDevice;

### struct GUsbDeviceClass

    struct GUsbDeviceClass {
    	GObjectClass			 parent_class;
    };

### GUsbDevicePrivate

    typedef struct _GUsbDevicePrivate GUsbDevicePrivate;

Private GUsbDevice data

## Property Details

### The `“context”` property

      “context”                  GUsbContext *

Flags: Write / Construct Only

### The `“libusb-device”` property

      “libusb-device”            gpointer

Flags: Read / Write / Construct Only

### The `“platform-id”` property

      “platform-id”              gchar *

Flags: Write / Construct Only

Default value: NULL