GUsbContext: GUsb Reference Manual

## GUsbContext GUsbContext — Per-thread instance integration for libusb |

## Functions

GQuark | g_usb_context_error_quark ()
GUsbContext * | g_usb_context_new ()
void | g_usb_context_set_flags ()
GUsbContextFlags | g_usb_context_get_flags ()
GUsbSource * | g_usb_context_get_source ()
GMainContext * | g_usb_context_get_main_context ()
void | g_usb_context_set_main_context ()
void | g_usb_context_enumerate ()
void | g_usb_context_set_debug ()
GPtrArray * | g_usb_context_get_devices ()
GUsbDevice * | g_usb_context_find_by_bus_address ()
GUsbDevice * | g_usb_context_find_by_vid_pid ()
GUsbDevice * | g_usb_context_find_by_platform_id ()
GUsbDevice * | g_usb_context_wait_for_replug ()

## Properties

gint | debug-level | Read / Write
gpointer | libusb-context | Read

## Signals

void | device-added | Run Last
void | device-removed | Run Last

## Types and Values

#define | G_USB_CONTEXT_ERROR
struct | GUsbContext
struct | GUsbContextClass
enum | GUsbContextError
enum | GUsbContextFlags
| GUsbContextPrivate

## Object Hierarchy

        GObject
        ╰── GUsbContext

## Implemented Interfaces

GUsbContext implements GInitable.

## Description

This object is used to get a context that is thread safe.

## Functions

### g_usb_context_error_quark ()

    GQuark
    g_usb_context_error_quark (void);

#### Returns

Our personal error quark.

Since: 0.1.0

### g_usb_context_new ()

    GUsbContext *
    g_usb_context_new (GError **error);

Creates a new context for accessing USB devices.

#### Parameters

error | a GError, or `NULL` |

#### Returns

a new `GUsbContext` object or `NULL` on error.

Since: 0.1.0

### g_usb_context_set_flags ()

    void
    g_usb_context_set_flags (GUsbContext *context,
                             GUsbContextFlags flags);

Sets the flags to use for the context. These should be set before `g_usb_context_enumerate()` is called.

#### Parameters

context | a GUsbContext |
flags | some GUsbContextFlags, e.g. `G_USB_CONTEXT_FLAGS_AUTO_OPEN_DEVICES` |

Since: 0.2.11

### g_usb_context_get_flags ()

    GUsbContextFlags
    g_usb_context_get_flags (GUsbContext *context);

Sets the flags to use for the context.

#### Parameters

context | a GUsbContext |

#### Returns

the GUsbContextFlags, e.g. `G_USB_CONTEXT_FLAGS_AUTO_OPEN_DEVICES`

Since: 0.2.11

### g_usb_context_get_source ()

    GUsbSource *
    g_usb_context_get_source (GUsbContext *context,
                              GMainContext *main_ctx);

`g_usb_context_get_source` is deprecated and should not be used in newly-written code.

This function does nothing.

#### Parameters

context | a GUsbContext |
main_ctx | a GMainContext, or `NULL` |

#### Returns

the GUsbSource.

[transfer none]

Since: 0.1.0

### g_usb_context_get_main_context ()

    GMainContext *
    g_usb_context_get_main_context (GUsbContext *context);

Gets the internal GMainContext to use for syncronous methods. By default the value is set to the value of `g_main_context_default()`

#### Parameters

context | a GUsbContext |

#### Returns

the GMainContext.

[transfer none]

Since: 0.2.5

### g_usb_context_set_main_context ()

    void
    g_usb_context_set_main_context (GUsbContext *context,
                                    GMainContext *main_ctx);

Sets the internal GMainContext to use for syncronous methods.

#### Parameters

context | a GUsbContext |

Since: 0.2.5

### g_usb_context_enumerate ()

    void
    g_usb_context_enumerate (GUsbContext *context);

Enumerates all the USB devices and adds them to the context.

You only need to call this function once, and any subsequent calls are silently ignored.

#### Parameters

context | a GUsbContext |

Since: 0.2.2

### g_usb_context_set_debug ()

    void
    g_usb_context_set_debug (GUsbContext *context,
                             GLogLevelFlags flags);

Sets the debug flags which control what is logged to the console.

Using `G_LOG_LEVEL_INFO` will output to standard out, and everything else logs to standard error.

#### Parameters

