Spice Channel

Spice Channel — the base channel class

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <spice-client.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);
const GError *      spice_channel_get_error             (SpiceChannel *channel);

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
  "socket"                   GSocket*              : Read
  "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

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.

GObjectClass parent_class;

Parent class.

channel_event ()

Signal class handler for the "channel_event" signal.

open_fd ()

Signal class handler for the "open_fd" signal.

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

Warning

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.

channel :

a SpiceChannel

spice_channel_connect ()

gboolean            spice_channel_connect               (SpiceChannel *channel);

Connect the channel, using SpiceSession connection informations

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.

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.

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

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

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.

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.

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.

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


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.

channel :

a SpiceChannel

Returns :

the pointer to the error, or NULL

Since 0.24

Property Details

The "channel-id" property

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

Channel ID.

Allowed values: >= -1

Default value: -1


The "channel-type" property

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

Channel type.

Allowed values: >= -1

Default value: -1


The "socket" property

  "socket"                   GSocket*              : Read

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.

Since 0.33


The "spice-session" property

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

Spice session.


The "total-read-bytes" property

  "total-read-bytes"         gulong                : Read

Total read bytes.

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 is changed. In case of errors, spice_channel_get_error() may provide additional informations on the source of the error.

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