Spice Session: Spice-GTK Reference Manual

## Spice Session

Spice Session — handles connection details, and active channels

## Stability Level

Stable, unless otherwise indicated

## Functions

SpiceSession * | spice_session_new ()
gboolean | spice_session_connect ()
gboolean | spice_session_open_fd ()
void | spice_session_disconnect ()
GList * | spice_session_get_channels ()
gboolean | spice_session_get_read_only ()
gboolean | spice_session_has_channel_type ()
SpiceURI * | spice_session_get_proxy_uri ()
gboolean | spice_session_is_for_migration ()
GOptionGroup * | spice_get_option_group ()
void | spice_set_session_option ()
GQuark | spice_client_error_quark ()

## Properties

GByteArray * | ca | Read / Write
char * | ca-file | Read / Write
int | cache-size | Read / Write
char * | cert-subject | Read / Write
char * | ciphers | Read / Write
gboolean | client-sockets | Read / Write
int | color-depth | Read / Write
GStrv | disable-effects | Read / Write
gboolean | enable-audio | Read / Write / Construct
gboolean | enable-smartcard | Read / Write
gboolean | enable-usbredir | Read / Write / Construct
gboolean | gl-scanout | Read / Write / Construct
int | glz-window-size | Read / Write
char * | host | Read / Write / Construct
gboolean | inhibit-keyboard-grab | Read / Write
SpiceSessionMigration | migration-state | Read
char * | name | Read
char * | password | Read / Write
char * | port | Read / Write
SpiceImageCompress | preferred-compression | Read / Write
int | protocol | Read / Write / Construct
char * | proxy | Read / Write
GByteArray * | pubkey | Read / Write
gboolean | read-only | Read / Write / Construct
GStrv | secure-channels | Read / Write
gboolean | share-dir-ro | Read / Write / Construct
char * | shared-dir | Read / Write / Construct
GStrv | smartcard-certificates | Read / Write
char * | smartcard-db | Read / Write
char * | tls-port | Read / Write
char * | unix-path | Read / Write / Construct
char * | uri | Read / Write
char * | username | Read / Write
gpointer | uuid | Read
SpiceSessionVerify | verify | Read / Write / Construct
GObject * | webdav-server | Read

## Signals

void | channel-destroy | Run First
void | channel-new | Run First
void | disconnected | Run First
void | mm-time-reset | Run First

## Types and Values

| SpiceSession
| SpiceSessionClass
enum | SpiceSessionMigration
enum | SpiceSessionVerify
enum | SpiceClientError
#define | SPICE_CLIENT_ERROR

## Object Hierarchy

        GObject
        ╰── SpiceSession

## Includes

    #include <spice-client.h>

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

## Functions

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

#### Parameters

session | a SpiceSession |

#### Returns

`FALSE` if the session state is invalid for connection request. `TRUE` if the connection is initiated. To know whether the connection is established, you must watch for channels creation (“channel-new”) and the channels state (“channel-event”).

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

Note however that additional sockets will be needed by all the channels created for `session` so users of this API should hook into SpiceChannel::open-fd signal for each channel they are interested in, and create and pass a new socket to the channel using spice_channel_open_fd, in the signal callback.

If `fd` is -1, a valid fd will be requested later via the SpiceChannel::open-fd signal. Typically, you would want to just pass -1 as `fd` this call since you will have to hook to SpiceChannel::open-fd signal anyway.

#### Parameters

session | a SpiceSession |
fd | a file descriptor (socket) or -1 |

#### Returns

`TRUE` on success.

### spice_session_disconnect ()

    void
    spice_session_disconnect (SpiceSession *session);

Disconnect the `session` , and destroy all channels.

#### Parameters

session | a SpiceSession |

### spice_session_get_channels ()

    GList *
    spice_session_get_channels (SpiceSession *session);

Get the list of current channels associated with this `session` .

#### Parameters

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

Checks whether the `session` is read-only.

#### Parameters

session | a SpiceSession |

#### Returns

