GUsbDevice

GUsbDevice — GLib device integration for libusb

Functions

Properties

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

Types and Values

Object Hierarchy

    GObject
    ╰── GUsbDevice

Implemented Interfaces

GUsbDevice implements GInitable.

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]

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

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