pidgin/pidgin

closing merged branch
jingle-reply-with-senders-both
2019-11-11, Gary Kramlich
2f28c8df6574
closing merged branch
/* 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_PLUGINS_H
#define PURPLE_PLUGINS_H
/**
* SECTION:plugins
* @section_id: libpurple-plugins
* @short_description: <filename>plugins.h</filename>
* @title: Plugin API
* @see_also: <link linkend="chapter-signals-plugin">Plugin signals</link>,
* <link linkend="chapter-plugin-ids">Plugin IDs</link>,
* <link linkend="chapter-plugin-i18n">Third Party Plugin Translation</link>
*/
#include <gplugin.h>
#include <gplugin-native.h>
#include "version.h"
#define PURPLE_PLUGINS_DOMAIN (g_quark_from_static_string("plugins"))
#define PURPLE_TYPE_PLUGIN GPLUGIN_TYPE_PLUGIN
#define PURPLE_PLUGIN(obj) GPLUGIN_PLUGIN(obj)
#define PURPLE_IS_PLUGIN(obj) GPLUGIN_IS_PLUGIN(obj)
#define PURPLE_PLUGIN_GET_IFACE(obj) GPLUGIN_PLUGIN_GET_IFACE(obj)
/**
* PurplePlugin:
*
* Represents a plugin handle.
* This type is an alias for GPluginPlugin.
*/
typedef GPluginPlugin PurplePlugin;
typedef GPluginPluginInterface PurplePluginInterface;
#define PURPLE_TYPE_PLUGIN_INFO (purple_plugin_info_get_type())
typedef struct _PurplePluginInfo PurplePluginInfo;
#define PURPLE_TYPE_PLUGIN_ACTION (purple_plugin_action_get_type())
typedef struct _PurplePluginAction PurplePluginAction;
#include "pluginpref.h"
/**
* PurplePluginActionCb:
* @action: the action information.
*
* A function called when the related Action Menu is activated.
*/
typedef void (*PurplePluginActionCb)(PurplePluginAction *action);
/**
* PurplePluginActionsCb:
* @plugin: the plugin associated with this callback.
*
* Returns a list of actions the plugin can perform.
*
* Returns: (transfer none): A list of actions the plugin can perform.
*/
typedef GList *(*PurplePluginActionsCb)(PurplePlugin *plugin);
/**
* PurplePluginExtraCb:
* @plugin: the plugin associated with this callback.
*
* Gives extra information about the plguin.
*
* Returns: a newly allocated string denoting extra information
* about a plugin.
*/
typedef gchar *(*PurplePluginExtraCb)(PurplePlugin *plugin);
/**
* PurplePluginPrefFrameCb:
* @plugin: the plugin associated with this callback.
*
* Returns the preferences frame for the plugin.
*
* Returns: Preference frame.
*/
typedef PurplePluginPrefFrame *(*PurplePluginPrefFrameCb)(PurplePlugin *plugin);
/**
* PurplePrefRequestCb:
*
* Returns the preferences request handle for a plugin.
*
* Returns: Preferences request handle.
*/
typedef gpointer (*PurplePluginPrefRequestCb)(PurplePlugin *plugin);
/**
* PurplePluginInfoFlags:
* @PURPLE_PLUGIN_INFO_FLAGS_INTERNAL: Plugin is not shown in UI lists
* @PURPLE_PLUGIN_INFO_FLAGS_AUTO_LOAD: Auto-load the plugin
*
* Flags that can be used to treat plugins differently.
*/
typedef enum /*< flags >*/
{
PURPLE_PLUGIN_INFO_FLAGS_INTERNAL = 1 << 1,
PURPLE_PLUGIN_INFO_FLAGS_AUTO_LOAD = 1 << 2,
} PurplePluginInfoFlags;
/**
* PurplePluginInfo:
* @ui_data: The UI data associated with the plugin. This is a convenience
* field provided to the UIs -- it is not used by the libpurple core.
*
* Holds information about a plugin.
*/
struct _PurplePluginInfo {
GPluginPluginInfo parent;
/*< public >*/
gpointer ui_data;
};
/**
* PurplePluginAction:
* @label: The label to display in the user interface.
* @callback: The function to call when the user wants to perform this action.
* @plugin: The plugin that this action belongs to.
* @user_data: User data to pass to @callback.
*
* Represents an action that the plugin can perform. This shows up in the Tools
* menu, under a submenu with the name of the plugin.
*/
struct _PurplePluginAction {
char *label;
PurplePluginActionCb callback;
PurplePlugin *plugin;
gpointer user_data;
};
/**
* PURPLE_PLUGIN_ABI_VERSION:
*
* Note: The lower six nibbles represent the ABI version for libpurple, the
* rest are required by GPlugin.
*
* Returns: An ABI version to set in plugins using major and minor versions.
*/
#define PURPLE_PLUGIN_ABI_VERSION(major,minor) \
(0x01000000 | ((major) << 16) | (minor))
/**
* PURPLE_PLUGIN_ABI_MAJOR_VERSION:
*
* Returns: The major version from an ABI version
*/
#define PURPLE_PLUGIN_ABI_MAJOR_VERSION(abi) \
((abi >> 16) & 0xff)
/**
* PURPLE_PLUGIN_ABI_MINOR_VERSION:
*
* Returns: The minor version from an ABI version
*/
#define PURPLE_PLUGIN_ABI_MINOR_VERSION(abi) \
(abi & 0xffff)
/**
* PURPLE_ABI_VERSION:
*
* A convenience‎ macro that returns an ABI version using PURPLE_MAJOR_VERSION
* and PURPLE_MINOR_VERSION
*/
#define PURPLE_ABI_VERSION PURPLE_PLUGIN_ABI_VERSION(PURPLE_MAJOR_VERSION, PURPLE_MINOR_VERSION)
/**
* PURPLE_PLUGIN_INIT:
*
* Defines the plugin's entry points.
*/
#define PURPLE_PLUGIN_INIT(pluginname,pluginquery,pluginload,pluginunload) \
G_MODULE_EXPORT GPluginPluginInfo *gplugin_query(GError **e); \
G_MODULE_EXPORT GPluginPluginInfo *gplugin_query(GError **e) { \
return GPLUGIN_PLUGIN_INFO(pluginquery(e)); \
} \
G_MODULE_EXPORT gboolean gplugin_load(GPluginNativePlugin *p, GError **e); \
G_MODULE_EXPORT gboolean gplugin_load(GPluginNativePlugin *p, GError **e) { \
return pluginload(PURPLE_PLUGIN(p), e); \
} \
G_MODULE_EXPORT gboolean gplugin_unload(GPluginNativePlugin *p, GError **e); \
G_MODULE_EXPORT gboolean gplugin_unload(GPluginNativePlugin *p, GError **e) { \
return pluginunload(PURPLE_PLUGIN(p), e); \
}
G_BEGIN_DECLS
/**************************************************************************/
/* Plugin API */
/**************************************************************************/
/**
* purple_plugin_load:
* @plugin: The plugin to load.
* @error: Return location for a #GError or %NULL. If provided, this
* will be set to the reason if the load fails.
*
* Attempts to load a plugin.
*
* Also see purple_plugin_unload().
*
* Returns: %TRUE if successful or already loaded, %FALSE otherwise.
*/
gboolean purple_plugin_load(PurplePlugin *plugin, GError **error);
/**
* purple_plugin_unload:
* @plugin: The plugin handle.
* @error: Return location for a #GError or %NULL. If provided, this
* will be set to the reason if the unload fails.
*
* Unloads the specified plugin.
*
* Also see purple_plugin_load().
*
* Returns: %TRUE if successful or not loaded, %FALSE otherwise.
*/
gboolean purple_plugin_unload(PurplePlugin *plugin, GError **error);
/**
* purple_plugin_is_loaded:
* @plugin: The plugin.
*
* Returns whether or not a plugin is currently loaded.
*
* Returns: %TRUE if loaded, or %FALSE otherwise.
*/
gboolean purple_plugin_is_loaded(PurplePlugin *plugin);
/**
* purple_plugin_get_info:
* @plugin: The plugin.
*
* Returns a plugin's #PurplePluginInfo instance.
*
* Returns: (transfer none): The plugin's #PurplePluginInfo instance.
* GPlugin refs the plugin info object before returning it. This workaround
* is to avoid managing the reference counts everywhere in our codebase
* where we use the plugin info. The plugin info instance is guaranteed to
* exist as long as the plugin exists.
*/
PurplePluginInfo *purple_plugin_get_info(PurplePlugin *plugin);
/**
* purple_plugin_disable:
*
* Disable a plugin.
*
* This function adds the plugin to a list of plugins to "disable at the next
* startup" by excluding said plugins from the list of plugins to save. The
* UI needs to call purple_plugins_save_loaded() after calling this for it
* to have any effect.
*/
void purple_plugin_disable(PurplePlugin *plugin);
/**
* purple_plugin_is_internal:
* @plugin: The plugin.
*
* Returns whether a plugin is an internal plugin. Internal plugins provide
* required additional functionality to the libpurple core. These plugins must
* not be shown in plugin lists. Examples of such plugins are in-tree protocol
* plugins, loaders etc.
*
* Returns: %TRUE if the plugin is an internal plugin, %FALSE otherwise.
*/
gboolean purple_plugin_is_internal(PurplePlugin *plugin);
/**
* purple_plugin_get_dependent_plugins:
* @plugin: The plugin whose dependent plugins are returned.
*
* Returns a list of plugins that depend on a particular plugin.
*
* Returns: (element-type PurplePlugin) (transfer none): The list of a plugins that depend on the specified
* plugin.
*/
GSList *purple_plugin_get_dependent_plugins(PurplePlugin *plugin);
/**************************************************************************/
/* PluginInfo API */
/**************************************************************************/
/**
* purple_plugin_info_get_type:
*
* Returns: The #GType for the #PurplePluginInfo object.
*/
G_DECLARE_FINAL_TYPE(PurplePluginInfo, purple_plugin_info, PURPLE, PLUGIN_INFO,
GPluginPluginInfo)
/**
* purple_plugin_info_new:
* @first_property: The first property name
* @...: The value of the first property, followed optionally by more
* name/value pairs, followed by %NULL
*
* Creates a new #PurplePluginInfo instance to be returned from
* #plugin_query of a plugin, using the provided name/value pairs.
*
* All properties except <literal>"id"</literal> and
* <literal>"purple-abi"</literal> are optional.
*
* Valid property names are:
* <informaltable frame='none'>
* <tgroup cols='2'><tbody>
* <row><entry><literal>"id"</literal></entry>
* <entry>(string) The ID of the plugin.</entry>
* </row>
* <row><entry><literal>"abi-version"</literal></entry>
* <entry>(<type>guint32</type>) The ABI version required by the
* plugin.</entry>
* </row>
* <row><entry><literal>"name"</literal></entry>
* <entry>(string) The translated name of the plugin.</entry>
* </row>
* <row><entry><literal>"version"</literal></entry>
* <entry>(string) Version of the plugin.</entry>
* </row>
* <row><entry><literal>"category"</literal></entry>
* <entry>(string) Primary category of the plugin.</entry>
* </row>
* <row><entry><literal>"summary"</literal></entry>
* <entry>(string) Brief summary of the plugin.</entry>
* </row>
* <row><entry><literal>"description"</literal></entry>
* <entry>(string) Full description of the plugin.</entry>
* </row>
* <row><entry><literal>"authors"</literal></entry>
* <entry>(<type>const gchar * const *</type>) A %NULL-terminated list of
* plugin authors. format: First Last &lt;user\@domain.com&gt;</entry>
* </row>
* <row><entry><literal>"website"</literal></entry>
* <entry>(string) Website of the plugin.</entry>
* </row>
* <row><entry><literal>"icon"</literal></entry>
* <entry>(string) Path to a plugin's icon.</entry>
* </row>
* <row><entry><literal>"license-id"</literal></entry>
* <entry>(string) Short name of the plugin's license. This should
* either be an identifier of the license from
* <ulink url="http://dep.debian.net/deps/dep5/#license-specification">
* DEP5</ulink> or "Other" for custom licenses.</entry>
* </row>
* <row><entry><literal>"license-text"</literal></entry>
* <entry>(string) The text of the plugin's license, if unlisted on
* DEP5.</entry>
* </row>
* <row><entry><literal>"license-url"</literal></entry>
* <entry>(string) The plugin's license URL, if unlisted on DEP5.</entry>
* </row>
* <row><entry><literal>"dependencies"</literal></entry>
* <entry>(<type>const gchar * const *</type>) A %NULL-terminated list of
* plugin IDs required by the plugin.</entry>
* </row>
* <row><entry><literal>"actions-cb"</literal></entry>
* <entry>(#PurplePluginActionsCb) Callback that returns a list of
* actions the plugin can perform.</entry>
* </row>
* <row><entry><literal>"extra-cb"</literal></entry>
* <entry>(#PurplePluginExtraCb) Callback that returns a newly
* allocated string denoting extra information about a plugin.</entry>
* </row>
* <row><entry><literal>"pref-frame-cb"</literal></entry>
* <entry>(#PurplePluginPrefFrameCb) Callback that returns a
* preferences frame for the plugin.</entry>
* </row>
* <row><entry><literal>"pref-request-cb"</literal></entry>
* <entry>(#PurplePluginPrefRequestCb) Callback that returns a
* preferences request handle for the plugin.</entry>
* </row>
* <row><entry><literal>"flags"</literal></entry>
* <entry>(#PurplePluginInfoFlags) The flags for a plugin.</entry>
* </row>
* </tbody></tgroup>
* </informaltable>
*
* See #PURPLE_PLUGIN_ABI_VERSION,
* <link linkend="chapter-plugin-ids">Plugin IDs</link>.
*
* Returns: A new #PurplePluginInfo instance.
*/
PurplePluginInfo *purple_plugin_info_new(const char *first_property, ...)
G_GNUC_NULL_TERMINATED;
/**
* purple_plugin_info_get_actions_cb:
* @info: The plugin info to get the callback from.
*
* Returns the callback that retrieves the list of actions a plugin can perform
* at that moment.
*
* Returns: The callback that returns a list of #PurplePluginAction
* instances corresponding to the actions a plugin can perform.
*/
PurplePluginActionsCb
purple_plugin_info_get_actions_cb(PurplePluginInfo *info);
/**
* purple_plugin_info_get_extra_cb:
* @info: The plugin info to get extra information from.
*
* Returns a callback that gives extra information about a plugin. You must
* free the string returned by this callback.
*
* Returns: The callback that returns extra information about a plugin.
*/
PurplePluginExtraCb
purple_plugin_info_get_extra_cb(PurplePluginInfo *info);
/**
* purple_plugin_info_get_pref_frame_cb:
* @info: The plugin info to get the callback from.
*
* Returns the callback that retrieves the preferences frame for a plugin, set
* via the "pref-frame-cb" property of the plugin info.
*
* Returns: The callback that returns the preferences frame.
*/
PurplePluginPrefFrameCb
purple_plugin_info_get_pref_frame_cb(PurplePluginInfo *info);
/**
* purple_plugin_info_get_pref_request_cb:
* @info: The plugin info to get the callback from.
*
* Returns the callback that retrieves the preferences request handle for a
* plugin, set via the "pref-request-cb" property of the plugin info.
*
* Returns: The callback that returns the preferences request handle.
*/
PurplePluginPrefRequestCb
purple_plugin_info_get_pref_request_cb(PurplePluginInfo *info);
/**
* purple_plugin_info_get_flags:
* @info: The plugin's info instance.
*
* Returns the plugin's flags.
*
* Returns: The flags of the plugin.
*/
PurplePluginInfoFlags
purple_plugin_info_get_flags(PurplePluginInfo *info);
/**
* purple_plugin_info_get_error:
* @info: The plugin info.
*
* Returns an error in the plugin info that would prevent the plugin from being
* loaded.
*
* Returns: The plugin info error, or %NULL.
*/
const gchar *purple_plugin_info_get_error(PurplePluginInfo *info);
/**
* purple_plugin_info_set_ui_data:
* @info: The plugin's info instance.
* @ui_data: A pointer to associate with this object.
*
* Set the UI data associated with a plugin.
*/
void purple_plugin_info_set_ui_data(PurplePluginInfo *info, gpointer ui_data);
/**
* purple_plugin_info_get_ui_data:
* @info: The plugin's info instance.
*
* Returns the UI data associated with a plugin.
*
* Returns: The UI data associated with this plugin. This is a
* convenience field provided to the UIs--it is not
* used by the libpurple core.
*/
gpointer purple_plugin_info_get_ui_data(PurplePluginInfo *info);
/**************************************************************************/
/* PluginAction API */
/**************************************************************************/
/**
* purple_plugin_action_get_type:
*
* Returns: The #GType for the #PurplePluginAction boxed structure.
*/
GType purple_plugin_action_get_type(void);
/**
* purple_plugin_action_new:
* @label: The description of the action to show to the user.
* @callback: (scope call): The callback to call when the user selects this
* action.
*
* Allocates and returns a new PurplePluginAction. Use this to add actions in a
* list in the "actions-cb" callback for your plugin.
*/
PurplePluginAction *purple_plugin_action_new(const char* label,
PurplePluginActionCb callback);
/**
* purple_plugin_action_free:
* @action: The PurplePluginAction to free.
*
* Frees a PurplePluginAction
*/
void purple_plugin_action_free(PurplePluginAction *action);
/**************************************************************************/
/* Plugins API */
/**************************************************************************/
/**
* purple_plugins_find_all:
*
* Returns a list of all plugins, whether loaded or not.
*
* Returns: (element-type PurplePlugin) (transfer full): A list of all plugins.
* The list is owned by the caller, and must be
* g_list_free()d to avoid leaking the nodes.
*/
GList *purple_plugins_find_all(void);
/**
* purple_plugins_get_loaded:
*
* Returns a list of all loaded plugins.
*
* Returns: (element-type PurplePlugin) (transfer none): A list of all loaded plugins.
*/
GList *purple_plugins_get_loaded(void);
/**
* purple_plugins_add_search_path:
* @path: The new search path.
*
* Add a new directory to search for plugins
*/
void purple_plugins_add_search_path(const gchar *path);
/**
* purple_plugins_refresh:
*
* Forces a refresh of all plugins found in the search paths, and loads plugins
* that are to be auto-loaded.
*
* See purple_plugins_add_search_path().
*/
void purple_plugins_refresh(void);
/**
* purple_plugins_find_plugin:
* @id: The plugin ID.
*
* Finds a plugin with the specified plugin ID.
*
* Returns: (transfer none): The plugin if found, or %NULL if not found.
*/
PurplePlugin *purple_plugins_find_plugin(const gchar *id);
/**
* purple_plugins_find_by_filename:
* @filename: The plugin filename.
*
* Finds a plugin with the specified filename (filename with a path).
*
* Returns: (transfer none): The plugin if found, or %NULL if not found.
*/
PurplePlugin *purple_plugins_find_by_filename(const char *filename);
/**
* purple_plugins_save_loaded:
* @key: The preference key to save the list of plugins to.
*
* Saves the list of loaded plugins to the specified preference key.
* Plugins that are set to auto-load are not saved.
*/
void purple_plugins_save_loaded(const char *key);
/**
* purple_plugins_load_saved:
* @key: The preference key containing the list of plugins.
*
* Attempts to load all the plugins in the specified preference key
* that were loaded when purple last quit.
*/
void purple_plugins_load_saved(const char *key);
/**************************************************************************/
/* Plugins Subsystem API */
/**************************************************************************/
/**
* purple_plugins_get_handle:
*
* Returns the plugin subsystem handle.
*
* Returns: (transfer none): The plugin sybsystem handle.
*/
void *purple_plugins_get_handle(void);
/**
* purple_plugins_init:
*
* Initializes the plugin subsystem
*/
void purple_plugins_init(void);
/**
* purple_plugins_uninit:
*
* Uninitializes the plugin subsystem
*/
void purple_plugins_uninit(void);
G_END_DECLS
#endif /* PURPLE_PLUGINS_H */