Spice USB Manager: Spice-GTK Reference Manual

## Spice USB Manager Spice USB Manager — USB device management |

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | SPICE_TYPE_USB_DEVICE
SpiceUsbDeviceManager * | spice_usb_device_manager_get ()
GPtrArray * | spice_usb_device_manager_get_devices ()
GPtrArray * | spice_usb_device_manager_get_devices_with_filter ()
gboolean | spice_usb_device_manager_is_device_connected ()
void | spice_usb_device_manager_disconnect_device ()
gboolean | spice_usb_device_manager_can_redirect_device ()
void | spice_usb_device_manager_connect_device_async ()
gboolean | spice_usb_device_manager_connect_device_finish ()
gchar * | spice_usb_device_get_description ()
gconstpointer | spice_usb_device_get_libusb_device ()

## Properties

gboolean | auto-connect | Read / Write
gchar * | auto-connect-filter | Read / Write / Construct
gchar * | redirect-on-connect | Read / Write
SpiceSession * | session | Read / Write / Construct Only

## Signals

void | auto-connect-failed | Run First
void | device-added | Run First
void | device-error | Run First
void | device-removed | Run First

## Types and Values

struct | SpiceUsbDeviceManager
struct | SpiceUsbDeviceManagerClass
| SpiceUsbDevice

## Object Hierarchy

        GBoxed
        ╰── SpiceUsbDevice
        GObject
        ╰── SpiceUsbDeviceManager

## Implemented Interfaces

SpiceUsbDeviceManager implements GInitable.

## Includes

    #include <usb-device-manager.h>

## Description

SpiceUsbDeviceManager monitors USB redirection channels and USB devices plugging/unplugging. If “auto-connect” is set to `TRUE`, it will automatically connect newly plugged USB devices to available channels.

There should always be a 1:1 relation between SpiceUsbDeviceManager objects and SpiceSession objects. Therefor there is no spice_usb_device_manager_new, instead there is `spice_usb_device_manager_get()` which ensures this 1:1 relation.

## Functions

### SPICE_TYPE_USB_DEVICE

    #define SPICE_TYPE_USB_DEVICE                    (spice_usb_device_get_type())

### spice_usb_device_manager_get ()

    SpiceUsbDeviceManager *
    spice_usb_device_manager_get (SpiceSession *session,
                                  GError **err);

Gets the SpiceUsbDeviceManager associated with the passed in SpiceSession. A new SpiceUsbDeviceManager instance will be created the first time this function is called for a certain SpiceSession.

Note that this function returns a weak reference, which should not be used after the SpiceSession itself has been unref-ed by the caller.

#### Parameters

session | SpiceSession for which to get the SpiceUsbDeviceManager |

#### Returns

a weak reference to the SpiceUsbDeviceManager associated with the passed in SpiceSession.

[transfer none]

### spice_usb_device_manager_get_devices ()

    GPtrArray *
    spice_usb_device_manager_get_devices (SpiceUsbDeviceManager *manager);

#### Parameters

manager | the SpiceUsbDeviceManager manager |

#### Returns

a `GPtrArray` array of `SpiceUsbDevice`.

[element-type SpiceUsbDevice][transfer full]

### spice_usb_device_manager_get_devices_with_filter ()

    GPtrArray *
    spice_usb_device_manager_get_devices_with_filter
                                   (SpiceUsbDeviceManager *manager,
                                    const gchar *filter);

#### Parameters

manager | the SpiceUsbDeviceManager manager |
filter | filter string for selecting which devices to return, see “auto-connect-filter” for the f ilter string format. | [allow-none]

#### Returns

a `GPtrArray` array of `SpiceUsbDevice`.

[element-type SpiceUsbDevice][transfer full]

Since: 0.20

### spice_usb_device_manager_is_device_connected ()

    gboolean
    spice_usb_device_manager_is_device_connected
                                   (SpiceUsbDeviceManager *manager,
                                    SpiceUsbDevice *device);

#### Parameters

manager | the SpiceUsbDeviceManager manager |
device | a SpiceUsbDevice |

#### Returns

`TRUE` if `device` has an associated USB redirection channel

### spice_usb_device_manager_disconnect_device ()

    void
    spice_usb_device_manager_disconnect_device
                                   (SpiceUsbDeviceManager *manager,
                                    SpiceUsbDevice *device);

#### Parameters

manager | the SpiceUsbDeviceManager manager |
device | a SpiceUsbDevice to disconnect |

#### Returns

`TRUE` if `device` has an associated USB redirection channel

### spice_usb_device_manager_can_redirect_device ()

    gboolean
    spice_usb_device_manager_can_redirect_device
                                   (SpiceUsbDeviceManager *self,
                                    SpiceUsbDevice *device,
                                    GError **err);

