Session and Channels

Session and Channels

Session

The SpiceSession is the entry point for any SPICE connection. It manages the lifecycle of all channels and holds connection parameters such as host, port, and TLS settings.

SpiceSession *session = spice_session_new();
g_object_set(session, "host", "localhost", "port", "5900", NULL);

g_signal_connect(session, "channel-new",
                 G_CALLBACK(on_channel_new), NULL);

spice_session_connect(session);

Channel Base Class

SpiceChannel is the abstract base class for all SPICE channels. It provides common functionality like capability negotiation and connection state management.

Main Channel

The SpiceMainChannel is always present in a SPICE session. It handles:

  • Agent communication — Testing agent capabilities and exchanging messages
  • Clipboard sharing — Copy/paste between client and guest
  • File transfer — Sending files to the guest via drag-and-drop or API
  • Display configuration — Informing the server about monitor layout
  • Mouse mode — Requesting client or server mouse mode

File transfers are tracked through SpiceFileTransferTask objects emitted by the SpiceMainChannel::new-file-transfer signal.

Display Channel

The SpiceDisplayChannel delivers the guest display. It supports both software rendering (via primary surface updates) and hardware accelerated rendering (via GL scanouts with EGL_MESA_image_dma_buf_export).

Key signals: - SpiceDisplayChannel::display-primary-create — A new framebuffer is available - SpiceDisplayChannel::display-invalidate — A region needs redrawing - SpiceDisplayChannel:gl-scanout — A new OpenGL scanout is available - SpiceDisplayChannel::gl-draw — An OpenGL region needs redrawing

Inputs Channel

The SpiceInputsChannel sends keyboard and mouse events to the guest. It supports both client-mode (absolute coordinates) and server-mode (relative motion) mouse input.

Cursor Channel

The SpiceCursorChannel receives mouse cursor shape and position updates from the guest, delivered as SpiceCursorShape data.

Audio Channels

Port Channel

The SpicePortChannel provides named, bidirectional data channels that applications can use for custom communication with the guest.

Other Channels