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

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

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 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
Generated by GTK-Doc V1.19