Spice USB Manager: Spice-GTK Reference Manual

Stability Level

Stable, unless otherwise indicated

Functions

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 ()
gboolean	spice_usb_device_manager_is_redirecting ()
gboolean	spice_usb_device_manager_can_redirect_device ()
void	spice_usb_device_manager_connect_device_async ()
gboolean	spice_usb_device_manager_connect_device_finish ()
void	spice_usb_device_manager_disconnect_device ()
void	spice_usb_device_manager_disconnect_device_async ()
gboolean	spice_usb_device_manager_disconnect_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
gint	free-channels	Read
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 <spice-client.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_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
err	a return location for GError, or `NULL`.	[allow-none]

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

Finds devices associated with the 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);

Finds devices associated with the manager complying with the filter

Parameters

manager	the SpiceUsbDeviceManager manager
filter	filter string for selecting which devices to return, see “auto-connect-filter” for the filter 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);

Finds if the device is connected.

Parameters

manager	the SpiceUsbDeviceManager manager
device	a SpiceUsbDevice

Returns

TRUE if device has an associated USB redirection channel

spice_usb_device_manager_is_redirecting ()

gboolean
spice_usb_device_manager_is_redirecting
                               (SpiceUsbDeviceManager *self);

Checks whether a device is being redirected

Parameters

self

the SpiceUsbDeviceManager manager

Returns

TRUE if device redirection negotiation flow is in progress

Since: 0.32

spice_usb_device_manager_can_redirect_device ()

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

Checks whether it is possible to redirect the device .

Parameters

self	the SpiceUsbDeviceManager manager
device	a SpiceUsbDevice to disconnect
err	a return location for a GError, or `NULL`.	[allow-none]

Returns

TRUE if device can be redirected

spice_usb_device_manager_connect_device_async ()

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

Asynchronously connects the device . When completed, callback will be called. Then it is possible to call spice_usb_device_manager_connect_device_finish() to get the result of the operation.

Parameters

self	a SpiceUsbDeviceManager.
device	a SpiceUsbDevice to redirect
cancellable	optional GCancellable object, `NULL` to ignore.	[allow-none]
callback	a GAsyncReadyCallback to call when the request is satisfied
user_data	the data to pass to callback function

spice_usb_device_manager_connect_device_finish ()

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

Finishes an async operation. See spice_usb_device_manager_connect_device_async().

Parameters

self	a SpiceUsbDeviceManager.
res	a GAsyncResult
err	a return location for a GError, or `NULL`.	[allow-none]

Returns

TRUE if connection is successful

spice_usb_device_manager_disconnect_device ()

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

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

Disconnects the device .

Parameters

manager	the SpiceUsbDeviceManager manager
device	a SpiceUsbDevice to disconnect

spice_usb_device_manager_disconnect_device_async ()

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

spice_usb_device_manager_disconnect_device_finish ()

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

Finishes an async operation. See spice_usb_device_manager_disconnect_device_async().

Parameters

self	a SpiceUsbDeviceManager.
res	a GAsyncResult
err	a return location for a GError, or `NULL`.	[allow-none]

Returns

TRUE if disconnection is successful

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

Finds the libusb_device associated with the 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

`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` ()	Signal class handler for the “device_error” signal.

SpiceUsbDevice

typedef struct _SpiceUsbDevice SpiceUsbDevice;

The SpiceUsbDevice struct is opaque and cannot be accessed directly.

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 `“free-channels”` property

  “free-channels”            gint

The number of available channels for redirecting USB devices.

Flags: Read

Allowed values: >= 0

Default value: 0

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