telepathy-glib API Reference Manual: TpChannelManager

TpChannelManager

TpChannelManager — interface for creating and tracking channels

Functions

void	(*TpChannelManagerChannelClassFunc) ()
void	(*TpChannelManagerForeachChannelClassFunc) ()
void	(*TpChannelManagerTypeChannelClassFunc) ()
void	(*TpChannelManagerTypeForeachChannelClassFunc) ()
void	(*TpChannelManagerForeachChannelFunc) ()
gboolean	(*TpChannelManagerRequestFunc) ()
gboolean	tp_channel_manager_asv_has_unknown_properties ()
gboolean	tp_channel_manager_create_channel ()
void	tp_channel_manager_emit_channel_closed ()
void	tp_channel_manager_emit_channel_closed_for_object ()
void	tp_channel_manager_emit_new_channel ()
void	tp_channel_manager_emit_request_already_satisfied ()
void	tp_channel_manager_emit_request_failed ()
void	tp_channel_manager_emit_request_failed_printf ()
gboolean	tp_channel_manager_ensure_channel ()
void	tp_channel_manager_foreach_channel ()
void	tp_channel_manager_foreach_channel_class ()
void	tp_channel_manager_type_foreach_channel_class ()

Signals

void	channel-closed	Has Details
void	new-channel	Has Details
void	request-already-satisfied	Has Details
void	request-failed	Has Details

Types and Values

	TpChannelManager
struct	TpChannelManagerIface

Object Hierarchy

    GInterface
    ╰── TpChannelManager

Known Implementations

TpChannelManager is implemented by TpSimplePasswordManager.

Includes

#include <telepathy-glib/telepathy-glib.h>

Description

A channel manager is attached to a connection. It carries out channel requests from the connection, and responds to channel-related events on the underlying network connection, for particular classes of channel (for example, incoming and outgoing calls, respectively). It also tracks currently-open channels of the relevant kinds.

The connection has an array of channel managers. In response to a call to CreateChannel or RequestChannel, the channel request is offered to each channel manager in turn, until one accepts the request. In a trivial implementation there might be a single channel manager which handles all requests and all incoming events, but in general, there will be multiple channel managers handling different types of channel.

For example, at the time of writing, Gabble has a roster channel manager which handles contact lists and groups, an IM channel manager which handles one-to-one messaging, a MUC channel manager which handles multi-user chat rooms, the index of chat rooms and MUC tubes, a media channel manager which handles VoIP calls, and a 1-1 tubes channel manager.

Functions

TpChannelManagerChannelClassFunc ()

void
(*TpChannelManagerChannelClassFunc) (TpChannelManager *manager,
                                     GHashTable *fixed_properties,
                                     const gchar * const *allowed_properties,
                                     gpointer user_data);

Signature of callbacks which act on each channel class supported by manager .

Parameters

manager	An object implementing TpChannelManager
fixed_properties	A table mapping (const gchar *) property names to GValues, representing the values those properties must take to request channels of a particular class.
allowed_properties	A `NULL`-terminated array of property names which may appear in requests for a particular channel class.
user_data	Arbitrary user-supplied data.

TpChannelManagerForeachChannelClassFunc ()

void
(*TpChannelManagerForeachChannelClassFunc)
                               (TpChannelManager *manager,
                                TpChannelManagerChannelClassFunc func,
                                gpointer user_data);

Signature of an implementation of foreach_channel_class, which must call func(manager, fixed, allowed, user_data) for each channel class understood by manager .

Parameters

manager	An object implementing TpChannelManager
func	A function
user_data	Arbitrary data to be passed as the final argument of `func`

TpChannelManagerTypeChannelClassFunc ()

void
(*TpChannelManagerTypeChannelClassFunc)
                               (GType type,
                                GHashTable *fixed_properties,
                                const gchar * const *allowed_properties,
                                gpointer user_data);

Signature of callbacks which act on each channel class potentially supported by instances of type .

Parameters

type	A type whose instances implement TpChannelManager
fixed_properties	A table mapping (const gchar *) property names to GValues, representing the values those properties must take to request channels of a particular class.
allowed_properties	A `NULL`-terminated array of property names which may appear in requests for a particular channel class.
user_data	Arbitrary user-supplied data.

TpChannelManagerTypeForeachChannelClassFunc ()

void
(*TpChannelManagerTypeForeachChannelClassFunc)
                               (GType type,
                                TpChannelManagerTypeChannelClassFunc func,
                                gpointer user_data);

Signature of an implementation of type_foreach_channel_class, which must call func(type, fixed, allowed, user_data) for each channel class potentially understood by instances of type .

Parameters

type	A type whose instances implement TpChannelManager
func	A function
user_data	Arbitrary data to be passed as the final argument of `func`

