## Spice Channel Spice Channel — the base channel class |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <spice-channel.h>

    enum                SpiceChannelEvent;
    struct              SpiceChannel;
    struct              SpiceChannelClass;

    SpiceChannel *      spice_channel_new                   (SpiceSession *s,
                                                             int type,
                                                             int id);
    void                spice_channel_destroy               (SpiceChannel *channel);
    gboolean            spice_channel_connect               (SpiceChannel *channel);
    gboolean            spice_channel_open_fd               (SpiceChannel *channel,
                                                             int fd);
    void                spice_channel_disconnect            (SpiceChannel *channel,
                                                             SpiceChannelEvent reason);
    gboolean            spice_channel_test_capability       (SpiceChannel *channel,
                                                             guint32 cap);
    void                spice_channel_set_capability        (SpiceChannel *channel,
                                                             guint32 cap);

## Object Hierarchy

      GEnum
       +----SpiceChannelEvent

      GObject
       +----SpiceChannel
             +----SpiceCursorChannel
             +----SpiceDisplayChannel
             +----SpiceInputsChannel
             +----SpiceMainChannel
             +----SpicePlaybackChannel
             +----SpiceRecordChannel
             +----SpiceSmartcardChannel

## Properties

      "channel-id"               gint                  : Read / Write / Construct Only
      "channel-type"             gint                  : Read / Write / Construct Only
      "spice-session"            SpiceSession*         : Read / Write / Construct Only
      "total-read-bytes"         gulong                : Read

## Signals

      "channel-event"                                  : Run First
      "open-fd"                                        : Run First

## Description

SpiceChannel is the base class for the different kind of Spice channel connections, such as SpiceMainChannel, or SpiceInputsChannel.

## Details

### enum SpiceChannelEvent

    typedef enum
    {
        SPICE_CHANNEL_NONE = 0,
        SPICE_CHANNEL_OPENED = 10,
        SPICE_CHANNEL_SWITCHING,
        SPICE_CHANNEL_CLOSED,
        SPICE_CHANNEL_ERROR_CONNECT = 20,
        SPICE_CHANNEL_ERROR_TLS,
        SPICE_CHANNEL_ERROR_LINK,
        SPICE_CHANNEL_ERROR_AUTH,
        SPICE_CHANNEL_ERROR_IO,
    } SpiceChannelEvent;

`SPICE_CHANNEL_NONE`: no event, or ignored event `SPICE_CHANNEL_OPENED`: connection is authentified and ready `SPICE_CHANNEL_CLOSED`: connection is closed normally (sent if channel was ready) `SPICE_CHANNEL_ERROR_CONNECT`: connection error `SPICE_CHANNEL_ERROR_TLS`: SSL error `SPICE_CHANNEL_ERROR_LINK`: error during link process `SPICE_CHANNEL_ERROR_AUTH`: authentication error `SPICE_CHANNEL_ERROR_IO`: IO error

An event, emitted by "channel-event" signal.

### struct SpiceChannel

    struct SpiceChannel;

### struct SpiceChannelClass

    struct SpiceChannelClass {
        GObjectClass parent_class;

        /* signals, main context */
        void (*channel_event)(SpiceChannel *channel, SpiceChannelEvent event);
        void (*open_fd)(SpiceChannel *channel, int with_tls);
    };

### spice_channel_new ()

    SpiceChannel *      spice_channel_new                   (SpiceSession *s,
                                                             int type,
                                                             int id);

Create a new SpiceChannel of type `type`, and channel ID `id`.

`s` : | the `SpiceSession` the channel is linked to
`type` : | the requested SPICECHANNELPRIVATE type
`id` : | the channel-id
Returns : | a weak reference to SpiceChannel, the session owns the reference

### spice_channel_destroy ()

    void                spice_channel_destroy               (SpiceChannel *channel);

Disconnect and unref the `channel`. Called by @`spice_session_disconnect()`

### spice_channel_connect ()

    gboolean            spice_channel_connect               (SpiceChannel *channel);

Connect the channel, using SpiceSession connection informations

Returns : | `TRUE` on success.

### spice_channel_open_fd ()

    gboolean            spice_channel_open_fd               (SpiceChannel *channel,
                                                             int fd);

Connect the channel using `fd` socket.

`fd` : | a file descriptor (socket)
Returns : | `TRUE` on success.

### spice_channel_disconnect ()

    void                spice_channel_disconnect            (SpiceChannel *channel,
                                                             SpiceChannelEvent reason);

Close the socket and reset connection specific data. Finally, emit `reason` "channel-event" on main context if not SPICE_CHANNEL_NONE.

`reason` : | a channel event emitted on main context (or SPICE_CHANNEL_NONE)

### spice_channel_test_capability ()

    gboolean            spice_channel_test_capability       (SpiceChannel *channel,
                                                             guint32 cap);

Test availability of remote "channel kind capability".

Returns : | `TRUE` if `cap` (channel kind capability) is available.

### spice_channel_set_capability ()

    void                spice_channel_set_capability        (SpiceChannel *channel,
                                                             guint32 cap);

Enable specific channel-kind capability.

`cap` : | a capability

## Property Details

### The `"channel-id"` property

      "channel-id"               gint                  : Read / Write / Construct Only

Allowed values: >= G_MAXULONG

Default value: -1

### The `"channel-type"` property

      "channel-type"             gint                  : Read / Write / Construct Only

Allowed values: >= G_MAXULONG

Default value: -1

### The `"spice-session"` property

      "spice-session"            SpiceSession*         : Read / Write / Construct Only

### The `"total-read-bytes"` property

      "total-read-bytes"         gulong                : Read

## Signal Details

### The `"channel-event"` signal

    void                user_function                      (SpiceChannel *channel,
                                                            gint          event,
                                                            gpointer      user_data)      : Run First

The "channel-event" signal is emitted when the state of the connection change.

`channel` : | the channel that emitted the signal
`event` : | a SpiceChannelEvent
`user_data` : | user data set when the signal handler was connected.

### The `"open-fd"` signal

    void                user_function                      (SpiceChannel *channel,
                                                            gint          with_tls,
                                                            gpointer      user_data)      : Run First

The "open-fd" signal is emitted when a new connection is requested. This signal is emitted when the connection is made with `spice_session_open_fd()`.

`channel` : | the channel that emitted the signal
`with_tls` : | wether TLS connection is requested
`user_data` : | user data set when the signal handler was connected.

## See Also

SpiceSession, SpiceMainChannel and other channels