plugin.h

Go to the documentation of this file.
00001 
00029 #ifndef _PURPLE_PLUGIN_H_
00030 #define _PURPLE_PLUGIN_H_
00031 
00032 #include <glib/glist.h>
00033 #include <gmodule.h>
00034 #include "signals.h"
00035 #include "value.h"
00036 
00037 typedef struct _PurplePlugin           PurplePlugin;
00038 typedef struct _PurplePluginInfo       PurplePluginInfo;
00039 typedef struct _PurplePluginUiInfo     PurplePluginUiInfo;
00040 typedef struct _PurplePluginLoaderInfo PurplePluginLoaderInfo;
00041 
00042 typedef struct _PurplePluginAction     PurplePluginAction;
00043 
00044 typedef int PurplePluginPriority; 
00046 #include "pluginpref.h"
00047 
00051 typedef enum
00052 {
00053     PURPLE_PLUGIN_UNKNOWN  = -1,  
00054     PURPLE_PLUGIN_STANDARD = 0,   
00055     PURPLE_PLUGIN_LOADER,         
00056     PURPLE_PLUGIN_PROTOCOL        
00058 } PurplePluginType;
00059 
00060 #define PURPLE_PRIORITY_DEFAULT     0
00061 #define PURPLE_PRIORITY_HIGHEST  9999
00062 #define PURPLE_PRIORITY_LOWEST  -9999
00063 
00064 #define PURPLE_PLUGIN_FLAG_INVISIBLE 0x01
00065 
00066 #define PURPLE_PLUGIN_MAGIC 5 /* once we hit 6.0.0 I think we can remove this */
00067 
00073 /* TODO We need to figure out exactly what parts of this are required. The
00074  * dependent plugin unloading stuff was causing crashes with perl and tcl
00075  * plugins because they didn't set ids and the dependency code was requiring
00076  * them. Then we need to actually make sure that plugins have all the right
00077  * parts before loading them. */
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; 
00108     GList *(*actions)(PurplePlugin *plugin, gpointer context);
00109 
00110     void (*_purple_reserved1)(void);
00111     void (*_purple_reserved2)(void);
00112     void (*_purple_reserved3)(void);
00113     void (*_purple_reserved4)(void);
00114 };
00115 
00119 struct _PurplePluginLoaderInfo
00120 {
00121     GList *exts;
00122 
00123     gboolean (*probe)(PurplePlugin *plugin);
00124     gboolean (*load)(PurplePlugin *plugin);
00125     gboolean (*unload)(PurplePlugin *plugin);
00126     void     (*destroy)(PurplePlugin *plugin);
00127 
00128     void (*_purple_reserved1)(void);
00129     void (*_purple_reserved2)(void);
00130     void (*_purple_reserved3)(void);
00131     void (*_purple_reserved4)(void);
00132 };
00133 
00137 struct _PurplePlugin
00138 {
00139     gboolean native_plugin;                
00140     gboolean loaded;                       
00141     void *handle;                          
00142     char *path;                            
00143     PurplePluginInfo *info;                  
00144     char *error;
00145     void *ipc_data;                        
00146     void *extra;                           
00147     gboolean unloadable;                   
00148     GList *dependent_plugins;              
00150     void (*_purple_reserved1)(void);
00151     void (*_purple_reserved2)(void);
00152     void (*_purple_reserved3)(void);
00153     void (*_purple_reserved4)(void);
00154 };
00155 
00156 #define PURPLE_PLUGIN_LOADER_INFO(plugin) \
00157     ((PurplePluginLoaderInfo *)(plugin)->info->extra_info)
00158 
00159 struct _PurplePluginUiInfo {
00160     PurplePluginPrefFrame *(*get_plugin_pref_frame)(PurplePlugin *plugin);
00161 
00162     int page_num;                                         
00163     PurplePluginPrefFrame *frame;                           
00165     void (*_purple_reserved1)(void);
00166     void (*_purple_reserved2)(void);
00167     void (*_purple_reserved3)(void);
00168     void (*_purple_reserved4)(void);
00169 };
00170 
00171 #define PURPLE_PLUGIN_HAS_PREF_FRAME(plugin) \
00172     ((plugin)->info != NULL && (plugin)->info->prefs_info != NULL)
00173 
00174 #define PURPLE_PLUGIN_UI_INFO(plugin) \
00175     ((PurplePluginUiInfo*)(plugin)->info->prefs_info)
00176 
00177 
00181 struct _PurplePluginAction {
00182     char *label;
00183     void (*callback)(PurplePluginAction *);
00184 
00186     PurplePlugin *plugin;
00187 
00190     gpointer context;
00191 };
00192 
00193 #define PURPLE_PLUGIN_HAS_ACTIONS(plugin) \
00194     ((plugin)->info != NULL && (plugin)->info->actions != NULL)
00195 
00196 #define PURPLE_PLUGIN_ACTIONS(plugin, context) \
00197     (PURPLE_PLUGIN_HAS_ACTIONS(plugin)? \
00198     (plugin)->info->actions(plugin, context): NULL)
00199 
00200 
00204 #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL)
00205 # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
00206     gboolean purple_init_##pluginname##_plugin(void);\
00207     gboolean purple_init_##pluginname##_plugin(void) { \
00208         PurplePlugin *plugin = purple_plugin_new(TRUE, NULL); \
00209         plugin->info = &(plugininfo); \
00210         initfunc((plugin)); \
00211         purple_plugin_load((plugin)); \
00212         return purple_plugin_register(plugin); \
00213     }
00214 #else /* PURPLE_PLUGINS  && !PURPLE_STATIC_PRPL */
00215 # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
00216     G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin); \
00217     G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin) { \
00218         plugin->info = &(plugininfo); \
00219         initfunc((plugin)); \
00220         return purple_plugin_register(plugin); \
00221     }
00222 #endif
00223 
00224 
00225 #ifdef __cplusplus
00226 extern "C" {
00227 #endif
00228 
00229 /**************************************************************************/
00231 /**************************************************************************/
00242 PurplePlugin *purple_plugin_new(gboolean native, const char *path);
00243 
00255 PurplePlugin *purple_plugin_probe(const char *filename);
00256 
00270 gboolean purple_plugin_register(PurplePlugin *plugin);
00271 
00282 gboolean purple_plugin_load(PurplePlugin *plugin);
00283 
00294 gboolean purple_plugin_unload(PurplePlugin *plugin);
00295 
00306 gboolean purple_plugin_reload(PurplePlugin *plugin);
00307 
00313 void purple_plugin_destroy(PurplePlugin *plugin);
00314 
00322 gboolean purple_plugin_is_loaded(const PurplePlugin *plugin);
00323 
00336 gboolean purple_plugin_is_unloadable(const PurplePlugin *plugin);
00337 
00345 const gchar *purple_plugin_get_id(const PurplePlugin *plugin);
00346 
00354 const gchar *purple_plugin_get_name(const PurplePlugin *plugin);
00355 
00363 const gchar *purple_plugin_get_version(const PurplePlugin *plugin);
00364 
00372 const gchar *purple_plugin_get_summary(const PurplePlugin *plugin);
00373 
00381 const gchar *purple_plugin_get_description(const PurplePlugin *plugin);
00382 
00390 const gchar *purple_plugin_get_author(const PurplePlugin *plugin);
00391 
00399 const gchar *purple_plugin_get_homepage(const PurplePlugin *plugin);
00400 
00403 /**************************************************************************/
00405 /**************************************************************************/
00422 gboolean purple_plugin_ipc_register(PurplePlugin *plugin, const char *command,
00423                                   PurpleCallback func,
00424                                   PurpleSignalMarshalFunc marshal,
00425                                   PurpleValue *ret_value, int num_params, ...);
00426 
00433 void purple_plugin_ipc_unregister(PurplePlugin *plugin, const char *command);
00434 
00440 void purple_plugin_ipc_unregister_all(PurplePlugin *plugin);
00441 
00453 gboolean purple_plugin_ipc_get_params(PurplePlugin *plugin, const char *command,
00454                                     PurpleValue **ret_value, int *num_params,
00455                                     PurpleValue ***params);
00456 
00468 void *purple_plugin_ipc_call(PurplePlugin *plugin, const char *command,
00469                            gboolean *ok, ...);
00470 
00473 /**************************************************************************/
00475 /**************************************************************************/
00483 void purple_plugins_add_search_path(const char *path);
00484 
00488 void purple_plugins_unload_all(void);
00489 
00493 void purple_plugins_destroy_all(void);
00494 
00500 void purple_plugins_save_loaded(const char *key);
00501 
00508 void purple_plugins_load_saved(const char *key);
00509 
00517 void purple_plugins_probe(const char *ext);
00518 
00524 gboolean purple_plugins_enabled(void);
00525 
00532 void purple_plugins_register_probe_notify_cb(void (*func)(void *), void *data);
00533 
00539 void purple_plugins_unregister_probe_notify_cb(void (*func)(void *));
00540 
00547 void purple_plugins_register_load_notify_cb(void (*func)(PurplePlugin *, void *),
00548                                           void *data);
00549 
00555 void purple_plugins_unregister_load_notify_cb(void (*func)(PurplePlugin *, void *));
00556 
00563 void purple_plugins_register_unload_notify_cb(void (*func)(PurplePlugin *, void *),
00564                                             void *data);
00565 
00571 void purple_plugins_unregister_unload_notify_cb(void (*func)(PurplePlugin *,
00572                                                            void *));
00573 
00581 PurplePlugin *purple_plugins_find_with_name(const char *name);
00582 
00590 PurplePlugin *purple_plugins_find_with_filename(const char *filename);
00591 
00599 PurplePlugin *purple_plugins_find_with_basename(const char *basename);
00600 
00608 PurplePlugin *purple_plugins_find_with_id(const char *id);
00609 
00615 GList *purple_plugins_get_loaded(void);
00616 
00625 GList *purple_plugins_get_protocols(void);
00626 
00632 GList *purple_plugins_get_all(void);
00633 
00636 /**************************************************************************/
00638 /**************************************************************************/
00646 void *purple_plugins_get_handle(void);
00647 
00651 void purple_plugins_init(void);
00652 
00656 void purple_plugins_uninit(void);
00657 
00666 PurplePluginAction *purple_plugin_action_new(const char* label, void (*callback)(PurplePluginAction *));
00667 
00673 void purple_plugin_action_free(PurplePluginAction *action);
00674 
00675 #ifdef __cplusplus
00676 }
00677 #endif
00678 
00679 #endif /* _PURPLE_PLUGIN_H_ */