![]() |
![]() |
![]() |
telepathy-glib Reference Manual | ![]() |
---|---|---|---|---|
#include <telepathy-glib/channel-manager.h> void (*TpChannelManagerChannelClassFunc) (TpChannelManager *manager, GHashTable *fixed_properties, const gchar * const *allowed_properties, gpointer user_data); void (*TpChannelManagerForeachChannelClassFunc) (TpChannelManager *manager, TpChannelManagerChannelClassFunc func, gpointer user_data); void (*TpChannelManagerForeachChannelFunc) (TpChannelManager *manager, TpExportableChannelFunc func, gpointer user_data); gboolean (*TpChannelManagerRequestFunc) (TpChannelManager *manager, gpointer request_token, GHashTable *request_properties); TpChannelManager; TpChannelManagerIface; gboolean tp_channel_manager_asv_has_unknown_properties (GHashTable *properties, const gchar * const *fixed, const gchar * const *allowed, GError **error); gboolean tp_channel_manager_create_channel (TpChannelManager *manager, gpointer request_token, GHashTable *request_properties); void tp_channel_manager_emit_channel_closed (gpointer instance, const gchar *path); void tp_channel_manager_emit_channel_closed_for_object (gpointer instance, TpExportableChannel *channel); void tp_channel_manager_emit_new_channel (gpointer instance, TpExportableChannel *channel, GSList *request_tokens); void tp_channel_manager_emit_new_channels (gpointer instance, GHashTable *channels); void tp_channel_manager_emit_request_already_satisfied (gpointer instance, gpointer request_token, TpExportableChannel *channel); void tp_channel_manager_emit_request_failed (gpointer instance, gpointer request_token, GQuark domain, gint code, const gchar *message); void tp_channel_manager_emit_request_failed_printf (gpointer instance, gpointer request_token, GQuark domain, gint code, const gchar *format, ...); void tp_channel_manager_foreach_channel (TpChannelManager *manager, TpExportableChannelFunc func, gpointer user_data); void tp_channel_manager_foreach_channel_class (TpChannelManager *manager, TpChannelManagerChannelClassFunc func, gpointer user_data); gboolean tp_channel_manager_request_channel (TpChannelManager *manager, gpointer request_token, GHashTable *request_properties);
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.
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
.
|
An object implementing TpChannelManager |
|
A table mapping (const gchar *) property names to GValues, representing the values those properties must take to request channels of a particular class. |
|
A NULL -terminated array of property names which may
appear in requests for a particular channel class.
|
|
Arbitrary user-supplied data. |
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
.
|
An object implementing TpChannelManager |
|
A function |
|
Arbitrary data to be passed as the final argument of func
|
void (*TpChannelManagerForeachChannelFunc) (TpChannelManager *manager, TpExportableChannelFunc 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.
|
an object implementing TpChannelManager |
|
A function |
|
Arbitrary data to be passed as the second argument of func
|
gboolean (*TpChannelManagerRequestFunc) (TpChannelManager *manager, gpointer request_token, GHashTable *request_properties);
Signature of an implementation of "create_channel" and "request_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-channels",
"already-satisfied" and
"request-failed" signals (including request_token
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
:
|
An object implementing TpChannelManager |
|
An opaque pointer representing this pending request. |
|
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 .
|
typedef struct _TpChannelManager TpChannelManager;
Opaque typedef representing any channel manager implementation.
typedef struct { GTypeInterface parent; TpChannelManagerForeachChannelFunc foreach_channel; TpChannelManagerForeachChannelClassFunc foreach_channel_class; TpChannelManagerRequestFunc create_channel; TpChannelManagerRequestFunc request_channel; /* in principle we could have EnsureChannel here too */ } TpChannelManagerIface;
The vtable for a channel manager implementation.
In addition to the fields documented here there are several GCallback
fields which must currently be NULL
.
GTypeInterface |
Fields shared with GTypeInterface. |
TpChannelManagerForeachChannelFunc |
Call func(channel, user_data) for each channel managed by this manager. If not implemented, the manager is assumed to manage no channels. |
TpChannelManagerForeachChannelClassFunc |
Call func(manager, fixed, allowed, user_data) for each class of channel that this manager can create. If not implemented, the manager is assumed to be able to create no classes of channels. |
TpChannelManagerRequestFunc |
Respond to a request for a new channel made with the Connection.Interface.Requests.CreateChannel method. See TpChannelManagerRequestFunc for details. |
TpChannelManagerRequestFunc |
Respond to a request for a (new or existing) channel made with the Connection.RequestChannel method. See TpChannelManagerRequestFunc for details. |
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
"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 FALSE
, and
set error
to a GError that could be used as a D-Bus method error.
|
a table mapping (const gchar *) property names to GValues, as passed to methods of TpChannelManager |
|
a NULL -terminated array of property names
|
|
a NULL -terminated array of property names
|
|
an address at which to store an error suitable for returning from
the D-Bus method when properties contains unknown properties
|
Returns : |
TRUE if all of the keys of properties are elements of fixed or
allowed ; else FALSE .
|
Since 0.7.15
gboolean tp_channel_manager_create_channel (TpChannelManager *manager, gpointer request_token, GHashTable *request_properties);
Offers an incoming CreateChannel call to manager
.
|
An object implementing TpChannelManager |
|
An opaque pointer representing this pending request. |
|
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.15
void tp_channel_manager_emit_channel_closed (gpointer instance, const gchar *path);
Emit the "channel-closed" signal indicating that the channel at the given object path has been closed.
|
An object implementing TpChannelManager |
|
A channel's object-path |
Since 0.7.15
void tp_channel_manager_emit_channel_closed_for_object (gpointer instance, TpExportableChannel *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
.)
|
An object implementing TpChannelManager |
|
A TpExportableChannel |
Since 0.7.15
void tp_channel_manager_emit_new_channel (gpointer instance, TpExportableChannel *channel, GSList *request_tokens);
Emit the "new-channels" signal indicating that the
channel has been created. (This is a convenient shortcut for calling
tp_channel_manager_emit_new_channels()
with a one-entry hash table.)
|
An object implementing TpChannelManager |
|
A TpExportableChannel |
|
the request tokens (opaque pointers) satisfied by this channel |
Since 0.7.15
void tp_channel_manager_emit_new_channels (gpointer instance, GHashTable *channels);
If channels
is non-empty, emit the "new-channels"
signal indicating that those channels have been created.
|
An object implementing TpChannelManager |
|
a GHashTable where the keys are
TpExportableChannel instances (hashed and compared
by g_direct_hash() and g_direct_equal() ) and the values are
linked lists (GSList) of request tokens (opaque pointers) satisfied by
these channels
|
Since 0.7.15
void tp_channel_manager_emit_request_already_satisfied (gpointer instance, gpointer request_token, TpExportableChannel *channel);
Emit the "request-already-satisfied" signal indicating
that the pre-existing channel channel
satisfies request_token
.
|
An object implementing TpChannelManager |
|
An opaque pointer representing the request that succeeded |
|
The channel that satisfies the request |
Since 0.7.15
void tp_channel_manager_emit_request_failed (gpointer instance, gpointer request_token, GQuark domain, gint code, const gchar *message);
Emit the "request-failed" signal indicating that
the request request_token
failed for the given reason.
|
An object implementing TpChannelManager |
|
An opaque pointer representing the request that failed |
|
a GError domain |
|
a GError code appropriate for domain
|
|
the error message |
Since 0.7.15
void tp_channel_manager_emit_request_failed_printf (gpointer instance, gpointer request_token, GQuark domain, gint code, const gchar *format, ...);
Emit the "request-failed" signal indicating that
the request request_token
failed for the given reason.
|
An object implementing TpChannelManager |
|
An opaque pointer representing the request that failed |
|
a GError domain |
|
a GError code appropriate for domain
|
|
a printf-style format string for the error message |
|
arguments for the format string |
Since 0.7.15
void tp_channel_manager_foreach_channel (TpChannelManager *manager, TpExportableChannelFunc func, gpointer user_data);
Calls func(channel, user_data) for each channel managed by manager
.
|
an object implementing TpChannelManager |
|
A function |
|
Arbitrary data to be passed as the second argument of func
|
Since 0.7.15
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
.
|
An object implementing TpChannelManager |
|
A function |
|
Arbitrary data to be passed as the final argument of func
|
Since 0.7.15
gboolean tp_channel_manager_request_channel (TpChannelManager *manager, gpointer request_token, GHashTable *request_properties);
Offers an incoming RequestChannel call to manager
.
|
An object implementing TpChannelManager |
|
An opaque pointer representing this pending request. |
|
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.15