## Main Channel

Main Channel — the main Spice channel

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <channel-main.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);
    gboolean            spice_main_send_monitor_config      (SpiceMainChannel *channel);
    gboolean            spice_main_agent_test_capability    (SpiceMainChannel *channel,
                                                             guint32 cap);
    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);

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

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

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

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

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

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

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

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

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

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

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

`type` : | a VD_AGENT_CLIPBOARD type

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

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

### The `"main-clipboard-selection"` signal

    void                user_function                      (SpiceMainChannel *main,
                                                            guint             arg1,
                                                            guint             arg2,
                                                            gpointer          arg3,
                                                            guint             arg4,
                                                            gpointer          user_data)      : Run Last

`main` : | the SpiceMainChannel that emitted the signal
`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             types,
                                                            gpointer          ntypes,
                                                            guint             arg3,
                                                            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
`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             arg1,
                                                            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
`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             types,
                                                            guint             Returns,
                                                            gpointer          user_data)      : Run Last

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

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.

## See Also

SpiceChannel, and the GTK widget SpiceDisplay