Main Channel

Main Channel — the main Spice channel

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <channel-main.h>

struct              SpiceMainChannel;
struct              SpiceMainChannelClass;

void                spice_main_set_display              (SpiceMainChannel *channel,
                                                         int id,
                                                         int x,
                                                         int y,
                                                         int width,
                                                         int height);
void                spice_main_set_display_enabled      (SpiceMainChannel *channel,
                                                         int id,
                                                         gboolean enabled);
gboolean            spice_main_send_monitor_config      (SpiceMainChannel *channel);
gboolean            spice_main_agent_test_capability    (SpiceMainChannel *channel,
                                                         guint32 cap);
void                spice_main_clipboard_selection_grab (SpiceMainChannel *channel,
                                                         guint selection,
                                                         guint32 *types,
                                                         int ntypes);
void                spice_main_clipboard_selection_notify
                                                        (SpiceMainChannel *channel,
                                                         guint selection,
                                                         guint32 type,
                                                         const guchar *data,
                                                         size_t size);
void                spice_main_clipboard_selection_release
                                                        (SpiceMainChannel *channel,
                                                         guint selection);
void                spice_main_clipboard_selection_request
                                                        (SpiceMainChannel *channel,
                                                         guint selection,
                                                         guint32 type);
void                spice_main_clipboard_grab           (SpiceMainChannel *channel,
                                                         guint32 *types,
                                                         int ntypes);
void                spice_main_clipboard_release        (SpiceMainChannel *channel);
void                spice_main_clipboard_notify         (SpiceMainChannel *channel,
                                                         guint32 type,
                                                         const guchar *data,
                                                         size_t size);
void                spice_main_clipboard_request        (SpiceMainChannel *channel,
                                                         guint32 type);

Object Hierarchy

  GObject
   +----SpiceChannel
         +----SpiceMainChannel

Properties

  "agent-caps-0"             gint                  : Read
  "agent-connected"          gboolean              : Read
  "color-depth"              guint                 : Read / Write / Construct
  "disable-animation"        gboolean              : Read / Write / Construct
  "disable-display-align"    gboolean              : Read / Write / Construct
  "disable-display-position" gboolean              : Read / Write / Construct
  "disable-font-smooth"      gboolean              : Read / Write / Construct
  "disable-wallpaper"        gboolean              : Read / Write / Construct
  "mouse-mode"               gint                  : Read

Signals

  "main-agent-update"                              : Run First
  "main-clipboard"                                 : Run Last
  "main-clipboard-grab"                            : Run Last
  "main-clipboard-release"                         : Run Last
  "main-clipboard-request"                         : Run Last
  "main-clipboard-selection"                       : Run Last
  "main-clipboard-selection-grab"                  : Run Last
  "main-clipboard-selection-release"               : Run Last
  "main-clipboard-selection-request"               : Run Last
  "main-mouse-update"                              : Run First
  "migration-started"                              : Run Last

Description

The main channel is the Spice session control channel. It handles communication initialization (channels list), migrations, mouse modes, multimedia time, and agent communication.

Details

struct SpiceMainChannel

struct SpiceMainChannel;

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


struct SpiceMainChannelClass

struct SpiceMainChannelClass {
    SpiceChannelClass parent_class;

    /* signals */
    void (*mouse_update)(SpiceChannel *channel);
    void (*agent_update)(SpiceChannel *channel);
};

Class structure for SpiceMainChannel.

SpiceChannelClass parent_class;

Parent class.

mouse_update ()

Signal class handler for the "mouse-update" signal.

agent_update ()

Signal class handler for the "agent-update" signal.

spice_main_set_display ()

void                spice_main_set_display              (SpiceMainChannel *channel,
                                                         int id,
                                                         int x,
                                                         int y,
                                                         int width,
                                                         int height);

Notify the guest of screen resolution change. The notification is sent 1 second later, if no further changes happen.

id :

display ID

x :

x position

y :

y position

width :

display width

height :

display height

spice_main_set_display_enabled ()

void                spice_main_set_display_enabled      (SpiceMainChannel *channel,
                                                         int id,
                                                         gboolean enabled);

When sending monitor configuration to agent guest, don't set display id, which the agent translates to disabling the display id. Note: this will take effect next time the monitor configuration is sent.

channel :

a SpiceMainChannel

id :

display ID (if -1: set all displays)

enabled :

wether display id is enabled

Since 0.6


spice_main_send_monitor_config ()

gboolean            spice_main_send_monitor_config      (SpiceMainChannel *channel);

Send monitors configuration previously set with spice_main_set_display() and spice_main_set_display_enabled()

Returns :

TRUE on success.

spice_main_agent_test_capability ()

gboolean            spice_main_agent_test_capability    (SpiceMainChannel *channel,
                                                         guint32 cap);

Test capability of a remote agent.

cap :

an agent capability identifier

Returns :

TRUE if cap (channel kind capability) is available.

spice_main_clipboard_selection_grab ()

void                spice_main_clipboard_selection_grab (SpiceMainChannel *channel,
                                                         guint selection,
                                                         guint32 *types,
                                                         int ntypes);

