plugin.h

Go to the documentation of this file.

 
/* purple
 *
 * Purple is the legal property of its developers, whose names are too numerous
 * to list here.  Please refer to the COPYRIGHT file distributed with this
 * source distribution.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
 */
#ifndef _PURPLE_PLUGIN_H_
#define _PURPLE_PLUGIN_H_
 
#include <glib.h>
#include <gmodule.h>
#include "signals.h"
#include "value.h"
 
typedef struct _PurplePlugin           PurplePlugin;
typedef struct _PurplePluginInfo       PurplePluginInfo;
typedef struct _PurplePluginUiInfo     PurplePluginUiInfo;
typedef struct _PurplePluginLoaderInfo PurplePluginLoaderInfo;
 
typedef struct _PurplePluginAction     PurplePluginAction;
 
typedef int PurplePluginPriority; 
#include "pluginpref.h"
 
typedef enum
{
    PURPLE_PLUGIN_UNKNOWN  = -1,  
    PURPLE_PLUGIN_STANDARD = 0,   
    PURPLE_PLUGIN_LOADER,         
    PURPLE_PLUGIN_PROTOCOL        
} PurplePluginType;
 
#define PURPLE_PRIORITY_DEFAULT     0
#define PURPLE_PRIORITY_HIGHEST  9999
#define PURPLE_PRIORITY_LOWEST  -9999
 
#define PURPLE_PLUGIN_FLAG_INVISIBLE 0x01
 
#define PURPLE_PLUGIN_MAGIC 5 /* once we hit 6.0.0 I think we can remove this */
 
struct _PurplePluginInfo
{
    unsigned int magic;
    unsigned int major_version;
    unsigned int minor_version;
    PurplePluginType type;
    char *ui_requirement;
    unsigned long flags;
    GList *dependencies;
    PurplePluginPriority priority;
 
    char *id;
    char *name;
    char *version;
    char *summary;
    char *description;
    char *author;
    char *homepage;
 
    gboolean (*load)(PurplePlugin *plugin);
    gboolean (*unload)(PurplePlugin *plugin);
    void (*destroy)(PurplePlugin *plugin);
 
    void *ui_info; 
    void *extra_info;
    PurplePluginUiInfo *prefs_info; 
    GList *(*actions)(PurplePlugin *plugin, gpointer context);
 
    void (*_purple_reserved1)(void);
    void (*_purple_reserved2)(void);
    void (*_purple_reserved3)(void);
    void (*_purple_reserved4)(void);
};
 
struct _PurplePluginLoaderInfo
{
    GList *exts;
 
    gboolean (*probe)(PurplePlugin *plugin);
    gboolean (*load)(PurplePlugin *plugin);
    gboolean (*unload)(PurplePlugin *plugin);
    void     (*destroy)(PurplePlugin *plugin);
 
    void (*_purple_reserved1)(void);
    void (*_purple_reserved2)(void);
    void (*_purple_reserved3)(void);
    void (*_purple_reserved4)(void);
};
 
struct _PurplePlugin
{
    gboolean native_plugin;                
    gboolean loaded;                       
    void *handle;                          
    char *path;                            
    PurplePluginInfo *info;                  
    char *error;
    void *ipc_data;                        
    void *extra;                           
    gboolean unloadable;                   
    GList *dependent_plugins;              
    void (*_purple_reserved1)(void);
    void (*_purple_reserved2)(void);
    void (*_purple_reserved3)(void);
    void (*_purple_reserved4)(void);
};
 
#define PURPLE_PLUGIN_LOADER_INFO(plugin) \
    ((PurplePluginLoaderInfo *)(plugin)->info->extra_info)
 
struct _PurplePluginUiInfo {
    PurplePluginPrefFrame *(*get_plugin_pref_frame)(PurplePlugin *plugin);
 
    int page_num;                                         
    PurplePluginPrefFrame *frame;                           
    void (*_purple_reserved1)(void);
    void (*_purple_reserved2)(void);
    void (*_purple_reserved3)(void);
    void (*_purple_reserved4)(void);
};
 
#define PURPLE_PLUGIN_HAS_PREF_FRAME(plugin) \
    ((plugin)->info != NULL && (plugin)->info->prefs_info != NULL)
 
#define PURPLE_PLUGIN_UI_INFO(plugin) \
    ((PurplePluginUiInfo*)(plugin)->info->prefs_info)
 
 
struct _PurplePluginAction {
    char *label;
    void (*callback)(PurplePluginAction *);
 
    PurplePlugin *plugin;
 
    gpointer context;
 
    gpointer user_data;
};
 
#define PURPLE_PLUGIN_HAS_ACTIONS(plugin) \
    ((plugin)->info != NULL && (plugin)->info->actions != NULL)
 
#define PURPLE_PLUGIN_ACTIONS(plugin, context) \
    (PURPLE_PLUGIN_HAS_ACTIONS(plugin)? \
    (plugin)->info->actions(plugin, context): NULL)
 
 
