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

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

## Types and Values

struct | SpiceMainChannel
struct | SpiceMainChannelClass

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