Spice USB Manager

Spice USB Manager — USB device management

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <usb-device-manager.h>

#define             SPICE_TYPE_USB_DEVICE
struct              SpiceUsbDeviceManager;
struct              SpiceUsbDeviceManagerClass;

SpiceUsbDeviceManager * spice_usb_device_manager_get    (SpiceSession *session,
                                                         GError **err);
GPtrArray *         spice_usb_device_manager_get_devices
                                                        (SpiceUsbDeviceManager *manager);
gboolean            spice_usb_device_manager_is_device_connected
                                                        (SpiceUsbDeviceManager *manager,
                                                         SpiceUsbDevice *device);
void                spice_usb_device_manager_disconnect_device
                                                        (SpiceUsbDeviceManager *manager,
                                                         SpiceUsbDevice *device);
gchar *             spice_usb_device_get_description    (SpiceUsbDevice *device,
                                                         const gchar *format);
                    SpiceUsbDevice;

Object Hierarchy

  GObject
   +----SpiceUsbDeviceManager
  GBoxed
   +----SpiceUsbDevice

Implemented Interfaces

SpiceUsbDeviceManager implements GInitable.

Properties

  "auto-connect"             gboolean              : Read / Write
  "auto-connect-filter"      gchar*                : Read / Write / Construct
  "session"                  SpiceSession*         : Read / Write / Construct Only

Signals

  "auto-connect-failed"                            : Run First
  "device-added"                                   : Run First
  "device-removed"                                 : Run First

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.

Details

SPICE_TYPE_USB_DEVICE

#define             SPICE_TYPE_USB_DEVICE

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

Class structure for SpiceUsbDeviceManager.

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.

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.

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

manager :

the SpiceUsbDeviceManager manager

Returns :

a GPtrArray array of SpiceUsbDevice. [element-type SpiceUsbDevice][transfer full]

spice_usb_device_manager_is_device_connected ()

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

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

manager :

the SpiceUsbDeviceManager manager

device :

a SpiceUsbDevice to disconnect

Returns :

TRUE if device has an associated USB redirection channel

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

device :

SpiceUsbDevice to get the description of

format :

an optionnal printf() format string with positional parameters

Returns :

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

SpiceUsbDevice

typedef struct _SpiceUsbDevice SpiceUsbDevice;

Property Details

The "auto-connect" property

  "auto-connect"             gboolean              : Read / Write

Auto connect plugged in USB devices.

Default value: FALSE


The "auto-connect-filter" property

  "auto-connect-filter"      gchar*                : Read / Write / Construct

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 are themselves are concatonated 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.

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


The "session" property

  "session"                  SpiceSession*         : Read / Write / Construct Only

SpiceSession this SpiceUsbDeviceManager is associated with

Signal Details

The "auto-connect-failed" signal

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

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.

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.

The "device-added" signal

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

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

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.

The "device-removed" signal

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

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

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.