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 <spice-client.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

channel

a SpiceMainChannel

 

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

void
spice_main_update_display (SpiceMainChannel *channel,
                           int id,
                           int x,
                           int y,
                           int width,
                           int height,
                           gboolean update);

Update the display id resolution.

If update is TRUE, the remote configuration will be updated too after 1 second without further changes. You can send when you want without delay the new configuration to the remote with spice_main_send_monitor_config()

Parameters

channel

a SpiceMainChannel

 

id

display ID

 

x

x position

 

y

y position

 

width

display width

 

height

display height

 

update

if TRUE, update guest resolution after 1sec.

 

spice_main_update_display_enabled ()

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

When sending monitor configuration to agent guest, if enabled is FALSE, don't set display id , which the agent translates to disabling the display id. If enabled is TRUE, the monitor will be included in the next monitor update. Note: this will take effect next time the monitor configuration is sent.

If update is FALSE, no server update will be triggered by this call, but the value will be saved and used in the next configuration update.

Parameters

channel

a SpiceMainChannel

 

id

display ID (if -1: set all displays)

 

enabled

wether display id is enabled

 

update

if TRUE, update guest display state after 1sec.

 

Since: 0.30


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

Parameters

channel

a SpiceMainChannel

 

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

channel

a SpiceMainChannel

 

cap

an agent capability identifier

 

Returns

TRUE if cap (channel kind capability) is available.


spice_main_request_mouse_mode ()

void
spice_main_request_mouse_mode (SpiceMainChannel *channel,
                               int mode);

Request a mouse mode to the server. The server may not be able to change the mouse mode, but spice-gtk will try to request it when possible.

Parameters

channel

a SpiceMainChannel

 

mode

a SPICE_MOUSE_MODE

 

Since: 0.32


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

channel

a SpiceMainChannel

 

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

channel

a SpiceMainChannel

 

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

channel

a SpiceMainChannel

 

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

channel

a SpiceMainChannel

 

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

channel

a SpiceMainChannel

 

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.

Parameters

channel

a SpiceMainChannel

 

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

channel

a SpiceMainChannel

 

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

channel

a SpiceMainChannel

 

type

a VD_AGENT_CLIPBOARD type

 

spice_main_file_copy_async ()

void
spice_main_file_copy_async (SpiceMainChannel *channel,
                            GFile **sources,
                            GFileCopyFlags flags,
                            GCancellable *cancellable,
                            GFileProgressCallback progress_callback,
                            gpointer progress_callback_data,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Copies the file sources to guest

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

If progress_callback is not NULL, then the operation can be monitored by setting this to a GFileProgressCallback function. progress_callback_data will be passed to this function. It is guaranteed that this callback will be called after all data has been transferred with the total number of bytes copied during the operation. Note that before release 0.31, progress_callback was broken since it only provided status for a single file transfer, but did not provide a way to determine which file it referred to. In release 0.31, this behavior was changed so that progress_callback provides the status of all ongoing file transfers. If you need to monitor the status of individual files, please connect to the “new-file-transfer” signal.

When the operation is finished, callback will be called. You can then call spice_main_file_copy_finish() to get the result of the operation. Note that before release 0.33 the callback was called for each file in multiple file transfer. This behavior was changed for the same reason as the progress_callback (above). If you need to monitor the ending of individual files, you can connect to "finished" signal from each SpiceFileTransferTask.

Parameters

channel

a SpiceMainChannel

 

sources

a NULL-terminated array of GFile objects to be transferred.

[array zero-terminated=1]

flags

set of GFileCopyFlags

 

cancellable

optional GCancellable object, NULL to ignore.

[allow-none]

progress_callback

function to callback with progress information, or NULL if progress information is not needed.

[allow-none][scope call]

progress_callback_data

user data to pass to progress_callback .

[closure]

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

the data to pass to callback function

 

spice_main_file_copy_finish ()

gboolean
spice_main_file_copy_finish (SpiceMainChannel *channel,
                             GAsyncResult *result,
                             GError **error);

Finishes copying the file started with spice_main_file_copy_async().

Parameters

channel

a SpiceMainChannel

 

result

a GAsyncResult.

 

error

a GError, or NULL

 

Returns

a TRUE on success, FALSE on error.

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

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)

Request clipboard data from the client.

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

Flags: Run Last


The “main-clipboard-selection” signal

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

Informs that clipboard selection data are available.

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)

Request clipboard data from the client.

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

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


The “new-file-transfer” signal

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

This signal is emitted when a new file transfer task has been initiated on this channel. Client applications may take a reference on the task object and use it to monitor the status of the file transfer task.

Parameters

main

the SpiceMainChannel that emitted the signal

 

task

a SpiceFileTransferTask

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 0.31

See Also

SpiceChannel, and the GTK widget SpiceDisplay