Main Channel: Spice-GTK Reference Manual

Main Channel

Main Channel — the main Spice channel

Stability Level

Stable, unless otherwise indicated

Functions

void	spice_main_set_display ()
void	spice_main_set_display_enabled ()
void	spice_main_update_display ()
void	spice_main_update_display_enabled ()
gboolean	spice_main_send_monitor_config ()
gboolean	spice_main_agent_test_capability ()
void	spice_main_clipboard_selection_grab ()
void	spice_main_clipboard_selection_notify ()
void	spice_main_clipboard_selection_release ()
void	spice_main_clipboard_selection_request ()
void	spice_main_clipboard_grab ()
void	spice_main_clipboard_release ()
void	spice_main_clipboard_notify ()
void	spice_main_clipboard_request ()
void	spice_main_file_copy_async ()
gboolean	spice_main_file_copy_finish ()

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

Types and Values

struct	SpiceMainChannel
struct	SpiceMainChannelClass

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_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.

Parameters

channel	a SpiceMainChannel
sources	a `NULL`-terminated array of GFile objects to be transferred
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

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