Grab the guest clipboard, with VD_AGENT_CLIPBOARD types.

selection :

one of the clipboard VD_AGENT_CLIPBOARD_SELECTION_*

types :

an array of VD_AGENT_CLIPBOARD types available in the clipboard

ntypes :

the number of types

Since 0.6


spice_main_clipboard_selection_notify ()

void                spice_main_clipboard_selection_notify
                                                        (SpiceMainChannel *channel,
                                                         guint selection,
                                                         guint32 type,
                                                         const guchar *data,
                                                         size_t size);

Send the clipboard data to the guest.

selection :

one of the clipboard VD_AGENT_CLIPBOARD_SELECTION_*

type :

a VD_AGENT_CLIPBOARD type

data :

clipboard data

size :

data length in bytes

Since 0.6


spice_main_clipboard_selection_release ()

void                spice_main_clipboard_selection_release
                                                        (SpiceMainChannel *channel,
                                                         guint selection);

Release the clipboard (for example, when the client looses the clipboard grab): Inform the guest no clipboard data is available.

selection :

one of the clipboard VD_AGENT_CLIPBOARD_SELECTION_*

Since 0.6


spice_main_clipboard_selection_request ()

void                spice_main_clipboard_selection_request
                                                        (SpiceMainChannel *channel,
                                                         guint selection,
                                                         guint32 type);

Request clipboard data of type from the guest. The reply is sent through the "main-clipboard" signal.

selection :

one of the clipboard VD_AGENT_CLIPBOARD_SELECTION_*

type :

a VD_AGENT_CLIPBOARD type

Since 0.6


spice_main_clipboard_grab ()

void                spice_main_clipboard_grab           (SpiceMainChannel *channel,
                                                         guint32 *types,
                                                         int ntypes);

Warning

spice_main_clipboard_grab has been deprecated since version 0.6 and should not be used in newly-written code. use spice_main_clipboard_selection_grab() instead.

Grab the guest clipboard, with VD_AGENT_CLIPBOARD types.

types :

an array of VD_AGENT_CLIPBOARD types available in the clipboard

ntypes :

the number of types

spice_main_clipboard_release ()

void                spice_main_clipboard_release        (SpiceMainChannel *channel);

Warning

spice_main_clipboard_release has been deprecated since version 0.6 and should not be used in newly-written code. use spice_main_clipboard_selection_release() instead.

Release the clipboard (for example, when the client looses the clipboard grab): Inform the guest no clipboard data is available.


spice_main_clipboard_notify ()

void                spice_main_clipboard_notify         (SpiceMainChannel *channel,
                                                         guint32 type,
                                                         const guchar *data,
                                                         size_t size);

Warning

spice_main_clipboard_notify has been deprecated since version 0.6 and should not be used in newly-written code. use spice_main_clipboard_selection_notify() instead.

Send the clipboard data to the guest.

type :

a VD_AGENT_CLIPBOARD type

data :

clipboard data

size :

data length in bytes

spice_main_clipboard_request ()

void                spice_main_clipboard_request        (SpiceMainChannel *channel,
                                                         guint32 type);

Warning

spice_main_clipboard_request has been deprecated since version 0.6 and should not be used in newly-written code. use spice_main_clipboard_selection_request() instead.

Request clipboard data of type from the guest. The reply is sent through the "main-clipboard" signal.

type :

a VD_AGENT_CLIPBOARD type

Property Details

The "agent-caps-0" property

  "agent-caps-0"             gint                  : Read

Agent capability bits 0 -> 31.

Allowed values: >= 0

Default value: 0


The "agent-connected" property

  "agent-connected"          gboolean              : Read

Whether the agent is connected.

Default value: FALSE


The "color-depth" property

  "color-depth"              guint                 : Read / Write / Construct

Color depth.

Allowed values: <= 32

Default value: 0


The "disable-animation" property

  "disable-animation"        gboolean              : Read / Write / Construct

Disable guest animations.

Default value: FALSE


The "disable-display-align" property

  "disable-display-align"    gboolean              : Read / Write / Construct

Disable automatic horizontal display position alignment.

Default value: FALSE

Since 0.13


The "disable-display-position" property

  "disable-display-position" gboolean              : Read / Write / Construct

Disable using display position when setting monitor config.

Default value: TRUE


The "disable-font-smooth" property

  "disable-font-smooth"      gboolean              : Read / Write / Construct

Disable guest font smoothing.

Default value: FALSE


The "disable-wallpaper" property

  "disable-wallpaper"        gboolean              : Read / Write / Construct

Disable guest wallpaper.

Default value: FALSE


The "mouse-mode" property

  "mouse-mode"               gint                  : Read

Spice protocol specifies two mouse modes, client mode and server mode. In client mode (SPICE_MOUSE_MODE_CLIENT), the affective mouse is the client side mouse: the client sends mouse position within the display and the server sends mouse shape messages. In server mode (SPICE_MOUSE_MODE_SERVER), the client sends relative mouse movements and the server sends position and shape commands.

Allowed values: >= 0

Default value: 0

Signal Details

The "main-agent-update" signal

void                user_function                      (SpiceMainChannel *main,
                                                        gpointer          user_data)      : Run First