TpChannelManagerForeachChannelFunc ()

void
(*TpChannelManagerForeachChannelFunc) (TpChannelManager *manager,
                                       TpBaseChannelFunc func,
                                       gpointer user_data);

Signature of an implementation of foreach_channel, which must call func(channel, user_data) for each channel managed by this channel manager.

Parameters

manager	an object implementing TpChannelManager
func	A function
user_data	Arbitrary data to be passed as the second argument of `func`

TpChannelManagerRequestFunc ()

gboolean
(*TpChannelManagerRequestFunc) (TpChannelManager *manager,
                                TpChannelManagerRequest *request,
                                GHashTable *request_properties);

Signature of an implementation of TpChannelManagerIface.create_channel.

Implementations should inspect the contents of request_properties to see if it matches a channel class handled by this manager. If so, they should return TRUE to accept responsibility for the request, and ultimately emit exactly one of the “new-channel”, “request-already-satisfied” and “request-failed” signals (including request in the appropriate argument).

If the implementation does not want to handle the request, it should return FALSE to allow the request to be offered to another channel manager.

Implementations may assume the following of request_properties :

the ChannelType property is present, and is a (const gchar *)
the TargetEntityType property is a valid TpEntityType, if present
if TargetEntityType is None, TargetHandle is omitted
if TargetEntityType is not None, TargetHandle is a valid TpHandle of that TpEntityType

Changed in version 0.15.5: Previously the TargetID property was guaranteed to be missing from request_properties . Now it is always present, whether it was in the original channel request or not.

Parameters

manager	An object implementing TpChannelManager
request	A TpChannelManagerRequest representing this pending request.
request_properties	A table mapping (const gchar *) property names to GValue, representing the desired properties of a channel requested by a Telepathy client. The hash table will be freed after the function returns; if the channel manager wants to keep it around, it must copy it.

Returns

TRUE if manager will handle this request, else FALSE.

tp_channel_manager_asv_has_unknown_properties ()

gboolean
tp_channel_manager_asv_has_unknown_properties
                               (GHashTable *properties,
                                const gchar * const *fixed,
                                const gchar * const *allowed,
                                GError **error);

Checks whether the keys of properties are elements of one of fixed and allowed . This is intended to be used by implementations of TpChannelManagerIface.create_channel which have decided to accept a request, to conform with the specification's requirement that unknown requested properties must cause a request to fail, not be silently ignored.

On encountering unknown properties, this function will return TRUE, and set error to a GError that could be used as a D-Bus method error.

Parameters

properties	a table mapping (const gchar *) property names to GValues, as passed to methods of TpChannelManager
fixed	a `NULL`-terminated array of property names
allowed	a `NULL`-terminated array of property names
error	an address at which to store an error suitable for returning from the D-Bus method when `properties` contains unknown properties

Returns

TRUE if properties contains keys not in either fixed or allowed ; else FALSE.

Since 0.7.15

tp_channel_manager_create_channel ()

gboolean
tp_channel_manager_create_channel (TpChannelManager *manager,
                                   TpChannelManagerRequest *request,
                                   GHashTable *request_properties);

Offers an incoming CreateChannel call to manager .

Parameters

manager	An object implementing TpChannelManager
request	A TpChannelManagerRequest representing this pending request.
request_properties	A table mapping (const gchar *) property names to GValue, representing the desired properties of a channel requested by a Telepathy client.

Returns

TRUE if this request will be handled by manager ; else FALSE.

tp_channel_manager_emit_channel_closed ()

void
tp_channel_manager_emit_channel_closed
                               (TpChannelManager *self,
                                const gchar *path);

Emit the “channel-closed” signal indicating that the channel at the given object path has been closed.

Parameters

self	An object implementing TpChannelManager
path	A channel's object-path

Since 0.7.15

tp_channel_manager_emit_channel_closed_for_object ()

void
tp_channel_manager_emit_channel_closed_for_object
                               (TpChannelManager *self,
                                TpBaseChannel *channel);

Emit the “channel-closed” signal indicating that the given channel has been closed. (This is a convenient shortcut for calling tp_channel_manager_emit_channel_closed() with the “object-path” property of channel .)

Parameters

self	An object implementing TpChannelManager
channel	A TpBaseChannel

Since 0.7.15

tp_channel_manager_emit_new_channel ()

void
tp_channel_manager_emit_new_channel (TpChannelManager *self,
                                     TpBaseChannel *channel,
                                     GSList *requests);

Emit the “new-channel” signal indicating that the channel has been created.

Parameters

self	An object implementing TpChannelManager
channel	A TpBaseChannel
requests	(element-type TelepathyGLib.ChannelManagerRequest) the TpChannelManagerRequest objects satisfied by this channel

