[Telepathy-commits] [telepathy-glib/master] BaseConnection: move gtkdoc to .c
Will Thompson
will.thompson at collabora.co.uk
Wed Sep 17 08:47:21 PDT 2008
---
telepathy-glib/base-connection.c | 197 ++++++++++++++++++++++++++++++++++++++
telepathy-glib/base-connection.h | 186 +-----------------------------------
2 files changed, 198 insertions(+), 185 deletions(-)
diff --git a/telepathy-glib/base-connection.c b/telepathy-glib/base-connection.c
index 8768d28..677436b 100644
--- a/telepathy-glib/base-connection.c
+++ b/telepathy-glib/base-connection.c
@@ -35,6 +35,203 @@
* asynchronously.
*/
+/**
+ * TpBaseConnectionProc:
+ * @self: The connection object
+ *
+ * Signature of a virtual method on #TpBaseConnection that takes no
+ * additional parameters and returns nothing.
+ */
+
+/**
+ * TpBaseConnectionStartConnectingImpl:
+ * @self: The connection object
+ * @error: Set to the error if %FALSE is returned
+ *
+ * Signature of an implementation of the start_connecting method
+ * of #TpBaseConnection.
+ *
+ * On entry, the implementation may assume that it is in state NEW.
+ *
+ * If %TRUE is returned, the Connect D-Bus method succeeds; the
+ * implementation must either have already set the status to CONNECTED by
+ * calling tp_base_connection_change_status(), or have arranged for a
+ * status change to either state DISCONNECTED or CONNECTED to be signalled by
+ * calling tp_base_connection_change_status() at some later time.
+ * If the status is still NEW after returning %TRUE, #TpBaseConnection will
+ * automatically change it to CONNECTING for reason REQUESTED.
+ *
+ * If %FALSE is returned, the error will be raised from Connect as an
+ * exception. If the status is not DISCONNECTED after %FALSE is returned,
+ * #TpBaseConnection will automatically change it to DISCONNECTED
+ * with a reason appropriate to the error; NetworkError results in
+ * NETWORK_ERROR, PermissionDenied results in AUTHENTICATION_FAILED, and all
+ * other errors currently result in NONE_SPECIFIED.
+ *
+ * All except the simplest connection managers are expected to implement this
+ * asynchronously, returning %TRUE in most cases and changing the status
+ * to CONNECTED or DISCONNECTED later.
+ *
+ * Returns: %FALSE if failure has already occurred, else %TRUE.
+ */
+
+/**
+ * TpBaseConnectionCreateHandleReposImpl:
+ * @self: The connection object
+ * @repos: An array of pointers to be filled in; the implementation
+ * may assume all are initially NULL.
+ *
+ * Signature of an implementation of the create_handle_repos method
+ * of #TpBaseConnection.
+ */
+
+/**
+ * TpBaseConnectionCreateChannelFactoriesImpl:
+ * @self: The implementation, a subclass of TpBaseConnection
+ *
+ * Signature of an implementation of the create_channel_factories method
+ * of #TpBaseConnection.
+ *
+ * Returns: a GPtrArray of objects implementing #TpChannelFactoryIface
+ * which, between them, implement all channel types this Connection
+ * supports.
+ */
+
+/**
+ * TpBaseConnectionCreateChannelManagersImpl:
+ * @self: The implementation, a subclass of TpBaseConnection
+ *
+ * Signature of an implementation of the create_channel_managers method
+ * of #TpBaseConnection.
+ *
+ * Returns: a GPtrArray of objects implementing #TpChannelManager
+ * which, between them, implement all channel types this Connection
+ * supports.
+ */
+
+/**
+ * TpBaseConnectionGetUniqueConnectionNameImpl:
+ * @self: The implementation, a subclass of TpBaseConnection
+ *
+ * Signature of the @get_unique_connection_name virtual method
+ * on #TpBaseConnection.
+ *
+ * Returns: a name for this connection which will be unique within this
+ * connection manager process, as a string which the caller must free
+ * with #g_free.
+ */
+
+/**
+ * TpBaseConnectionClass:
+ * @parent_class: The superclass' structure
+ * @create_handle_repos: Fill in suitable handle repositories in the
+ * given array for all those handle types this Connection supports.
+ * Must be set by subclasses to a non-%NULL value; the function must create
+ * at least a CONTACT handle repository (failing to do so will cause a crash).
+ * @create_channel_factories: Create an array of channel factories for this
+ * Connection. At least one of this or @create_channel_managers must be set by
+ * subclasses to a non-%NULL value; in new code, setting this to %NULL and
+ * using channel managers exclusively is recommended.
+ * @get_unique_connection_name: Construct a unique name for this connection
+ * (for example using the protocol's format for usernames). If %NULL (the
+ * default), a unique name will be generated. Subclasses should usually
+ * override this to get more obvious names, to aid debugging and prevent
+ * multiple connections to the same account.
+ * @connecting: If set by subclasses, will be called just after the state
+ * changes to CONNECTING. May be %NULL if nothing special needs to happen.
+ * @connected: If set by subclasses, will be called just after the state
+ * changes to CONNECTED. May be %NULL if nothing special needs to happen.
+ * @disconnected: If set by subclasses, will be called just after the state
+ * changes to DISCONNECTED. May be %NULL if nothing special needs to happen.
+ * @shut_down: Called after disconnected() is called, to clean up the
+ * connection. Must start the shutdown process for the underlying
+ * network connection, and arrange for tp_base_connection_finish_shutdown()
+ * to be called after the underlying connection has been closed. May not
+ * be left as %NULL.
+ * @start_connecting: Asynchronously start connecting - called to implement
+ * the Connect D-Bus method. See #TpBaseConnectionStartConnectingImpl for
+ * details. May not be left as %NULL.
+ * @interfaces_always_present: A strv of extra D-Bus interfaces which are
+ * always implemented by instances of this class, which may be filled in
+ * by subclasses. The default is to list no additional interfaces.
+ * Individual instances may detect which additional interfaces they support
+ * and signal them before going to state CONNECTED by calling
+ * tp_base_connection_add_interfaces().
+ * @create_channel_managers: Create an array of channel managers for this
+ * Connection. At least one of this or @create_channel_factories must be set
+ * by subclasses to a non-%NULL value.
+ * Since: 0.7.UNRELEASED
+ *
+ * The class of a #TpBaseConnection. Many members are virtual methods etc.
+ * to be filled in in the subclass' class_init function.
+ *
+ * In addition to the fields documented here, there are three gpointer fields
+ * which must currently be %NULL (a meaning may be defined for these in a
+ * future version of telepathy-glib), and a pointer to opaque private data.
+ */
+
+/**
+ * TP_INTERNAL_CONNECTION_STATUS_NEW:
+ *
+ * A special value for #TpConnectionStatus, used within GLib connection
+ * managers to indicate that the connection is disconnected because
+ * connection has never been attempted (as distinct from disconnected
+ * after connection has started, either by user request or an error).
+ *
+ * Must never be visible on the D-Bus - %TP_CONNECTION_STATUS_DISCONNECTED
+ * is sent instead.
+ */
+
+/**
+ * TpBaseConnection:
+ * @parent: Fields shared by the superclass.
+ * @bus_name: A D-Bus well-known bus name, owned by the connection manager
+ * process and associated with this connection. Set by
+ * tp_base_connection_register; should be considered read-only by subclasses.
+ * @object_path: The object-path of this connection. Set by
+ * tp_base_connection_register; should be considered read-only by subclasses.
+ * @status: Connection status - may either be a valid TpConnectionStatus or
+ * TP_INTERNAL_CONNECTION_STATUS_NEW. Should be considered read-only by
+ * subclasses: use tp_base_connection_change_status() to set it.
+ * @self_handle: The handle of type %TP_HANDLE_TYPE_CONTACT representing the
+ * local user. Must be set nonzero by the subclass before moving to state
+ * CONNECTED. Since 0.7.UNRELEASED, setting this property directly is
+ * deprecated, in favour of tp_base_connection_set_self_handle(); if this
+ * property is set directly, the connection must ensure it holds a reference
+ * to the handle. Changing this property directly having moved to state
+ * CONNECTED is very strongly discouraged, as this will prevent the
+ * SelfHandleChanged signal being emitted.
+ *
+ * Data structure representing a generic #TpSvcConnection implementation.
+ *
+ * In addition to the fields documented here, there are four gpointer fields
+ * which must currently be %NULL (a meaning may be defined for these in a
+ * future version of telepathy-glib), and a pointer to opaque private data.
+ */
+
+/**
+ * TpChannelManagerIter:
+ * @see_also: tp_base_connection_channel_manager_iter_init(),
+ * tp_base_connection_channel_manager_iter_next()
+ *
+ * An iterator over the #TpChannelManager objects known to a #TpBaseConnection.
+ * It has no public fields.
+ *
+ * Since: 0.7.UNRELEASED
+ */
+
+/**
+ * TP_BASE_CONNECTION_ERROR_IF_NOT_CONNECTED:
+ * @conn: A TpBaseConnection
+ * @context: A DBusGMethodInvocation
+ *
+ * If @conn is not in state #TP_CONNECTION_STATUS_CONNECTED, complete the
+ * D-Bus method invocation @context by raising the Telepathy error
+ * #TP_ERROR_DISCONNECTED, and return from the current function (which
+ * must be void). For use in D-Bus method implementations.
+ */
+
+
#include <telepathy-glib/base-connection.h>
#include <string.h>
diff --git a/telepathy-glib/base-connection.h b/telepathy-glib/base-connection.h
index bd69248..2aa9cf2 100644
--- a/telepathy-glib/base-connection.h
+++ b/telepathy-glib/base-connection.h
@@ -37,151 +37,24 @@ typedef struct _TpBaseConnection TpBaseConnection;
typedef struct _TpBaseConnectionClass TpBaseConnectionClass;
typedef struct _TpBaseConnectionPrivate TpBaseConnectionPrivate;
-/**
- * TpBaseConnectionProc:
- * @self: The connection object
- *
- * Signature of a virtual method on #TpBaseConnection that takes no
- * additional parameters and returns nothing.
- */
typedef void (*TpBaseConnectionProc) (TpBaseConnection *self);
-/**
- * TpBaseConnectionStartConnectingImpl:
- * @self: The connection object
- * @error: Set to the error if %FALSE is returned
- *
- * Signature of an implementation of the start_connecting method
- * of #TpBaseConnection.
- *
- * On entry, the implementation may assume that it is in state NEW.
- *
- * If %TRUE is returned, the Connect D-Bus method succeeds; the
- * implementation must either have already set the status to CONNECTED by
- * calling tp_base_connection_change_status(), or have arranged for a
- * status change to either state DISCONNECTED or CONNECTED to be signalled by
- * calling tp_base_connection_change_status() at some later time.
- * If the status is still NEW after returning %TRUE, #TpBaseConnection will
- * automatically change it to CONNECTING for reason REQUESTED.
- *
- * If %FALSE is returned, the error will be raised from Connect as an
- * exception. If the status is not DISCONNECTED after %FALSE is returned,
- * #TpBaseConnection will automatically change it to DISCONNECTED
- * with a reason appropriate to the error; NetworkError results in
- * NETWORK_ERROR, PermissionDenied results in AUTHENTICATION_FAILED, and all
- * other errors currently result in NONE_SPECIFIED.
- *
- * All except the simplest connection managers are expected to implement this
- * asynchronously, returning %TRUE in most cases and changing the status
- * to CONNECTED or DISCONNECTED later.
- *
- * Returns: %FALSE if failure has already occurred, else %TRUE.
- */
typedef gboolean (*TpBaseConnectionStartConnectingImpl) (
TpBaseConnection *self, GError **error);
-/**
- * TpBaseConnectionCreateHandleReposImpl:
- * @self: The connection object
- * @repos: An array of pointers to be filled in; the implementation
- * may assume all are initially NULL.
- *
- * Signature of an implementation of the create_handle_repos method
- * of #TpBaseConnection.
- */
typedef void (*TpBaseConnectionCreateHandleReposImpl) (TpBaseConnection *self,
TpHandleRepoIface *repos[NUM_TP_HANDLE_TYPES]);
-/**
- * TpBaseConnectionCreateChannelFactoriesImpl:
- * @self: The implementation, a subclass of TpBaseConnection
- *
- * Signature of an implementation of the create_channel_factories method
- * of #TpBaseConnection.
- *
- * Returns: a GPtrArray of objects implementing #TpChannelFactoryIface
- * which, between them, implement all channel types this Connection
- * supports.
- */
+
typedef GPtrArray *(*TpBaseConnectionCreateChannelFactoriesImpl) (
TpBaseConnection *self);
-/**
- * TpBaseConnectionCreateChannelManagersImpl:
- * @self: The implementation, a subclass of TpBaseConnection
- *
- * Signature of an implementation of the create_channel_managers method
- * of #TpBaseConnection.
- *
- * Returns: a GPtrArray of objects implementing #TpChannelManager
- * which, between them, implement all channel types this Connection
- * supports.
- */
typedef GPtrArray *(*TpBaseConnectionCreateChannelManagersImpl) (
TpBaseConnection *self);
-/**
- * TpBaseConnectionGetUniqueConnectionNameImpl:
- * @self: The implementation, a subclass of TpBaseConnection
- *
- * Signature of the @get_unique_connection_name virtual method
- * on #TpBaseConnection.
- *
- * Returns: a name for this connection which will be unique within this
- * connection manager process, as a string which the caller must free
- * with #g_free.
- */
typedef gchar *(*TpBaseConnectionGetUniqueConnectionNameImpl) (
TpBaseConnection *self);
-/**
- * TpBaseConnectionClass:
- * @parent_class: The superclass' structure
- * @create_handle_repos: Fill in suitable handle repositories in the
- * given array for all those handle types this Connection supports.
- * Must be set by subclasses to a non-%NULL value; the function must create
- * at least a CONTACT handle repository (failing to do so will cause a crash).
- * @create_channel_factories: Create an array of channel factories for this
- * Connection. At least one of this or @create_channel_managers must be set by
- * subclasses to a non-%NULL value; in new code, setting this to %NULL and
- * using channel managers exclusively is recommended.
- * @get_unique_connection_name: Construct a unique name for this connection
- * (for example using the protocol's format for usernames). If %NULL (the
- * default), a unique name will be generated. Subclasses should usually
- * override this to get more obvious names, to aid debugging and prevent
- * multiple connections to the same account.
- * @connecting: If set by subclasses, will be called just after the state
- * changes to CONNECTING. May be %NULL if nothing special needs to happen.
- * @connected: If set by subclasses, will be called just after the state
- * changes to CONNECTED. May be %NULL if nothing special needs to happen.
- * @disconnected: If set by subclasses, will be called just after the state
- * changes to DISCONNECTED. May be %NULL if nothing special needs to happen.
- * @shut_down: Called after disconnected() is called, to clean up the
- * connection. Must start the shutdown process for the underlying
- * network connection, and arrange for tp_base_connection_finish_shutdown()
- * to be called after the underlying connection has been closed. May not
- * be left as %NULL.
- * @start_connecting: Asynchronously start connecting - called to implement
- * the Connect D-Bus method. See #TpBaseConnectionStartConnectingImpl for
- * details. May not be left as %NULL.
- * @interfaces_always_present: A strv of extra D-Bus interfaces which are
- * always implemented by instances of this class, which may be filled in
- * by subclasses. The default is to list no additional interfaces.
- * Individual instances may detect which additional interfaces they support
- * and signal them before going to state CONNECTED by calling
- * tp_base_connection_add_interfaces().
- * @create_channel_managers: Create an array of channel managers for this
- * Connection. At least one of this or @create_channel_factories must be set
- * by subclasses to a non-%NULL value.
- * Since: 0.7.UNRELEASED
- *
- * The class of a #TpBaseConnection. Many members are virtual methods etc.
- * to be filled in in the subclass' class_init function.
- *
- * In addition to the fields documented here, there are three gpointer fields
- * which must currently be %NULL (a meaning may be defined for these in a
- * future version of telepathy-glib), and a pointer to opaque private data.
- */
struct _TpBaseConnectionClass {
GObjectClass parent_class;
@@ -211,45 +84,8 @@ struct _TpBaseConnectionClass {
gpointer priv;
};
-/**
- * TP_INTERNAL_CONNECTION_STATUS_NEW:
- *
- * A special value for #TpConnectionStatus, used within GLib connection
- * managers to indicate that the connection is disconnected because
- * connection has never been attempted (as distinct from disconnected
- * after connection has started, either by user request or an error).
- *
- * Must never be visible on the D-Bus - %TP_CONNECTION_STATUS_DISCONNECTED
- * is sent instead.
- */
# define TP_INTERNAL_CONNECTION_STATUS_NEW ((TpConnectionStatus)(-1))
-/**
- * TpBaseConnection:
- * @parent: Fields shared by the superclass.
- * @bus_name: A D-Bus well-known bus name, owned by the connection manager
- * process and associated with this connection. Set by
- * tp_base_connection_register; should be considered read-only by subclasses.
- * @object_path: The object-path of this connection. Set by
- * tp_base_connection_register; should be considered read-only by subclasses.
- * @status: Connection status - may either be a valid TpConnectionStatus or
- * TP_INTERNAL_CONNECTION_STATUS_NEW. Should be considered read-only by
- * subclasses: use tp_base_connection_change_status() to set it.
- * @self_handle: The handle of type %TP_HANDLE_TYPE_CONTACT representing the
- * local user. Must be set nonzero by the subclass before moving to state
- * CONNECTED. Since 0.7.UNRELEASED, setting this property directly is
- * deprecated, in favour of tp_base_connection_set_self_handle(); if this
- * property is set directly, the connection must ensure it holds a reference
- * to the handle. Changing this property directly having moved to state
- * CONNECTED is very strongly discouraged, as this will prevent the
- * SelfHandleChanged signal being emitted.
- *
- * Data structure representing a generic #TpSvcConnection implementation.
- *
- * In addition to the fields documented here, there are four gpointer fields
- * which must currently be %NULL (a meaning may be defined for these in a
- * future version of telepathy-glib), and a pointer to opaque private data.
- */
struct _TpBaseConnection {
/*<public>*/
GObject parent;
@@ -300,16 +136,6 @@ void tp_base_connection_register_with_contacts_mixin (TpBaseConnection *self);
typedef struct _TpChannelManagerIter TpChannelManagerIter;
-/**
- * TpChannelManagerIter:
- * @see_also: tp_base_connection_channel_manager_iter_init(),
- * tp_base_connection_channel_manager_iter_next()
- *
- * An iterator over the #TpChannelManager objects known to a #TpBaseConnection.
- * It has no public fields.
- *
- * Since: 0.7.UNRELEASED
- */
struct _TpChannelManagerIter {
/*<private>*/
TpBaseConnection *self;
@@ -341,16 +167,6 @@ gboolean tp_base_connection_channel_manager_iter_next (
(G_TYPE_INSTANCE_GET_CLASS ((obj), TP_TYPE_BASE_CONNECTION, \
TpBaseConnectionClass))
-/**
- * TP_BASE_CONNECTION_ERROR_IF_NOT_CONNECTED:
- * @conn: A TpBaseConnection
- * @context: A DBusGMethodInvocation
- *
- * If @conn is not in state #TP_CONNECTION_STATUS_CONNECTED, complete the
- * D-Bus method invocation @context by raising the Telepathy error
- * #TP_ERROR_DISCONNECTED, and return from the current function (which
- * must be void). For use in D-Bus method implementations.
- */
/* The cast of a string literal to (gchar *) is to keep C++ compilers happy */
#define TP_BASE_CONNECTION_ERROR_IF_NOT_CONNECTED(conn, context) \
G_STMT_START { \
--
1.5.6.5
More information about the Telepathy-commits
mailing list