doc/reference/libpurple/plugin_ids.xml

<?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-plugin-ids">
  <title>Plugin IDs</title>

  <sect2 id="plugin-ids-introduction">
  <title>Introduction</title>
  <para>
Every plugin contains a unique identifier. Third-party plugins (that is,
plugins written by anyone who is not a libpurple, Pidgin, or Finch developer)
are expected to use a plugin ID that follows a specific format. This format
categorizes plugins and makes duplicate IDs highly unlikely.
  </para>
  </sect2>

  <sect2 id="plugin-ids-format">
  <title>Format</title>
  <para>
The basic format of a plugin ID is as follows:

<programlisting>
type-username-pluginname
</programlisting>
  </para>

  <para>
The <emphasis>type</emphasis> indicator specifies the type of plugin. This must be one
of the following:

  <table>
  <title>Types of plugins</title>
  <tgroup cols="2">
    <colspec colwidth="*" colnum="1" align="left"/>
    <colspec colwidth="*" colnum="2" align="left"/>
    <thead>
       <row>
<entry><emphasis>type</emphasis></entry>
<entry>description</entry>
      </row>
    </thead>
    <tbody>
      <row>
<entry><literal>core</literal></entry>
<entry>
A core libpurple plugin, capable of being loaded in any program using libpurple.
Core plugins may not contain any UI-specific code.
</entry>
      </row>
      <row>
<entry><literal>prpl</literal></entry>
<entry>
A protocol plugin. This is a core plugin which provides libpurple the ability to
connect to another IM or chat network.
</entry>
      </row>
      <row>
<entry><literal>gtk</literal></entry>
<entry>
A GTK+ (a.k.a. Pidgin) plugin. These plugins may use GTK+ code, but may not use
window toolkit code, such as X11, Win32, Cocoa, or Carbon.
</entry>
      </row>
      <row>
<entry><literal>gtk-x11</literal></entry>
<entry>
A GTK+ plugin that uses X11 code. These plugins may use both GTK+ code and X11
code, allowing to hook into features specific to X11.
</entry>
      </row>
      <row>
<entry><literal>gtk-win32</literal></entry>
<entry>
A GTK+ plugin that uses Win32 code. These plugins may use both GTK+ code and
Win32 code, allowing to hook into features available on Windows.
</entry>
      </row>
      <row>
<entry><literal>gnt</literal></entry>
<entry>
A GNT (a.k.a. Finch) plugin. These plugins may use GNT code.
</entry>
      </row>
    </tbody>
  </tgroup>
  </table>
  </para>

  <para>
The <emphasis>username</emphasis> must be a unique identifier for you. It
<emphasis>should</emphasis> be your https://developer.pidgin.im Trac user ID. Failing that, you
could use your SourceForge user ID or your Freenode IRC nickname, if you
have either. The https://developer.pidgin.im Trac user ID is preferred.
Do <emphasis>not</emphasis> leave this field blank!
  </para>

  <para>
The <emphasis>pluginname</emphasis> is the name of your plugin. It is usually all
lowercase letters and matches the static plugin ID (the first argument to
the PURPLE_PLUGIN_INIT() macro call), although it can be anything you
like. Do <emphasis>not</emphasis> include version information in the plugin ID--the
<literal>PurplePluginInfo</literal> object already has a property for this.
  </para>
  </sect2>

  <sect2 id="plugin-ids-nospaces">
  <title>One Last Rule for Plugin IDs</title>
  <para>
Plugin IDs may <emphasis>NOT</emphasis> contain spaces. If you need a space, use another
hyphen (-).
  </para>
  </sect2>

  <sect2 id="plugin-ids-exceptions">
  <title>Exceptions to the Rule</title>
  <para>
As with any rule there are exceptions. If you browse through the source
tree you will see that the plugins we distribute with the Pidgin source
do not contain a username field. This is because while one developer may
have written each specific plugin, the plugins are maintained
collectively by the entire development team. This lack of a username
field is also an indicator that the plugin is one of our plugins and not
a third-party plugin.

Another exception to the rule is the <ulink
url="http://plugins.guifications.org/trac/wiki/PluginPack">Purple Plugin
Pack</ulink>. All plugins whose lives started in the Purple Plugin Pack use
<literal>"plugin_pack"</literal> for the username field to indicate origination in
the Purple Plugin Pack.

These two exceptions are mentioned here for completeness. We don't
encourage breaking the conventions set forth by the rules outlined above.
  </para>
  </sect2>

  <sect2 id="plugin-ids-examples">
  <title>Examples of Well-Chosen Plugin IDs</title>
  <para>
The following is a list of well-chosen Plugin IDs listing a few good examples.

  <table>
  <title>Examples</title>
  <tgroup cols="2">
    <colspec colwidth="*" colnum="1" align="left"/>
    <colspec colwidth="*" colnum="2" align="left"/>
    <thead>
       <row>
<entry>id</entry>
<entry>description</entry>
      </row>
    </thead>
    <tbody>
      <row>
<entry><literal>"gtk-amc_grim-guifications"</literal></entry>
<entry>
This is the plugin ID for the Guifications 2.x plugin.
</entry>
      </row>
      <row>
<entry><literal>"gtk-rlaager-album"</literal></entry>
<entry>
This is the plugin ID for the Album plugin, which is now part of the
Purple Plugin Pack. Its ID follows the rules because its life started prior
to its inclusion in the Plugin Pack.
</entry>
      </row>
      <row>
<entry><literal>"core-rlaager-irchelper"</literal></entry>
<entry>
This is the plugin ID for the IRC Helper plugin, which is now part of the
Purple Plugin Pack. Its ID follows the rules because its life started prior
to its inclusion in the Plugin Pack.
</entry>
      </row>
    </tbody>
  </tgroup>
  </table>
  </para>
  </sect2>

  <sect2 id="plugin-ids-plugin-db">
  <title>Plugin Database</title>
  <para>
Although it doesn't exist yet, in time there will be a plugin database
on the Pidgin website, where users can download and install new plugins.
Plugins will be accessed by your plugin ID, which is one reason why it
must be unique. 
  </para>
 </sect2>
</chapter>