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

## Signals

void | main-agent-update | Run First
void | main-clipboard | Run Last
gboolean | main-clipboard-grab | Run Last
void | main-clipboard-release | Run Last
gboolean | main-clipboard-request | Run Last
void | main-clipboard-selection | Run Last
gboolean | main-clipboard-selection-grab | Run Last
void | main-clipboard-selection-release | Run Last
gboolean | main-clipboard-selection-request | Run Last
void | main-mouse-update | Run First
void | migration-started | Run Last
void | new-file-transfer | Run Last

## 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

### 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