### spice_usb_device_manager_connect_device_async ()

    void
    spice_usb_device_manager_connect_device_async
                                   (SpiceUsbDeviceManager *manager,
                                    SpiceUsbDevice *device,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

#### Parameters

manager | the SpiceUsbDeviceManager manager |
device | a SpiceUsbDevice to redirect |
cancellable | a GCancellable or NULL |
callback | a GAsyncReadyCallback to call when the request is satisfied |
user_data | data to pass to callback |

### spice_usb_device_manager_connect_device_finish ()

    gboolean
    spice_usb_device_manager_connect_device_finish
                                   (SpiceUsbDeviceManager *self,
                                    GAsyncResult *res,
                                    GError **err);

### spice_usb_device_get_description ()

    gchar *
    spice_usb_device_get_description (SpiceUsbDevice *device,
                                      const gchar *format);

Get a string describing the device which is suitable as a description of the device for the end user. The returned string should be freed with `g_free()` when no longer needed.

The `format` positional parameters are the following:

- '%`1`$s' manufacturer

- '%`2`$s' product

- '%`3`$s' descriptor (a [vendor_id:product_id] string)

- '%`4`$d' bus

- '%`5`$d' address

(the default format string is "%`s` %`s` %`s` at %`d`-%`d`")

#### Parameters

device | SpiceUsbDevice to get the description of |
format | an optional `printf()` format string with positional parameters. | [allow-none]

#### Returns

a newly-allocated string holding the description, or `NULL` if failed

### spice_usb_device_get_libusb_device ()

    gconstpointer
    spice_usb_device_get_libusb_device (const SpiceUsbDevice *device);

#### Parameters

device | SpiceUsbDevice to get the descriptor information of |

#### Returns

the `libusb_device` associated to `SpiceUsbDevice`.

[transfer none]

Since: 0.27

## Types and Values

### struct SpiceUsbDeviceManager

    struct SpiceUsbDeviceManager;

The SpiceUsbDeviceManager struct is opaque and should not be accessed directly.

### struct SpiceUsbDeviceManagerClass

    struct SpiceUsbDeviceManagerClass {
        GObjectClass parent_class;

        /* signals */
        void (*device_added) (SpiceUsbDeviceManager *manager,
                              SpiceUsbDevice *device);
        void (*device_removed) (SpiceUsbDeviceManager *manager,
                                SpiceUsbDevice *device);
        void (*auto_connect_failed) (SpiceUsbDeviceManager *manager,
                                     SpiceUsbDevice *device, GError *error);
        void (*device_error) (SpiceUsbDeviceManager *manager,
                              SpiceUsbDevice *device, GError *error);
    };

Class structure for SpiceUsbDeviceManager.

#### Members

GObjectClass `parent_class`; | Parent class. |
`device_added` () | Signal class handler for the “device-added” signal. |
`device_removed` () | Signal class handler for the “device-removed” signal. |
`auto_connect_failed` () | Signal class handler for the “auto-connect-failed” signal. |
`device_error` () |  |

### SpiceUsbDevice

    typedef struct _SpiceUsbDevice SpiceUsbDevice;

## Property Details

### The `“auto-connect”` property

      “auto-connect”             gboolean

Set this to TRUE to automatically redirect newly plugged in device.

Note when SpiceGtkSession's auto-usbredir property is TRUE, this property is controlled by SpiceGtkSession.

Flags: Read / Write

Default value: FALSE

### The `“auto-connect-filter”` property

      “auto-connect-filter”      gchar *

Set a string specifying a filter to use to determine which USB devices to autoconnect when plugged in, a filter consists of one or more rules. Where each rule has the form of:

`class` ,`vendor` ,`product` ,`version` ,`allow`

Use -1 for `class` /`vendor` /`product` /`version` to accept any value.

And the rules themselves are concatenated like this:

`rule1` |`rule2` |`rule3`

The default setting filters out HID (class 0x03) USB devices from auto connect and auto connects anything else. Note the explicit allow rule at the end, this is necessary since by default all devices without a matching filter rule will not auto-connect.

Filter strings in this format can be easily created with the RHEV-M USB filter editor tool.

Flags: Read / Write / Construct

Default value: "0x03,-1,-1,-1,0|-1,-1,-1,-1,1"

### The `“redirect-on-connect”` property

      “redirect-on-connect”      gchar *

Set a string specifying a filter selecting USB devices to automatically redirect after a Spice connection has been established.

See “auto-connect-filter” for the filter string format.

Flags: Read / Write

Default value: NULL

### The `“session”` property

      “session”                  SpiceSession *

SpiceSession this SpiceUsbDeviceManager is associated with

Flags: Read / Write / Construct Only

## Signal Details

### The `“auto-connect-failed”` signal

    void
    user_function (SpiceUsbDeviceManager *manager,
                   SpiceUsbDevice        *device,
                   GError                *error,
                   gpointer               user_data)

The “auto-connect-failed” signal is emitted whenever the auto-connect property is true, and a newly plugged in device could not be auto-connected.

#### Parameters

manager | the SpiceUsbDeviceManager that emitted the signal |
device | SpiceUsbDevice boxed object corresponding to the device which failed to auto connect |
error | GError describing the reason why the autoconnect failed |
user_data | user data set when the signal handler was connected. |

Flags: Run First

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

    void
    user_function (SpiceUsbDeviceManager *manager,
                   SpiceUsbDevice        *device,
                   gpointer               user_data)

The “device-added” signal is emitted whenever a new USB device has been plugged in.

#### Parameters

manager | the SpiceUsbDeviceManager that emitted the signal |
device | SpiceUsbDevice boxed object corresponding to the added device |
user_data | user data set when the signal handler was connected. |

Flags: Run First

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

    void
    user_function (SpiceUsbDeviceManager *manager,
                   SpiceUsbDevice        *device,
                   GError                *error,
                   gpointer               user_data)

The “device-error” signal is emitted whenever an error happens which causes a device to no longer be available to the guest.

#### Parameters

manager | SpiceUsbDeviceManager that emitted the signal |
device | SpiceUsbDevice boxed object corresponding to the device which has an error |
error | GError describing the error |
user_data | user data set when the signal handler was connected. |

Flags: Run First

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

    void
    user_function (SpiceUsbDeviceManager *manager,
                   SpiceUsbDevice        *device,
                   gpointer               user_data)

The “device-removed” signal is emitted whenever an USB device has been removed.

#### Parameters

manager | the SpiceUsbDeviceManager that emitted the signal |
device | SpiceUsbDevice boxed object corresponding to the removed device |
user_data | user data set when the signal handler was connected. |

Flags: Run First