/soc/2013/ankitkv/gobjectification: ebb632962d4e: Updated C-HOWT...
Ankit Vani
a at nevitus.org
Sun Sep 22 10:27:47 EDT 2013
Changeset: ebb632962d4eec177247c81681e5431751e78570
Author: Ankit Vani <a at nevitus.org>
Date: 2013-09-22 19:56 +0530
Branch: soc.2013.gobjectification.plugins
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/ebb632962d4e
Description:
Updated C-HOWTO.dox according to the new plugin API
diffstat:
doc/C-HOWTO.dox | 266 ++++++++++---------------------------------------------
1 files changed, 49 insertions(+), 217 deletions(-)
diffs (299 lines):
diff --git a/doc/C-HOWTO.dox b/doc/C-HOWTO.dox
--- a/doc/C-HOWTO.dox
+++ b/doc/C-HOWTO.dox
@@ -27,10 +27,33 @@
#include "notify.h"
#include "plugins.h"
-#include "version.h"
+
+static PurplePluginInfo *
+plugin_query(GError **error)
+{
+ const gchar * const authors[] = {
+ "Author Name <e at mail>",
+ NULL
+ };
+
+ /* For specific notes on the meanings of each of these members, consult the
+ C Plugin Howto on the website. */
+ return purple_plugin_info_new (
+ "name", "Hello World!",
+ "version", VERSION,
+ "category", "Example",
+ "summary", "Hello World Plugin",
+ "description", "Hello World Plugin",
+ "authors", authors,
+ "website", "http://helloworld.tld",
+ "abi-version", PURPLE_ABI_VERSION,
+ NULL
+ );
+}
static gboolean
-plugin_load(PurplePlugin *plugin) {
+plugin_load(PurplePlugin *plugin, GError **error)
+{
purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!",
"This is the Hello World! plugin :)",
NULL, NULL, NULL, NULL);
@@ -38,45 +61,13 @@ plugin_load(PurplePlugin *plugin) {
return TRUE;
}
-static PurplePluginInfo info = {
- PURPLE_PLUGIN_MAGIC,
- PURPLE_MAJOR_VERSION,
- PURPLE_MINOR_VERSION,
- PURPLE_PLUGIN_STANDARD,
- NULL,
- 0,
- NULL,
- PURPLE_PRIORITY_DEFAULT,
-
- "core-hello_world",
- "Hello World!",
- VERSION,
-
- "Hello World Plugin",
- "Hello World Plugin",
- NULL,
- "http://helloworld.tld",
-
- plugin_load,
- NULL,
- NULL,
-
- NULL,
- NULL,
- NULL,
- NULL,
- NULL,
- NULL,
- NULL,
- NULL
-};
-
-static void
-init_plugin(PurplePlugin *plugin)
+static gboolean
+plugin_unload(PurplePlugin *plugin, GError **error)
{
+ return TRUE;
}
-PURPLE_INIT_PLUGIN(hello_world, init_plugin, info);
+PURPLE_PLUGIN_INIT(hello_world, plugin_query, plugin_load, plugin_unload);
@endcode
@@ -85,189 +76,30 @@ PURPLE_INIT_PLUGIN(hello_world, init_plu
glib wrappers of the standard C types.
Next, we include plugins.h which has all the plugin specific stuff that we
- need. For example: @c PurplePlugin, @c PurplePluginInfo,
- @c PURPLE_PLUGIN_MAGIC, and @c PURPLE_INIT_PLUGIN().
+ need. For example: @c #PurplePlugin, @c #PurplePluginInfo,
+ and @c PURPLE_PLUGIN_INIT().
- Our last include is version.h which defines @c PURPLE_MAJOR_VERSION, and
- @c PURPLE_MINOR_VERSION. There is not much you need to know about these,
- except that they are required and will stop your plugin from crashing Pidgin
- when something has changed that your plugin does not know about yet.
+ @c plugin_query, @c plugin_load and @c plugin_unload must be implemented in
+ every plugin. Each of these functions can return an error on failure by using
+ @c g_set_error on the @c error argument.
- @c plugin_load is not required. It is called when the plugin is loaded so
- that you can initialize any variables and so on. In this plugin we'll just
- use it to display a message.
+ @c plugin_query is called when the plugin is probed by the plugin system, and
+ returns various information about the plugin in form of a newly created
+ PurplePluginInfo instance. See plugins.h for a list of available properties
+ you can use in @c purple_plugin_info_new .
- Next we have the @c PurplePluginInfo structure. Every plugin MUST have one of
- these. Below is a code snipet of the same struct used in @c hello_world with
- comments describing what each is.
+ @c plugin_load is called when the plugin is loaded so that you can initialize
+ any variables, register dynamic types, and so on. Plugins may also want to
+ add their preferences to the pref tree--more about that later. In this plugin
+ we'll just use it to display a message.
- @code
-static PurplePluginInfo info = {
- PURPLE_PLUGIN_MAGIC, /* Plugin magic, this must always be
- PURPLE_PLUGIN_MAGIC.
- */
- PURPLE_MAJOR_VERSION, /* This is also defined in libpurple. It helps
- libpurple's plugin system determine which
- version of libpurple this plugin was
- compiled for, and whether loading it will
- cause problems.
- */
- PURPLE_MINOR_VERSION, /* See previous */
- PURPLE_PLUGIN_STANDARD, /* PurplePluginType: There are 4 different
- values for this field. The first is
- PURPLE_PLUGIN_UNKNOWN, which should not be
- used. The second is PURPLE_PLUGIN_STANDARD;
- this is the value most plugins will use.
- Next, we have PURPLE_PLUGIN_LOADER; this is
- the type you want to load if your plugin
- is going to make it possible to load non-
- native plugins. For example, the Perl and
- Tcl loader plugins are of this type.
- Last, we have PURPLE_PLUGIN_PROTOCOL. If
- your plugin is going to allow the user to
- connect to another network, this is the
- type you'd want to use.
- */
- NULL, /* This field is the UI requirement. If you're
- writing a core plugin, this must be NULL
- and the plugin must not contain any UI
- code. If you're writing a Pidgin plugin,
- you need to use PIDGIN_PLUGIN_TYPE. If you
- are writing a Finch plugin, you would use
- FINCH_PLUGIN_TYPE.
- */
- 0, /* This field is for plugin flags. Currently,
- the only flag available to plugins is
- invisible (PURPLE_PLUGIN_FLAG_INVISIBLE).
- It causes the plugin to NOT appear in the
- list of plugins.
- */
- NULL, /* This is a GList of plugin dependencies. In
- other words, a GList of plugin id's that
- your plugin depends on. Set this value to
- NULL no matter what. If your plugin has
- dependencies, set them at run-time in the
- plugin_init function.
- */
- PURPLE_PRIORITY_DEFAULT,/* This is the priority libpurple with give your
- plugin. There are three possible values
- for this field, PURPLE_PRIORITY_DEFAULT,
- PURPLE_PRIORITY_HIGHEST, and
- PURPLE_PRIORITY_LOWEST
- */
+ @c plugin_unload is called when the plugin is unloaded, and we can use it to
+ wrap up everything, and free our variables.
- "core-hello_world", /* This is your plugin's id. There is a whole
- page dedicated to this in the Related Pages
- section of the API docs.
- */
- "Hello World!", /* This is your plugin's name. This is what
- will be displayed for your plugin in the UI.
- */
- 1.1, /* This is the version of your plugin. */
-
- "Hello World Plugin", /* This is the summary of your plugin. It
- should be a short little blurb. The UI
- determines where, if at all, to display
- this.
- */
- "Hello World Plugin", /* This is the description of your plugin. It
- can be as long and as descriptive as you
- like. And like the summary, it's up to the
- UI where, if at all, to display this (and
- how much to display).
- */
- NULL, /* This is where you can put your name and
- email address.
- */
- "http://helloworld.tld",/* This is the website for the plugin. This
- tells users where to find new versions,
- report bugs, etc.
- */
-
- plugin_load, /* This is a pointer to a function for
- libpurple to call when it is loading the
- plugin. It should be of the type:
-
- gboolean plugin_load(PurplePlugin *plugin)
-
- Returning FALSE will stop the loading of the
- plugin. Anything else would evaluate as
- TRUE and the plugin will continue to load.
- */
- NULL, /* Same as above except it is called when
- libpurple tries to unload your plugin. It
- should be of the type:
-
- gboolean plugin_unload(PurplePlugin *plugin)
-
- Returning TRUE will tell libpurple to
- continue unloading while FALSE will stop
- the unloading of your plugin.
- */
- NULL, /* Similar to the two above members, except
- this is called when libpurple tries to
- destory the plugin. This is generally only
- called when for some reason or another the
- plugin fails to probe correctly. It should
- be of the type:
-
- void plugin_destroy(PurplePlugin *plugin)
- */
-
- NULL, /* This is a pointer to a UI-specific struct.
- For a Pidgin plugin it will be a pointer to a
- PidginPluginUiInfo struct, for example.
- */
- NULL, /* This is a pointer to either a
- PurplePluginLoaderInfo struct or a
- PurplePluginProtocolInfo struct, and is
- beyond the scope of this document.
- */
- NULL, /* This is a pointer to a PurplePluginUiInfo
- struct. It is a core/ui split way for
- core plugins to have a UI configuration
- frame. You can find an example of this
- code in:
- libpurple/plugins/pluginpref_example.c
- */
- NULL, /* This is a function pointer where you can define
- "plugin actions". The UI controls how
- they're displayed. It should be of the
- type:
-
- GList *function_name(PurplePlugin *plugin,
- gpointer context)
-
- It must return a GList of
- PurplePluginActions.
- */
- NULL, /* This is a pointer reserved for future use.
- We set it to NULL to indicate we don't
- need it.
- */
- NULL, /* This is a pointer reserved for future use.
- We set it to NULL to indicate we don't
- need it.
- */
- NULL, /* This is a pointer reserved for future use.
- We set it to NULL to indicate we don't
- need it.
- */
- NULL /* This is a pointer reserved for future use.
- We set it to NULL to indicate we don't
- need it.
- */
-};
- @endcode
-
- Finally we have @c init_plugin and @c PURPLE_INIT_PLUGIN. @c init_plugin is
- a function that gets called when libpurple probes the plugin. Most plugins
- will add their preferences to the pref tree here--more about that later.
- @c PURPLE_INIT_PLUGIN is a macro that EVERY plugin MUST have.
- @c PURPLE_INIT_PLUGIN tells libpurple some very basic things about your
- plugin, like what name to use if the plugin is compiled staticly, the
- @c init_plugin function, and the name of the PurplePluginInfo structure. As
- you may have guessed, this also gets read when libpurple is probing your
- plugin. If this is missing, the plugin will not load.
+ Finally we have @c PURPLE_PLUGIN_INIT(). @c PURPLE_PLUGIN_INIT is a macro
+ that every plugin MUST have. @c PURPLE_PLUGIN_INIT tells libpurple some
+ basic things about your plugin, like what name to use if the plugin is
+ compiled statically, and the @c plugin_query, @c plugin_load, and
+ @c plugin_unload functions.
*/
// vim: syntax=c.doxygen
More information about the Commits
mailing list