Since 0.7.15

tp_channel_manager_emit_request_already_satisfied ()

void
tp_channel_manager_emit_request_already_satisfied
                               (TpChannelManager *self,
                                TpChannelManagerRequest *request,
                                TpBaseChannel *channel);

Emit the “request-already-satisfied” signal indicating that the pre-existing channel channel satisfies request .

Parameters

self	An object implementing TpChannelManager
request	An TpChannelManagerRequest representing the request that succeeded
channel	The channel that satisfies the request

tp_channel_manager_emit_request_failed ()

void
tp_channel_manager_emit_request_failed
                               (TpChannelManager *self,
                                TpChannelManagerRequest *request,
                                GQuark domain,
                                gint code,
                                const gchar *message);

Emit the “request-failed” signal indicating that the request request failed for the given reason.

Parameters

self	An object implementing TpChannelManager
request	An TpChannelManagerRequest representing the request that failed
domain	a GError domain
code	a GError code appropriate for `domain`
message	the error message

tp_channel_manager_emit_request_failed_printf ()

void
tp_channel_manager_emit_request_failed_printf
                               (TpChannelManager *self,
                                TpChannelManagerRequest *request,
                                GQuark domain,
                                gint code,
                                const gchar *format,
                                ...);

Emit the “request-failed” signal indicating that the request request failed for the given reason.

Parameters

self	An object implementing TpChannelManager
request	A TpChannelManagerRequest representing the request that failed
domain	a GError domain
code	a GError code appropriate for `domain`
format	a printf-style format string for the error message
...	arguments for the format string

Since 0.7.15

tp_channel_manager_ensure_channel ()

gboolean
tp_channel_manager_ensure_channel (TpChannelManager *manager,
                                   TpChannelManagerRequest *request,
                                   GHashTable *request_properties);

Offers an incoming EnsureChannel call to manager .

Parameters

manager	An object implementing TpChannelManager
request	A TpChannelManagerRequest representing this pending request.
request_properties	A table mapping (const gchar *) property names to GValue, representing the desired properties of a channel requested by a Telepathy client.

Returns

TRUE if this request will be handled by manager ; else FALSE.

Since 0.7.16

tp_channel_manager_foreach_channel ()

void
tp_channel_manager_foreach_channel (TpChannelManager *manager,
                                    TpBaseChannelFunc func,
                                    gpointer user_data);

Calls func(channel, user_data) for each channel managed by manager .

Parameters

manager	an object implementing TpChannelManager
func	A function.	[scope call]
user_data	Arbitrary data to be passed as the second argument of `func`

Since 0.7.15

tp_channel_manager_foreach_channel_class ()

void
tp_channel_manager_foreach_channel_class
                               (TpChannelManager *manager,
                                TpChannelManagerChannelClassFunc func,
                                gpointer user_data);

Calls func(manager, fixed, allowed, user_data) for each channel class understood by manager .

Parameters

manager	An object implementing TpChannelManager
func	A function.	[scope call]
user_data	Arbitrary data to be passed as the final argument of `func`

Since 0.7.15

tp_channel_manager_type_foreach_channel_class ()

void
tp_channel_manager_type_foreach_channel_class
                               (GType type,
                                TpChannelManagerTypeChannelClassFunc func,
                                gpointer user_data);

Calls func(type, fixed, allowed, user_data) for each channel class potentially understood by instances of type .

Parameters

type	A type whose instances implement TpChannelManager
func	A function.	[scope call]
user_data	Arbitrary data to be passed as the final argument of `func`

Since 0.11.11

Types and Values

TpChannelManager

typedef struct _TpChannelManager TpChannelManager;

Opaque typedef representing any channel manager implementation.

struct TpChannelManagerIface

struct TpChannelManagerIface {
    GTypeInterface parent;

    TpChannelManagerForeachChannelFunc foreach_channel;

    TpChannelManagerForeachChannelClassFunc foreach_channel_class;

    TpChannelManagerRequestFunc create_channel;
    TpChannelManagerRequestFunc ensure_channel;

    TpChannelManagerTypeForeachChannelClassFunc type_foreach_channel_class;
};

The vtable for a channel manager implementation.

In addition to the fields documented here there are several GCallback fields which must currently be NULL.

Members