whether 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` .

#### Parameters

session | a SpiceSession |
type | a “channel-type” |

#### Returns

TRUE if a `type` channel is available otherwise FALSE.

### spice_session_get_proxy_uri ()

    SpiceURI *
    spice_session_get_proxy_uri (SpiceSession *session);

Gets the `session` proxy uri.

#### Parameters

session | a SpiceSession |

#### Returns

the session proxy SpiceURI or `NULL`.

[transfer none]

Since: 0.24

### spice_session_is_for_migration ()

    gboolean
    spice_session_is_for_migration (SpiceSession *session);

During seamless migration, channels may be created to establish a connection with the target, but they are temporary and should only handle migration steps. In order to avoid other interactions with the client, channels should check this value.

#### Parameters

session | a Spice session |

#### Returns

`TRUE` if the session is a copy created during migration

Since: 0.27

### spice_get_option_group ()

    GOptionGroup *
    spice_get_option_group (void);

Gets commandline options.

Bindings for other languages are available since 0.32

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

#### Parameters

session | a SpiceSession to set option upon |

### spice_client_error_quark ()

    GQuark
    spice_client_error_quark (void);

Gets a GQuark representing the string "spice-client-error-quark"

#### Returns

the GQuark representing the string.

## Types and Values

### SpiceSession

    typedef struct _SpiceSession SpiceSession;

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

### SpiceSessionClass

    typedef struct {
        GObjectClass parent_class;

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

Class structure for SpiceSession.

#### Members

`channel_new` () | Signal class handler for the “channel_new” signal. |
`channel_destroy` () | Signal class handler for the “channel_destroy” signal. |

### enum SpiceSessionMigration

Session migration state.

#### Members

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) |
SPICE_SESSION_MIGRATION_CONNECTING | the migration is connecting to destination (Since: 0.27) |

### enum SpiceSessionVerify

Peer certificate verification parameters flags.

#### Members

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 |

### enum SpiceClientError

Error codes returned by spice-client API.

#### Members

SPICE_CLIENT_ERROR_FAILED | generic error code |
SPICE_CLIENT_ERROR_USB_DEVICE_REJECTED | device redirection rejected by host |
SPICE_CLIENT_ERROR_USB_DEVICE_LOST | device disconnected (fatal IO error) |
SPICE_CLIENT_ERROR_AUTH_NEEDS_PASSWORD | password is required |
SPICE_CLIENT_ERROR_AUTH_NEEDS_USERNAME | username is required |
SPICE_CLIENT_ERROR_AUTH_NEEDS_PASSWORD_AND_USERNAME | password and username are required |
SPICE_CLIENT_ERROR_USB_SERVICE | USB service error |

### SPICE_CLIENT_ERROR

    #define SPICE_CLIENT_ERROR spice_client_error_quark()

Error domain for spice client errors.

## Property Details

### The `“ca”` property

      “ca”                       GByteArray *

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

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

Owner: SpiceSession

Flags: Read / Write

Since: 0.15

### The `“ca-file”` property

      “ca-file”                  char *

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

Owner: SpiceSession

Flags: Read / Write

Default value: NULL

### The `“cache-size”` property

      “cache-size”               int

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

Owner: SpiceSession

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9

### The `“cert-subject”` property

      “cert-subject”             char *

Certificate subject to check.

Owner: SpiceSession

Flags: Read / Write

Default value: NULL

### The `“ciphers”` property

      “ciphers”                  char *

SSL cipher list.

Owner: SpiceSession

Flags: Read / Write

Default value: NULL

### The `“client-sockets”` property

      “client-sockets”           gboolean

Sockets are provided by the client.

Owner: SpiceSession

Flags: Read / Write

Default value: FALSE

### The `“color-depth”` property

      “color-depth”              int

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

`SpiceSession:color-depth` has been deprecated since version 0.37 and should not be used in newly-written code.

Deprecated due lack of support in drivers, only Windows 7 and older. This option is currently ignored.

Owner: SpiceSession

Flags: Read / Write

Allowed values: [0,32]

Default value: 0

Since: 0.7

### The `“disable-effects”` property

      “disable-effects”          GStrv

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.

Owner: SpiceSession

Flags: Read / Write

Since: 0.7

### The `“enable-audio”` property

      “enable-audio”             gboolean

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

Owner: SpiceSession

Flags: Read / Write / Construct

Default value: TRUE

Since: 0.8

### The `“enable-smartcard”` property

      “enable-smartcard”         gboolean

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

Owner: SpiceSession

Flags: Read / Write

Default value: FALSE

Since: 0.7

### The `“enable-usbredir”` property

      “enable-usbredir”          gboolean

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

Owner: SpiceSession

Flags: Read / Write / Construct

Default value: TRUE

Since: 0.8

### The `“gl-scanout”` property

      “gl-scanout”               gboolean

Whether to enable gl-scanout (Unix only). Set to TRUE by default on EGL-enabled host, unless SPICE_DISABLE_GL_SCANOUT environment variable is set.

Owner: SpiceSession

Flags: Read / Write / Construct

Default value: TRUE

Since: 0.36

### The `“glz-window-size”` property

      “glz-window-size”          int

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

Owner: SpiceSession

Flags: Read / Write

Allowed values: [0,134217728]

Default value: 0

Since: 0.9

### The `“host”` property

      “host”                     char *

URL of the SPICE host to connect to

Owner: SpiceSession

Flags: Read / Write / Construct

Default value: "localhost"

### The `“inhibit-keyboard-grab”` property

      “inhibit-keyboard-grab”    gboolean

Request that SpiceDisplays don't grab the keyboard.

Owner: SpiceSession

Flags: Read / Write

Default value: FALSE

### The `“migration-state”` property

      “migration-state”          SpiceSessionMigration

SpiceSessionMigration bit field indicating if a migration is in progress

Owner: SpiceSession

Flags: Read

Default value: SPICE_SESSION_MIGRATION_NONE

### The `“name”` property

      “name”                     char *

Spice server name.

Owner: SpiceSession

Flags: Read

Default value: NULL

Since: 0.11

### The `“password”` property

      “password”                 char *

TLS password to use

Owner: SpiceSession

Flags: Read / Write

Default value: NULL

### The `“port”` property

      “port”                     char *

Port to connect to for unencrypted sessions

Owner: SpiceSession

Flags: Read / Write

Default value: NULL

### The `“preferred-compression”` property

      “preferred-compression”    SpiceImageCompress

The image compression algorithm the client prefers to use. It is reported to the server.

Owner: SpiceSession

Flags: Read / Write

Default value: SPICE_IMAGE_COMPRESSION_INVALID

Since: 0.29

### The `“protocol”` property

      “protocol”                 int

Version of the SPICE protocol to use

Owner: SpiceSession

Flags: Read / Write / Construct

Allowed values: [1,2]

Default value: 2

### The `“proxy”` property

      “proxy”                    char *

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

Owner: SpiceSession

Flags: Read / Write

Default value: NULL

Since: 0.17

### The `“pubkey”` property

      “pubkey”                   GByteArray *

Public key to check.

Owner: SpiceSession

Flags: Read / Write

### The `“read-only”` property

      “read-only”                gboolean

Whether this connection is read-only mode.

Owner: SpiceSession

Flags: Read / Write / Construct

Default value: FALSE

Since: 0.8

### The `“secure-channels”` property

      “secure-channels”          GStrv

A string array of channel types to be secured.

Owner: SpiceSession

Flags: Read / Write

Since: 0.20

### The `“share-dir-ro”` property

      “share-dir-ro”             gboolean

Whether to share the directory read-only.

Owner: SpiceSession

Flags: Read / Write / Construct

Default value: FALSE

Since: 0.28

### The `“shared-dir”` property

      “shared-dir”               char *

Location of the shared directory

Owner: SpiceSession

Flags: Read / Write / Construct

Default value: NULL

Since: 0.24

### The `“smartcard-certificates”` property

      “smartcard-certificates”   GStrv

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

Owner: SpiceSession

Flags: Read / Write

Since: 0.7

### The `“smartcard-db”` property

      “smartcard-db”             char *

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

Owner: SpiceSession

Flags: Read / Write

Default value: NULL

Since: 0.7

### The `“tls-port”` property

      “tls-port”                 char *

Port to connect to for TLS sessions

Owner: SpiceSession

Flags: Read / Write

Default value: NULL

### The `“unix-path”` property

      “unix-path”                char *

Path of the Unix socket to connect to

Owner: SpiceSession

Flags: Read / Write / Construct

Default value: NULL

Since: 0.28

### The `“uri”` property

      “uri”                      char *

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

Owner: SpiceSession

Flags: Read / Write

Default value: NULL

### The `“username”` property

      “username”                 char *

Username to use

Owner: SpiceSession

Flags: Read / Write

Default value: NULL

### The `“uuid”` property

      “uuid”                     gpointer

Spice server uuid.

Owner: SpiceSession

Flags: Read

Since: 0.11

### The `“verify”` property

      “verify”                   SpiceSessionVerify

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

Owner: SpiceSession

Flags: Read / Write / Construct

Default value: SPICE_SESSION_VERIFY_HOSTNAME

### The `“webdav-server”` property

      “webdav-server”            GObject *

Phodav server that is internally used by SpiceSession to make “shared-dir” available to the host.

Owner: SpiceSession

Flags: Read

Since: 0.39

## Signal Details

### The `“channel-destroy”` signal

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

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

#### Parameters

session | the session that emitted the signal |
channel | the destroyed SpiceChannel |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“channel-new”` signal

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

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

#### Parameters

session | the session that emitted the signal |
channel | the new SpiceChannel |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“disconnected”` signal

    void
    user_function (SpiceSession *session,
                   gpointer      user_data)

The “disconnected” signal is emitted when all channels have been destroyed.

#### Parameters

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

Flags: Run First

Since: 0.35

### The `“mm-time-reset”` signal

    void
    user_function (SpiceSession *session,
                   gpointer      user_data)

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

Since 0.20

#### Parameters

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

Flags: Run First

## See Also

SpiceChannel, and the GTK widget SpiceDisplay