Notify when the SpiceMainChannel:agent-connected or SpiceMainChannel:agent-caps-0 property change.

main :

the SpiceMainChannel that emitted the signal

user_data :

user data set when the signal handler was connected.

The "main-clipboard" signal

void                user_function                      (SpiceMainChannel *main,
                                                        guint             type,
                                                        gpointer          data,
                                                        guint             size,
                                                        gpointer          user_data)      : Run Last

Warning

SpiceMainChannel::main-clipboard has been deprecated since version 0.6 and should not be used in newly-written code. use SpiceMainChannel::main-clipboard-selection instead.

Provides guest clipboard data requested by spice_main_clipboard_request().

main :

the SpiceMainChannel that emitted the signal

type :

the VD_AGENT_CLIPBOARD data type

data :

clipboard data

size :

size of data in bytes

user_data :

user data set when the signal handler was connected.

The "main-clipboard-grab" signal

gboolean            user_function                      (SpiceMainChannel *main,
                                                        gpointer          types,
                                                        guint             ntypes,
                                                        gpointer          user_data)      : Run Last

Warning

SpiceMainChannel::main-clipboard-grab has been deprecated since version 0.6 and should not be used in newly-written code. use SpiceMainChannel::main-clipboard-selection-grab instead.

Inform when clipboard data is available from the guest, and for which types.

main :

the SpiceMainChannel that emitted the signal

types :

the VD_AGENT_CLIPBOARD data types

ntypes :

the number of types

user_data :

user data set when the signal handler was connected.

The "main-clipboard-release" signal

void                user_function                      (SpiceMainChannel *main,
                                                        gpointer          user_data)      : Run Last

Warning

SpiceMainChannel::main-clipboard-release has been deprecated since version 0.6 and should not be used in newly-written code. use SpiceMainChannel::main-clipboard-selection-release instead.

Inform when the clipboard is released from the guest, when no clipboard data is available from the guest.

main :

the SpiceMainChannel that emitted the signal

user_data :

user data set when the signal handler was connected.

The "main-clipboard-request" signal

gboolean            user_function                      (SpiceMainChannel *main,
                                                        guint             types,
                                                        gpointer          user_data)      : Run Last

Warning

SpiceMainChannel::main-clipboard-request has been deprecated since version 0.6 and should not be used in newly-written code. use SpiceMainChannel::main-clipboard-selection-request instead.

main :

the SpiceMainChannel that emitted the signal

types :

the VD_AGENT_CLIPBOARD request type

user_data :

user data set when the signal handler was connected.

Returns :

TRUE if the request is successful Request clipbard data from the client.

The "main-clipboard-selection" signal

void                user_function                      (SpiceMainChannel *main,
                                                        guint             arg1,
                                                        guint             arg2,
                                                        gpointer          arg3,
                                                        guint             arg4,
                                                        gpointer          user_data)      : Run Last

main :

the SpiceMainChannel that emitted the signal

user_data :

user data set when the signal handler was connected.

Since 0.6


The "main-clipboard-selection-grab" signal

gboolean            user_function                      (SpiceMainChannel *main,
                                                        guint             types,
                                                        gpointer          ntypes,
                                                        guint             arg3,
                                                        gpointer          user_data)      : Run Last

Inform when clipboard data is available from the guest, and for which types.

main :

the SpiceMainChannel that emitted the signal

types :

the VD_AGENT_CLIPBOARD data types

ntypes :

the number of types

user_data :

user data set when the signal handler was connected.

Since 0.6


The "main-clipboard-selection-release" signal

void                user_function                      (SpiceMainChannel *main,
                                                        guint             arg1,
                                                        gpointer          user_data)      : Run Last

Inform when the clipboard is released from the guest, when no clipboard data is available from the guest.

main :

the SpiceMainChannel that emitted the signal

user_data :

user data set when the signal handler was connected.

Since 0.6


The "main-clipboard-selection-request" signal

gboolean            user_function                      (SpiceMainChannel *main,
                                                        guint             types,
                                                        guint             Returns,
                                                        gpointer          user_data)      : Run Last

main :

the SpiceMainChannel that emitted the signal

types :

the VD_AGENT_CLIPBOARD request type

user_data :

user data set when the signal handler was connected.

Returns :

TRUE if the request is successful Request clipbard data from the client.

Since 0.6


The "main-mouse-update" signal

void                user_function                      (SpiceMainChannel *main,
                                                        gpointer          user_data)      : Run First

Notify when the mouse mode has changed.

main :

the SpiceMainChannel that emitted the signal

user_data :

user data set when the signal handler was connected.

The "migration-started" signal

void                user_function                      (SpiceMainChannel *main,
                                                        GObject          *session,
                                                        gpointer          user_data)      : Run Last

Inform when migration is starting. Application wishing to make connections themself can set the "client-sockets" to TRUE, then follow "channel-new" creation, and use spice_channel_open_fd() once the socket is created.

main :

the SpiceMainChannel that emitted the signal

session :

a migration SpiceSession

user_data :

user data set when the signal handler was connected.

See Also

SpiceChannel, and the GTK widget SpiceDisplay