plugin.h

Go to the documentation of this file.
00001 
00025 #ifndef _PURPLE_PLUGIN_H_
00026 #define _PURPLE_PLUGIN_H_
00027 
00028 #include <glib/glist.h>
00029 #include <gmodule.h>
00030 #include "signals.h"
00031 #include "value.h"
00032 
00033 typedef struct _PurplePlugin           PurplePlugin;
00034 typedef struct _PurplePluginInfo       PurplePluginInfo;
00035 typedef struct _PurplePluginUiInfo     PurplePluginUiInfo;
00036 typedef struct _PurplePluginLoaderInfo PurplePluginLoaderInfo;
00037 
00038 typedef struct _PurplePluginAction     PurplePluginAction;
00039 
00040 typedef int PurplePluginPriority; 
00042 #include "pluginpref.h"
00043 
00047 typedef enum
00048 {
00049     PURPLE_PLUGIN_UNKNOWN  = -1,  
00050     PURPLE_PLUGIN_STANDARD = 0,   
00051     PURPLE_PLUGIN_LOADER,         
00052     PURPLE_PLUGIN_PROTOCOL        
00054 } PurplePluginType;
00055 
00056 #define PURPLE_PRIORITY_DEFAULT     0
00057 #define PURPLE_PRIORITY_HIGHEST  9999
00058 #define PURPLE_PRIORITY_LOWEST  -9999
00059 
00060 #define PURPLE_PLUGIN_FLAG_INVISIBLE 0x01
00061 
00062 #define PURPLE_PLUGIN_MAGIC 5 /* once we hit 6.0.0 I think we can remove this */
00063 
00069 /* TODO We need to figure out exactly what parts of this are required. The
00070  * dependent plugin unloading stuff was causing crashes with perl and tcl
00071  * plugins because they didn't set ids and the dependency code was requiring
00072  * them. Then we need to actually make sure that plugins have all the right
00073  * parts before loading them. */
00074 struct _PurplePluginInfo
00075 {
00076     unsigned int magic;
00077     unsigned int major_version;
00078     unsigned int minor_version;
00079     PurplePluginType type;
00080     char *ui_requirement;
00081     unsigned long flags;
00082     GList *dependencies;
00083     PurplePluginPriority priority;
00084 
00085     char *id;
00086     char *name;
00087     char *version;
00088     char *summary;
00089     char *description;
00090     char *author;
00091     char *homepage;
00092 
00097     gboolean (*load)(PurplePlugin *plugin);
00098     gboolean (*unload)(PurplePlugin *plugin);
00099     void (*destroy)(PurplePlugin *plugin);
00100 
00101     void *ui_info; 
00102     void *extra_info;
00103     PurplePluginUiInfo *prefs_info; 
00104     GList *(*actions)(PurplePlugin *plugin, gpointer context);
00105 
00106     void (*_purple_reserved1)(void);
00107     void (*_purple_reserved2)(void);
00108     void (*_purple_reserved3)(void);
00109     void (*_purple_reserved4)(void);
00110 };
00111 
00115 struct _PurplePluginLoaderInfo
00116 {
00117     GList *exts;
00118 
00119     gboolean (*probe)(PurplePlugin *plugin);
00120     gboolean (*load)(PurplePlugin *plugin);
00121     gboolean (*unload)(PurplePlugin *plugin);
00122     void     (*destroy)(PurplePlugin *plugin);
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 _PurplePlugin
00134 {
00135     gboolean native_plugin;                
00136     gboolean loaded;                       
00137     void *handle;                          
00138     char *path;                            
00139     PurplePluginInfo *info;                  
00140     char *error;
00141     void *ipc_data;                        
00142     void *extra;                           
00143     gboolean unloadable;                   
00144     GList *dependent_plugins;              
00146     void (*_purple_reserved1)(void);
00147     void (*_purple_reserved2)(void);
00148     void (*_purple_reserved3)(void);
00149     void (*_purple_reserved4)(void);
00150 };
00151 
00152 #define PURPLE_PLUGIN_LOADER_INFO(plugin) \
00153     ((PurplePluginLoaderInfo *)(plugin)->info->extra_info)
00154 
00155 struct _PurplePluginUiInfo {
00156     PurplePluginPrefFrame *(*get_plugin_pref_frame)(PurplePlugin *plugin);
00157 
00158     int page_num;                                         
00159     PurplePluginPrefFrame *frame;                           
00161     void (*_purple_reserved1)(void);
00162     void (*_purple_reserved2)(void);
00163     void (*_purple_reserved3)(void);
00164     void (*_purple_reserved4)(void);
00165 };
00166 
00167 #define PURPLE_PLUGIN_HAS_PREF_FRAME(plugin) \
00168     ((plugin)->info != NULL && (plugin)->info->prefs_info != NULL)
00169 
00170 #define PURPLE_PLUGIN_UI_INFO(plugin) \
00171     ((PurplePluginUiInfo*)(plugin)->info->prefs_info)
00172 
00173 
00177 struct _PurplePluginAction {
00178     char *label;
00179     void (*callback)(PurplePluginAction *);
00180 
00182     PurplePlugin *plugin;
00183 
00186     gpointer context;
00187 };
00188 
00189 #define PURPLE_PLUGIN_HAS_ACTIONS(plugin) \
00190     ((plugin)->info != NULL && (plugin)->info->actions != NULL)
00191 
00192 #define PURPLE_PLUGIN_ACTIONS(plugin, context) \
00193     (PURPLE_PLUGIN_HAS_ACTIONS(plugin)? \
00194     (plugin)->info->actions(plugin, context): NULL)
00195 
00196 
00200 #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL)
00201 # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
00202     gboolean purple_init_##pluginname##_plugin(void);\
00203     gboolean purple_init_##pluginname##_plugin(void) { \
00204         PurplePlugin *plugin = purple_plugin_new(TRUE, NULL); \
00205         plugin->info = &(plugininfo); \
00206         initfunc((plugin)); \
00207         purple_plugin_load((plugin)); \
00208         return purple_plugin_register(plugin); \
00209     }
00210 #else /* PURPLE_PLUGINS  && !PURPLE_STATIC_PRPL */
00211 # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
00212     G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin); \
00213     G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin) { \
00214         plugin->info = &(plugininfo); \
00215         initfunc((plugin)); \
00216         return purple_plugin_register(plugin); \
00217     }
00218 #endif
00219 
00220 
00221 #ifdef __cplusplus
00222 extern "C" {
00223 #endif
00224 
00225 /**************************************************************************/
00227 /**************************************************************************/
00238 PurplePlugin *purple_plugin_new(gboolean native, const char *path);
00239 
00251 PurplePlugin *purple_plugin_probe(const char *filename);
00252 
00266 gboolean purple_plugin_register(PurplePlugin *plugin);
00267 
00278 gboolean purple_plugin_load(PurplePlugin *plugin);
00279 
00290 gboolean purple_plugin_unload(PurplePlugin *plugin);
00291 
00302 gboolean purple_plugin_reload(PurplePlugin *plugin);
00303 
00309 void purple_plugin_destroy(PurplePlugin *plugin);
00310 
00318 gboolean purple_plugin_is_loaded(const PurplePlugin *plugin);
00319 
00332 gboolean purple_plugin_is_unloadable(const PurplePlugin *plugin);
00333 
00341 const gchar *purple_plugin_get_id(const PurplePlugin *plugin);
00342 
00350 const gchar *purple_plugin_get_name(const PurplePlugin *plugin);
00351 
00359 const gchar *purple_plugin_get_version(const PurplePlugin *plugin);
00360 
00368 const gchar *purple_plugin_get_summary(const PurplePlugin *plugin);
00369 
00377 const gchar *purple_plugin_get_description(const PurplePlugin *plugin);
00378 
00386 const gchar *purple_plugin_get_author(const PurplePlugin *plugin);
00387 
00395 const gchar *purple_plugin_get_homepage(const PurplePlugin *plugin);
00396 
00399 /**************************************************************************/
00401 /**************************************************************************/
00418 gboolean purple_plugin_ipc_register(PurplePlugin *plugin, const char *command,
00419                                   PurpleCallback func,
00420                                   PurpleSignalMarshalFunc marshal,
00421                                   PurpleValue *ret_value, int num_params, ...);
00422 
00429 void purple_plugin_ipc_unregister(PurplePlugin *plugin, const char *command);
00430 
00436 void purple_plugin_ipc_unregister_all(PurplePlugin *plugin);
00437 
00449 gboolean purple_plugin_ipc_get_params(PurplePlugin *plugin, const char *command,
00450                                     PurpleValue **ret_value, int *num_params,
00451                                     PurpleValue ***params);
00452 
00464 void *purple_plugin_ipc_call(PurplePlugin *plugin, const char *command,
00465                            gboolean *ok, ...);
00466 
00469 /**************************************************************************/
00471 /**************************************************************************/
00479 void purple_plugins_add_search_path(const char *path);
00480 
00484 void purple_plugins_unload_all(void);
00485 
00489 void purple_plugins_destroy_all(void);
00490 
00496 void purple_plugins_save_loaded(const char *key);
00497 
00504 void purple_plugins_load_saved(const char *key);
00505 
00513 void purple_plugins_probe(const char *ext);
00514 
00520 gboolean purple_plugins_enabled(void);
00521 
00528 void purple_plugins_register_probe_notify_cb(void (*func)(void *), void *data);
00529 
00535 void purple_plugins_unregister_probe_notify_cb(void (*func)(void *));
00536 
00543 void purple_plugins_register_load_notify_cb(void (*func)(PurplePlugin *, void *),
00544                                           void *data);
00545 
00551 void purple_plugins_unregister_load_notify_cb(void (*func)(PurplePlugin *, void *));
00552 
00559 void purple_plugins_register_unload_notify_cb(void (*func)(PurplePlugin *, void *),
00560                                             void *data);
00561 
00567 void purple_plugins_unregister_unload_notify_cb(void (*func)(PurplePlugin *,
00568                                                            void *));
00569 
00577 PurplePlugin *purple_plugins_find_with_name(const char *name);
00578 
00586 PurplePlugin *purple_plugins_find_with_filename(const char *filename);
00587 
00595 PurplePlugin *purple_plugins_find_with_basename(const char *basename);
00596 
00604 PurplePlugin *purple_plugins_find_with_id(const char *id);
00605 
00611 GList *purple_plugins_get_loaded(void);
00612 
00621 GList *purple_plugins_get_protocols(void);
00622 
00628 GList *purple_plugins_get_all(void);
00629 
00632 /**************************************************************************/
00634 /**************************************************************************/
00642 void *purple_plugins_get_handle(void);
00643 
00647 void purple_plugins_init(void);
00648 
00652 void purple_plugins_uninit(void);
00653 
00662 PurplePluginAction *purple_plugin_action_new(const char* label, void (*callback)(PurplePluginAction *));
00663 
00669 void purple_plugin_action_free(PurplePluginAction *action);
00670 
00671 #ifdef __cplusplus
00672 }
00673 #endif
00674 
00675 #endif /* _PURPLE_PLUGIN_H_ */