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

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

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