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