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

GOptionGroup *      spice_cmdline_get_option_group      (void);
void                spice_cmdline_session_setup         (SpiceSession *session);

Object Hierarchy

  GObject
   +----SpiceSession

Properties

  "ca-file"                  gchar*                : Read / Write
  "cert-subject"             gchar*                : Read / Write
  "client-sockets"           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
  "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.

Returns :

a GList of unowned SpiceChannels.

spice_cmdline_get_option_group ()

GOptionGroup *      spice_cmdline_get_option_group      (void);

spice_cmdline_session_setup ()

void                spice_cmdline_session_setup         (SpiceSession *session);

Property Details

The "ca-file" property

  "ca-file"                  gchar*                : Read / Write

File holding the CA certificates.

Default value: NULL


The "cert-subject" property

  "cert-subject"             gchar*                : Read / Write

Certificate subject to check.

Default value: NULL


The "client-sockets" property

  "client-sockets"           gboolean              : Read / Write

Sockets are provided by the client.

Default value: FALSE


The "host" property

  "host"                     gchar*                : Read / Write / Construct

Remote host.

Default value: "localhost"


The "migration-state" property

  "migration-state"          SpiceSessionMigration  : Read

Migration state.

Default value: SPICE_SESSION_MIGRATION_NONE


The "password" property

  "password"                 gchar*                : Read / Write

Default value: NULL


The "port" property

  "port"                     gchar*                : Read / Write

Remote port (plaintext).

Default value: NULL


The "protocol" property

  "protocol"                 gint                  : Read / Write / Construct

Spice protocol major version.

Allowed values: [1,2]

Default value: 2


The "pubkey" property

  "pubkey"                   GByteArray*           : Read / Write

Public key to check.


The "tls-port" property

  "tls-port"                 gchar*                : Read / Write

Remote port (encrypted).

Default value: NULL


The "uri" property

  "uri"                      gchar*                : Read / Write

Spice connection URI.

Default value: NULL


The "verify" property

  "verify"                   SpiceSessionVerify    : Read / Write / Construct

Certificate verification parameters.

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