Mercurial > pidgin3 / file revision

<?xml version='1.0' encoding="ISO-8859-1"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<chapter id="chapter-tut-c-plugins">
  <title>C Plugins tutorial</title>

  <programlisting>
 @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 &lt;purple.h&gt;

static PurplePluginInfo *
plugin_query(GError **error)
{
	const gchar * const authors[] = {
		"Author Name &lt;e@mail&gt;",
		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.

  </programlisting>
</chapter>