--- a/libpurple/dbus-server.h Fri Jan 31 19:42:12 2014 +0530
+++ b/libpurple/dbus-server.h Fri Jan 31 20:07:33 2014 +0530
@@ -33,16 +33,18 @@
G_BEGIN_DECLS
/**
- Types of pointers are identified by the ADDRESS of a PurpleDbusType
- object. This way, plugins can easily access types defined in purple
- proper as well as introduce their own types that will not conflict
- with those introduced by other plugins.
-
- The structure PurpleDbusType has only one element (PurpleDBusType::parent), a
- contains a pointer to the parent type, or %NULL if the type has no
- parent. Parent means the same as the base class in object oriented
- programming.
-*/
+ * PurpleDBusType:
+ *
+ * Types of pointers are identified by the ADDRESS of a PurpleDbusType
+ * object. This way, plugins can easily access types defined in purple
+ * proper as well as introduce their own types that will not conflict
+ * with those introduced by other plugins.
+ *
+ * The structure PurpleDbusType has only one element (PurpleDBusType::parent), a
+ * contains a pointer to the parent type, or %NULL if the type has no
+ * parent. Parent means the same as the base class in object oriented
+ * programming.
+ */
typedef struct _PurpleDBusType PurpleDBusType;
@@ -90,64 +92,69 @@
}
/**
- Initializes purple dbus pointer registration engine.
-
- Remote dbus applications need a way of addressing objects exposed
- by purple to the outside world. In purple itself, these objects (such
- as PurpleBuddy and company) are identified by pointers. The purple
- dbus pointer registration engine converts pointers to handles and
- back.
-
- In order for an object to participate in the scheme, it must
- register itself and its type with the engine. This registration
- allocates an integer id which can be resolved to the pointer and
- back.
-
- Handles are not persistent. They are reissued every time purple is
- started. This is not good; external applications that use purple
- should work even whether purple was restarted in the middle of the
- interaction.
-
- Pointer registration is only a temporary solution. When PurpleBuddy
- and similar structures have been converted into gobjects, this
- registration will be done automatically by objects themselves.
-
- By the way, this kind of object-handle translation should be so
- common that there must be a library (maybe even glib) that
- implements it. I feel a bit like reinventing the wheel here.
-*/
+ * purple_dbus_init_ids:
+ *
+ * Initializes purple dbus pointer registration engine.
+ *
+ * Remote dbus applications need a way of addressing objects exposed
+ * by purple to the outside world. In purple itself, these objects (such
+ * as PurpleBuddy and company) are identified by pointers. The purple
+ * dbus pointer registration engine converts pointers to handles and
+ * back.
+ *
+ * In order for an object to participate in the scheme, it must
+ * register itself and its type with the engine. This registration
+ * allocates an integer id which can be resolved to the pointer and
+ * back.
+ *
+ * Handles are not persistent. They are reissued every time purple is
+ * started. This is not good; external applications that use purple
+ * should work even whether purple was restarted in the middle of the
+ * interaction.
+ *
+ * Pointer registration is only a temporary solution. When PurpleBuddy
+ * and similar structures have been converted into gobjects, this
+ * registration will be done automatically by objects themselves.
+ *
+ * By the way, this kind of object-handle translation should be so
+ * common that there must be a library (maybe even glib) that
+ * implements it. I feel a bit like reinventing the wheel here.
+ */
void purple_dbus_init_ids(void);
/**
- Registers a typed pointer.
-
- @node: The pointer to register.
- @type: Type of that pointer.
+ * purple_dbus_register_pointer:
+ * @node: The pointer to register.
+ * @type: Type of that pointer.
+ *
+ * Registers a typed pointer.
*/
void purple_dbus_register_pointer(gpointer node, PurpleDBusType *type);
/**
- Unregisters a pointer previously registered with
- purple_dbus_register_pointer.
-
- @node: The pointer to register.
+ * purple_dbus_unregister_pointer:
+ * @node: The pointer to register.
+ *
+ * Unregisters a pointer previously registered with
+ * purple_dbus_register_pointer.
*/
void purple_dbus_unregister_pointer(gpointer node);
-
-
/**
- Emits a dbus signal.
-
- @name: The name of the signal ("bla-bla-blaa")
- @num_values: The number of parameters.
- @types: Array of GTypes representing the types of the parameters.
- @vargs: A va_list containing the actual parameters.
- */
+ * purple_dbus_signal_emit_purple:
+ * @name: The name of the signal ("bla-bla-blaa")
+ * @num_values: The number of parameters.
+ * @types: Array of GTypes representing the types of the parameters.
+ * @vargs: A va_list containing the actual parameters.
+ *
+ * Emits a dbus signal.
+ */
void purple_dbus_signal_emit_purple(const char *name, int num_values,
GType *types, va_list vargs);
/**
+ * purple_dbus_get_init_error:
+ *
* Returns whether Purple's D-BUS subsystem is up and running. If it's
* NOT running then purple_dbus_dispatch_init() failed for some reason,
* and a message should have been purple_debug_error()'ed.
@@ -164,6 +171,8 @@
const char *purple_dbus_get_init_error(void);
/**
+ * purple_dbus_get_handle:
+ *
* Returns the dbus subsystem handle.
*
* Returns: The dbus subsystem handle.
@@ -171,31 +180,36 @@
void *purple_dbus_get_handle(void);
/**
+ * purple_dbus_is_owner:
+ *
* Determines whether this instance owns the DBus service name
*/
gboolean purple_dbus_is_owner(void);
/**
+ * purple_dbus_init:
+ *
* Starts Purple's D-BUS server. It is responsible for handling DBUS
* requests from other applications.
*/
void purple_dbus_init(void);
/**
+ * purple_dbus_uninit:
+ *
* Uninitializes Purple's D-BUS server.
*/
void purple_dbus_uninit(void);
/**
-
- Macro #DBUS_EXPORT expands to nothing. It is used to indicate to the
- dbus-analyze-functions.py script that the given function should be
- available to other applications through DBUS. If
- dbus-analyze-functions.py is run without the "--export-only" option,
- this prefix is ignored.
-
+ * DBUS_EXPORT:
+ *
+ * Macro #DBUS_EXPORT expands to nothing. It is used to indicate to the
+ * dbus-analyze-functions.py script that the given function should be
+ * available to other applications through DBUS. If
+ * dbus-analyze-functions.py is run without the "--export-only" option,
+ * this prefix is ignored.
*/
-
#define DBUS_EXPORT
/*