plugin.h

Go to the documentation of this file.
00001 
00006 /* purple
00007  *
00008  * Purple is the legal property of its developers, whose names are too numerous
00009  * to list here.  Please refer to the COPYRIGHT file distributed with this
00010  * source distribution.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU General Public License as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
00025  *
00026  * @see @ref plugin-signals
00027  * @see @ref plugin-ids
00028  * @see @ref plugin-i18n
00029  */
00030 #ifndef _PURPLE_PLUGIN_H_
00031 #define _PURPLE_PLUGIN_H_
00032 
00033 #include <glib/glist.h>
00034 #include <gmodule.h>
00035 #include "signals.h"
00036 #include "value.h"
00037 
00038 typedef struct _PurplePlugin           PurplePlugin;
00039 typedef struct _PurplePluginInfo       PurplePluginInfo;
00040 typedef struct _PurplePluginUiInfo     PurplePluginUiInfo;
00041 typedef struct _PurplePluginLoaderInfo PurplePluginLoaderInfo;
00042 
00043 typedef struct _PurplePluginAction     PurplePluginAction;
00044 
00045 typedef int PurplePluginPriority; 
00047 #include "pluginpref.h"
00048 
00052 typedef enum
00053 {
00054     PURPLE_PLUGIN_UNKNOWN  = -1,  
00055     PURPLE_PLUGIN_STANDARD = 0,   
00056     PURPLE_PLUGIN_LOADER,         
00057     PURPLE_PLUGIN_PROTOCOL        
00059 } PurplePluginType;
00060 
00061 #define PURPLE_PRIORITY_DEFAULT     0
00062 #define PURPLE_PRIORITY_HIGHEST  9999
00063 #define PURPLE_PRIORITY_LOWEST  -9999
00064 
00065 #define PURPLE_PLUGIN_FLAG_INVISIBLE 0x01
00066 
00067 #define PURPLE_PLUGIN_MAGIC 5 /* once we hit 6.0.0 I think we can remove this */
00068 
00074 /* TODO We need to figure out exactly what parts of this are required. The
00075  * dependent plugin unloading stuff was causing crashes with perl and tcl
00076  * plugins because they didn't set ids and the dependency code was requiring
00077  * them. Then we need to actually make sure that plugins have all the right
00078  * parts before loading them. */
00079 struct _PurplePluginInfo
00080 {
00081     unsigned int magic;
00082     unsigned int major_version;
00083     unsigned int minor_version;
00084     PurplePluginType type;
00085     char *ui_requirement;
00086     unsigned long flags;
00087     GList *dependencies;
00088     PurplePluginPriority priority;
00089 
00090     char *id;
00091     char *name;
00092     char *version;
00093     char *summary;
00094     char *description;
00095     char *author;
00096     char *homepage;
00097 
00102     gboolean (*load)(PurplePlugin *plugin);
00103     gboolean (*unload)(PurplePlugin *plugin);
00104     void (*destroy)(PurplePlugin *plugin);
00105 
00106     void *ui_info; 
00107     void *extra_info;
00108     PurplePluginUiInfo *prefs_info; 
00109     GList *(*actions)(PurplePlugin *plugin, gpointer context);
00110 
00111     void (*_purple_reserved1)(void);
00112     void (*_purple_reserved2)(void);
00113     void (*_purple_reserved3)(void);
00114     void (*_purple_reserved4)(void);
00115 };
00116 
00120 struct _PurplePluginLoaderInfo
00121 {
00122     GList *exts;
00123 
00124     gboolean (*probe)(PurplePlugin *plugin);
00125     gboolean (*load)(PurplePlugin *plugin);
00126     gboolean (*unload)(PurplePlugin *plugin);
00127     void     (*destroy)(PurplePlugin *plugin);
00128 
00129     void (*_purple_reserved1)(void);
00130     void (*_purple_reserved2)(void);
00131     void (*_purple_reserved3)(void);
00132     void (*_purple_reserved4)(void);
00133 };
00134 
00138 struct _PurplePlugin
00139 {
00140     gboolean native_plugin;                
00141     gboolean loaded;                       
00142     void *handle;                          
00143     char *path;                            
00144     PurplePluginInfo *info;                  
00145     char *error;
00146     void *ipc_data;                        
00147     void *extra;                           
00148     gboolean unloadable;                   
00149     GList *dependent_plugins;              
00151     void (*_purple_reserved1)(void);
00152     void (*_purple_reserved2)(void);
00153     void (*_purple_reserved3)(void);
00154     void (*_purple_reserved4)(void);
00155 };
00156 
00157 #define PURPLE_PLUGIN_LOADER_INFO(plugin) \
00158     ((PurplePluginLoaderInfo *)(plugin)->info->extra_info)
00159 
00160 struct _PurplePluginUiInfo {
00161     PurplePluginPrefFrame *(*get_plugin_pref_frame)(PurplePlugin *plugin);
00162 
00163     int page_num;                                         
00164     PurplePluginPrefFrame *frame;                           
00166     void (*_purple_reserved1)(void);
00167     void (*_purple_reserved2)(void);
00168     void (*_purple_reserved3)(void);
00169     void (*_purple_reserved4)(void);
00170 };
00171 
00172 #define PURPLE_PLUGIN_HAS_PREF_FRAME(plugin) \
00173     ((plugin)->info != NULL && (plugin)->info->prefs_info != NULL)
00174 
00175 #define PURPLE_PLUGIN_UI_INFO(plugin) \
00176     ((PurplePluginUiInfo*)(plugin)->info->prefs_info)
00177 
00178 
00182 struct _PurplePluginAction {
00183     char *label;
00184     void (*callback)(PurplePluginAction *);
00185 
00187     PurplePlugin *plugin;
00188 
00191     gpointer context;
00192     
00193     gpointer user_data;
00194 };
00195 
00196 #define PURPLE_PLUGIN_HAS_ACTIONS(plugin) \
00197     ((plugin)->info != NULL && (plugin)->info->actions != NULL)
00198 
00199 #define PURPLE_PLUGIN_ACTIONS(plugin, context) \
00200     (PURPLE_PLUGIN_HAS_ACTIONS(plugin)? \
00201     (plugin)->info->actions(plugin, context): NULL)
00202 
00203 
00207 #if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL)
00208 # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
00209     gboolean purple_init_##pluginname##_plugin(void);\
00210     gboolean purple_init_##pluginname##_plugin(void) { \
00211         PurplePlugin *plugin = purple_plugin_new(TRUE, NULL); \
00212         plugin->info = &(plugininfo); \
00213         initfunc((plugin)); \
00214         purple_plugin_load((plugin)); \
00215         return purple_plugin_register(plugin); \
00216     }
00217 #else /* PURPLE_PLUGINS  && !PURPLE_STATIC_PRPL */
00218 # define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
00219     G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin); \
00220     G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin) { \
00221         plugin->info = &(plugininfo); \
00222         initfunc((plugin)); \
00223         return purple_plugin_register(plugin); \
00224     }
00225 #endif
00226 
00227 
00228 #ifdef __cplusplus
00229 extern "C" {
00230 #endif
00231 
00232 /**************************************************************************/
00234 /**************************************************************************/
00245 PurplePlugin *purple_plugin_new(gboolean native, const char *path);
00246 
00258 PurplePlugin *purple_plugin_probe(const char *filename);
00259 
00273 gboolean purple_plugin_register(PurplePlugin *plugin);
00274 
00285 gboolean purple_plugin_load(PurplePlugin *plugin);
00286 
00297 gboolean purple_plugin_unload(PurplePlugin *plugin);
00298 
00309 gboolean purple_plugin_reload(PurplePlugin *plugin);
00310 
00316 void purple_plugin_destroy(PurplePlugin *plugin);
00317 
00325 gboolean purple_plugin_is_loaded(const PurplePlugin *plugin);
00326 
00339 gboolean purple_plugin_is_unloadable(const PurplePlugin *plugin);
00340 
00348 const gchar *purple_plugin_get_id(const PurplePlugin *plugin);
00349 
00357 const gchar *purple_plugin_get_name(const PurplePlugin *plugin);
00358 
00366 const gchar *purple_plugin_get_version(const PurplePlugin *plugin);
00367 
00375 const gchar *purple_plugin_get_summary(const PurplePlugin *plugin);
00376 
00384 const gchar *purple_plugin_get_description(const PurplePlugin *plugin);
00385 
00393 const gchar *purple_plugin_get_author(const PurplePlugin *plugin);
00394 
00402 const gchar *purple_plugin_get_homepage(const PurplePlugin *plugin);
00403 
00406 /**************************************************************************/
00408 /**************************************************************************/
00425 gboolean purple_plugin_ipc_register(PurplePlugin *plugin, const char *command,
00426                                   PurpleCallback func,
00427                                   PurpleSignalMarshalFunc marshal,
00428                                   PurpleValue *ret_value, int num_params, ...);
00429 
00436 void purple_plugin_ipc_unregister(PurplePlugin *plugin, const char *command);
00437 
00443 void purple_plugin_ipc_unregister_all(PurplePlugin *plugin);
00444 
00456 gboolean purple_plugin_ipc_get_params(PurplePlugin *plugin, const char *command,
00457                                     PurpleValue **ret_value, int *num_params,
00458                                     PurpleValue ***params);
00459 
00471 void *purple_plugin_ipc_call(PurplePlugin *plugin, const char *command,
00472                            gboolean *ok, ...);
00473 
00476 /**************************************************************************/
00478 /**************************************************************************/
00486 void purple_plugins_add_search_path(const char *path);
00487 
00491 void purple_plugins_unload_all(void);
00492 
00496 void purple_plugins_destroy_all(void);
00497 
00503 void purple_plugins_save_loaded(const char *key);
00504 
00511 void purple_plugins_load_saved(const char *key);
00512 
00520 void purple_plugins_probe(const char *ext);
00521 
00527 gboolean purple_plugins_enabled(void);
00528 
00535 void purple_plugins_register_probe_notify_cb(void (*func)(void *), void *data);
00536 
00542 void purple_plugins_unregister_probe_notify_cb(void (*func)(void *));
00543 
00550 void purple_plugins_register_load_notify_cb(void (*func)(PurplePlugin *, void *),
00551                                           void *data);
00552 
00558 void purple_plugins_unregister_load_notify_cb(void (*func)(PurplePlugin *, void *));
00559 
00566 void purple_plugins_register_unload_notify_cb(void (*func)(PurplePlugin *, void *),
00567                                             void *data);
00568 
00574 void purple_plugins_unregister_unload_notify_cb(void (*func)(PurplePlugin *,
00575                                                            void *));
00576 
00584 PurplePlugin *purple_plugins_find_with_name(const char *name);
00585 
00593 PurplePlugin *purple_plugins_find_with_filename(const char *filename);
00594 
00602 PurplePlugin *purple_plugins_find_with_basename(const char *basename);
00603 
00611 PurplePlugin *purple_plugins_find_with_id(const char *id);
00612 
00618 GList *purple_plugins_get_loaded(void);
00619 
00628 GList *purple_plugins_get_protocols(void);
00629 
00635 GList *purple_plugins_get_all(void);
00636 
00639 /**************************************************************************/
00641 /**************************************************************************/
00649 void *purple_plugins_get_handle(void);
00650 
00654 void purple_plugins_init(void);
00655 
00659 void purple_plugins_uninit(void);
00660 
00669 PurplePluginAction *purple_plugin_action_new(const char* label, void (*callback)(PurplePluginAction *));
00670 
00676 void purple_plugin_action_free(PurplePluginAction *action);
00677 
00678 #ifdef __cplusplus
00679 }
00680 #endif
00681 
00682 #endif /* _PURPLE_PLUGIN_H_ */