view doc/plugin-ids.dox @ 32533:e091c8ea292e

Pluck all MSNP18 changes. This is pretty much to fix sending OIMs. *** Plucked rev b8b574c4d6f6c05105b372191ca5259b4ae0ad41 ([e-mail]): Add a function for parsing a network:username for MSNP18. *** Plucked rev 86bb401efa33f02ca5d28fea216a39a3cf29b5b4 ([e-mail]): Fix UBX on MSNP18. *** Plucked rev ba2513694e6abcbdfddc66820f1df20540a36847 ([e-mail]): Fix NLN on MSNP18. *** Plucked rev 83a617670da618f4dbdeeebbdb5e2813a4ad2c0c ([e-mail]): Switch to ABFindContactsPaged instead of ABFindAll. *** Plucked rev b6bd214d29db885c6d28628c163fa144bdf4a76d ([e-mail]): Send circle authentication on the notification server on MSNP18. *** Plucked rev 2ca50146aa67469313579cea414e4a2b660939aa ([e-mail]): Make a small name change. *** Plucked rev 2c13bf358104060d6713317e18e03b434862cb38 ([e-mail]): Add a missing function. *** Plucked rev a8deb3f73726f4148e8f36f317a88fedcb051c34 ([e-mail]): Update UUM to allow sending to users on any network. *** Plucked rev dddff988e830a7a2fa0e40aad200f0e908b9231e ([e-mail]): Switch to MSNP18. *** Plucked rev 9fe45819000c530c509c07b7feb29ce9d4ea13b0 ([e-mail]): Send offline messages using UUM. *** Plucked rev c1584182b85f99fa3507ea3f76b07865ee7e43f7 ([e-mail]): Drop support for protocols below 18. *** Plucked rev f0388e54998489dbe4b6133796f77459f20fe884 ([e-mail]): Fix indices for client capabilities and display pics.

/** @page plugin-ids Plugin IDs

 @section Introduction
  Every plugin contains a unique identifier to prevent duplicate plugin
  loading and conflicts. 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.

 @section Format
  The basic format of a plugin ID is as follows:

  <tt><i>type</i>-<i>username</i>-<i>pluginname</i></tt>

  The @em type indicator specifies the type of plugin. This must be one
  of the following:

    - core      - A core libpurple plugin, capable of being loaded in any
                  program using libpurple. Core plugins may not contain any
                  UI-specific code.
    - prpl      - A protocol plugin. This is a special type of core plugin,
                  which provides libpurple the ability to connect to
                  another IM or chat network.
    - lopl      - A loader plugin, which loads scripts as plugins. Perl and
                  Tcl plugins are made possible by loader plugins.
    - gtk       - A GTK+ 2.x (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.
    - gtk-x11   - A GTK+ 2.x plugin that uses X11 code. These plugins may
                  use both GTK+ code and X11 code, allowing to hook into
                  features specific to X11.
    - gtk-win32 - 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.
    - gnt       - A GNT (a.k.a. Finch) plugin. These plugins may use GNT code.
    - qpe       - A plugin for the (now-abandoned) Qutopia user interface.

  The @em username must be a unique identifier for you. It
  @em should be your http://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 http://developer.pidgin.im Trac user ID is preferred.
  Do @em not leave this field blank!

  The @em pluginname is the name of your plugin. It is usually all
  lowercase letters and matches the static plugin ID (the first argument to
  the PURPLE_INIT_PLUGIN() macro call), although it can be anything you
  like. Do @em not include version information in the plugin ID--the
  #PurplePluginInfo structure already has a field for this.

 @section nospaces One Last Rule for Plugin IDs

  The last rule of plugin IDs is the most important of all. Plugin IDs may
  @em NOT contain spaces. If you need a space, use another hyphen (-).

 @section exceptions Exceptions to the Rule

  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 <a
  href="http://plugins.guifications.org/trac/wiki/PluginPack">Purple Plugin
  Pack</a>. All plugins whose lives started in the Purple Plugin Pack use
  <tt>"plugin_pack"</tt> 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.

 @section examples Examples of Well-Chosen Plugin IDs

  The following is a list of well-chosen Plugin IDs listing a few good examples.

    - <tt>"gtk-amc_grim-guifications"</tt> - This is the plugin ID for the
                                             Guifications 2.x plugin.
    - <tt>"gtk-rlaager-album"</tt> - 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.
    - <tt>"core-rlaager-irchelper"</tt> - 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.

 @section plugin-db Plugin Database
  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. 

 */

// vim: syntax=c.doxygen tw=75 et