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
gchar * ca-file Read / Write
gint cache-size Read / Write
gchar * cert-subject Read / Write
gchar * ciphers Read / Write
gboolean client-sockets Read / Write
gint 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
gint glz-window-size Read / Write
gchar * host Read / Write / Construct
gboolean inhibit-keyboard-grab Read / Write
SpiceSessionMigration migration-state Read
gchar * name Read
gchar * password Read / Write
gchar * port Read / Write
SpiceImageCompress preferred-compression Read / Write
gint protocol Read / Write / Construct
gchar * 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
gchar * shared-dir Read / Write / Construct
GStrv smartcard-certificates Read / Write
gchar * smartcard-db Read / Write
gchar * tls-port Read / Write
gchar * unix-path Read / Write / Construct
gchar * uri Read / Write
gchar * username Read / Write
gpointer uuid Read
SpiceSessionVerify verify Read / Write / Construct

Signals

void channel-destroy Run First
void channel-new 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

    GEnum
    ╰── SpiceSessionMigration
    GFlags
    ╰── SpiceSessionVerify
    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-----

Flags: Read / Write

Since: 0.15

The “ca-file” property

  “ca-file”                  gchar *

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

Flags: Read / Write

Default value: NULL

The “cache-size” property

  “cache-size”               gint

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

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.9

The “cert-subject” property

  “cert-subject”             gchar *

Certificate subject to check.

Flags: Read / Write

Default value: NULL

The “ciphers” property

  “ciphers”                  gchar *

SSL cipher list.

Flags: Read / Write

Default value: NULL

The “client-sockets” property

  “client-sockets”           gboolean

Sockets are provided by the client.

Flags: Read / Write

Default value: FALSE

The “color-depth” property

  “color-depth”              gint

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

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.

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.

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

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

Flags: Read / Write / Construct

Default value: TRUE

Since: 0.8

The “glz-window-size” property

  “glz-window-size”          gint

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

Flags: Read / Write

Allowed values: [0,134217728]

Default value: 0

Since: 0.9

The “host” property

  “host”                     gchar *

URL of the SPICE host to connect to

Flags: Read / Write / Construct

Default value: "localhost"

The “inhibit-keyboard-grab” property

  “inhibit-keyboard-grab”    gboolean

Request that SpiceDisplays don't grab the keyboard.

Flags: Read / Write

Default value: FALSE

The “migration-state” property

  “migration-state”          SpiceSessionMigration

SpiceSessionMigration bit field indicating if a migration is in progress

Flags: Read

Default value: SPICE_SESSION_MIGRATION_NONE

The “name” property

  “name”                     gchar *

Spice server name.

Flags: Read

Default value: NULL

Since: 0.11

The “password” property

  “password”                 gchar *

TLS password to use

Flags: Read / Write

Default value: NULL

The “port” property

  “port”                     gchar *

Port to connect to for unencrypted sessions

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.

Flags: Read / Write

Default value: SPICE_IMAGE_COMPRESSION_INVALID

Since: 0.29

The “protocol” property

  “protocol”                 gint

Version of the SPICE protocol to use

Flags: Read / Write / Construct

Allowed values: [1,2]

Default value: 2

The “proxy” property

  “proxy”                    gchar *

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

Flags: Read / Write

Default value: NULL

Since: 0.17

The “pubkey” property

  “pubkey”                   GByteArray *

Public key to check.

Flags: Read / Write

The “read-only” property

  “read-only”                gboolean

Whether this connection is read-only mode.

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.

Flags: Read / Write

Since: 0.20

The “share-dir-ro” property

  “share-dir-ro”             gboolean

Whether to share the directory read-only.

Flags: Read / Write / Construct

Default value: FALSE

Since: 0.28

The “shared-dir” property

  “shared-dir”               gchar *

Location of the shared directory

Flags: Read / Write / Construct

Default value: "/home/pgrunt/Public"

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

Flags: Read / Write

Since: 0.7

The “smartcard-db” property

  “smartcard-db”             gchar *

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

Flags: Read / Write

Default value: NULL

Since: 0.7

The “tls-port” property

  “tls-port”                 gchar *

Port to connect to for TLS sessions

Flags: Read / Write

Default value: NULL

The “unix-path” property

  “unix-path”                gchar *

Path of the Unix socket to connect to

Flags: Read / Write / Construct

Default value: NULL

Since: 0.28

The “uri” property

  “uri”                      gchar *

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

Flags: Read / Write

Default value: NULL

The “username” property

  “username”                 gchar *

Username to use

Flags: Read / Write

Default value: NULL

The “uuid” property

  “uuid”                     gpointer

Spice server uuid.

Flags: Read

Since: 0.11

The “verify” property

  “verify”                   SpiceSessionVerify

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

Flags: Read / Write / Construct

Default value: SPICE_SESSION_VERIFY_HOSTNAME

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

Generated by GTK-Doc V1.25