diff src/dbus-server.h @ 11067:2eca9ed49469

[gaim-migrate @ 13048] Modified configure.ac so that it rejects dbus builds with the dbus library older than 0.34 Added a simple object registration system to the dbus implementation so that it is possible to query object properties remotely (eg. give me property "name" of buddy with id = 5). committer: Tailor Script <[e-mail]>

--- a/src/dbus-server.h	Thu Jul 07 15:43:05 2005 +0000
+++ b/src/dbus-server.h	Thu Jul 07 15:43:48 2005 +0000
@@ -27,8 +27,28 @@
 #ifndef _GAIM_DBUS_SERVER_H_
 #define _GAIM_DBUS_SERVER_H_
 
+
 G_BEGIN_DECLS
 
+/* These are the categories of codes used by gaim dbus implementation
+   for remote calls.  In practice, they don't matter
+ */
+typedef enum {
+  DBUS_ERROR_NONE = 0,
+  DBUS_ERROR_NOT_FOUND = 1
+} DbusErrorCodes;
+
+/* Types of pointers that can be registered with the gaim dbus pointer
+   registration engine.  See below */
+typedef enum {
+  DBUS_POINTER_GROUP,
+  DBUS_POINTER_CONTACT,
+  DBUS_POINTER_BUDDY,
+  DBUS_POINTER_CHAT,
+  DBUS_POINTER_ACCOUNT
+} GaimDBusPointerType;
+
+
 /**
  * Starts the gaim DBUS server.  It is responsible for handling DBUS
  * requests from other applications.
@@ -37,6 +57,52 @@
  */
 gboolean dbus_server_init(void);
 
+/**
+   Initializes gaim dbus pointer registration engine.
+
+   Remote dbus applications need a way of addressing objects exposed
+   by gaim to the outside world.  In gaim itself, these objects (such
+   as GaimBuddy and company) are identified by pointers.  The gaim
+   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 gaim is
+   started.  This is not good; external applications that use gaim
+   should work even whether gaim was restarted in the middle of the
+   interaction.
+
+   Pointer registration is only a temporary solution.  When GaimBuddy
+   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 gaim_dbus_init_ids(void);
+
+/** 
+    Registers a typed pointer.
+
+    @node   The pointer to register.
+    @type   Type of that pointer.
+ */
+void gaim_dbus_register_pointer(gpointer node, GaimDBusPointerType type);
+
+/** 
+    Unregisters a pointer previously registered with
+    gaim_dbus_register_pointer.
+
+    @node   The pointer to register.
+ */
+void gaim_dbus_unregister_pointer(gpointer node);
+
+
 G_END_DECLS
 
 #endif	/* _GAIM_DBUS_SERVER_H_ */