Main Channel

Main Channel — the main Spice channel

Stability Level

Stable, unless otherwise indicated

Functions

Properties

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

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── SpiceChannel
        ╰── SpiceMainChannel

Includes

#include <channel-main.h>

Description

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

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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 loses the clipboard grab): Inform the guest no clipboard data is available.

Parameters

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-selection” signal.

Parameters

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

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 .

Parameters

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

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

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.

Parameters

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

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.

Parameters

type

a VD_AGENT_CLIPBOARD type

 

Types and Values

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.

Members

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.

 

Property Details

The “agent-caps-0” property

  “agent-caps-0”             gint

Agent capability bits 0 -> 31.

Flags: Read

Allowed values: >= 0

Default value: 0


The “agent-connected” property

  “agent-connected”          gboolean

Whether the agent is connected.

Flags: Read

Default value: FALSE


The “color-depth” property

  “color-depth”              guint

Color depth.

Flags: Read / Write / Construct

Allowed values: <= 32

Default value: 0


The “disable-animation” property

  “disable-animation”        gboolean

Disable guest animations.

Flags: Read / Write / Construct

Default value: FALSE


The “disable-display-align” property

  “disable-display-align”    gboolean

Disable automatic horizontal display position alignment.

Flags: Read / Write / Construct

Default value: FALSE

Since 0.13


The “disable-display-position” property

  “disable-display-position” gboolean

Disable using display position when setting monitor config.

Flags: Read / Write / Construct

Default value: TRUE


The “disable-font-smooth” property

  “disable-font-smooth”      gboolean

Disable guest font smoothing.

Flags: Read / Write / Construct

Default value: FALSE


The “disable-wallpaper” property

  “disable-wallpaper”        gboolean

Disable guest wallpaper.

Flags: Read / Write / Construct

Default value: FALSE


The “max-clipboard” property

  “max-clipboard”            gint

Maximum size of clipboard operations in bytes (default 100MB, -1 for unlimited size);

Flags: Read / Write / Construct

Allowed values: >= -1

Default value: 104857600

Since 0.22


The “mouse-mode” property

  “mouse-mode”               gint

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.

Flags: Read

Allowed values: >= 0

Default value: 0

Signal Details

The “main-agent-update” signal

void
user_function (SpiceMainChannel *main,
               gpointer          user_data)

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

Parameters

main

the SpiceMainChannel that emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “main-clipboard” signal

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

Provides guest clipboard data requested by spice_main_clipboard_request().

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.

Parameters

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.

 

Flags: Run Last


The “main-clipboard-grab” signal

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

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

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.

Parameters

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.

 

Flags: Run Last


The “main-clipboard-release” signal

void
user_function (SpiceMainChannel *main,
               gpointer          user_data)

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

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.

Parameters

main

the SpiceMainChannel that emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “main-clipboard-request” signal

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

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.

Parameters

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.

Flags: Run Last


The “main-clipboard-selection” signal

void
user_function (SpiceMainChannel *main,
               guint             selection,
               guint             type,
               gpointer          data,
               guint             size,
               gpointer          user_data)

Parameters

main

the SpiceMainChannel that emitted the signal

 

selection

a VD_AGENT_CLIPBOARD_SELECTION clipboard

 

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.

 

Flags: Run Last

Since 0.6


The “main-clipboard-selection-grab” signal

gboolean
user_function (SpiceMainChannel *main,
               guint             selection,
               gpointer          types,
               guint             ntypes,
               gpointer          user_data)

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

Parameters

main

the SpiceMainChannel that emitted the signal

 

selection

a VD_AGENT_CLIPBOARD_SELECTION clipboard

 

types

the VD_AGENT_CLIPBOARD data types

 

ntypes

the number of types

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 0.6


The “main-clipboard-selection-release” signal

void
user_function (SpiceMainChannel *main,
               guint             selection,
               gpointer          user_data)

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

Parameters

main

the SpiceMainChannel that emitted the signal

 

selection

a VD_AGENT_CLIPBOARD_SELECTION clipboard

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since 0.6


The “main-clipboard-selection-request” signal

gboolean
user_function (SpiceMainChannel *main,
               guint             selection,
               guint             types,
               gpointer          user_data)

Parameters

main

the SpiceMainChannel that emitted the signal

 

selection

a VD_AGENT_CLIPBOARD_SELECTION clipboard

 

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.

Flags: Run Last

Since 0.6


The “main-mouse-update” signal

void
user_function (SpiceMainChannel *main,
               gpointer          user_data)

Notify when the mouse mode has changed.

Parameters

main

the SpiceMainChannel that emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “migration-started” signal

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

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.

Parameters

main

the SpiceMainChannel that emitted the signal

 

session

a migration SpiceSession

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

See Also

SpiceChannel, and the GTK widget SpiceDisplay