libpurple/dbus-server.h

   1 /**
   2  * @file dbus-server.h Purple DBUS Server
   3  * @ingroup core
   4  * @see @ref dbus-server-signals
   5  */
   6
   7 /* purple
   8  *
   9  * Purple is the legal property of its developers, whose names are too numerous
  10  * to list here.  Please refer to the COPYRIGHT file distributed with this
  11  * source distribution.
  12  *
  13  * This program is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2 of the License, or
  16  * (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, write to the Free Software
  25  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  26  */
  27
  28 #ifndef _PURPLE_DBUS_SERVER_H_
  29 #define _PURPLE_DBUS_SERVER_H_
  30
  31 #include "dbus-purple.h"
  32 #include "value.h"
  33
  34 G_BEGIN_DECLS
  35
  36 /**
  37    Types of pointers are identified by the ADDRESS of a PurpleDbusType
  38    object.  This way, plugins can easily access types defined in purple
  39    proper as well as introduce their own types that will not conflict
  40    with those introduced by other plugins.
  41
  42    The structure PurpleDbusType has only one element (PurpleDBusType::parent), a
  43    contains a pointer to the parent type, or @c NULL if the type has no
  44    parent.  Parent means the same as the base class in object oriented
  45    programming.
  46 */
  47
  48 typedef struct _PurpleDBusType PurpleDBusType;
  49
  50 struct _PurpleDBusType {
  51     PurpleDBusType *parent;
  52 };
  53
  54 #include "dbus-bindings.h"
  55
  56 /* By convention, the PurpleDBusType variable representing each structure
  57    PurpleSomeStructure has the name PURPLE_DBUS_TYPE_PurpleSomeStructure.
  58    The following macros facilitate defining such variables
  59
  60    #PURPLE_DBUS_DECLARE_TYPE declares an extern variable representing a
  61    given type, for use in header files.
  62
  63    #PURPLE_DBUS_DEFINE_TYPE defines a variable representing a given
  64    type, use in .c files.  It defines a new type without a parent; for
  65    types with a parent use #PURPLE_DBUS_DEFINE_INHERITING_TYPE.
  66   */
  67
  68 #define PURPLE_DBUS_TYPE(type) (&PURPLE_DBUS_TYPE_##type)
  69
  70
  71 #define PURPLE_DBUS_DECLARE_TYPE(type) \
  72     extern PurpleDBusType PURPLE_DBUS_TYPE_##type;
  73
  74 #define PURPLE_DBUS_DEFINE_TYPE(type) \
  75     PurpleDBusType PURPLE_DBUS_TYPE_##type = { NULL };
  76
  77 #define PURPLE_DBUS_DEFINE_INHERITING_TYPE(type, parent) \
  78     PurpleDBusType PURPLE_DBUS_TYPE_##type = { PURPLE_DBUS_TYPE(parent) };
  79
  80 #define PURPLE_DBUS_RETURN_FALSE_IF_DISABLED(plugin) \
  81         if (purple_dbus_get_init_error() != NULL) \
  82         { \
  83                 gchar *title; \
  84                 title = g_strdup_printf("Unable to Load %s Plugin", plugin->info->name); \
  85                 purple_notify_error(NULL, title, \
  86                                 _("Purple's D-BUS server is not running for the reason listed below"), \
  87                                 _(purple_dbus_get_init_error())); \
  88                 g_free(title); \
  89                 return FALSE; \
  90         }
  91
  92 /**
  93    Initializes purple dbus pointer registration engine.
  94
  95    Remote dbus applications need a way of addressing objects exposed
  96    by purple to the outside world.  In purple itself, these objects (such
  97    as PurpleBuddy and company) are identified by pointers.  The purple
  98    dbus pointer registration engine converts pointers to handles and
  99    back.
 100
 101    In order for an object to participate in the scheme, it must
 102    register itself and its type with the engine.  This registration
 103    allocates an integer id which can be resolved to the pointer and
 104    back.
 105
 106    Handles are not persistent.  They are reissued every time purple is
 107    started.  This is not good; external applications that use purple
 108    should work even whether purple was restarted in the middle of the
 109    interaction.
 110
 111    Pointer registration is only a temporary solution.  When PurpleBuddy
 112    and similar structures have been converted into gobjects, this
 113    registration will be done automatically by objects themselves.
 114
 115    By the way, this kind of object-handle translation should be so
 116    common that there must be a library (maybe even glib) that
 117    implements it.  I feel a bit like reinventing the wheel here.
 118 */
 119 void purple_dbus_init_ids(void);
 120
 121 /**
 122     Registers a typed pointer.
 123
 124     @param node   The pointer to register.
 125     @param type   Type of that pointer.
 126  */
 127 void purple_dbus_register_pointer(gpointer node, PurpleDBusType *type);
 128
 129 /**
 130     Unregisters a pointer previously registered with
 131     purple_dbus_register_pointer.
 132
 133     @param node   The pointer to register.
 134  */
 135 void purple_dbus_unregister_pointer(gpointer node);
 136
 137
 138
 139 /**
 140     Emits a dbus signal.
 141
 142     @param name        The name of the signal ("bla-bla-blaa")
 143     @param num_values  The number of parameters.
 144     @param values      Array of pointers to #PurpleValue objects representing
 145                        the types of the parameters.
 146     @param vargs       A va_list containing the actual parameters.
 147   */
 148 void purple_dbus_signal_emit_purple(const char *name, int num_values,
 149                                 PurpleValue **values, va_list vargs);
 150
 151 /**
 152  * Returns whether Purple's D-BUS subsystem is up and running.  If it's
 153  * NOT running then purple_dbus_dispatch_init() failed for some reason,
 154  * and a message should have been purple_debug_error()'ed.
 155  *
 156  * Purple plugins that use D-BUS should use the
 157  * PURPLE_DBUS_RETURN_FALSE_IF_DISABLED macro to short-circuit
 158  * initialization if Purple's D-BUS subsystem is not running.
 159  *
 160  * @return If the D-BUS subsystem started with no problems then this
 161  *         will return NULL and everything will be hunky dory.  If
 162  *         there was an error initializing the D-BUS subsystem then
 163  *         this will return an error message explaining why.
 164  */
 165 const char *purple_dbus_get_init_error(void);
 166
 167 /**
 168  * Returns the dbus subsystem handle.
 169  *
 170  * @return The dbus subsystem handle.
 171  */
 172 void *purple_dbus_get_handle(void);
 173
 174 /**
 175  * Determines whether this instance owns the DBus service name
 176  *
 177  * @since 2.1.0
 178  */
 179 gboolean purple_dbus_is_owner(void);
 180
 181 /**
 182  * Starts Purple's D-BUS server.  It is responsible for handling DBUS
 183  * requests from other applications.
 184  */
 185 void purple_dbus_init(void);
 186
 187 /**
 188  * Uninitializes Purple's D-BUS server.
 189  */
 190 void purple_dbus_uninit(void);
 191
 192 /**
 193
 194  Macro #DBUS_EXPORT expands to nothing.  It is used to indicate to the
 195  dbus-analyze-functions.py script that the given function should be
 196  available to other applications through DBUS.  If
 197  dbus-analyze-functions.py is run without the "--export-only" option,
 198  this prefix is ignored.
 199
 200  */
 201
 202 #define DBUS_EXPORT
 203
 204 /*
 205    Here we include the list of #PURPLE_DBUS_DECLARE_TYPE statements for
 206    all structs defined in purple.  This file has been generated by the
 207    #dbus-analyze-types.py script.
 208 */
 209
 210 #include "dbus-types.h"
 211
 212 G_END_DECLS
 213
 214 #endif  /* _PURPLE_DBUS_SERVER_H_ */