diff options
Diffstat (limited to 'doc/en/dev/plugins.en.xml')
| -rw-r--r-- | doc/en/dev/plugins.en.xml | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/doc/en/dev/plugins.en.xml b/doc/en/dev/plugins.en.xml new file mode 100644 index 000000000..fd2e2f7db --- /dev/null +++ b/doc/en/dev/plugins.en.xml @@ -0,0 +1,250 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<!-- + +WeeChat documentation (english version) + +Copyright (c) 2003-2008 by FlashCode <flashcode@flashtux.org> + +This manual is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 3 of the License, or +(at your option) any later version. + +This manual is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see <http://www.gnu.org/licenses/>. + +--> + +<chapter id="chapPlugins"> + <title>Plugins</title> + + <para> + This chapter describes WeeChat plugin API and default plugins provided with + WeeChat. + </para> + + <section id="secPluginsInWeeChat"> + <title>Plugins in WeeChat</title> + + <para> + A plugin is a C program which can call WeeChat functions defined in + an interface. + </para> + + <para> + This C program does not need WeeChat sources to compile and can be + dynamically loaded into WeeChat with command + <command>/plugin</command>. + </para> + + <para> + The plugin has to be a dynamic library, for dynamic loading by + operating system. + Under GNU/Linux, the file has ".so" extension, ".dll" under + Windows. + </para> + + </section> + + <section id="secWriteAPlugin"> + <title>Write a plugin</title> + + <para> + The plugin has to include "weechat-plugin.h" file (available in + WeeChat source code). + This file defines structures and types used to communicate with + WeeChat. + </para> + + <para> + The plugin must use some mandatory macros (to define some variables) + and some functions (without them the plugin can't load): + + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Macro</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>WEECHAT_PLUGIN_NAME</literal></entry> + <entry>plugin name</entry> + </row> + <row> + <entry><literal>WEECHAT_PLUGIN_DESCRIPTION</literal></entry> + <entry>short description of plugin</entry> + </row> + <row> + <entry><literal>WEECHAT_PLUGIN_VERSION</literal></entry> + <entry>plugin version</entry> + </row> + <row> + <entry><literal>WEECHAT_PLUGIN_WEECHAT_VERSION</literal></entry> + <entry> + target WeeChat version where plugin will run (warning: plugin + will not run on any other WeeChat version!) + </entry> + </row> + <row> + <entry><literal>WEECHAT_PLUGIN_LICENSE</literal></entry> + <entry>plugin license</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Function</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>int weechat_plugin_init (struct t_weechat_plugin *plugin, int argc, char *argv[])</literal></entry> + <entry> + function called when plugin is loaded, must return + WEECHAT_RC_OK if successful, WEECHAT_RC_ERROR if error + (if error, plugin will NOT be loaded), argc/argv are arguments + for plugin (given on command line by user) + </entry> + </row> + <row> + <entry><literal>int weechat_plugin_end (struct t_weechat_plugin *plugin)</literal></entry> + <entry>function called when plugin is unloaded</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + + &plugin_api.en.xml; + + <section id="secCompilePlugin"> + <title>Compile plugin</title> + + <para> + Compile does not need WeeChat sources, only file + "<literal>weechat-plugin.h</literal>". + </para> + + <para> + To compile a plugin which has one file "toto.c" (under GNU/Linux): +<screen> +<prompt>$ </prompt><userinput>gcc -fPIC -Wall -c toto.c</userinput> +<prompt>$ </prompt><userinput>gcc -shared -fPIC -o libtoto.so toto.o</userinput> +</screen> + </para> + + </section> + + <section id="secLoadPlugin"> + <title>Load plugin into WeeChat</title> + + <para> + Copy "libtoto.so" file into system plugins directory (for example + "<literal>/usr/local/lib/weechat/plugins</literal>") or into + user's plugins directory (for example + "<literal>/home/xxxxx/.weechat/plugins</literal>"). + </para> + + <para> + Under WeeChat: + <screen><userinput>/plugin load toto</userinput></screen> + </para> + + </section> + + <section id="secPluginExample"> + <title>Plugin example</title> + + <para> + Full example of plugin, which adds a /double command, which displays + two times arguments on current buffer, or execute two times a command + (ok that's not very useful, but that's just an example!): +<screen> +#include <stdlib.h> + +#include "weechat-plugin.h" + +WEECHAT_PLUGIN_NAME("double"); +WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat"); +WEECHAT_PLUGIN_AUTHOR("FlashCode <flashcode@flashtux.org>"); +WEECHAT_PLUGIN_VERSION("0.1"); +WEECHAT_PLUGIN_WEECHAT_VERSION("0.2.7"); +WEECHAT_PLUGIN_LICENSE("GPL3"); + +struct t_weechat_plugin *weechat_plugin = NULL; + + +/* "/double" command manager */ + +int +double_cmd (void *data, struct t_gui_buffer *buffer, int argc, + char **argv, char **argv_eol) +{ + /* make C compiler happy */ + (void) argv; + + if (argc > 1) + { + weechat_command (NULL, argv_eol[1]); + weechat_command (NULL, argv_eol[1]); + } + + return WEECHAT_RC_OK; +} + +int +weechat_plugin_init (struct t_weechat_plugin *plugin, + int argc, char *argv[]) +{ + weechat_plugin = plugin; + + weechat_hook_command ("double", + "Display two times a message", + "msg", + "msg: message to display two times", + NULL, + &double_cmd, NULL); + + return WEECHAT_RC_OK; +} + +int +weechat_plugin_end (struct t_weechat_plugin *plugin) +{ + /* nothing done here */ + (void) plugin; + + return WEECHAT_RC_OK; +} +</screen> + </para> + + </section> + + </section> + + &plugin_irc.en.xml; + + <!-- &plugin_charset.en.xml; --> + + &plugin_fifo.en.xml; + + <!-- &plugin_scripts.en.xml; --> + + &plugin_xfer.en.xml; + +</chapter> |