Main Channel

Main Channel — the main Spice channel

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <spice-client.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);
void                spice_main_update_display           (SpiceMainChannel *channel,
                                                         int id,
                                                         int x,
                                                         int y,
                                                         int width,
                                                         int height,
                                                         gboolean update);
void                spice_main_update_display_enabled   (SpiceMainChannel *channel,
                                                         int id,
                                                         gboolean enabled,
                                                         gboolean update);
gboolean            spice_main_send_monitor_config      (SpiceMainChannel *channel);
gboolean            spice_main_agent_test_capability    (SpiceMainChannel *channel,
                                                         guint32 cap);
void                spice_main_request_mouse_mode       (SpiceMainChannel *channel,
                                                         int mode);
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);
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);
gboolean            spice_main_file_copy_finish         (SpiceMainChannel *channel,
                                                         GAsyncResult *result,
                                                         GError **error);

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
  "max-clipboard"            gint                  : 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
  "new-file-transfer"                              : 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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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

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.

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

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

channel :

a SpiceMainChannel

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.

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

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.

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.

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

channel :

a SpiceMainChannel

result :

a GAsyncResult.

error :

a GError, or NULL

Returns :

a TRUE on success, FALSE on error.

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 "max-clipboard" property

  "max-clipboard"            gint                  : Read / Write / Construct

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

Allowed values: >= -1

Default value: 104857600

Since 0.22


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.

Request clipboard data from the client.

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

The "main-clipboard-selection" signal

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

Informs that clipboard selection data are available.

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.

Since 0.6


The "main-clipboard-selection-grab" signal

gboolean            user_function                      (SpiceMainChannel *main,
                                                        guint             selection,
                                                        gpointer          types,
                                                        guint             ntypes,
                                                        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

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.

Since 0.6


The "main-clipboard-selection-release" signal

void                user_function                      (SpiceMainChannel *main,
                                                        guint             selection,
                                                        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

selection :

a VD_AGENT_CLIPBOARD_SELECTION clipboard

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             selection,
                                                        guint             types,
                                                        gpointer          user_data)      : Run Last

Request clipboard data from the client.

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

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.

The "new-file-transfer" signal

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

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.

main :

the SpiceMainChannel that emitted the signal

task :

a SpiceFileTransferTask

user_data :

user data set when the signal handler was connected.

Since 0.31

See Also

SpiceChannel, and the GTK widget SpiceDisplay