Spice Session

Spice Session — handles connection details, and active channels

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <spice-session.h>

struct              SpiceSession;
struct              SpiceSessionClass;
SpiceSession *      spice_session_new                   (void);
gboolean            spice_session_connect               (SpiceSession *session);
gboolean            spice_session_open_fd               (SpiceSession *session,
                                                         int fd);
void                spice_session_disconnect            (SpiceSession *session);
GList *             spice_session_get_channels          (SpiceSession *session);

enum                SpiceSessionMigration;
enum                SpiceSessionVerify;
GOptionGroup *      spice_get_option_group              (void);
void                spice_set_session_option            (SpiceSession *session);

Object Hierarchy

  GObject
   +----SpiceSession
  GEnum
   +----SpiceSessionMigration
  GFlags
   +----SpiceSessionVerify

Properties

  "ca-file"                  gchar*                : Read / Write
  "cert-subject"             gchar*                : Read / Write
  "ciphers"                  gchar*                : Read / Write
  "client-sockets"           gboolean              : Read / Write
  "color-depth"              gint                  : Read / Write
  "disable-effects"          GStrv                 : Read / Write
  "enable-smartcard"         gboolean              : Read / Write
  "enable-usbredir"          gboolean              : Read / Write
  "host"                     gchar*                : Read / Write / Construct
  "migration-state"          SpiceSessionMigration  : Read
  "password"                 gchar*                : Read / Write
  "port"                     gchar*                : Read / Write
  "protocol"                 gint                  : Read / Write / Construct
  "pubkey"                   GByteArray*           : Read / Write
  "smartcard-certificates"   GStrv                 : Read / Write
  "smartcard-db"             gchar*                : Read / Write
  "tls-port"                 gchar*                : Read / Write
  "uri"                      gchar*                : Read / Write
  "verify"                   SpiceSessionVerify    : Read / Write / Construct

Signals

  "channel-destroy"                                : Run First
  "channel-new"                                    : Run First

Description

The SpiceSession class handles all the SpiceChannel connections. It's also the class that contains connections informations, such as "host" and "port".

You can simply set the property "uri" to something like "spice://127.0.0.1?port=5930" to configure your connection details.

You may want to connect to "channel-new" signal, to be informed of the availability of channels and to interact with them.

For example, when the SpiceInputsChannel is available and get the event SPICE_CHANNEL_OPENED, you can send key events with spice_inputs_key_press(). When the SpiceMainChannel is available, you can start sharing the clipboard... .

Once SpiceSession properties set, you can call spice_session_connect() to start connecting and communicating with a Spice server.

Details

struct SpiceSession

struct SpiceSession;

struct SpiceSessionClass

struct SpiceSessionClass {
    GObjectClass parent_class;

    /* signals */
    void (*channel_new)(SpiceSession *session, SpiceChannel *channel);
    void (*channel_destroy)(SpiceSession *session, SpiceChannel *channel);
};

spice_session_new ()

SpiceSession *      spice_session_new                   (void);

Creates a new Spice session.

Returns :

a new SpiceSession

spice_session_connect ()

gboolean            spice_session_connect               (SpiceSession *session);

Open the session using the "host" and "port".

Returns :

FALSE if the connection failed.

spice_session_open_fd ()

gboolean            spice_session_open_fd               (SpiceSession *session,
                                                         int fd);

Open the session using the provided fd socket file descriptor. This is useful if you create the fd yourself, for example to setup a SSH tunnel.

fd :

a file descriptor

spice_session_disconnect ()

void                spice_session_disconnect            (SpiceSession *session);

Disconnect the session, and destroy all channels.


spice_session_get_channels ()

GList *             spice_session_get_channels          (SpiceSession *session);

Get the list of current channels associated with this session.

session :

a SpiceSession

Returns :

a GList of unowned SpiceChannel channels. [element-type SpiceChannel][transfer container]

enum SpiceSessionMigration

typedef enum {
    SPICE_SESSION_MIGRATION_NONE,
    SPICE_SESSION_MIGRATION_SWITCHING,
    SPICE_SESSION_MIGRATION_MIGRATING,
} SpiceSessionMigration;

SPICE_SESSION_MIGRATION_NONE: no migration going on SPICE_SESSION_MIGRATION_SWITCHING: the session is switching host (destroy and reconnect) SPICE_SESSION_MIGRATION_MIGRATING: the session is migrating seamlessly (reconnect)

Session migration state.


enum SpiceSessionVerify

typedef enum {
    SPICE_SESSION_VERIFY_PUBKEY   = (1 << 0),
    SPICE_SESSION_VERIFY_HOSTNAME = (1 << 1),
    SPICE_SESSION_VERIFY_SUBJECT  = (1 << 2),
} SpiceSessionVerify;

