libpurple/plugins.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef _PURPLE_PLUGINS_H_
  23 #define _PURPLE_PLUGINS_H_
  24 /**
  25  * SECTION:plugins
  26  * @section_id: libpurple-plugins
  27  * @short_description: <filename>plugins.h</filename>
  28  * @title: Plugin API
  29  * @see_also: <link linkend="chapter-signals-plugin">Plugin signals</link>,
  30  *     <link linkend="chapter-plugin-ids">Plugin IDs</link>,
  31  *     <link linkend="chapter-plugin-i18n">Third Party Plugin Translation</link>
  32  */
  33
  34 #ifdef PURPLE_PLUGINS
  35 #include <gplugin.h>
  36 #include <gplugin-native.h>
  37 #else
  38 #include <glib.h>
  39 #include <glib-object.h>
  40 #endif
  41
  42 #include "version.h"
  43
  44 #define PURPLE_PLUGINS_DOMAIN          (g_quark_from_static_string("plugins"))
  45
  46 #ifdef PURPLE_PLUGINS
  47
  48 #define PURPLE_TYPE_PLUGIN             GPLUGIN_TYPE_PLUGIN
  49 #define PURPLE_PLUGIN(obj)             GPLUGIN_PLUGIN(obj)
  50 #define PURPLE_PLUGIN_CLASS(klass)     GPLUGIN_PLUGIN_CLASS(klass)
  51 #define PURPLE_IS_PLUGIN(obj)          GPLUGIN_IS_PLUGIN(obj)
  52 #define PURPLE_IS_PLUGIN_CLASS(klass)  GPLUGIN_IS_PLUGIN_CLASS(klass)
  53 #define PURPLE_PLUGIN_GET_CLASS(obj)   GPLUGIN_PLUGIN_GET_CLASS(obj)
  54
  55 /**
  56  * PurplePlugin:
  57  *
  58  * Represents a plugin handle.
  59  * This type is an alias for GPluginPlugin.
  60  */
  61 typedef GPluginPlugin PurplePlugin;
  62
  63 typedef GPluginPluginClass PurplePluginClass;
  64
  65 #else /* !defined(PURPLE_PLUGINS) */
  66
  67 #define PURPLE_TYPE_PLUGIN             G_TYPE_OBJECT
  68 #define PURPLE_PLUGIN(obj)             G_OBJECT(obj)
  69 #define PURPLE_PLUGIN_CLASS(klass)     G_OBJECT_CLASS(klass)
  70 #define PURPLE_IS_PLUGIN(obj)          G_IS_OBJECT(obj)
  71 #define PURPLE_IS_PLUGIN_CLASS(klass)  G_IS_OBJECT_CLASS(klass)
  72 #define PURPLE_PLUGIN_GET_CLASS(obj)   G_OBJECT_GET_CLASS(obj)
  73
  74 typedef GObject PurplePlugin;
  75 typedef GObjectClass PurplePluginClass;
  76
  77 #endif /* PURPLE_PLUGINS */
  78
  79 #define PURPLE_TYPE_PLUGIN_INFO             (purple_plugin_info_get_type())
  80 #define PURPLE_PLUGIN_INFO(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_PLUGIN_INFO, PurplePluginInfo))
  81 #define PURPLE_PLUGIN_INFO_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass), PURPLE_TYPE_PLUGIN_INFO, PurplePluginInfoClass))
  82 #define PURPLE_IS_PLUGIN_INFO(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PLUGIN_INFO))
  83 #define PURPLE_IS_PLUGIN_INFO_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_PLUGIN_INFO))
  84 #define PURPLE_PLUGIN_INFO_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_PLUGIN_INFO, PurplePluginInfoClass))
  85
  86 typedef struct _PurplePluginInfo PurplePluginInfo;
  87 typedef struct _PurplePluginInfoClass PurplePluginInfoClass;
  88
  89 #define PURPLE_TYPE_PLUGIN_ACTION  (purple_plugin_action_get_type())
  90
  91 typedef struct _PurplePluginAction PurplePluginAction;
  92
  93 #include "pluginpref.h"
  94
  95 /**
  96  * PurplePluginActionCb:
  97  * @action: the action information.
  98  *
  99  * A function called when the related Action Menu is activated.
 100  */
 101 typedef void (*PurplePluginActionCb)(PurplePluginAction *action);
 102
 103 /**
 104  * PurplePluginActionsCb:
 105  * @plugin: the plugin associated with this callback.
 106  *
 107  * Returns a list of actions the plugin can perform.
 108  *
 109  * Returns: (transfer none): A list of actions the plugin can perform.
 110  */
 111 typedef GList *(*PurplePluginActionsCb)(PurplePlugin *plugin);
 112
 113 /**
 114  * PurplePluginExtraCb:
 115  * @plugin: the plugin associated with this callback.
 116  *
 117  * Gives extra information about the plguin.
 118  *
 119  * Returns: a newly allocated string denoting extra information
 120  * about a plugin.
 121  */
 122 typedef gchar *(*PurplePluginExtraCb)(PurplePlugin *plugin);
 123
 124 /**
 125  * PurplePluginPrefFrameCb:
 126  * @plugin: the plugin associated with this callback.
 127  *
 128  * Returns the preferences frame for the plugin.
 129  *
 130  * Returns: Preference frame.
 131  */
 132 typedef PurplePluginPrefFrame *(*PurplePluginPrefFrameCb)(PurplePlugin *plugin);
 133
 134 /**
 135  * PurplePrefRequestCb:
 136  *
 137  * Returns the preferences request handle for a plugin.
 138  *
 139  * Returns: Preferences request handle.
 140  */
 141 typedef gpointer (*PurplePluginPrefRequestCb)(PurplePlugin *plugin);
 142
 143 /**
 144  * PurplePluginInfoFlags:
 145  * @PURPLE_PLUGIN_INFO_FLAGS_INTERNAL:  Plugin is not shown in UI lists
 146  * @PURPLE_PLUGIN_INFO_FLAGS_AUTO_LOAD: Auto-load the plugin
 147  *
 148  * Flags that can be used to treat plugins differently.
 149  */
 150 typedef enum /*< flags >*/
 151 {
 152         PURPLE_PLUGIN_INFO_FLAGS_INTERNAL  = 1 << 1,
 153         PURPLE_PLUGIN_INFO_FLAGS_AUTO_LOAD = 1 << 2,
 154
 155 } PurplePluginInfoFlags;
 156
 157 /**
 158  * PurplePluginInfo:
 159  * @ui_data: The UI data associated with the plugin. This is a convenience
 160  *           field provided to the UIs -- it is not used by the libpurple core.
 161  *
 162  * Holds information about a plugin.
 163  */
 164 struct _PurplePluginInfo {
 165 #ifdef PURPLE_PLUGINS
 166         GPluginPluginInfo parent;
 167 #else
 168         GObject parent;
 169 #endif
 170
 171         /*< public >*/
 172         gpointer ui_data;
 173 };
 174
 175 struct _PurplePluginInfoClass {
 176 #ifdef PURPLE_PLUGINS
 177         GPluginPluginInfoClass parent_class;
 178 #else
 179         GObjectClass parent_class;
 180 #endif
 181
 182         /*< private >*/
 183         void (*_purple_reserved1)(void);
 184         void (*_purple_reserved2)(void);
 185         void (*_purple_reserved3)(void);
 186         void (*_purple_reserved4)(void);
 187 };
 188
 189 /**
 190  * PurplePluginAction:
 191  *
 192  * Represents an action that the plugin can perform. This shows up in the Tools
 193  * menu, under a submenu with the name of the plugin.
 194  */
 195 struct _PurplePluginAction {
 196         char *label;
 197         PurplePluginActionCb callback;
 198         PurplePlugin *plugin;
 199         gpointer user_data;
 200 };
 201
 202 /**
 203  * PURPLE_PLUGIN_ABI_VERSION:
 204  *
 205  * Note: The lower six nibbles represent the ABI version for libpurple, the
 206  *       rest are required by GPlugin.
 207  *
 208  * Returns: An ABI version to set in plugins using major and minor versions.
 209  */
 210 #define PURPLE_PLUGIN_ABI_VERSION(major,minor) \
 211         (0x01000000 | ((major) << 16) | (minor))
 212
 213 /**
 214  * PURPLE_PLUGIN_ABI_MAJOR_VERSION:
 215  *
 216  * Returns: The major version from an ABI version
 217  */
 218 #define PURPLE_PLUGIN_ABI_MAJOR_VERSION(abi) \
 219         ((abi >> 16) & 0xff)
 220
 221 /**
 222  * PURPLE_PLUGIN_ABI_MINOR_VERSION:
 223  *
 224  * Returns: The minor version from an ABI version
 225  */
 226 #define PURPLE_PLUGIN_ABI_MINOR_VERSION(abi) \
 227         (abi & 0xffff)
 228
 229 /**
 230  * PURPLE_ABI_VERSION:
 231  *
 232  * A convenience‎ macro that returns an ABI version using PURPLE_MAJOR_VERSION
 233  * and PURPLE_MINOR_VERSION
 234  */
 235 #define PURPLE_ABI_VERSION PURPLE_PLUGIN_ABI_VERSION(PURPLE_MAJOR_VERSION, PURPLE_MINOR_VERSION)
 236
 237 /**
 238  * PURPLE_PLUGIN_INIT:
 239  *
 240  * Defines the plugin's entry points.
 241  */
 242 #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL)
 243 #define PURPLE_PLUGIN_INIT(pluginname,pluginquery,pluginload,pluginunload) \
 244         PurplePluginInfo * pluginname##_plugin_query(void); \
 245         PurplePluginInfo * pluginname##_plugin_query(void) { \
 246                 return pluginquery(NULL); \
 247         } \
 248         gboolean pluginname##_plugin_load(void); \
 249         gboolean pluginname##_plugin_load(void) { \
 250                 GError *e = NULL; \
 251                 gboolean loaded = pluginload(NULL, &e); \
 252                 if (e) g_error_free(e); \
 253                 return loaded; \
 254         } \
 255         gboolean pluginname##_plugin_unload(void); \
 256         gboolean pluginname##_plugin_unload(void) { \
 257                 GError *e = NULL; \
 258                 gboolean unloaded = pluginunload(NULL, &e); \
 259                 if (e) g_error_free(e); \
 260                 return unloaded; \
 261         }
 262 #else /* PURPLE_PLUGINS && !PURPLE_STATIC_PRPL */
 263 #define PURPLE_PLUGIN_INIT(pluginname,pluginquery,pluginload,pluginunload) \
 264         G_MODULE_EXPORT GPluginPluginInfo *gplugin_query(GError **e); \
 265         G_MODULE_EXPORT GPluginPluginInfo *gplugin_query(GError **e) { \
 266                 return GPLUGIN_PLUGIN_INFO(pluginquery(e)); \
 267         } \
 268         G_MODULE_EXPORT gboolean gplugin_load(GPluginNativePlugin *p, GError **e); \
 269         G_MODULE_EXPORT gboolean gplugin_load(GPluginNativePlugin *p, GError **e) { \
 270                 return pluginload(PURPLE_PLUGIN(p), e); \
 271         } \
 272         G_MODULE_EXPORT gboolean gplugin_unload(GPluginNativePlugin *p, GError **e); \
 273         G_MODULE_EXPORT gboolean gplugin_unload(GPluginNativePlugin *p, GError **e) { \
 274                 return pluginunload(PURPLE_PLUGIN(p), e); \
 275         }
 276 #endif
 277
 278 /**
 279  * PURPLE_DEFINE_TYPE:
 280  * @TN:   The name of the new type, in Camel case.
 281  * @t_n:  The name of the new type, in lowercase, words separated by '_'.
 282  * @T_P:  The #GType of the parent type.
 283  *
 284  * A convenience macro for type implementations, which defines a *_get_type()
 285  * function; and a *_register_type() function for use in your plugin's load
 286  * function. You must define an instance initialization function *_init()
 287  * and a class initialization function *_class_init() for the type.
 288  *
 289  * The type will be registered statically if used in a static protocol or if
 290  * plugins support is disabled.
 291  */
 292 #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL)
 293 #define PURPLE_DEFINE_TYPE(TN, t_n, T_P) \
 294         PURPLE_DEFINE_STATIC_TYPE(TN, t_n, T_P)
 295 #else
 296 #define PURPLE_DEFINE_TYPE(TN, t_n, T_P) \
 297         PURPLE_DEFINE_DYNAMIC_TYPE(TN, t_n, T_P)
 298 #endif
 299
 300 /**
 301  * PURPLE_DEFINE_TYPE_EXTENDED:
 302  * @TN:     The name of the new type, in Camel case.
 303  * @t_n:    The name of the new type, in lowercase, words separated by '_'.
 304  * @T_P:    The #GType of the parent type.
 305  * @flags:  #GTypeFlags to register the type with.
 306  * @CODE:   Custom code that gets inserted in *_get_type().
 307  *
 308  * A more general version of PURPLE_DEFINE_TYPE() which allows you to
 309  * specify #GTypeFlags and custom code.
 310  */
 311 #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL)
 312 #define PURPLE_DEFINE_TYPE_EXTENDED \
 313         PURPLE_DEFINE_STATIC_TYPE_EXTENDED
 314 #else
 315 #define PURPLE_DEFINE_TYPE_EXTENDED \
 316         PURPLE_DEFINE_DYNAMIC_TYPE_EXTENDED
 317 #endif
 318
 319 /**
 320  * PURPLE_IMPLEMENT_INTERFACE_STATIC:
 321  * @TYPE_IFACE:  The #GType of the interface to add.
 322  * @iface_init:  The interface init function.
 323  *
 324  * A convenience macro to ease static interface addition in the CODE section
 325  * of PURPLE_DEFINE_TYPE_EXTENDED(). You should use this macro if the
 326  * interface is a part of the libpurple core.
 327  */
 328 #define PURPLE_IMPLEMENT_INTERFACE_STATIC(TYPE_IFACE, iface_init) { \
 329         const GInterfaceInfo interface_info = { \
 330                 (GInterfaceInitFunc) iface_init, NULL, NULL \
 331         }; \
 332         g_type_add_interface_static(type_id, TYPE_IFACE, &interface_info); \
 333 }
 334
 335 /**
 336  * PURPLE_IMPLEMENT_INTERFACE:
 337  * @TYPE_IFACE:  The #GType of the interface to add.
 338  * @iface_init:  The interface init function.
 339  *
 340  * A convenience macro to ease interface addition in the CODE section
 341  * of PURPLE_DEFINE_TYPE_EXTENDED(). You should use this macro if the
 342  * interface lives in the plugin.
 343  */
 344 #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL)
 345 #define PURPLE_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init) \
 346         PURPLE_IMPLEMENT_INTERFACE_STATIC(TYPE_IFACE, iface_init)
 347 #else
 348 #define PURPLE_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init) \
 349         PURPLE_IMPLEMENT_INTERFACE_DYNAMIC(TYPE_IFACE, iface_init)
 350 #endif
 351
 352 /**
 353  * PURPLE_DEFINE_DYNAMIC_TYPE:
 354  *
 355  * A convenience macro for dynamic type implementations.
 356  */
 357 #define PURPLE_DEFINE_DYNAMIC_TYPE(TN, t_n, T_P) \
 358         PURPLE_DEFINE_DYNAMIC_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
 359
 360 /**
 361  * PURPLE_DEFINE_DYNAMIC_TYPE_EXTENDED:
 362  *
 363  * A more general version of PURPLE_DEFINE_DYNAMIC_TYPE().
 364  */
 365 #define PURPLE_DEFINE_DYNAMIC_TYPE_EXTENDED(TypeName, type_name, TYPE_PARENT, flags, CODE) \
 366 static GType type_name##_type_id = 0; \
 367 G_MODULE_EXPORT GType type_name##_get_type(void) { \
 368         return type_name##_type_id; \
 369 } \
 370 void type_name##_register_type(PurplePlugin *); \
 371 void type_name##_register_type(PurplePlugin *plugin) { \
 372         GType type_id; \
 373         const GTypeInfo type_info = { \
 374                 sizeof (TypeName##Class), \
 375                 (GBaseInitFunc) NULL, \
 376                 (GBaseFinalizeFunc) NULL, \
 377                 (GClassInitFunc) type_name##_class_init, \
 378                 (GClassFinalizeFunc) NULL, \
 379                 NULL, \
 380                 sizeof (TypeName), \
 381                 0, \
 382                 (GInstanceInitFunc) type_name##_init, \
 383                 NULL \
 384         }; \
 385         type_id = purple_plugin_register_type(plugin, TYPE_PARENT, #TypeName, \
 386                                               &type_info, (GTypeFlags) flags); \
 387         type_name##_type_id = type_id; \
 388         { CODE ; } \
 389 }
 390
 391 /**
 392  * PURPLE_IMPLEMENT_INTERFACE_DYNAMIC:
 393  *
 394  * A convenience macro to ease dynamic interface addition.
 395  */
 396 #define PURPLE_IMPLEMENT_INTERFACE_DYNAMIC(TYPE_IFACE, iface_init) { \
 397         const GInterfaceInfo interface_info = { \
 398                 (GInterfaceInitFunc) iface_init, NULL, NULL \
 399         }; \
 400         purple_plugin_add_interface(plugin, type_id, TYPE_IFACE, &interface_info); \
 401 }
 402
 403 /**
 404  * PURPLE_DEFINE_STATIC_TYPE:
 405  *
 406  * A convenience macro for static type implementations.
 407  */
 408 #define PURPLE_DEFINE_STATIC_TYPE(TN, t_n, T_P) \
 409         PURPLE_DEFINE_STATIC_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
 410
 411 /**
 412  * PURPLE_DEFINE_STATIC_TYPE_EXTENDED:
 413  *
 414  * A more general version of PURPLE_DEFINE_STATIC_TYPE().
 415  */
 416 #define PURPLE_DEFINE_STATIC_TYPE_EXTENDED(TypeName, type_name, TYPE_PARENT, flags, CODE) \
 417 static GType type_name##_type_id = 0; \
 418 GType type_name##_get_type(void) { \
 419         if (G_UNLIKELY(type_name##_type_id == 0)) { \
 420                 GType type_id; \
 421                 const GTypeInfo type_info = { \
 422                         sizeof (TypeName##Class), \
 423                         (GBaseInitFunc) NULL, \
 424                         (GBaseFinalizeFunc) NULL, \
 425                         (GClassInitFunc) type_name##_class_init, \
 426                         (GClassFinalizeFunc) NULL, \
 427                         NULL, \
 428                         sizeof (TypeName), \
 429                         0, \
 430                         (GInstanceInitFunc) type_name##_init, \
 431                         NULL \
 432                 }; \
 433                 type_id = g_type_register_static(TYPE_PARENT, #TypeName, &type_info, \
 434                                                  (GTypeFlags) flags); \
 435                 type_name##_type_id = type_id; \
 436                 { CODE ; } \
 437         } \
 438         return type_name##_type_id; \
 439 } \
 440 void type_name##_register_type(PurplePlugin *); \
 441 void type_name##_register_type(PurplePlugin *plugin) { }
 442
 443 G_BEGIN_DECLS
 444
 445 /**************************************************************************/
 446 /* Plugin API                                                             */
 447 /**************************************************************************/
 448
 449 /**
 450  * purple_plugin_load:
 451  * @plugin: The plugin to load.
 452  * @error:  Return location for a #GError or %NULL. If provided, this
 453  *               will be set to the reason if the load fails.
 454  *
 455  * Attempts to load a plugin.
 456  *
 457  * Also see purple_plugin_unload().
 458  *
 459  * Returns: %TRUE if successful or already loaded, %FALSE otherwise.
 460  */
 461 gboolean purple_plugin_load(PurplePlugin *plugin, GError **error);
 462
 463 /**
 464  * purple_plugin_unload:
 465  * @plugin: The plugin handle.
 466  * @error:  Return location for a #GError or %NULL. If provided, this
 467  *               will be set to the reason if the unload fails.
 468  *
 469  * Unloads the specified plugin.
 470  *
 471  * Also see purple_plugin_load().
 472  *
 473  * Returns: %TRUE if successful or not loaded, %FALSE otherwise.
 474  */
 475 gboolean purple_plugin_unload(PurplePlugin *plugin, GError **error);
 476
 477 /**
 478  * purple_plugin_is_loaded:
 479  * @plugin: The plugin.
 480  *
 481  * Returns whether or not a plugin is currently loaded.
 482  *
 483  * Returns: %TRUE if loaded, or %FALSE otherwise.
 484  */
 485 gboolean purple_plugin_is_loaded(const PurplePlugin *plugin);
 486
 487 /**
 488  * purple_plugin_get_filename:
 489  * @plugin: The plugin.
 490  *
 491  * Returns a plugin's filename, along with the path.
 492  *
 493  * Returns: The plugin's filename.
 494  */
 495 const gchar *purple_plugin_get_filename(const PurplePlugin *plugin);
 496
 497 /**
 498  * purple_plugin_get_info:
 499  * @plugin: The plugin.
 500  *
 501  * Returns a plugin's #PurplePluginInfo instance.
 502  *
 503  * Returns: (transfer none) The plugin's #PurplePluginInfo instance.
 504  * GPlugin refs the plugin info object before returning it. This workaround
 505  * is to avoid managing the reference counts everywhere in our codebase
 506  * where we use the plugin info. The plugin info instance is guaranteed to
 507  * exist as long as the plugin exists.
 508  */
 509 PurplePluginInfo *purple_plugin_get_info(const PurplePlugin *plugin);
 510
 511 /**
 512  * purple_plugin_disable:
 513  *
 514  * Disable a plugin.
 515  *
 516  * This function adds the plugin to a list of plugins to "disable at the next
 517  * startup" by excluding said plugins from the list of plugins to save.  The
 518  * UI needs to call purple_plugins_save_loaded() after calling this for it
 519  * to have any effect.
 520  */
 521 void purple_plugin_disable(PurplePlugin *plugin);
 522
 523 /**
 524  * purple_plugin_register_type:
 525  * @plugin:  The plugin that is registering the type.
 526  * @parent:  Type from which this type will be derived.
 527  * @name:    Name of the new type.
 528  * @info:    Information to initialize and destroy a type's classes and
 529  *           instances.
 530  * @flags:   Bitwise combination of values that determines the nature
 531  *           (e.g. abstract or not) of the type.
 532  *
 533  * Registers a new dynamic type.
 534  *
 535  * Returns: The new GType, or %G_TYPE_INVALID if registration failed.
 536  */
 537 GType purple_plugin_register_type(PurplePlugin *plugin, GType parent,
 538                                   const gchar *name, const GTypeInfo *info,
 539                                   GTypeFlags flags);
 540
 541 /**
 542  * purple_plugin_add_interface:
 543  * @plugin:          The plugin that is adding the interface type.
 544  * @instance_type:   The GType of the instantiable type.
 545  * @interface_type:  The GType of the interface type.
 546  * @interface_info:  Information used to manage the interface type.
 547  *
 548  * Adds a dynamic interface type to an instantiable type.
 549  */
 550 void purple_plugin_add_interface(PurplePlugin *plugin, GType instance_type,
 551                                  GType interface_type,
 552                                  const GInterfaceInfo *interface_info);
 553
 554 /**
 555  * purple_plugin_is_internal:
 556  * @plugin: The plugin.
 557  *
 558  * Returns whether a plugin is an internal plugin. Internal plugins provide
 559  * required additional functionality to the libpurple core. These plugins must
 560  * not be shown in plugin lists. Examples of such plugins are in-tree protocol
 561  * plugins, loaders etc.
 562  *
 563  * Returns: %TRUE if the plugin is an internal plugin, %FALSE otherwise.
 564  */
 565 gboolean purple_plugin_is_internal(const PurplePlugin *plugin);
 566
 567 /**
 568  * purple_plugin_get_dependent_plugins:
 569  * @plugin: The plugin whose dependent plugins are returned.
 570  *
 571  * Returns a list of plugins that depend on a particular plugin.
 572  *
 573  * Returns: (element-type PurplePlugin) (transfer none): The list of a plugins that depend on the specified
 574  *                           plugin.
 575  */
 576 GSList *purple_plugin_get_dependent_plugins(const PurplePlugin *plugin);
 577
 578 /**************************************************************************/
 579 /* PluginInfo API                                                         */
 580 /**************************************************************************/
 581
 582 /**
 583  * purple_plugin_info_get_type:
 584  *
 585  * Returns: The #GType for the #PurplePluginInfo object.
 586  */
 587 GType purple_plugin_info_get_type(void);
 588
 589 /**
 590  * purple_plugin_info_new:
 591  * @first_property:  The first property name
 592  * @...:  The value of the first property, followed optionally by more
 593  *             name/value pairs, followed by %NULL
 594  *
 595  * Creates a new #PurplePluginInfo instance to be returned from
 596  * #plugin_query of a plugin, using the provided name/value pairs.
 597  *
 598  * All properties except <literal>"id"</literal> and
 599  * <literal>"purple-abi"</literal> are optional.
 600  *
 601  * Valid property names are:
 602  * <informaltable frame='none'>
 603  *   <tgroup cols='2'><tbody>
 604  *   <row><entry><literal>"id"</literal></entry>
 605  *     <entry>(string) The ID of the plugin.</entry>
 606  *   </row>
 607  *   <row><entry><literal>"abi-version"</literal></entry>
 608  *     <entry>(<type>guint32</type>) The ABI version required by the
 609  *       plugin.</entry>
 610  *   </row>
 611  *   <row><entry><literal>"name"</literal></entry>
 612  *     <entry>(string) The translated name of the plugin.</entry>
 613  *   </row>
 614  *   <row><entry><literal>"version"</literal></entry>
 615  *     <entry>(string) Version of the plugin.</entry>
 616  *   </row>
 617  *   <row><entry><literal>"category"</literal></entry>
 618  *     <entry>(string) Primary category of the plugin.</entry>
 619  *   </row>
 620  *   <row><entry><literal>"summary"</literal></entry>
 621  *     <entry>(string) Brief summary of the plugin.</entry>
 622  *   </row>
 623  *   <row><entry><literal>"description"</literal></entry>
 624  *     <entry>(string) Full description of the plugin.</entry>
 625  *   </row>
 626  *   <row><entry><literal>"authors"</literal></entry>
 627  *     <entry>(<type>const gchar * const *</type>) A %NULL-terminated list of
 628  *       plugin authors. format: First Last &lt;user\@domain.com&gt;</entry>
 629  *   </row>
 630  *   <row><entry><literal>"website"</literal></entry>
 631  *     <entry>(string) Website of the plugin.</entry>
 632  *   </row>
 633  *   <row><entry><literal>"icon"</literal></entry>
 634  *     <entry>(string) Path to a plugin's icon.</entry>
 635  *   </row>
 636  *   <row><entry><literal>"license-id"</literal></entry>
 637  *     <entry>(string) Short name of the plugin's license. This should
 638  *       either be an identifier of the license from
 639  *       <ulink url="http://dep.debian.net/deps/dep5/#license-specification">
 640  *       DEP5</ulink> or "Other" for custom licenses.</entry>
 641  *   </row>
 642  *   <row><entry><literal>"license-text"</literal></entry>
 643  *     <entry>(string) The text of the plugin's license, if unlisted on
 644  *       DEP5.</entry>
 645  *   </row>
 646  *   <row><entry><literal>"license-url"</literal></entry>
 647  *     <entry>(string) The plugin's license URL, if unlisted on DEP5.</entry>
 648  *   </row>
 649  *   <row><entry><literal>"dependencies"</literal></entry>
 650  *     <entry>(<type>const gchar * const *</type>) A %NULL-terminated list of
 651  *       plugin IDs required by the plugin.</entry>
 652  *   </row>
 653  *   <row><entry><literal>"actions-cb"</literal></entry>
 654  *     <entry>(#PurplePluginActionsCb) Callback that returns a list of
 655  *       actions the plugin can perform.</entry>
 656  *   </row>
 657  *   <row><entry><literal>"extra-cb"</literal></entry>
 658  *     <entry>(#PurplePluginExtraCb) Callback that returns a newly
 659  *       allocated string denoting extra information about a plugin.</entry>
 660  *   </row>
 661  *   <row><entry><literal>"pref-frame-cb"</literal></entry>
 662  *     <entry>(#PurplePluginPrefFrameCb) Callback that returns a
 663  *       preferences frame for the plugin.</entry>
 664  *   </row>
 665  *   <row><entry><literal>"pref-request-cb"</literal></entry>
 666  *     <entry>(#PurplePluginPrefRequestCb) Callback that returns a
 667  *       preferences request handle for the plugin.</entry>
 668  *   </row>
 669  *   <row><entry><literal>"flags"</literal></entry>
 670  *     <entry>(#PurplePluginInfoFlags) The flags for a plugin.</entry>
 671  *   </row>
 672  *   </tbody></tgroup>
 673  * </informaltable>
 674  *
 675  * See #PURPLE_PLUGIN_ABI_VERSION,
 676  *     <link linkend="chapter-plugin-ids">Plugin IDs</link>.
 677  *
 678  * Returns: A new #PurplePluginInfo instance.
 679  */
 680 PurplePluginInfo *purple_plugin_info_new(const char *first_property, ...)
 681                   G_GNUC_NULL_TERMINATED;
 682
 683 /**
 684  * purple_plugin_info_get_id:
 685  * @info: The plugin's info instance.
 686  *
 687  * Returns a plugin's ID.
 688  *
 689  * Returns: The plugin's ID.
 690  */
 691 const gchar *purple_plugin_info_get_id(const PurplePluginInfo *info);
 692
 693 /**
 694  * purple_plugin_info_get_name:
 695  * @info: The plugin's info instance.
 696  *
 697  * Returns a plugin's translated name.
 698  *
 699  * Returns: The name of the plugin, or %NULL.
 700  */
 701 const gchar *purple_plugin_info_get_name(const PurplePluginInfo *info);
 702
 703 /**
 704  * purple_plugin_info_get_version:
 705  * @info: The plugin's info instance.
 706  *
 707  * Returns a plugin's version.
 708  *
 709  * Returns: The version of the plugin, or %NULL.
 710  */
 711 const gchar *purple_plugin_info_get_version(const PurplePluginInfo *info);
 712
 713 /**
 714  * purple_plugin_info_get_category:
 715  * @info: The plugin's info instance.
 716  *
 717  * Returns a plugin's primary category.
 718  *
 719  * Returns: The primary category of the plugin, or %NULL.
 720  */
 721 const gchar *purple_plugin_info_get_category(const PurplePluginInfo *info);
 722
 723 /**
 724  * purple_plugin_info_get_summary:
 725  * @info: The plugin's info instance.
 726  *
 727  * Returns a plugin's summary.
 728  *
 729  * Returns: The summary of the plugin, or %NULL.
 730  */
 731 const gchar *purple_plugin_info_get_summary(const PurplePluginInfo *info);
 732
 733 /**
 734  * purple_plugin_info_get_description:
 735  * @info: The plugin's info instance.
 736  *
 737  * Returns a plugin's description.
 738  *
 739  * Returns: The description of the plugin, or %NULL.
 740  */
 741 const gchar *purple_plugin_info_get_description(const PurplePluginInfo *info);
 742
 743 /**
 744  * purple_plugin_info_get_authors:
 745  * @info: The plugin's info instance.
 746  *
 747  * Returns a NULL-terminated list of the plugin's authors.
 748  *
 749  * Returns: The authors of the plugin, or %NULL.
 750  */
 751 const gchar * const *
 752 purple_plugin_info_get_authors(const PurplePluginInfo *info);
 753
 754 /**
 755  * purple_plugin_info_get_website:
 756  * @info: The plugin's info instance.
 757  *
 758  * Returns a plugin's website.
 759  *
 760  * Returns: The website of the plugin, or %NULL.
 761  */
 762 const gchar *purple_plugin_info_get_website(const PurplePluginInfo *info);
 763
 764 /**
 765  * purple_plugin_info_get_icon:
 766  * @info: The plugin's info instance.
 767  *
 768  * Returns the path to a plugin's icon.
 769  *
 770  * Returns: The path to the plugin's icon, or %NULL.
 771  */
 772 const gchar *purple_plugin_info_get_icon(const PurplePluginInfo *info);
 773
 774 /**
 775  * purple_plugin_info_get_license_id:
 776  * @info: The plugin's info instance.
 777  *
 778  * Returns a short name of the plugin's license.
 779  *
 780  * Returns: The license name of the plugin, or %NULL.
 781  */
 782 const gchar *purple_plugin_info_get_license_id(const PurplePluginInfo *info);
 783
 784 /**
 785  * purple_plugin_info_get_license_text:
 786  * @info: The plugin's info instance.
 787  *
 788  * Returns the text of a plugin's license.
 789  *
 790  * Returns: The license text of the plugin, or %NULL.
 791  */
 792 const gchar *purple_plugin_info_get_license_text(const PurplePluginInfo *info);
 793
 794 /**
 795  * purple_plugin_info_get_license_url:
 796  * @info: The plugin's info instance.
 797  *
 798  * Returns the URL of a plugin's license.
 799  *
 800  * Returns: The license URL of the plugin, or %NULL.
 801  */
 802 const gchar *purple_plugin_info_get_license_url(const PurplePluginInfo *info);
 803
 804 /**
 805  * purple_plugin_info_get_dependencies:
 806  * @info: The plugin's info instance.
 807  *
 808  * Returns a NULL-terminated list of IDs of plugins required by a plugin.
 809  *
 810  * Returns: The dependencies of the plugin, or %NULL.
 811  */
 812 const gchar * const *
 813 purple_plugin_info_get_dependencies(const PurplePluginInfo *info);
 814
 815 /**
 816  * purple_plugin_info_get_abi_version:
 817  * @info: The plugin's info instance.
 818  *
 819  * Returns the required purple ABI version for a plugin.
 820  *
 821  * Returns: The required purple ABI version for the plugin.
 822  */
 823 guint32 purple_plugin_info_get_abi_version(const PurplePluginInfo *info);
 824
 825 /**
 826  * purple_plugin_info_get_actions_cb:
 827  * @info: The plugin info to get the callback from.
 828  *
 829  * Returns the callback that retrieves the list of actions a plugin can perform
 830  * at that moment.
 831  *
 832  * Returns: The callback that returns a list of #PurplePluginAction
 833  *          instances corresponding to the actions a plugin can perform.
 834  */
 835 PurplePluginActionsCb
 836 purple_plugin_info_get_actions_cb(const PurplePluginInfo *info);
 837
 838 /**
 839  * purple_plugin_info_get_extra_cb:
 840  * @info: The plugin info to get extra information from.
 841  *
 842  * Returns a callback that gives extra information about a plugin. You must
 843  * free the string returned by this callback.
 844  *
 845  * Returns: The callback that returns extra information about a plugin.
 846  */
 847 PurplePluginExtraCb
 848 purple_plugin_info_get_extra_cb(const PurplePluginInfo *info);
 849
 850 /**
 851  * purple_plugin_info_get_pref_frame_cb:
 852  * @info: The plugin info to get the callback from.
 853  *
 854  * Returns the callback that retrieves the preferences frame for a plugin, set
 855  * via the "pref-frame-cb" property of the plugin info.
 856  *
 857  * Returns: The callback that returns the preferences frame.
 858  */
 859 PurplePluginPrefFrameCb
 860 purple_plugin_info_get_pref_frame_cb(const PurplePluginInfo *info);
 861
 862 /**
 863  * purple_plugin_info_get_pref_request_cb:
 864  * @info: The plugin info to get the callback from.
 865  *
 866  * Returns the callback that retrieves the preferences request handle for a
 867  * plugin, set via the "pref-request-cb" property of the plugin info.
 868  *
 869  * Returns: The callback that returns the preferences request handle.
 870  */
 871 PurplePluginPrefRequestCb
 872 purple_plugin_info_get_pref_request_cb(const PurplePluginInfo *info);
 873
 874 /**
 875  * purple_plugin_info_get_flags:
 876  * @info: The plugin's info instance.
 877  *
 878  * Returns the plugin's flags.
 879  *
 880  * Returns: The flags of the plugin.
 881  */
 882 PurplePluginInfoFlags
 883 purple_plugin_info_get_flags(const PurplePluginInfo *info);
 884
 885 /**
 886  * purple_plugin_info_get_error:
 887  * @info: The plugin info.
 888  *
 889  * Returns an error in the plugin info that would prevent the plugin from being
 890  * loaded.
 891  *
 892  * Returns: The plugin info error, or %NULL.
 893  */
 894 const gchar *purple_plugin_info_get_error(const PurplePluginInfo *info);
 895
 896 /**
 897  * purple_plugin_info_set_ui_data:
 898  * @info: The plugin's info instance.
 899  * @ui_data: A pointer to associate with this object.
 900  *
 901  * Set the UI data associated with a plugin.
 902  */
 903 void purple_plugin_info_set_ui_data(PurplePluginInfo *info, gpointer ui_data);
 904
 905 /**
 906  * purple_plugin_info_get_ui_data:
 907  * @info: The plugin's info instance.
 908  *
 909  * Returns the UI data associated with a plugin.
 910  *
 911  * Returns: The UI data associated with this plugin.  This is a
 912  *          convenience field provided to the UIs--it is not
 913  *          used by the libpurple core.
 914  */
 915 gpointer purple_plugin_info_get_ui_data(const PurplePluginInfo *info);
 916
 917 /**************************************************************************/
 918 /* PluginAction API                                                       */
 919 /**************************************************************************/
 920
 921 /**
 922  * purple_plugin_action_get_type:
 923  *
 924  * Returns: The #GType for the #PurplePluginAction boxed structure.
 925  */
 926 GType purple_plugin_action_get_type(void);
 927
 928 /**
 929  * purple_plugin_action_new:
 930  * @label:    The description of the action to show to the user.
 931  * @callback: (scope call): The callback to call when the user selects this
 932  *            action.
 933  *
 934  * Allocates and returns a new PurplePluginAction. Use this to add actions in a
 935  * list in the "actions-cb" callback for your plugin.
 936  */
 937 PurplePluginAction *purple_plugin_action_new(const char* label,
 938                 PurplePluginActionCb callback);
 939
 940 /**
 941  * purple_plugin_action_free:
 942  * @action: The PurplePluginAction to free.
 943  *
 944  * Frees a PurplePluginAction
 945  */
 946 void purple_plugin_action_free(PurplePluginAction *action);
 947
 948 /**************************************************************************/
 949 /* Plugins API                                                            */
 950 /**************************************************************************/
 951
 952 /**
 953  * purple_plugins_find_all:
 954  *
 955  * Returns a list of all plugins, whether loaded or not.
 956  *
 957  * Returns: (element-type PurplePlugin) (transfer full): A list of all plugins.
 958  *             The list is owned by the caller, and must be
 959  *         g_list_free()d to avoid leaking the nodes.
 960  */
 961 GList *purple_plugins_find_all(void);
 962
 963 /**
 964  * purple_plugins_get_loaded:
 965  *
 966  * Returns a list of all loaded plugins.
 967  *
 968  * Returns: (element-type PurplePlugin) (transfer none): A list of all loaded plugins.
 969  */
 970 GList *purple_plugins_get_loaded(void);
 971
 972 /**
 973  * purple_plugins_add_search_path:
 974  * @path: The new search path.
 975  *
 976  * Add a new directory to search for plugins
 977  */
 978 void purple_plugins_add_search_path(const gchar *path);
 979
 980 /**
 981  * purple_plugins_refresh:
 982  *
 983  * Forces a refresh of all plugins found in the search paths, and loads plugins
 984  * that are to be auto-loaded.
 985  *
 986  * See purple_plugins_add_search_path().
 987  */
 988 void purple_plugins_refresh(void);
 989
 990 /**
 991  * purple_plugins_find_plugin:
 992  * @id: The plugin ID.
 993  *
 994  * Finds a plugin with the specified plugin ID.
 995  *
 996  * Returns: (transfer none): The plugin if found, or %NULL if not found.
 997  */
 998 PurplePlugin *purple_plugins_find_plugin(const gchar *id);
 999
1000 /**
1001  * purple_plugins_find_by_filename:
1002  * @filename: The plugin filename.
1003  *
1004  * Finds a plugin with the specified filename (filename with a path).
1005  *
1006  * Returns: (transfer none): The plugin if found, or %NULL if not found.
1007  */
1008 PurplePlugin *purple_plugins_find_by_filename(const char *filename);
1009
1010 /**
1011  * purple_plugins_save_loaded:
1012  * @key: The preference key to save the list of plugins to.
1013  *
1014  * Saves the list of loaded plugins to the specified preference key.
1015  * Plugins that are set to auto-load are not saved.
1016  */
1017 void purple_plugins_save_loaded(const char *key);
1018
1019 /**
1020  * purple_plugins_load_saved:
1021  * @key: The preference key containing the list of plugins.
1022  *
1023  * Attempts to load all the plugins in the specified preference key
1024  * that were loaded when purple last quit.
1025  */
1026 void purple_plugins_load_saved(const char *key);
1027
1028 /**************************************************************************/
1029 /* Plugins Subsystem API                                                  */
1030 /**************************************************************************/
1031
1032 /**
1033  * purple_plugins_get_handle:
1034  *
1035  * Returns the plugin subsystem handle.
1036  *
1037  * Returns: (transfer none): The plugin sybsystem handle.
1038  */
1039 void *purple_plugins_get_handle(void);
1040
1041 /**
1042  * purple_plugins_init:
1043  *
1044  * Initializes the plugin subsystem
1045  */
1046 void purple_plugins_init(void);
1047
1048 /**
1049  * purple_plugins_uninit:
1050  *
1051  * Uninitializes the plugin subsystem
1052  */
1053 void purple_plugins_uninit(void);
1054
1055 G_END_DECLS
1056
1057 #endif /* _PURPLE_PLUGINS_H_ */