#if !defined(PURPLE_PLUGINS) || defined(PURPLE_STATIC_PRPL)
# define _FUNC_NAME(x) purple_init_##x##_plugin
# define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
    gboolean _FUNC_NAME(pluginname)(void);\
    gboolean _FUNC_NAME(pluginname)(void) { \
        PurplePlugin *plugin = purple_plugin_new(TRUE, NULL); \
        plugin->info = &(plugininfo); \
        initfunc((plugin)); \
        purple_plugin_load((plugin)); \
        return purple_plugin_register(plugin); \
    }
#else /* PURPLE_PLUGINS  && !PURPLE_STATIC_PRPL */
# define PURPLE_INIT_PLUGIN(pluginname, initfunc, plugininfo) \
    G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin); \
    G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin) { \
        plugin->info = &(plugininfo); \
        initfunc((plugin)); \
        return purple_plugin_register(plugin); \
    }
#endif
 
 
#ifdef __cplusplus
extern "C" {
#endif
 
/**************************************************************************/
/**************************************************************************/
PurplePlugin *purple_plugin_new(gboolean native, const char *path);
 
PurplePlugin *purple_plugin_probe(const char *filename);
 
gboolean purple_plugin_register(PurplePlugin *plugin);
 
gboolean purple_plugin_load(PurplePlugin *plugin);
 
gboolean purple_plugin_unload(PurplePlugin *plugin);
 
void purple_plugin_disable(PurplePlugin *plugin);
 
gboolean purple_plugin_reload(PurplePlugin *plugin);
 
void purple_plugin_destroy(PurplePlugin *plugin);
 
gboolean purple_plugin_is_loaded(const PurplePlugin *plugin);
 
gboolean purple_plugin_is_unloadable(const PurplePlugin *plugin);
 
const gchar *purple_plugin_get_id(const PurplePlugin *plugin);
 
const gchar *purple_plugin_get_name(const PurplePlugin *plugin);
 
const gchar *purple_plugin_get_version(const PurplePlugin *plugin);
 
const gchar *purple_plugin_get_summary(const PurplePlugin *plugin);
 
const gchar *purple_plugin_get_description(const PurplePlugin *plugin);
 
const gchar *purple_plugin_get_author(const PurplePlugin *plugin);
 
const gchar *purple_plugin_get_homepage(const PurplePlugin *plugin);
 
/**************************************************************************/
/**************************************************************************/
gboolean purple_plugin_ipc_register(PurplePlugin *plugin, const char *command,
                                  PurpleCallback func,
                                  PurpleSignalMarshalFunc marshal,
                                  PurpleValue *ret_value, int num_params, ...);
 
void purple_plugin_ipc_unregister(PurplePlugin *plugin, const char *command);
 
void purple_plugin_ipc_unregister_all(PurplePlugin *plugin);
 
gboolean purple_plugin_ipc_get_params(PurplePlugin *plugin, const char *command,
                                    PurpleValue **ret_value, int *num_params,
                                    PurpleValue ***params);
 
void *purple_plugin_ipc_call(PurplePlugin *plugin, const char *command,
                           gboolean *ok, ...);
 
/**************************************************************************/
/**************************************************************************/
void purple_plugins_add_search_path(const char *path);
 
GList *purple_plugins_get_search_paths(void);
 
void purple_plugins_unload_all(void);
 
void purple_plugins_unload(PurplePluginType type);
 
void purple_plugins_destroy_all(void);
 
void purple_plugins_save_loaded(const char *key);
 
void purple_plugins_load_saved(const char *key);
 
void purple_plugins_probe(const char *ext);
 
gboolean purple_plugins_enabled(void);
 
#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
void purple_plugins_register_probe_notify_cb(void (*func)(void *), void *data);
#endif
 
#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
void purple_plugins_unregister_probe_notify_cb(void (*func)(void *));
#endif
 
#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
void purple_plugins_register_load_notify_cb(void (*func)(PurplePlugin *, void *),
                                          void *data);
#endif
 
#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
void purple_plugins_unregister_load_notify_cb(void (*func)(PurplePlugin *, void *));
#endif
 
#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
void purple_plugins_register_unload_notify_cb(void (*func)(PurplePlugin *, void *),
                                            void *data);
#endif
 
#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_PLUGIN_C_)
void purple_plugins_unregister_unload_notify_cb(void (*func)(PurplePlugin *,
                                                           void *));
#endif
 
PurplePlugin *purple_plugins_find_with_name(const char *name);
 
PurplePlugin *purple_plugins_find_with_filename(const char *filename);
 
PurplePlugin *purple_plugins_find_with_basename(const char *basename);
 
PurplePlugin *purple_plugins_find_with_id(const char *id);
 
GList *purple_plugins_get_loaded(void);
 
GList *purple_plugins_get_protocols(void);
 
GList *purple_plugins_get_all(void);
 
/**************************************************************************/
/**************************************************************************/
void *purple_plugins_get_handle(void);
 
void purple_plugins_init(void);
 
void purple_plugins_uninit(void);
 
PurplePluginAction *purple_plugin_action_new(const char* label, void (*callback)(PurplePluginAction *));
 
void purple_plugin_action_free(PurplePluginAction *action);
 
#ifdef __cplusplus
}
#endif
 
#endif /* _PURPLE_PLUGIN_H_ */