context | a GUsbContext |
flags | a GLogLevelFlags such as `G_LOG_LEVEL_ERROR` | `G_LOG_LEVEL_INFO`, or 0 |

Since: 0.1.0

### g_usb_context_get_devices ()

    GPtrArray *
    g_usb_context_get_devices (GUsbContext *context);

#### Parameters

context | a GUsbContext |

#### Returns

a new GPtrArray of GUsbDevice's.

[transfer full][element-type GUsbDevice]

Since: 0.2.2

### g_usb_context_find_by_bus_address ()

    GUsbDevice *
    g_usb_context_find_by_bus_address (GUsbContext *context,
                                       guint8 bus,
                                       guint8 address,
                                       GError **error);

Finds a device based on its bus and address values.

#### Parameters

context | a GUsbContext |
bus | a bus number |
address | a bus address |
error | A GError or `NULL` |

#### Returns

a new GUsbDevice, or `NULL` if not found.

[transfer full]

Since: 0.2.2

### g_usb_context_find_by_vid_pid ()

    GUsbDevice *
    g_usb_context_find_by_vid_pid (GUsbContext *context,
                                   guint16 vid,
                                   guint16 pid,
                                   GError **error);

Finds a device based on its bus and address values.

#### Parameters

context | a GUsbContext |
vid | a vendor ID |
pid | a product ID |
error | A GError or `NULL` |

#### Returns

a new GUsbDevice, or `NULL` if not found.

[transfer full]

Since: 0.2.2

### g_usb_context_find_by_platform_id ()

    GUsbDevice *
    g_usb_context_find_by_platform_id (GUsbContext *context,
                                       const gchar *platform_id,
                                       GError **error);

Finds a device based on its platform id value.

#### Parameters

context | a GUsbContext |
platform_id | a platform id, e.g. "usb:00:03:03:02" |
error | A GError or `NULL` |

#### Returns

a new GUsbDevice, or `NULL` if not found.

[transfer full]

Since: 0.2.4

### g_usb_context_wait_for_replug ()

    GUsbDevice *
    g_usb_context_wait_for_replug (GUsbContext *context,
                                   GUsbDevice *device,
                                   guint timeout_ms,
                                   GError **error);

Waits for the device to be replugged. It may come back with a different VID:PID.

Warning: This is syncronous and blocks until the device comes back or the timeout triggers.

#### Parameters

context | a GUsbContext |
device | a GUsbDevice |
timeout_ms | timeout to wait |
error | A GError or `NULL` |

#### Returns

a new GUsbDevice, or `NULL` for invalid.

[transfer full]

Since: 0.2.9

## Types and Values

### G_USB_CONTEXT_ERROR

    #define G_USB_CONTEXT_ERROR		(g_usb_context_error_quark ())

### struct GUsbContext

    struct GUsbContext;

### struct GUsbContextClass

    struct GUsbContextClass {
    	GObjectClass			 parent_class;
    	void (*device_added)		(GUsbContext		*context,
    					 GUsbDevice		*device);
    	void (*device_removed)		(GUsbContext		*context,
    					 GUsbDevice		*device);
    };

### enum GUsbContextError

#### Members

G_USB_CONTEXT_ERROR_INTERNAL |  |

### enum GUsbContextFlags

The flags to use for the context.

#### Members

G_USB_CONTEXT_FLAGS_NONE |  |
G_USB_CONTEXT_FLAGS_AUTO_OPEN_DEVICES |  |

### GUsbContextPrivate

    typedef struct _GUsbContextPrivate GUsbContextPrivate;

Private GUsbContext data

## Property Details

### The `“debug-level”` property

      “debug-level”              gint

Flags: Read / Write

Allowed values: [0,3]

Default value: 0

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

      “libusb-context”           gpointer

Flags: Read

## Signal Details

### The `“device-added”` signal

    void
    user_function (GUsbContext *context,
                   GUsbDevice  *device,
                   gpointer     user_data)

This signal is emitted when a USB device is added.

#### Parameters

context | the GUsbContext instance that emitted the signal |
device | A GUsbDevice |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“device-removed”` signal

    void
    user_function (GUsbContext *context,
                   GUsbDevice  *device,
                   gpointer     user_data)

This signal is emitted when a USB device is removed.

#### Parameters

context | the GUsbContext instance that emitted the signal |
device | A GUsbDevice |
user_data | user data set when the signal handler was connected. |

Flags: Run Last