Spice Session

## Spice Session Spice Session — handles connection details, and active channels |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <spice-session.h>

                        SpiceSession;
                        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);
    gboolean            spice_session_get_read_only         (SpiceSession *session);
    gboolean            spice_session_has_channel_type      (SpiceSession *session,
                                                             gint type);

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

    enum                SpiceClientError;
    #define             SPICE_CLIENT_ERROR
    GQuark              spice_client_error_quark            (void);

## Object Hierarchy

      GObject
       +----SpiceSession

      GEnum
       +----SpiceSessionMigration

      GFlags
       +----SpiceSessionVerify

## Properties

      "ca"                       GByteArray*           : Read / Write
      "ca-file"                  gchar*                : Read / Write
      "cache-size"               gint                  : 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-audio"             gboolean              : Read / Write / Construct
      "enable-smartcard"         gboolean              : Read / Write
      "enable-usbredir"          gboolean              : Read / Write / Construct
      "glz-window-size"          gint                  : Read / Write
      "host"                     gchar*                : Read / Write / Construct
      "inhibit-keyboard-grab"    gboolean              : Read / Write
      "migration-state"          SpiceSessionMigration  : Read
      "name"                     gchar*                : Read
      "password"                 gchar*                : Read / Write
      "port"                     gchar*                : Read / Write
      "protocol"                 gint                  : Read / Write / Construct
      "proxy"                    gchar*                : Read / Write
      "pubkey"                   GByteArray*           : Read / Write
      "read-only"                gboolean              : Read / Write / Construct
      "secure-channels"          GStrv                 : Read / Write
      "smartcard-certificates"   GStrv                 : Read / Write
      "smartcard-db"             gchar*                : Read / Write
      "tls-port"                 gchar*                : Read / Write
      "uri"                      gchar*                : Read / Write
      "uuid"                     gpointer              : Read
      "verify"                   SpiceSessionVerify    : Read / Write / Construct

## Signals

      "channel-destroy"                                : Run First
      "channel-new"                                    : Run First
      "mm-time-reset"                                  : 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

### SpiceSession

    typedef struct _SpiceSession SpiceSession;

### SpiceSessionClass

    typedef struct {
        GObjectClass parent_class;

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

### 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.

If `fd` is -1, a valid fd will be requested later via the SpiceChannel::open-fd signal.

`fd` : | a file descriptor (socket) or -1

### 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]

### spice_session_get_read_only ()

    gboolean            spice_session_get_read_only         (SpiceSession *session);

`session` : | a SpiceSession
Returns : | wether the `session` is in read-only mode.

### spice_session_has_channel_type ()

    gboolean            spice_session_has_channel_type      (SpiceSession *session,
                                                             gint type);

See if there is a `type` channel in the channels associated with this `session`.

`session` : | a SpiceSession
Returns : | TRUE if a `type` channel is available otherwise FALSE.

### enum SpiceSessionMigration

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

Session migration state.

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

### enum SpiceSessionVerify

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

Peer certificate verification parameters flags.

`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

### 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

### enum SpiceClientError

    typedef enum {
        SPICE_CLIENT_ERROR_FAILED,
        SPICE_CLIENT_USB_DEVICE_REJECTED,
        SPICE_CLIENT_USB_DEVICE_LOST,
    } SpiceClientError;

Error codes returned by spice-client API.

`SPICE_CLIENT_ERROR_FAILED` | generic error code
`SPICE_CLIENT_USB_DEVICE_REJECTED` |
`SPICE_CLIENT_USB_DEVICE_LOST` |

### SPICE_CLIENT_ERROR

    #define SPICE_CLIENT_ERROR spice_client_error_quark()

### spice_client_error_quark ()

    GQuark              spice_client_error_quark            (void);

## Property Details

### The `"ca"` property

      "ca"                       GByteArray*           : Read / Write

CA certificates in PEM format. The text data can contain several CA certificates identified by:

-----BEGIN CERTIFICATE----- ... (CA certificate in base64 encoding) ... -----END CERTIFICATE-----

Since 0.15

### 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 `"cache-size"` property

      "cache-size"               gint                  : Read / Write

Images cache size. If 0, don't set.

Allowed values: >= 0

Default value: 0

Since 0.9

### 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 string array 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-audio"` property

      "enable-audio"             gboolean              : Read / Write / Construct

If set to TRUE, the audio channels will be enabled for playback and recording.

Default value: TRUE

Since 0.8

### 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 / Construct

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

Default value: TRUE

Since 0.8

### The `"glz-window-size"` property

      "glz-window-size"          gint                  : Read / Write

Glz window size. If 0, don't set.

Allowed values: [0,134217728]

Default value: 0

Since 0.9

### The `"host"` property

      "host"                     gchar*                : Read / Write / Construct

URL of the SPICE host to connect to

Default value: "localhost"

### The `"inhibit-keyboard-grab"` property

      "inhibit-keyboard-grab"    gboolean              : Read / Write

Request that SpiceDisplays don't grab the keyboard.

Default value: FALSE

### 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 `"name"` property

      "name"                     gchar*                : Read

Spice server name.

Default value: NULL

Since 0.11

### 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 `"proxy"` property

      "proxy"                    gchar*                : Read / Write

URI to the proxy server to use when doing network connection. of the form [protocol://]<host>[:port]

Default value: NULL

Since 0.17

### The `"pubkey"` property

      "pubkey"                   GByteArray*           : Read / Write

Public key to check.

### The `"read-only"` property

      "read-only"                gboolean              : Read / Write / Construct

Whether this connection is read-only mode.

Default value: FALSE

Since 0.8

### The `"secure-channels"` property

      "secure-channels"          GStrv                 : Read / Write

A string array of channel types to be secured.

Since 0.20

### 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 `"uuid"` property

      "uuid"                     gpointer              : Read

Spice server uuid.

Since 0.11

### 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.

### The `"mm-time-reset"` signal

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

The "mm-time-reset" is emitted when we identify discontinuity in mm-time

Since 0.20

`session` : | the session that emitted the signal
`user_data` : | user data set when the signal handler was connected.

## See Also

SpiceChannel, and the GTK widget SpiceDisplay