plugin.h

Go to the documentation of this file.
00001 
00009 /* purple
00010  *
00011  * Purple is the legal property of its developers, whose names are too numerous
00012  * to list here.  Please refer to the COPYRIGHT file distributed with this
00013  * source distribution.
00014  *
00015  * This program is free software; you can redistribute it and/or modify
00016  * it under the terms of the GNU General Public License as published by
00017  * the Free Software Foundation; either version 2 of the License, or
00018  * (at your option) any later version.
00019  *
00020  * This program is distributed in the hope that it will be useful,
00021  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00022  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00023  * GNU General Public License for more details.
00024  *
00025  * You should have received a copy of the GNU General Public License
00026  * along with this program; if not, write to the Free Software
00027  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
00028  */
00029 #ifndef _PURPLE_PLUGIN_H_
00030 #define _PURPLE_PLUGIN_H_
00031 
00032 #include <glib.h>
00033 #include <gmodule.h>
00034 #include "signals.h"
00035 #include "value.h"
00036 
00038 typedef struct _PurplePlugin           PurplePlugin;
00040 typedef struct _PurplePluginInfo       PurplePluginInfo;
00042 typedef struct _PurplePluginUiInfo     PurplePluginUiInfo;
00044 typedef struct _PurplePluginLoaderInfo PurplePluginLoaderInfo;
00045 
00047 typedef struct _PurplePluginAction     PurplePluginAction;
00048 
00049 typedef int PurplePluginPriority; 
00051 #include "pluginpref.h"
00052 
00056 typedef enum
00057 {
00058     PURPLE_PLUGIN_UNKNOWN  = -1,  
00059     PURPLE_PLUGIN_STANDARD = 0,   
00060     PURPLE_PLUGIN_LOADER,         
00061     PURPLE_PLUGIN_PROTOCOL        
00063 } PurplePluginType;
00064 
00065 #define PURPLE_PRIORITY_DEFAULT     0
00066 #define PURPLE_PRIORITY_HIGHEST  9999
00067 #define PURPLE_PRIORITY_LOWEST  -9999
00068 
00069 #define PURPLE_PLUGIN_FLAG_INVISIBLE 0x01
00070 
00071 #define PURPLE_PLUGIN_MAGIC 5 /* once we hit 6.0.0 I think we can remove this */
00072 
00078 struct _PurplePluginInfo
00079 {
00080     unsigned int magic;
00081     unsigned int major_version;
00082     unsigned int minor_version;
00083     PurplePluginType type;
00084     char *ui_requirement;
00085     unsigned long flags;
00086     GList *dependencies;
00087     PurplePluginPriority priority;
00088 
00089     char *id;
00090     char *name;
00091     char *version;
00092     char *summary;
00093     char *description;
00094     char *author;
00095     char *homepage;
00096 
00101     gboolean (*load)(PurplePlugin *plugin);
00102     gboolean (*unload)(PurplePlugin *plugin);
00103     void (*destroy)(PurplePlugin *plugin);
00104 
00105     void *ui_info; 
00106     void *extra_info;
00107     PurplePluginUiInfo *prefs_info; 
00122     GList *(*actions)(PurplePlugin *plugin, gpointer context);
00123 
00124     void (*_purple_reserved1)(void);
00125     void (*_purple_reserved2)(void);
00126     void (*_purple_reserved3)(void);
00127     void (*_purple_reserved4)(void);
00128 };
00129 
00133 struct _PurplePluginLoaderInfo
00134 {
00135     GList *exts;
00136 
00137     gboolean (*probe)(PurplePlugin *plugin);
00138     gboolean (*load)(PurplePlugin *plugin);
00139     gboolean (*unload)(PurplePlugin *plugin);
00140     void     (*destroy)(PurplePlugin *plugin);
00141 
00142     void (*_purple_reserved1)(void);
00143     void (*_purple_reserved2)(void);
00144     void (*_purple_reserved3)(void);
00145     void (*_purple_reserved4)(void);
00146 };
00147 
00151 struct _PurplePlugin
00152 {
00153     gboolean native_plugin;                
00154     gboolean loaded;                       
00155     void *handle;                          
00156     char *path;                            
00157     PurplePluginInfo *info;                  
00158     char *error;
00159     void *ipc_data;                        
00160     void *extra;                           
00161     gboolean unloadable;                   
00162     GList *dependent_plugins;              
00164     void (*_purple_reserved1)(void);
00165     void (*_purple_reserved2)(void);
00166     void (*_purple_reserved3)(void);
00167     void (*_purple_reserved4)(void);
00168 };
00169 
00170 #define PURPLE_PLUGIN_LOADER_INFO(plugin) \
00171     ((PurplePluginLoaderInfo *)(plugin)->info->extra_info)
00172 
00173 struct _PurplePluginUiInfo {
00174     PurplePluginPrefFrame *(*get_plugin_pref_frame)(PurplePlugin *plugin);
00175 
00176     int page_num;                                         
00177     PurplePluginPrefFrame *frame;                           
00179     void (*_purple_reserved1)(void);
00180     void (*_purple_reserved2)(void);
00181     void (*_purple_reserved3)(void);
00182     void (*_purple_reserved4)(void);
00183 };
00184 
00185 #define PURPLE_PLUGIN_HAS_PREF_FRAME(plugin) \
00186     ((plugin)->info != NULL && (plugin)->info->prefs_info != NULL)
00187 
00188 #define PURPLE_PLUGIN_UI_INFO(plugin) \
00189     ((PurplePluginUiInfo*)(plugin)->info->prefs_info)
00190 
00191 
00195 struct _PurplePluginAction {
00196     char *label;
00197     void (*callback)(PurplePluginAction *);
00198 
00200     PurplePlugin *plugin;
00201 
00204     gpointer context;
00205 
00206     gpointer user_data;
00207 };
00208 
00209 #define PURPLE_PLUGIN_HAS_ACTIONS(plugin) \
00210     ((plugin)->info != NULL && (plugin)->info->actions != NULL)
00211 
00212 #define PURPLE_PLUGIN_ACTIONS(plugin, context) \
00213     (PURPLE_PLUGIN_HAS_ACTIONS(plugin)? \
00214     (plugin)->info->actions(plugin, context): NULL)
00215 
00216 
00220 #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL)
00221 # define _FUNC_NAME(x) purple_init_##x##_plugin
00222 # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
00223     gboolean _FUNC_NAME(pluginname)(void);\
00224     gboolean _FUNC_NAME(pluginname)(void) { \
00225         PurplePlugin *plugin = purple_plugin_new(TRUE, NULL); \
00226         plugin->info = &(plugininfo); \
00227         initfunc((plugin)); \
00228         purple_plugin_load((plugin)); \
00229         return purple_plugin_register(plugin); \
00230     }
00231 #else /* PURPLE_PLUGINS  && !PURPLE_STATIC_PRPL */
00232 # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
00233     G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin); \
00234     G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin) { \
00235         plugin->info = &(plugininfo); \
00236         initfunc((plugin)); \
00237         return purple_plugin_register(plugin); \
00238     }
00239 #endif
00240 
00241 
00242 #ifdef __cplusplus
00243 extern "C" {
00244 #endif
00245 
00246 /**************************************************************************/
00248 /**************************************************************************/
00259 PurplePlugin *purple_plugin_new(gboolean native, const char *path);
00260 
00272 PurplePlugin *purple_plugin_probe(const char *filename);
00273 
00287 gboolean purple_plugin_register(PurplePlugin *plugin);
00288 
00299 gboolean purple_plugin_load(PurplePlugin *plugin);
00300 
00311 gboolean purple_plugin_unload(PurplePlugin *plugin);
00312 
00323 void purple_plugin_disable(PurplePlugin *plugin);
00324 
00335 gboolean purple_plugin_reload(PurplePlugin *plugin);
00336 
00342 void purple_plugin_destroy(PurplePlugin *plugin);
00343 
00351 gboolean purple_plugin_is_loaded(const PurplePlugin *plugin);
00352 
00365 gboolean purple_plugin_is_unloadable(const PurplePlugin *plugin);
00366 
00374 const gchar *purple_plugin_get_id(const PurplePlugin *plugin);
00375 
00383 const gchar *purple_plugin_get_name(const PurplePlugin *plugin);
00384 
00392 const gchar *purple_plugin_get_version(const PurplePlugin *plugin);
00393 
00401 const gchar *purple_plugin_get_summary(const PurplePlugin *plugin);
00402 
00410 const gchar *purple_plugin_get_description(const PurplePlugin *plugin);
00411 
00419 const gchar *purple_plugin_get_author(const PurplePlugin *plugin);
00420 
00428 const gchar *purple_plugin_get_homepage(const PurplePlugin *plugin);
00429 
00432 /**************************************************************************/
00434 /**************************************************************************/
00451 gboolean purple_plugin_ipc_register(PurplePlugin *plugin, const char *command,
00452                                   PurpleCallback func,
00453                                   PurpleSignalMarshalFunc marshal,
00454                                   PurpleValue *ret_value, int num_params, ...);
00455 
00462 void purple_plugin_ipc_unregister(PurplePlugin *plugin, const char *command);
00463 
00469 void purple_plugin_ipc_unregister_all(PurplePlugin *plugin);
00470 
00482 gboolean purple_plugin_ipc_get_params(PurplePlugin *plugin, const char *command,
00483                                     PurpleValue **ret_value, int *num_params,
00484                                     PurpleValue ***params);
00485 
00497 void *purple_plugin_ipc_call(PurplePlugin *plugin, const char *command,
00498                            gboolean *ok, ...);
00499 
00502 /**************************************************************************/
00504 /**************************************************************************/
00512 void purple_plugins_add_search_path(const char *path);
00513 
00521 GList *purple_plugins_get_search_paths(void);
00522 
00526 void purple_plugins_unload_all(void);
00527 
00531 void purple_plugins_unload(PurplePluginType type);
00532 
00536 void purple_plugins_destroy_all(void);
00537 
00543 void purple_plugins_save_loaded(const char *key);
00544 
00551 void purple_plugins_load_saved(const char *key);
00552 
00560 void purple_plugins_probe(const char *ext);
00561 
00567 gboolean purple_plugins_enabled(void);
00568 
00569 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
00570 
00577 void purple_plugins_register_probe_notify_cb(void (*func)(void *), void *data);
00578 #endif
00579 
00580 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
00581 
00587 void purple_plugins_unregister_probe_notify_cb(void (*func)(void *));
00588 #endif
00589 
00590 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
00591 
00598 void purple_plugins_register_load_notify_cb(void (*func)(PurplePlugin *, void *),
00599                                           void *data);
00600 #endif
00601 
00602 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
00603 
00609 void purple_plugins_unregister_load_notify_cb(void (*func)(PurplePlugin *, void *));
00610 #endif
00611 
00612 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
00613 
00620 void purple_plugins_register_unload_notify_cb(void (*func)(PurplePlugin *, void *),
00621                                             void *data);
00622 #endif
00623 
00624 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
00625 
00631 void purple_plugins_unregister_unload_notify_cb(void (*func)(PurplePlugin *,
00632                                                            void *));
00633 #endif
00634 
00642 PurplePlugin *purple_plugins_find_with_name(const char *name);
00643 
00651 PurplePlugin *purple_plugins_find_with_filename(const char *filename);
00652 
00660 PurplePlugin *purple_plugins_find_with_basename(const char *basename);
00661 
00669 PurplePlugin *purple_plugins_find_with_id(const char *id);
00670 
00676 GList *purple_plugins_get_loaded(void);
00677 
00686 GList *purple_plugins_get_protocols(void);
00687 
00693 GList *purple_plugins_get_all(void);
00694 
00697 /**************************************************************************/
00699 /**************************************************************************/
00707 void *purple_plugins_get_handle(void);
00708 
00712 void purple_plugins_init(void);
00713 
00717 void purple_plugins_uninit(void);
00718 
00727 PurplePluginAction *purple_plugin_action_new(const char* label, void (*callback)(PurplePluginAction *));
00728 
00734 void purple_plugin_action_free(PurplePluginAction *action);
00735 
00736 #ifdef __cplusplus
00737 }
00738 #endif
00739 
00740 #endif /* _PURPLE_PLUGIN_H_ */