[Telepathy-commits] [telepathy-glib/master] Document TpChannelManager
Will Thompson
will.thompson at collabora.co.uk
Thu Sep 11 07:51:26 PDT 2008
---
docs/reference/telepathy-glib-sections.txt | 30 ++++++++++
telepathy-glib/channel-manager.c | 79 +++++++++++++++++++++++--
telepathy-glib/channel-manager.h | 88 +++++++++++++++++++++++++++-
3 files changed, 191 insertions(+), 6 deletions(-)
diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index 0a97f4b..79914ee 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -109,6 +109,36 @@ TP_CHANNEL_FACTORY_IFACE_GET_CLASS
</SECTION>
<SECTION>
+<INCLUDE>telepathy-glib/channel-manager.h</INCLUDE>
+<FILE>channel-manager</FILE>
+TpChannelManagerChannelClassFunc
+TpChannelManagerForeachChannelClassFunc
+TpChannelManagerForeachChannelFunc
+TpChannelManagerRequestFunc
+<TITLE>TpChannelManager</TITLE>
+TpChannelManager
+TpChannelManagerIface
+tp_channel_manager_asv_has_unknown_properties
+tp_channel_manager_create_channel
+tp_channel_manager_emit_channel_closed
+tp_channel_manager_emit_channel_closed_for_object
+tp_channel_manager_emit_new_channel
+tp_channel_manager_emit_new_channels
+tp_channel_manager_emit_request_already_satisfied
+tp_channel_manager_emit_request_failed
+tp_channel_manager_emit_request_failed_printf
+tp_channel_manager_foreach_channel
+tp_channel_manager_foreach_channel_class
+tp_channel_manager_request_channel
+<SUBSECTION Standard>
+TP_CHANNEL_MANAGER
+TP_IS_CHANNEL_MANAGER
+TP_TYPE_CHANNEL_MANAGER
+tp_channel_manager_get_type
+TP_CHANNEL_MANAGER_GET_INTERFACE
+</SECTION>
+
+<SECTION>
<INCLUDE>telepathy-glib/exportable-channel.h</INCLUDE>
<FILE>exportable-channel</FILE>
TpExportableChannelFunc
diff --git a/telepathy-glib/channel-manager.c b/telepathy-glib/channel-manager.c
index b090eaf..31d0dc6 100644
--- a/telepathy-glib/channel-manager.c
+++ b/telepathy-glib/channel-manager.c
@@ -20,6 +20,32 @@
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION:channel-manager
+ * @title: TpChannelManager
+ * @short_description: interface for creating and tracking channels
+ * @see_also: #TpSvcConnection
+ *
+ * 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 and the index of chat rooms, and a media channel
+ * manager which handles VoIP calls.
+ */
+
#include "config.h"
#include "channel-manager.h"
@@ -197,7 +223,8 @@ tp_channel_manager_emit_new_channels (gpointer instance,
* tp_channel_manager_emit_new_channel:
* @instance: An object implementing #TpChannelManager
* @channel: A #TpExportableChannel
- * @requests: the request tokens (opaque pointers) satisfied by this channel
+ * @request_tokens: the request tokens (opaque pointers) satisfied by this
+ * channel
*
* Emit the #TpChannelManager::new-channels signal indicating that the
* channel has been created. (This is a convenient shortcut for calling
@@ -350,6 +377,14 @@ tp_channel_manager_emit_request_failed_printf (gpointer instance,
/* Virtual-method wrappers */
+/**
+ * tp_channel_manager_foreach_channel:
+ * @manager: an object implementing #TpChannelManager
+ * @func: A function
+ * @user_data: Arbitrary data to be passed as the second argument of @func
+ *
+ * Calls func(channel, user_data) for each channel managed by @manager.
+ */
void
tp_channel_manager_foreach_channel (TpChannelManager *manager,
TpExportableChannelFunc func,
@@ -367,6 +402,15 @@ tp_channel_manager_foreach_channel (TpChannelManager *manager,
}
+/**
+ * tp_channel_manager_foreach_channel_class:
+ * @manager: An object implementing #TpChannelManager
+ * @func: A function
+ * @user_data: Arbitrary data to be passed as the final argument of @func
+ *
+ * Calls func(manager, fixed, allowed, user_data) for each channel class
+ * understood by @manager.
+ */
void
tp_channel_manager_foreach_channel_class (TpChannelManager *manager,
TpChannelManagerChannelClassFunc func,
@@ -385,6 +429,18 @@ tp_channel_manager_foreach_channel_class (TpChannelManager *manager,
}
+/**
+ * tp_channel_manager_create_channel:
+ * @manager: An object implementing #TpChannelManager
+ * @request_token: An opaque pointer 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.
+ *
+ * Offers an incoming CreateChannel call to @manager.
+ *
+ * Returns: %TRUE if this request will be handled by @manager; else %FALSE.
+ */
gboolean
tp_channel_manager_create_channel (TpChannelManager *manager,
gpointer request_token,
@@ -403,6 +459,18 @@ tp_channel_manager_create_channel (TpChannelManager *manager,
}
+/**
+ * tp_channel_manager_request_channel:
+ * @manager: An object implementing #TpChannelManager
+ * @request_token: An opaque pointer 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.
+ *
+ * Offers an incoming RequestChannel call to @manager.
+ *
+ * Returns: %TRUE if this request will be handled by @manager; else %FALSE.
+ */
gboolean
tp_channel_manager_request_channel (TpChannelManager *manager,
gpointer request_token,
@@ -431,15 +499,16 @@ tp_channel_manager_request_channel (TpChannelManager *manager,
* the D-Bus method when @properties contains unknown properties
*
* Checks whether the keys of @properties are elements of one of @fixed and
- * @allowed. This is intended to be used by channel managers which have
- * decided to accept a request, to conform with the specification's
- * requirement that unknown properties must be rejected, not silently ignored.
+ * @allowed. This is intended to be used by implementations of
+ * #TpChannelManager::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.
*
* Returns: %TRUE if all of the keys of @properties are elements of @fixed or
- * @allowed.
+ * @allowed; else %FALSE.
*/
gboolean
tp_channel_manager_asv_has_unknown_properties (GHashTable *properties,
diff --git a/telepathy-glib/channel-manager.h b/telepathy-glib/channel-manager.h
index a6bf46d..0ba8320 100644
--- a/telepathy-glib/channel-manager.h
+++ b/telepathy-glib/channel-manager.h
@@ -43,12 +43,28 @@ G_BEGIN_DECLS
(G_TYPE_INSTANCE_GET_INTERFACE ((obj), \
TP_TYPE_CHANNEL_MANAGER, TpChannelManagerIface))
+/**
+ * TpChannelManager:
+ *
+ * Opaque typedef representing any channel manager implementation.
+ */
typedef struct _TpChannelManager TpChannelManager;
+
+/* documented below */
typedef struct _TpChannelManagerIface TpChannelManagerIface;
/* virtual methods */
+/**
+ * TpChannelManagerForeachChannelFunc:
+ * @manager: an object implementing #TpChannelManager
+ * @func: A function
+ * @user_data: Arbitrary data to be passed as the second argument of @func
+ *
+ * Signature of an implementation of foreach_channel, which must call
+ * func(channel, user_data) for each channel managed by this channel manager.
+ */
typedef void (*TpChannelManagerForeachChannelFunc) (
TpChannelManager *manager, TpExportableChannelFunc func,
gpointer user_data);
@@ -57,12 +73,34 @@ void tp_channel_manager_foreach_channel (TpChannelManager *manager,
TpExportableChannelFunc func, gpointer user_data);
+/**
+ * TpChannelManagerChannelClassFunc:
+ * @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.
+ *
+ * Signature of callbacks which act on each channel class supported by @manager.
+ */
typedef void (*TpChannelManagerChannelClassFunc) (
TpChannelManager *manager,
GHashTable *fixed_properties,
const gchar * const *allowed_properties,
gpointer user_data);
+/**
+ * TpChannelManagerForeachChannelClassFunc:
+ * @manager: An object implementing #TpChannelManager
+ * @func: A function
+ * @user_data: Arbitrary data to be passed as the final argument of @func
+ *
+ * Signature of an implementation of foreach_channel_class, which must call
+ * func(manager, fixed, allowed, user_data) for each channel class understood
+ * by @manager.
+ */
typedef void (*TpChannelManagerForeachChannelClassFunc) (
TpChannelManager *manager, TpChannelManagerChannelClassFunc func,
gpointer user_data);
@@ -72,6 +110,30 @@ void tp_channel_manager_foreach_channel_class (
TpChannelManagerChannelClassFunc func, gpointer user_data);
+/**
+ * TpChannelManagerRequestFunc:
+ * @manager: An object implementing #TpChannelManager
+ * @request_token: An opaque pointer 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.
+ *
+ * Signature of an implementation of #TpChannelManagerIface::create_channel and
+ * #TpChannelManagerIface::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 #TpChannelManagerIface::new-channels,
+ * #TpChannelManagerIface::already-satisfied and
+ * #TpChannelManagerIface::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.
+ *
+ * Returns: %TRUE if @manager will handle this request, else %FALSE.
+ */
typedef gboolean (*TpChannelManagerRequestFunc) (
TpChannelManager *manager, gpointer request_token,
GHashTable *request_properties);
@@ -83,6 +145,27 @@ gboolean tp_channel_manager_request_channel (TpChannelManager *manager,
gpointer request_token, GHashTable *request_properties);
+/**
+ * TpChannelManagerIface:
+ * @parent: Fields shared with GTypeInterface.
+ * @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.
+ * @foreach_channel_class: 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.
+ * @create_channel: Respond to a request for a new channel made with the
+ * Connection.Interface.Requests.CreateChannel method. See
+ * #TpChannelManagerRequestFunc for details.
+ * @request_channel: Respond to a request for a (new or existing) channel made
+ * with the Connection.RequestChannel method. See #TpChannelManagerRequestFunc
+ * for details.
+ *
+ * The vtable for a channel manager implementation.
+ *
+ * In addition to the fields documented here there are thirteen GCallback
+ * fields which must currently be %NULL.
+ */
struct _TpChannelManagerIface {
GTypeInterface parent;
@@ -94,7 +177,10 @@ struct _TpChannelManagerIface {
TpChannelManagerRequestFunc request_channel;
/* in principle we could have EnsureChannel here too */
- /* ensure_channel and two caps-related methods */
+ /*<private>*/
+ /* extra spaces left for ensure_channel and two caps-related methods, which
+ * will be added in the near future.
+ */
GCallback _near_future[3];
GCallback _future[8];
--
1.5.6.5
More information about the Telepathy-commits
mailing list