comparison: doc/reference/libpurple/plugin-ids.dox
doc/reference/libpurple/plugin-ids.dox
- branch
- soc.2013.gobjectification.plugins
- changeset 36900
- 423fbe5e5289
- parent 36797
- 997a3fb7f1c0
equal
deleted
inserted
replaced
| 36899:b2591070c07b | 36900:423fbe5e5289 |
|---|---|
| 1 /** @page plugin-ids Plugin IDs | |
| 2 | |
| 3 @section Introduction | |
| 4 Every plugin contains a unique identifier. Third-party plugins (that is, | |
| 5 plugins written by anyone who is not a libpurple, Pidgin, or Finch developer) | |
| 6 are expected to use a plugin ID that follows a specific format. This format | |
| 7 categorizes plugins and makes duplicate IDs highly unlikely. | |
| 8 | |
| 9 @section Format | |
| 10 The basic format of a plugin ID is as follows: | |
| 11 | |
| 12 <tt><i>type</i>-<i>username</i>-<i>pluginname</i></tt> | |
| 13 | |
| 14 The @em type indicator specifies the type of plugin. This must be one | |
| 15 of the following: | |
| 16 | |
| 17 - core - A core libpurple plugin, capable of being loaded in any | |
| 18 program using libpurple. Core plugins may not contain any | |
| 19 UI-specific code. | |
| 20 - protocol - A protocol plugin. This is a core plugin which provides | |
| 21 libpurple the ability to connect to another IM or chat | |
| 22 network. | |
| 23 - gtk - A GTK+ (a.k.a. Pidgin) plugin. These plugins may use | |
| 24 GTK+ code, but may not use window toolkit code, such as | |
| 25 X11, Win32, Cocoa, or Carbon. | |
| 26 - gtk-x11 - A GTK+ plugin that uses X11 code. These plugins may | |
| 27 use both GTK+ code and X11 code, allowing to hook into | |
| 28 features specific to X11. | |
| 29 - gtk-win32 - A GTK+ plugin that uses Win32 code. These plugins may use | |
| 30 both GTK+ code and Win32 code, allowing to hook into | |
| 31 features available on Windows. | |
| 32 - gnt - A GNT (a.k.a. Finch) plugin. These plugins may use GNT code. | |
| 33 - qpe - A plugin for the (now-abandoned) Qutopia user interface. | |
| 34 | |
| 35 The @em username must be a unique identifier for you. It | |
| 36 @em should be your https://developer.pidgin.im Trac user ID. Failing that, you | |
| 37 could use your SourceForge user ID or your Freenode IRC nickname, if you | |
| 38 have either. The https://developer.pidgin.im Trac user ID is preferred. | |
| 39 Do @em not leave this field blank! | |
| 40 | |
| 41 The @em pluginname is the name of your plugin. It is usually all | |
| 42 lowercase letters and matches the static plugin ID (the first argument to | |
| 43 the PURPLE_PLUGIN_INIT() macro call), although it can be anything you | |
| 44 like. Do @em not include version information in the plugin ID--the | |
| 45 #PurplePluginInfo object already has a property for this. | |
| 46 | |
| 47 @section nospaces One Last Rule for Plugin IDs | |
| 48 | |
| 49 Plugin IDs may @em NOT contain spaces. If you need a space, use another | |
| 50 hyphen (-). | |
| 51 | |
| 52 @section exceptions Exceptions to the Rule | |
| 53 | |
| 54 As with any rule there are exceptions. If you browse through the source | |
| 55 tree you will see that the plugins we distribute with the Pidgin source | |
| 56 do not contain a username field. This is because while one developer may | |
| 57 have written each specific plugin, the plugins are maintained | |
| 58 collectively by the entire development team. This lack of a username | |
| 59 field is also an indicator that the plugin is one of our plugins and not | |
| 60 a third-party plugin. | |
| 61 | |
| 62 Another exception to the rule is the <a | |
| 63 href="http://plugins.guifications.org/trac/wiki/PluginPack">Purple Plugin | |
| 64 Pack</a>. All plugins whose lives started in the Purple Plugin Pack use | |
| 65 <tt>"plugin_pack"</tt> for the username field to indicate origination in | |
| 66 the Purple Plugin Pack. | |
| 67 | |
| 68 These two exceptions are mentioned here for completeness. We don't | |
| 69 encourage breaking the conventions set forth by the rules outlined above. | |
| 70 | |
| 71 @section examples Examples of Well-Chosen Plugin IDs | |
| 72 | |
| 73 The following is a list of well-chosen Plugin IDs listing a few good examples. | |
| 74 | |
| 75 - <tt>"gtk-amc_grim-guifications"</tt> - This is the plugin ID for the | |
| 76 Guifications 2.x plugin. | |
| 77 - <tt>"gtk-rlaager-album"</tt> - This is the plugin ID for the Album | |
| 78 plugin, which is now part of the | |
| 79 Purple Plugin Pack. Its ID follows the | |
| 80 rules because its life started prior | |
| 81 to its inclusion in the Plugin Pack. | |
| 82 - <tt>"core-rlaager-irchelper"</tt> - This is the plugin ID for the IRC | |
| 83 Helper plugin, which is now part | |
| 84 of the Purple Plugin Pack. Its ID | |
| 85 follows the rules because its | |
| 86 life started prior to its | |
| 87 inclusion in the Plugin Pack. | |
| 88 | |
| 89 @section plugin-db Plugin Database | |
| 90 Although it doesn't exist yet, in time there will be a plugin database | |
| 91 on the Pidgin website, where users can download and install new plugins. | |
| 92 Plugins will be accessed by your plugin ID, which is one reason why it | |
| 93 must be unique. | |
| 94 | |
| 95 */ | |
| 96 | |
| 97 // vim: syntax=c.doxygen tw=75 et |