SPICE_SESSION_VERIFY_PUBKEY: verify certificate public key matching SPICE_SESSION_VERIFY_HOSTNAME: verify certificate hostname matching SPICE_SESSION_VERIFY_SUBJECT: verify certificate subject matching

Peer certificate verification parameters flags.


spice_get_option_group ()

GOptionGroup *      spice_get_option_group              (void);

Returns :

a GOptionGroup for the commandline arguments specific to Spice. You have to call spice_set_session_option() after to set the options on a SpiceSession. [transfer full]

spice_set_session_option ()

void                spice_set_session_option            (SpiceSession *session);

Set various properties on session, according to the commandline arguments given to spice_get_option_group() option group.

session :

a SpiceSession to set option upon

Property Details

The "ca-file" property

  "ca-file"                  gchar*                : Read / Write

File holding the CA certificates for the host the client is connecting to

Default value: NULL


The "cert-subject" property

  "cert-subject"             gchar*                : Read / Write

Certificate subject to check.

Default value: NULL


The "ciphers" property

  "ciphers"                  gchar*                : Read / Write

SSL cipher list.

Default value: NULL


The "client-sockets" property

  "client-sockets"           gboolean              : Read / Write

Sockets are provided by the client.

Default value: FALSE


The "color-depth" property

  "color-depth"              gint                  : Read / Write

Display color depth to set on new display channels. If 0, don't set.

Allowed values: [0,32]

Default value: 0

Since 0.7


The "disable-effects" property

  "disable-effects"          GStrv                 : Read / Write

A comma-separated list of effects to disable. The settings will be applied on new display channels. The following effets can be disabled "wallpaper", "font-smooth", "animation", and "all", which will disable all the effects. If NULL, don't apply changes.

Since 0.7


The "enable-smartcard" property

  "enable-smartcard"         gboolean              : Read / Write

If set to TRUE, the smartcard channel will be enabled and smartcard events will be forwarded to the guest

Default value: FALSE

Since 0.7


The "enable-usbredir" property

  "enable-usbredir"          gboolean              : Read / Write

If set to TRUE, the usbredir channel will be enabled and USB devices can be redirected to the guest

Default value: TRUE

Since 0.7


The "host" property

  "host"                     gchar*                : Read / Write / Construct

URL of the SPICE host to connect to

Default value: "localhost"


The "migration-state" property

  "migration-state"          SpiceSessionMigration  : Read

SpiceSessionMigration bit field indicating if a migration is in progress

Default value: SPICE_SESSION_MIGRATION_NONE


The "password" property

  "password"                 gchar*                : Read / Write

TLS password to use

Default value: NULL


The "port" property

  "port"                     gchar*                : Read / Write

Port to connect to for unencrypted sessions

Default value: NULL


The "protocol" property

  "protocol"                 gint                  : Read / Write / Construct

Version of the SPICE protocol to use

Allowed values: [1,2]

Default value: 2


The "pubkey" property

  "pubkey"                   GByteArray*           : Read / Write

Public key to check.


The "smartcard-certificates" property

  "smartcard-certificates"   GStrv                 : Read / Write

This property is used when one wants to simulate a smartcard with no hardware smartcard reader. If it's set to a NULL-terminated string array containing the names of 3 valid certificates, these will be used to simulate a smartcard in the guest see_also: spice_smartcard_manager_insert_card()

Since 0.7


The "smartcard-db" property

  "smartcard-db"             gchar*                : Read / Write

Path to the NSS certificate database containing the certificates to use to simulate a software smartcard

Default value: NULL

Since 0.7


The "tls-port" property

  "tls-port"                 gchar*                : Read / Write

Port to connect to for TLS sessions

Default value: NULL


The "uri" property

  "uri"                      gchar*                : Read / Write

URI of the SPICE host to connect to. The URI is of the form spice://hostname?port=XXX or spice://hostname?tls_port=XXX

Default value: NULL


The "verify" property

  "verify"                   SpiceSessionVerify    : Read / Write / Construct

SpiceSessionVerify bit field indicating which parts of the peer certificate should be checked

Default value: SPICE_SESSION_VERIFY_HOSTNAME

Signal Details

The "channel-destroy" signal

void                user_function                      (SpiceSession *session,
                                                        SpiceChannel *channel,
                                                        gpointer      user_data)      : Run First

The "channel-destroy" signal is emitted each time a SpiceChannel is destroyed.

session :

the session that emitted the signal

channel :

the destroyed SpiceChannel

user_data :

user data set when the signal handler was connected.

The "channel-new" signal

void                user_function                      (SpiceSession *session,
                                                        SpiceChannel *channel,
                                                        gpointer      user_data)      : Run First

The "channel-new" signal is emitted each time a SpiceChannel is created.

session :

the session that emitted the signal

channel :

the new SpiceChannel

user_data :

user data set when the signal handler was connected.

See Also

SpiceChannel, and the GTK widget SpiceDisplay