## Spice Channel

Spice Channel — the base channel class

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <spice-channel.h>

    enum                SpiceChannelEvent;
                        SpiceChannel;
                        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);
    gboolean            spice_channel_test_common_capability
                                                            (SpiceChannel *channel,
                                                             guint32 cap);
    const gchar *       spice_channel_type_to_string        (gint type);
    gint                spice_channel_string_to_type        (const gchar *str);
    void                spice_channel_set_capability        (SpiceChannel *channel,
                                                             guint32 cap);
    void                spice_channel_flush_async           (SpiceChannel *channel,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            spice_channel_flush_finish          (SpiceChannel *channel,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GEnum
       +----SpiceChannelEvent

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

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

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

`SPICE_CHANNEL_NONE` | no event, or ignored event
`SPICE_CHANNEL_OPENED` | connection is authentified and ready
`SPICE_CHANNEL_SWITCHING` |
`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

### SpiceChannel

    typedef struct _SpiceChannel SpiceChannel;

### SpiceChannelClass

    typedef struct {
        GObjectClass parent_class;

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

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

If `fd` is -1, a valid fd will be requested later via the SpiceChannel::open-fd signal.

`fd` : | a file descriptor (socket) or -1. request mechanism
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_test_common_capability ()

    gboolean            spice_channel_test_common_capability
                                                            (SpiceChannel *channel,
                                                             guint32 cap);

Test availability of remote "common channel capability".

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

### spice_channel_type_to_string ()

    const gchar *       spice_channel_type_to_string        (gint type);

Convert a channel-type property value to a string.

`type` : | a channel-type property value
Returns : | string representation of `type`.

Since 0.20

### spice_channel_string_to_type ()

    gint                spice_channel_string_to_type        (const gchar *str);

Convert a channel-type property value to a string.

`str` : | a string representation of the channel-type property
Returns : | the channel-type property value for a `str` channel

Since 0.21

### spice_channel_set_capability ()

    void                spice_channel_set_capability        (SpiceChannel *channel,
                                                             guint32 cap);

### Warning

`spice_channel_set_capability` has been deprecated since version 0.13 and should not be used in newly-written code. this function has been removed

Enable specific channel-kind capability.

`cap` : | a capability

### spice_channel_flush_async ()

    void                spice_channel_flush_async           (SpiceChannel *channel,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Forces an asynchronous write of all user-space buffered data for the given channel.

When the operation is finished callback will be called. You can then call `spice_channel_flush_finish()` to get the result of the operation.

`channel` : | a SpiceChannel
`cancellable` : | optional GCancellable object, `NULL` to ignore. [allow-none]
`callback` : | callback to call when the request is satisfied. [scope async]
`user_data` : | the data to pass to callback function. [closure]

Since 0.15

### spice_channel_flush_finish ()

    gboolean            spice_channel_flush_finish          (SpiceChannel *channel,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes flushing a channel.

`channel` : | a SpiceChannel
`result` : | a GAsyncResult
`error` : | a GError location to store the error occurring, or `NULL` to ignore.
Returns : | `TRUE` if flush operation succeeded, `FALSE` otherwise.

Since 0.15

## Property Details

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

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

Allowed values: >= -1

Default value: -1

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

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

Allowed values: >= -1

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,
                                                            SpiceChannelEvent 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