GTypeInterface `parent`;	Fields shared with GTypeInterface.
TpChannelManagerForeachChannelFunc `foreach_channel`;	Call func(channel, user_data) for each channel managed by this manager. If not implemented, the manager is assumed to manage no channels.
TpChannelManagerForeachChannelClassFunc `foreach_channel_class`;	Call func(manager, fixed, allowed, user_data) for each class of channel that this instance can create (a subset of the channel classes produced by `type_foreach_channel_class` ). If not implemented, `type_foreach_channel_class` is used.
TpChannelManagerRequestFunc `create_channel`;	Respond to a request for a new channel made with the Connection.Interface.Requests.CreateChannel method. See TpChannelManagerRequestFunc for details.
TpChannelManagerRequestFunc `ensure_channel`;	Respond to a request for a (new or existing) channel made with the Connection.Interface.Requests.EnsureChannel method. See TpChannelManagerRequestFunc for details. Since: 0.7.16
TpChannelManagerTypeForeachChannelClassFunc `type_foreach_channel_class`;	Call func(cls, fixed, allowed, user_data) for each class of channel that instances of this class might be able to create. Since: 0.11.11

Since 0.7.15

Signal Details

The `“channel-closed”` signal

void
user_function (TpChannelManager *self,
               gchar            *path,
               gpointer          user_data)

Emitted when a channel has been closed. The Connection should generally respond to this signal by emitting ChannelClosed.

Parameters

self	the channel manager
path	the channel's object-path
user_data	user data set when the signal handler was connected.

Flags: Has Details

The `“new-channel”` signal

void
user_function (TpChannelManager *self,
               GObject          *channel,
               gpointer          channels,
               gpointer          user_data)

Emitted when a new channel has been created. The Connection should generally emit NewChannel in response to this signal, and then return from pending CreateChannel, EnsureChannel calls if appropriate.

Parameters

self	the channel manager
channel	a object implementing TpBaseChannel
channels	a GSList of TpChannelManagerRequest satisfied by `channel` .	[type GLib.SList][element-type TelepathyGLib.ChannelManagerRequest]
user_data	user data set when the signal handler was connected.

Flags: Has Details

The `“request-already-satisfied”` signal

void
user_function (TpChannelManager        *self,
               TpChannelManagerRequest *request,
               GObject                 *channel,
               gpointer                 user_data)

Emitted when a channel request is satisfied by an existing channel. The Connection should generally respond to this signal by returning success from EnsureChannel or RequestChannel.

Parameters

self	the channel manager
request	a TpChannelManagerRequest supplied by the requester, representing a request
channel	the existing TpBaseChannel that satisfies the request
user_data	user data set when the signal handler was connected.

Flags: Has Details

The `“request-failed”` signal

void
user_function (TpChannelManager        *self,
               TpChannelManagerRequest *request,
               guint                    domain,
               gint                     code,
               gchar                   *message,
               gpointer                 user_data)

Emitted when a channel request has failed. The Connection should generally respond to this signal by returning failure from CreateChannel, EnsureChannel or RequestChannel.

Parameters

self	the channel manager
request	a TpChannelManagerRequest supplied by the requester, representing a request
domain	the domain of a GError indicating why the request failed
code	the error code of a GError indicating why the request failed
message	the string part of a GError indicating why the request failed
user_data	user data set when the signal handler was connected.

Flags: Has Details

TpChannelManager

Functions

Signals

Types and Values

Object Hierarchy

Known Implementations

Includes

Description

Functions

TpChannelManagerChannelClassFunc ()

Parameters

TpChannelManagerForeachChannelClassFunc ()

Parameters

TpChannelManagerTypeChannelClassFunc ()

Parameters

TpChannelManagerTypeForeachChannelClassFunc ()

Parameters

TpChannelManagerForeachChannelFunc ()

Parameters

TpChannelManagerRequestFunc ()

Parameters

Returns

tp_channel_manager_asv_has_unknown_properties ()

Parameters

Returns

tp_channel_manager_create_channel ()

Parameters

Returns

tp_channel_manager_emit_channel_closed ()

Parameters

tp_channel_manager_emit_channel_closed_for_object ()

Parameters

tp_channel_manager_emit_new_channel ()

Parameters

tp_channel_manager_emit_request_already_satisfied ()

Parameters

tp_channel_manager_emit_request_failed ()

Parameters

tp_channel_manager_emit_request_failed_printf ()

Parameters

tp_channel_manager_ensure_channel ()

Parameters

Returns

tp_channel_manager_foreach_channel ()

Parameters

tp_channel_manager_foreach_channel_class ()

Parameters

tp_channel_manager_type_foreach_channel_class ()

Parameters

Types and Values

TpChannelManager

struct TpChannelManagerIface

Members

Signal Details

The “channel-closed” signal

Parameters

The “new-channel” signal

Parameters

The “request-already-satisfied” signal

Parameters

The “request-failed” signal

Parameters

See Also

The `“channel-closed”` signal

The `“new-channel”` signal

The `“request-already-satisfied”` signal

The `“request-failed”` signal