Spice Channel

Spice Channel — the base channel class

Stability Level

Stable, unless otherwise indicated

Functions

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

Types and Values

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