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
GSocket * | socket | Read
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-client.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` .

#### Parameters

channel | a SpiceChannel |

### spice_channel_connect ()

    gboolean
    spice_channel_connect (SpiceChannel *channel);

Connect the channel, using SpiceSession connection informations

#### Parameters

channel | a SpiceChannel |

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

channel | a SpiceChannel |
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

channel | a SpiceChannel |
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".

#### Parameters

channel | a SpiceChannel |
cap | a 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".

#### Parameters

channel | a SpiceChannel |
cap | a 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

channel | a SpiceChannel |
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.

#### Parameters

channel | a SpiceChannel |

#### 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 | disconnecting from the current host and connecting to the target host. |
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;

The SpiceChannel struct is opaque and should not be accessed directly.

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

Class structure for SpiceChannel.

#### Members

`channel_event` () | Signal class handler for the “channel_event” signal. |
`open_fd` () | Signal class handler for the “open_fd” signal. |

## Property Details

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

      “channel-id”               gint

Channel ID.

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1

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

      “channel-type”             gint

Channel type.

Flags: Read / Write / Construct Only

Allowed values: >= -1

Default value: -1

### The `“socket”` property

      “socket”                   GSocket *

Get the underlying GSocket. Note that you should not read or write any data to it directly since this will likely corrupt the channel stream. This property is mainly useful to get some connections details.

Flags: Read

Since: 0.33

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

      “spice-session”            SpiceSession *

Spice session.

Flags: Read / Write / Construct Only

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

      “total-read-bytes”         gulong

Total read bytes.

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