doc/C-HOWTO.dox

   1 /** @page c-howto C Plugin HOWTO
   2
   3  @section Introduction
   4   C plugins are native plugins.  They have complete access to all of the API,
   5   and can do basically whatever they want.  All of the protocol plugins, as
   6   well as the Mono, Perl, and Tcl loader plugins are written in C.
   7
   8  @section getting_started Getting Started
   9   To develop a plugin you need to have the libpurple and (for UI plugins) the
  10   Pidgin/Finch source code or development headers.  It is generally a good idea
  11   to compile against the same version of Pidgin that you are running.  You may
  12   also want to develop against the code in our Monotone repository if you need
  13   to use a new feature.  Please do not abuse our Monotone repository, however.
  14
  15   All plugins must have @c PURPLE_PLUGINS defined and the definition must be
  16   before including any libpurple, Pidgin, or Finch header files.  Failure to do
  17   so can lead to strange errors that are hard to diagnose.  Just don't forget!
  18
  19  @section hello_world Hello World!
  20   I know every tutorial has a hello world, so why should libpurple be any
  21   different?
  22
  23   @code
  24 #define PURPLE_PLUGINS
  25
  26 #include <glib.h>
  27
  28 #include "notify.h"
  29 #include "plugin.h"
  30 #include "version.h"
  31
  32 static gboolean
  33 plugin_load(PurplePlugin *plugin) {
  34         purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!",
  35                                                 "This is the Hello World! plugin :)", NULL, NULL, NULL);
  36
  37         return TRUE;
  38 }
  39
  40 static PurplePluginInfo info = {
  41         PURPLE_PLUGIN_MAGIC,
  42         PURPLE_MAJOR_VERSION,
  43         PURPLE_MINOR_VERSION,
  44         PURPLE_PLUGIN_STANDARD,
  45         NULL,
  46         0,
  47         NULL,
  48         PURPLE_PRIORITY_DEFAULT,
  49
  50         "core-hello_world",
  51         "Hello World!",
  52         VERSION,
  53
  54         "Hello World Plugin",
  55         "Hello World Plugin",
  56         NULL,
  57         "http://helloworld.tld",
  58
  59         plugin_load,
  60         NULL,
  61         NULL,
  62
  63         NULL,
  64         NULL,
  65         NULL,
  66         NULL,
  67         NULL,
  68         NULL,
  69         NULL,
  70         NULL
  71 };
  72
  73 static void
  74 init_plugin(PurplePlugin *plugin)
  75 {
  76 }
  77
  78 PURPLE_INIT_PLUGIN(hello_world, init_plugin, info);
  79
  80   @endcode
  81
  82   Okay, so what does all this mean?  We start off by defining @c PURPLE_PLUGINS
  83   like described before.  Next we include glib.h, mainly for gboolean and the
  84   glib wrappers of the standard C types.
  85
  86   Next, we include plugin.h which has all the plugin specific stuff that we
  87   need.  For example: @c PurplePlugin, @c PurplePluginInfo,
  88   @c PURPLE_PLUGIN_MAGIC, and @c PURPLE_INIT_PLUGIN().
  89
  90   Our last include is version.h which defines @c PURPLE_MAJOR_VERSION, and
  91   @c PURPLE_MINOR_VERSION.  There is not much you need to know about these,
  92   except that they are required and will stop your plugin from crashing Pidgin
  93   when something has changed that your plugin does not know about yet.
  94
  95   @c plugin_load is not required.  It is called when the plugin is loaded so
  96   that you can initialize any variables and so on.  In this plugin we'll just
  97   use it to display a message.
  98
  99   Next we have the @c PurplePluginInfo structure.  Every plugin MUST have one of
 100   these.  Below is a code snipet of the same struct used in @c hello_world with
 101   comments describing what each is.
 102
 103   @code
 104 static PurplePluginInfo info = {
 105         PURPLE_PLUGIN_MAGIC,    /* Plugin magic, this must always be
 106                                    PURPLE_PLUGIN_MAGIC.
 107                                  */
 108         PURPLE_MAJOR_VERSION,   /* This is also defined in libpurple.  It helps
 109                                    libpurple's plugin system determine which
 110                                    version of libpurple this plugin was
 111                                    compiled for, and whether loading it will
 112                                    cause problems.
 113                                  */
 114         PURPLE_MINOR_VERSION,   /* See previous */
 115         PURPLE_PLUGIN_STANDARD, /* PurplePluginType: There are 4 different
 116                                    values for this field.  The first is
 117                                    PURPLE_PLUGIN_UNKNOWN, which should not be
 118                                    used.  The second is PURPLE_PLUGIN_STANDARD;
 119                                    this is the value most plugins will use.
 120                                    Next, we have PURPLE_PLUGIN_LOADER; this is
 121                                    the type you want to load if your plugin
 122                                    is going to make it possible to load non-
 123                                    native plugins.  For example, the Perl and
 124                                    Tcl loader plugins are of this type.
 125                                    Last, we have PURPLE_PLUGIN_PROTOCOL.  If
 126                                    your plugin is going to allow the user to
 127                                    connect to another network, this is the
 128                                    type you'd want to use.
 129                                  */
 130         NULL,                   /* This field is the UI requirement.  If you're
 131                                    writing a core plugin, this must be NULL
 132                                    and the plugin must not contain any UI
 133                                    code.  If you're writing a Pidgin plugin,
 134                                    you need to use PIDGIN_PLUGIN_TYPE.  If you
 135                                    are writing a Finch plugin, you would use
 136                                    FINCH_PLUGIN_TYPE.
 137                                  */
 138         0,                      /* This field is for plugin flags.  Currently,
 139                                    the only flag available to plugins is
 140                                    invisible (PURPLE_PLUGIN_FLAG_INVISIBLE).
 141                                    It causes the plugin to NOT appear in the
 142                                    list of plugins.
 143                                  */
 144         NULL,                   /* This is a GList of plugin dependencies.  In
 145                                    other words, a GList of plugin id's that
 146                                    your plugin depends on.  Set this value to
 147                                    NULL no matter what.  If your plugin has
 148                                    dependencies, set them at run-time in the
 149                                    plugin_init function.
 150                                  */
 151         PURPLE_PRIORITY_DEFAULT,/* This is the priority libpurple with give your
 152                                    plugin.  There are three possible values
 153                                    for this field, PURPLE_PRIORITY_DEFAULT,
 154                                    PURPLE_PRIORITY_HIGHEST, and
 155                                    PURPLE_PRIORITY_LOWEST
 156                                  */
 157
 158         "core-hello_world",     /* This is your plugin's id.  There is a whole
 159                                    page dedicated to this in the Related Pages
 160                                    section of the API docs.
 161                                  */
 162         "Hello World!",         /* This is your plugin's name.  This is what
 163                                    will be displayed for your plugin in the UI.
 164                                  */
 165         1.1,                    /* This is the version of your plugin. */
 166
 167         "Hello World Plugin",   /* This is the summary of your plugin.  It
 168                                    should be a short little blurb.  The UI
 169                                    determines where, if at all, to display
 170                                    this.
 171                                  */
 172         "Hello World Plugin",   /* This is the description of your plugin. It
 173                                    can be as long and as descriptive as you
 174                                    like.  And like the summary, it's up to the
 175                                    UI where, if at all, to display this (and
 176                                    how much to display).
 177                                  */
 178         NULL,                   /* This is where you can put your name and
 179                                    email address.
 180                                  */
 181         "http://helloworld.tld",/* This is the website for the plugin.  This
 182                                    tells users where to find new versions,
 183                                    report bugs, etc.
 184                                  */
 185
 186         plugin_load,            /* This is a pointer to a function for
 187                                    libpurple to call when it is loading the
 188                                    plugin.  It should be of the type:
 189
 190                                    gboolean plugin_load(PurplePlugin *plugin)
 191
 192                                    Returning FALSE will stop the loading of the
 193                                    plugin.  Anything else would evaluate as
 194                                    TRUE and the plugin will continue to load.
 195                                  */
 196         NULL,                   /* Same as above except it is called when
 197                                    libpurple tries to unload your plugin.  It
 198                                    should be of the type:
 199
 200                                    gboolean plugin_unload(PurplePlugin *plugin)
 201
 202                                    Returning TRUE will tell libpurple to
 203                                    continue unloading while FALSE will stop
 204                                    the unloading of your plugin.
 205                                  */
 206         NULL,                   /* Similar to the two above members, except
 207                                    this is called when libpurple tries to
 208                                    destory the plugin.  This is generally only
 209                                    called when for some reason or another the
 210                                    plugin fails to probe correctly.  It should
 211                                    be of the type:
 212
 213                                    void plugin_destroy(PurplePlugin *plugin)
 214                                  */
 215
 216         NULL,                   /* This is a pointer to a UI-specific struct.
 217                                    For a Pidgin plugin it will be a pointer to a
 218                                    PidginPluginUiInfo struct, for example.
 219                                  */
 220         NULL,                   /* This is a pointer to either a
 221                                    PurplePluginLoaderInfo struct or a
 222                                    PurplePluginProtocolInfo struct, and is
 223                                    beyond the scope of this document.
 224                                  */
 225         NULL,                   /* This is a pointer to a PurplePluginUiInfo
 226                                    struct.  It is a core/ui split way for
 227                                    core plugins to have a UI configuration
 228                                    frame.  You can find an example of this
 229                                    code in:
 230                                      libpurple/plugins/pluginpref_example.c
 231                                  */
 232         NULL,                   /* This is a function pointer where you can define
 233                                    "plugin actions".  The UI controls how
 234                                    they're displayed.  It should be of the
 235                                    type:
 236
 237                                    GList *function_name(PurplePlugin *plugin,
 238                                                         gpointer context)
 239
 240                                     It must return a GList of
 241                                     PurplePluginActions.
 242                                  */
 243         NULL,                   /* This is a pointer reserved for future use.
 244                                        We set it to NULL to indicate we don't
 245                                                                    need it.
 246                                                                  */
 247         NULL,                   /* This is a pointer reserved for future use.
 248                                        We set it to NULL to indicate we don't
 249                                                                    need it.
 250                                                                  */
 251         NULL,                   /* This is a pointer reserved for future use.
 252                                        We set it to NULL to indicate we don't
 253                                                                    need it.
 254                                                                  */
 255         NULL                    /* This is a pointer reserved for future use.
 256                                        We set it to NULL to indicate we don't
 257                                                                    need it.
 258                                                                  */
 259 };
 260   @endcode
 261
 262   Finally we have @c init_plugin and @c PURPLE_INIT_PLUGIN.  @c init_plugin is
 263   a function that gets called when libpurple probes the plugin.  Most plugins
 264   will add their preferences to the pref tree here--more about that later.
 265   @c PURPLE_INIT_PLUGIN is a macro that EVERY plugin MUST have.
 266   @c PURPLE_INIT_PLUGIN tells libpurple some very basic things about your
 267   plugin, like what name to use if the plugin is compiled staticly, the
 268   @c init_plugin function, and the name of the PurplePluginInfo structure.  As
 269   you may have guessed, this also gets read when libpurple is probing your
 270   plugin.  If this is missing, the plugin will not load.
 271  */
 272 // vim: syntax=c.doxygen