--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reference/libpurple/C-HOWTO.dox Sun Oct 13 15:41:22 2013 +0530
@@ -0,0 +1,97 @@
+/** @page c-howto C Plugin HOWTO
+
+ @section Introduction
+ C plugins are native plugins. They have complete access to all of the API,
+ and can do basically whatever they want. All of the protocol plugins, as
+ well as the Mono, Perl, and Tcl loader plugins are written in C.
+
+ @section getting_started Getting Started
+ To develop a plugin you need to have the libpurple and (for UI plugins) the
+ Pidgin/Finch source code or development headers. It is generally a good idea
+ to compile against the same version of Pidgin that you are running. You may
+ also want to develop against the code in our Mercurial repository if you need
+ to use a new feature. Please do not abuse our Mercurial repository, however.
+
+ All plugins must have @c PURPLE_PLUGINS defined and the definition must be
+ before including any libpurple, Pidgin, or Finch header files. Failure to do
+ so can lead to strange errors that are hard to diagnose. Including purple.h
+ will define this for you.
+
+ @section hello_world Hello World!
+ I know every tutorial has a hello world, so why should libpurple be any
+ different?
+
+ @code
+#include <purple.h>
+
+static PurplePluginInfo *
+plugin_query(GError **error)
+{
+ const gchar * const authors[] = {
+ "Author Name <e@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, GError **error)
+{
+ purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!",
+ "This is the Hello World! plugin :)",
+ NULL, NULL, NULL, NULL);
+
+ return TRUE;
+}
+
+static gboolean
+plugin_unload(PurplePlugin *plugin, GError **error)
+{
+ return TRUE;
+}
+
+PURPLE_PLUGIN_INIT(hello_world, plugin_query, plugin_load, plugin_unload);
+
+ @endcode
+
+ Okay, so what does all this mean? We start off by including purple.h. This
+ file defines @c PURPLE_PLUGINS as described before so that we don't have to
+ manually define it. It also includes all the libpurple header files.
+
+ @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_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 .
+
+ @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.
+
+ @c plugin_unload is called when the plugin is unloaded, and we can use it to
+ wrap up everything, and free our variables.
+
+ 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