doc/reference/libpurple/tut_c_plugins.xml

   1 <?xml version='1.0' encoding="ISO-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 ]>
   5 <chapter id="chapter-tut-c-plugins">
   6   <title>C Plugins tutorial</title>
   7
   8   <sect2 id="tut-c-plugins-introduction">
   9   <title>Introduction</title>
  10   <para>
  11   C plugins are native plugins.  They have complete access to all of the API,
  12   and can do basically whatever they want.  All of the protocol plugins are
  13   also written in C.
  14   </para>
  15   </sect2>
  16
  17   <sect2 id="tut-c-plugins-getting-started">
  18   <title>Getting Started</title>
  19   <para>
  20   To develop a plugin you need to have the libpurple and (for UI plugins) the
  21   Pidgin/Finch source code or development headers.  It is generally a good idea
  22   to compile against the same version of Pidgin that you are running.  You may
  23   also want to develop against the code in our Mercurial repository if you need
  24   to use a new feature.  Please do not abuse our Mercurial repository, however.
  25   </para>
  26   </sect2>
  27
  28   <sect2 id="tut-c-plugins-hello-world">
  29   <title>An Example</title>
  30   <para>
  31   I know every tutorial has a hello world, so why should libpurple be any
  32   different?
  33
  34 <example>
  35 <title>Hello World!</title>
  36 <programlisting>
  37 #include &lt;purple.h&gt;
  38
  39 static PurplePluginInfo *
  40 plugin_query(GError **error)
  41 {
  42         const gchar * const authors[] = {
  43                 "Author Name &lt;e@mail&gt;",
  44                 NULL
  45         };
  46
  47         /* For specific notes on the meanings of each of these members, consult the
  48            C Plugin Howto on the website. */
  49         return purple_plugin_info_new (
  50                 "name",         "Hello World!",
  51                 "version",      VERSION,
  52                 "category",     "Example",
  53                 "summary",      "Hello World Plugin",
  54                 "description",  "Hello World Plugin",
  55                 "authors",      authors,
  56                 "website",      "http://helloworld.tld",
  57                 "abi-version",  PURPLE_ABI_VERSION,
  58                 NULL
  59         );
  60 }
  61
  62 static gboolean
  63 plugin_load(PurplePlugin *plugin, GError **error)
  64 {
  65         purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!",
  66                                                 "This is the Hello World! plugin :)",
  67                                                 NULL, NULL, NULL, NULL);
  68
  69         return TRUE;
  70 }
  71
  72 static gboolean
  73 plugin_unload(PurplePlugin *plugin, GError **error)
  74 {
  75         return TRUE;
  76 }
  77
  78 PURPLE_PLUGIN_INIT(hello_world, plugin_query, plugin_load, plugin_unload);
  79 </programlisting>
  80 </example>
  81   </para>
  82
  83   <para>
  84   Okay, so what does all this mean?  We start off by including purple.h.  This
  85   file includes all the libpurple header files.
  86   </para>
  87
  88   <para>
  89   <literal>plugin_query</literal>, <literal>plugin_load</literal> and
  90   <literal>plugin_unload</literal> must be implemented in every plugin.  Each of
  91   these functions can return an error on failure by using
  92   <function>g_set_error()</function> on the <literal>error</literal> argument.
  93   </para>
  94
  95   <para>
  96   <literal>plugin_query</literal> is called when the plugin is probed by the
  97   plugin system, and returns various information about the plugin in form of a
  98   newly created <literal>PurplePluginInfo</literal> instance.  For a list of all
  99   available properties, see
 100   <link linkend="purple-plugin-info-new"><function>purple_plugin_info_new()</function></link>.
 101   </para>
 102
 103   <para>
 104   <literal>plugin_load</literal> is called when the plugin is loaded so that you
 105   can initialize any variables, register dynamic types, and so on.  Plugins may
 106   also want to add their preferences to the pref tree--more about that later.
 107   In this plugin we'll just use it to display a message.
 108   </para>
 109
 110   <para>
 111   <literal>plugin_unload</literal> is called when the plugin is unloaded, and we
 112   can use it to wrap up everything, and free our variables.
 113   </para>
 114
 115   <para>
 116   Finally we have
 117   <link linkend="PURPLE-PLUGIN-INIT:CAPS"><function>PURPLE_PLUGIN_INIT()</function></link>.
 118   It is a macro that every plugin MUST have. It tells libpurple some basic
 119   things about your plugin, like what name to use if the plugin is compiled
 120   statically, along with the <literal>plugin_query</literal>,
 121   <literal>plugin_load</literal>, and <literal>plugin_unload</literal>
 122   functions.
 123   </para>
 124  </sect2>
 125 </chapter>