Spice Channel: Spice-GTK Reference Manual

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

## Stability Level

Stable, unless otherwise indicated

## Functions

SpiceChannel * | spice_channel_new ()
void | spice_channel_destroy ()
gboolean | spice_channel_connect ()
gboolean | spice_channel_open_fd ()
void | spice_channel_disconnect ()
gboolean | spice_channel_test_capability ()
gboolean | spice_channel_test_common_capability ()
const gchar * | spice_channel_type_to_string ()
gint | spice_channel_string_to_type ()
void | spice_channel_set_capability ()
void | spice_channel_flush_async ()
gboolean | spice_channel_flush_finish ()
const GError * | spice_channel_get_error ()

## Properties

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

## Signals

void | channel-event | Run First
void | open-fd | Run First

## Types and Values

enum | SpiceChannelEvent
| SpiceChannel
| SpiceChannelClass

## Object Hierarchy

        GEnum
        ╰── SpiceChannelEvent
        GObject
        ╰── SpiceChannel
            ├── SpiceCursorChannel
            ├── SpiceDisplayChannel
            ├── SpiceInputsChannel
            ├── SpiceMainChannel
            ├── SpicePlaybackChannel
            ├── SpiceRecordChannel
            ├── SpiceSmartcardChannel
            ├── SpiceUsbredirChannel
            ╰── SpicePortChannel

## Includes

    #include <spice-channel.h>

## Description

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

## Functions

### spice_channel_new ()

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

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

#### Parameters

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

`spice_channel_destroy` has been deprecated since version 0.27 and should not be used in newly-written code.

this function has been deprecated because it is misleading, the object is not actually destroyed. Instead, it is recommended to call explicitely `spice_channel_disconnect()` and `g_object_unref()`.

Disconnect and unref the `channel` .

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

### spice_channel_get_error ()

    const GError *
    spice_channel_get_error (SpiceChannel *channel);

Retrieves the GError currently set on channel, if the SpiceChannel is in error state and can provide additional error details.

#### Returns

the pointer to the error, or `NULL`

Since: 0.24

## Types and Values

### enum SpiceChannelEvent

An event, emitted by “channel-event” signal.

#### Members

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;

## Property Details

### The `“channel-id”` property

      “channel-id”               gint

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1

### The `“channel-type”` property

      “channel-type”             gint

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1

### The `“spice-session”` property

      “spice-session”            SpiceSession *

Flags: Read / Write / Construct Only

### The `“total-read-bytes”` property

      “total-read-bytes”         gulong

Flags: Read

## Signal Details

### The `“channel-event”` signal

    void
    user_function (SpiceChannel     *channel,
                   SpiceChannelEvent event,
                   gpointer          user_data)

The “channel-event” signal is emitted when the state of the connection is changed. In case of errors, `spice_channel_get_error()` may provide additional informations on the source of the error.

#### Parameters

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

Flags: Run First

### The `“open-fd”` signal

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

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

#### Parameters

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

Flags: Run First

## See Also

SpiceSession, SpiceMainChannel and other channels