GUsbDevice

## GUsbDevice GUsbDevice — GLib device integration for libusb |

## Synopsis

    struct              GUsbDevice;
    enum                GUsbDeviceClaimInterfaceFlags;
    struct              GUsbDeviceClass;
    enum                GUsbDeviceDirection;
    enum                GUsbDeviceError;
    enum                GUsbDeviceRecipient;
    enum                GUsbDeviceRequestType;
    #define             G_USB_DEVICE_ERROR
    gboolean            g_usb_device_bulk_transfer          (GUsbDevice *device,
                                                             guint8 endpoint,
                                                             guint8 *data,
                                                             gsize length,
                                                             gsize *actual_length,
                                                             guint timeout,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                g_usb_device_bulk_transfer_async    (GUsbDevice *device,
                                                             guint8 endpoint,
                                                             guint8 *data,
                                                             gsize length,
                                                             guint timeout,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gssize              g_usb_device_bulk_transfer_finish   (GUsbDevice *device,
                                                             GAsyncResult *res,
                                                             GError **error);
    gboolean            g_usb_device_claim_interface        (GUsbDevice *device,
                                                             gint interface,
                                                             GUsbDeviceClaimInterfaceFlags flags,
                                                             GError **error);
    gboolean            g_usb_device_close                  (GUsbDevice *device,
                                                             GError **error);
    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);
    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);
    gssize              g_usb_device_control_transfer_finish
                                                            (GUsbDevice *device,
                                                             GAsyncResult *res,
                                                             GError **error);
    GQuark              g_usb_device_error_quark            (void);
    guint8              g_usb_device_get_address            (GUsbDevice *device);
    guint8              g_usb_device_get_bus                (GUsbDevice *device);
    gint                g_usb_device_get_configuration      (GUsbDevice *device,
                                                             GError **error);
    guint8              g_usb_device_get_manufacturer_index (GUsbDevice *device);
    guint16             g_usb_device_get_pid                (GUsbDevice *device);
    const gchar *       g_usb_device_get_platform_id        (GUsbDevice *device);
    guint8              g_usb_device_get_product_index      (GUsbDevice *device);
    guint8              g_usb_device_get_serial_number_index
                                                            (GUsbDevice *device);
    gchar *             g_usb_device_get_string_descriptor  (GUsbDevice *device,
                                                             guint8 desc_index,
                                                             GError **error);
    guint16             g_usb_device_get_vid                (GUsbDevice *device);
    gboolean            g_usb_device_interrupt_transfer     (GUsbDevice *device,
                                                             guint8 endpoint,
                                                             guint8 *data,
                                                             gsize length,
                                                             gsize *actual_length,
                                                             guint timeout,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                g_usb_device_interrupt_transfer_async
                                                            (GUsbDevice *device,
                                                             guint8 endpoint,
                                                             guint8 *data,
                                                             gsize length,
                                                             guint timeout,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gssize              g_usb_device_interrupt_transfer_finish
                                                            (GUsbDevice *device,
                                                             GAsyncResult *res,
                                                             GError **error);
    gboolean            g_usb_device_open                   (GUsbDevice *device,
                                                             GError **error);
    gboolean            g_usb_device_release_interface      (GUsbDevice *device,
                                                             gint interface,
                                                             GUsbDeviceClaimInterfaceFlags flags,
                                                             GError **error);
    gboolean            g_usb_device_reset                  (GUsbDevice *device,
                                                             GError **error);
    gboolean            g_usb_device_set_configuration      (GUsbDevice *device,
                                                             gint configuration,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GUsbDevice

## Properties

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

## Description

This object is a thin glib wrapper around a libusb_device

## Details

### struct GUsbDevice

    struct GUsbDevice;

### enum GUsbDeviceClaimInterfaceFlags

    typedef enum {
    	G_USB_DEVICE_CLAIM_INTERFACE_BIND_KERNEL_DRIVER		= 1 << 0,
    } GUsbDeviceClaimInterfaceFlags;

Flags for the g_usb_device_claim_interface and g_usb_device_release_interface methods flags parameters.

### struct GUsbDeviceClass

    struct GUsbDeviceClass {
    	GObjectClass			 parent_class;
    };

### enum GUsbDeviceDirection

    typedef enum {
    	G_USB_DEVICE_DIRECTION_DEVICE_TO_HOST, /* IN */
    	G_USB_DEVICE_DIRECTION_HOST_TO_DEVICE  /* OUT */
    } GUsbDeviceDirection;

The message direction.

### enum GUsbDeviceError

    typedef enum {
    	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
    } GUsbDeviceError;

The error code.

### enum GUsbDeviceRecipient

    typedef enum {
    	G_USB_DEVICE_RECIPIENT_DEVICE,
    	G_USB_DEVICE_RECIPIENT_INTERFACE,
    	G_USB_DEVICE_RECIPIENT_ENDPOINT,
    	G_USB_DEVICE_RECIPIENT_OTHER
    } GUsbDeviceRecipient;

The message recipient.

### enum GUsbDeviceRequestType

    typedef enum {
    	G_USB_DEVICE_REQUEST_TYPE_STANDARD,
    	G_USB_DEVICE_REQUEST_TYPE_CLASS,
    	G_USB_DEVICE_REQUEST_TYPE_VENDOR,
    	G_USB_DEVICE_REQUEST_TYPE_RESERVED
    } GUsbDeviceRequestType;

The message request type.

### G_USB_DEVICE_ERROR

    #define G_USB_DEVICE_ERROR		(g_usb_device_error_quark ())

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

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

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

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

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

Claim an interface of the device.

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

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

Closes the device when it is no longer required.

`device` : | a GUsbDevice
`error` : | a GError, or `NULL`
Returns : | `TRUE` on success

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

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

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

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

    GQuark              g_usb_device_error_quark            (void);

Returns : | Our personal error quark.

Since 0.1.0

### g_usb_device_get_address ()

    guint8              g_usb_device_get_address            (GUsbDevice *device);

Gets the USB address for the device.

`device` : | a GUsbDevice
Returns : | The 8-bit address

Since 0.1.0

### g_usb_device_get_bus ()

    guint8              g_usb_device_get_bus                (GUsbDevice *device);

Gets the USB bus number for the device.

`device` : | a GUsbDevice
Returns : | The 8-bit bus number

Since 0.1.0

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

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

    guint8              g_usb_device_get_manufacturer_index (GUsbDevice *device);

Gets the index for the Manufacturer string descriptor.

`device` : | a GUsbDevice
Returns : | a string descriptor index.

Since 0.1.0

### g_usb_device_get_pid ()

    guint16             g_usb_device_get_pid                (GUsbDevice *device);

Gets the product ID for the device.

`device` : | a GUsbDevice
Returns : | an ID.

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

`device` : | a GUsbDevice
Returns : | The platform ID, or `NULL`

Since 0.1.1

### g_usb_device_get_product_index ()

    guint8              g_usb_device_get_product_index      (GUsbDevice *device);

Gets the index for the Product string descriptor.

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

`device` : | a GUsbDevice
Returns : | a string descriptor index.

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.

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

    guint16             g_usb_device_get_vid                (GUsbDevice *device);

Gets the vendor ID for the device.

`device` : | a GUsbDevice
Returns : | an ID.

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.

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

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

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

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

Opens the device for use.

Warning: this function is synchronous.

`device` : | a GUsbDevice
`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.

`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_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.

`device` : | a GUsbDevice
`error` : | a GError, or `NULL`
Returns : | `TRUE` on success

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

`device` : | a GUsbDevice
`configuration` : | the configuration value to set
`error` : | a GError, or `NULL`
Returns : | `TRUE` on success

Since 0.1.0

## Property Details

### The `"context"` property

      "context"                  GUsbContext*          : Write / Construct Only

### The `"libusb-device"` property

      "libusb-device"            gpointer              : Read / Write / Construct Only

### The `"platform-id"` property

      "platform-id"              gchar*                : Write / Construct Only

Default value: NULL