summaryrefslogtreecommitdiff
path: root/doc/en/dev
diff options
context:
space:
mode:
authorSebastien Helleu <flashcode@flashtux.org>2008-11-07 18:27:16 +0100
committerSebastien Helleu <flashcode@flashtux.org>2008-11-07 18:27:16 +0100
commit67d8312f461b74b747088b6661a21426ab2a01e6 (patch)
tree2f797a4e048205a1eb03b9ddbf82166e26046940 /doc/en/dev
parentbc5bb29970ee029ee646b8805b83b3a9d71a2ef8 (diff)
downloadweechat-67d8312f461b74b747088b6661a21426ab2a01e6.zip
Update developer guide (add 50% of new C API functions)
Diffstat (limited to 'doc/en/dev')
-rw-r--r--doc/en/dev/plugin_api.en.xml4705
-rw-r--r--doc/en/dev/plugin_c_api.en.xml7300
-rw-r--r--doc/en/dev/plugin_script_api.en.xml (renamed from doc/en/dev/plugin_scripts.en.xml)8
-rw-r--r--doc/en/dev/plugins.en.xml12
-rw-r--r--doc/en/dev/weechat_dev.en.xml15
5 files changed, 7319 insertions, 4721 deletions
diff --git a/doc/en/dev/plugin_api.en.xml b/doc/en/dev/plugin_api.en.xml
index 8d90cb480..3dd037d75 100644
--- a/doc/en/dev/plugin_api.en.xml
+++ b/doc/en/dev/plugin_api.en.xml
@@ -21,4708 +21,11 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
-->
-<section id="secPluginAPI">
+<chapter id="chapPluginAPI">
<title>Plugin API</title>
- <!-- =============================[ strings ]============================ -->
+ &plugin_c_api.en.xml;
- <section id="secAPI_strings">
- <title>Strings</title>
-
- <para>
- Many string functions below are already available thru standard C
- functions, but it's recommended to use functions in this API because
- they are ok with UTF-8 and locale.
- </para>
-
- <section id="secAPI_weechat_charset_set">
- <title>weechat_charset_set</title>
-
- <para>
- Prototype:
- <command>
- void weechat_charset_set (const char *charset)
- </command>
- </para>
- <para>
- Set new plugin charset.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>charset</option>: new charset to use
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Example:
- <screen>weechat_charset_set (plugin, "iso-8859-1");</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_iconv_to_internal">
- <title>weechat_iconv_to_internal</title>
-
- <para>
- Prototype:
- <command>
- void weechat_iconv_to_internal (const char *charset,
- const char *string)
- </command>
- </para>
- <para>
- Convert string to WeeChat internal charset (UTF-8).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>charset</option>: charset to convert
- </para>
- </listitem>
- <listitem>
- <para>
- <option>string</option>: string to convert
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: converted string.
- </para>
- <para>
- Note: result has to be free by a call to "free" after use.
- </para>
- <para>
- Example:
- <screen>char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string: é à");</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_iconv_from_internal">
- <title>weechat_iconv_from_internal</title>
-
- <para>
- Prototype:
- <command>
- void weechat_iconv_from_internal (const char *charset,
- const char *string)
- </command>
- </para>
- <para>
- Convert string from internal WeeChat charset (UTF-8) to another.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>charset</option>: target charset
- </para>
- </listitem>
- <listitem>
- <para>
- <option>string</option>: string to convert
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: converted string.
- </para>
- <para>
- Note: result has to be free by a call to "free" after use.
- </para>
- <para>
- Example:
- <screen>char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_gettext">
- <title>weechat_gettext</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_gettext (const char *string)
- </command>
- </para>
- <para>
- Return translated string (depends on local language).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string to translate
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: translated string.
- </para>
- <para>
- Example:
- <screen>char *str = weechat_gettext ("hello !");</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_ngettext">
- <title>weechat_ngettext</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_ngettext (const char *string, const char *plural,
- int count)
- </command>
- </para>
- <para>
- Return translated string, using single or plural form, according to
- count.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>single</option>: string to translate (single form)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>plural</option>: string to translate (plural form)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>count</option>: used to choose between single and plural
- form
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: translated string.
- </para>
- <para>
- Example:
- <screen>char *str = weechat_ngettext ("file", "files", num_files);</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_strndup">
- <title>weechat_strndup</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_strndup (const char *string, int length)
- </command>
- </para>
- <para>
- Return duplicated string, with max "length" chars.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string to duplicate
- </para>
- </listitem>
- <listitem>
- <para>
- <option>length</option>: max chars to duplicate
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: duplicated string.
- </para>
- <para>
- Note: result has to be free by a call to "free" after use.
- </para>
- <para>
- Example:
- <screen>char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_tolower">
- <title>weechat_string_tolower</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_string_tolower (const char *string)
- </command>
- </para>
- <para>
- Convert UTF-8 string to lower case.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string to convert
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>weechat_string_tolower ("AbCdEé"); /* result: "abcdeé" */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_toupper">
- <title>weechat_string_toupper</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_string_toupper (const char *string)
- </command>
- </para>
- <para>
- Convert UTF-8 string to upper case.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string to convert
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>weechat_string_toupper ("AbCdEé"); /* result: "ABCDEé" */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_strcasecmp">
- <title>weechat_strcasecmp</title>
-
- <para>
- Prototype:
- <command>
- int weechat_strcasecmp (const char *string1, const char *string2)
- </command>
- </para>
- <para>
- Locale and case independent string comparison.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string1</option>: first string for comparison
- </para>
- </listitem>
- <listitem>
- <para>
- <option>string2</option>: second string for comparison
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: difference between two strings: negative if
- string1 &lt; string2, zero if string1 == string2, positive if
- string1 &gt; string2
- </para>
- <para>
- Example:
- <screen>int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */ </screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_strncasecmp">
- <title>weechat_strncasecmp</title>
-
- <para>
- Prototype:
- <command>
- int weechat_strncasecmp (const char *string1, const char *string2,
- int max)
- </command>
- </para>
- <para>
- Locale and case independent string comparison, for "max" chars.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string1</option>: first string for comparison
- </para>
- </listitem>
- <listitem>
- <para>
- <option>string2</option>: second string for comparison
- </para>
- </listitem>
- <listitem>
- <para>
- <option>max</option>: max number of chars for comparison
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: difference between two strings: negative if
- string1 &lt; string2, zero if string1 == string2, positive if
- string1 &gt; string2
- </para>
- <para>
- Example:
- <screen>int diff = weechat_strncasecmp ("aaa", "CCC", 2); /* == -2 */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_strcmp_ignore_chars">
- <title>weechat_strcmp_ignore_chars</title>
-
- <para>
- Prototype:
- <command>
- int weechat_strcmp_ignore_chars (const char *string1,
- const char *string2, const char *chars_ignored, int case_sensitive)
- </command>
- </para>
- <para>
- Locale (and optionally case independent) string comparison, ignoring
- some chars.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string1</option>: first string for comparison
- </para>
- </listitem>
- <listitem>
- <para>
- <option>string2</option>: second string for comparison
- </para>
- </listitem>
- <listitem>
- <para>
- <option>chars_ignored</option>: string with chars to ignore
- </para>
- </listitem>
- <listitem>
- <para>
- <option>case_sensitive</option>: 1 for case sensitive comparison,
- 0 otherwise
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: difference between two strings: negative if
- string1 &lt; string2, zero if string1 == string2, positive if
- string1 &gt; string2
- </para>
- <para>
- Example:
- <screen>int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_strcasestr">
- <title>weechat_strcasestr</title>
-
- <para>
- Prototype:
- <command>
- int weechat_strcasestr (const char *string, const char *search)
- </command>
- </para>
- <para>
- Locale and case independent string search.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>search</option>: string to search in "string"
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: pointer to string found, or NULL if not found
- </para>
- <para>
- Example:
- <screen>char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_match">
- <title>weechat_string_match</title>
-
- <para>
- Prototype:
- <command>
- int weechat_string_match (const char *string, const char *mask,
- int case_sensitive)
- </command>
- </para>
- <para>
- Check if a string matches a mask. Mask may begin or end with "*" (no
- other "*" are allowed inside mask).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>mask</option>: mask
- </para>
- </listitem>
- <listitem>
- <para>
- <option>case_sensitive</option>: 1 for case sensitive search,
- otherwise 0
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: 1 if string matches mask, otherwise 0.
- </para>
- <para>
- Examples:
-<screen>
-int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */
-int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */
-int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */
-</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_replace">
- <title>weechat_string_replace</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_string_replace (const char *string, const char *search,
- const char *replace)
- </command>
- </para>
- <para>
- Replace "search" string by new one in a string.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>search</option>: string to replace
- </para>
- </listitem>
- <listitem>
- <para>
- <option>replace</option>: replacement for "search" string
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: string with "search" replaced by "replace".
- </para>
- <para>
- Note: result has to be free by a call to "free" after use.
- </para>
- <para>
- Example:
- <screen>char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_remove_quotes">
- <title>weechat_string_remove_quotes</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_string_remove_quotes (const char *string,
- const char *quotes)
- </command>
- </para>
- <para>
- Remove quotes at beginning/end of string (ignore spaces if there are
- before first quote or after last quote).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>quotes</option>: string with list of quotes
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: string without quotes at beginning/end.
- </para>
- <para>
- Note: result has to be free by a call to "free" after use.
- </para>
- <para>
- Example:
- <screen>char *str = weechat_string_remove_quotes (string, " 'abc' ", "'"); /* result: "abc" */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_strip">
- <title>weechat_string_strip</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_string_strip (const char *string, int left, int right,
- const char *chars)
- </command>
- </para>
- <para>
- Strip chars at beginning and/or end of string.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>left</option>: strip left chars if different from 0
- </para>
- </listitem>
- <listitem>
- <para>
- <option>right</option>: strip right chars if different from 0
- </para>
- </listitem>
- <listitem>
- <para>
- <option>chars</option>: string with chars to strip
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: stripped string.
- </para>
- <para>
- Note: result has to be free by a call to "free" after use.
- </para>
- <para>
- Example:
- <screen>char *str = weechat_strip (string, " ", 0, 1); /* remove spaces at end of string */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_has_highlight">
- <title>weechat_string_has_highlight</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_string_has_highlight (const char *string,
- const char highlight_words)
- </command>
- </para>
- <para>
- Check if a string has highlights, using list of highlight words.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>highlight_words</option>: list of highlight words,
- separated by comma
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: 1 if string has one or more highlights, 0 otherwise.
- </para>
- <para>
- Example:
- <screen>if (weechat_string_has_highlight (string, "word1,word2")) ...</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_explode">
- <title>weechat_string_explode</title>
-
- <para>
- Prototype:
- <command>
- char **weechat_string_explode (const char *string,
- const char *separators, int keep_eol, int num_items_max,
- int *num_items)
- </command>
- </para>
- <para>
- Explode a string according to one or more delimiter(s).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string to explode
- </para>
- </listitem>
- <listitem>
- <para>
- <option>separators</option>: delimiters used for explosion
- </para>
- </listitem>
- <listitem>
- <para>
- <option>keep_eol</option>: if different from 0, then each argument
- will contain all string until end of line (see example below)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>num_items_max</option>: maximum number of items
- created (0 = no limit)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>num_items</option>: pointer to int which will
- contain number of items created
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: array of strings, NULL if problem.
- </para>
- <para>
- Note: result has to be free by a call to "weechat_string_free_exploded"
- after use.
- </para>
- <para>
- Examples:
- <screen>
-char **argv;
-int argc;
-argv = weechat_string_explode ("abc de fghi", " ", 0, 0, &amp;argc);
-/* result: argv[0] == "abc"
- argv[1] == "de"
- argv[2] == "fghi"
- argv[3] == NULL
- argc == 3
-*/
-weechat_string_free_exploded (argv);
+ <!-- &plugin_script_api.en.xml; -->
-argv = weechat_string_explode ("abc de fghi", " ", 1, 0, &amp;argc);
-/* result: argv[0] == "abc de fghi"
- argv[1] == "de fghi"
- argv[2] == "fghi"
- argv[3] == NULL
- argc == 3
-*/
-weechat_string_free_exploded (argv);
- </screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_free_exploded">
- <title>weechat_string_free_exploded</title>
-
- <para>
- Prototype:
- <command>
- void weechat_string_free_exploded (char **exploded_string)
- </command>
- </para>
- <para>
- Free memory used by a string explosion.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>exploded_string</option>: string exploded by
- "weechat_string_explode" function
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>
-char *argv;
-int argc;
-argv = weechat_string_explode (string, " ", 0, 0, &amp;argc);
-...
-weechat_string_free_exploded (, argv);
- </screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_build_with_exploded">
- <title>weechat_string_build_with_exploded</title>
-
- <para>
- Prototype:
- <command>
- char **weechat_string_build_with_exploded (char **exploded_string,
- const char *separator)
- </command>
- </para>
- <para>
- Build a string with exploded string.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>exploded_string</option>: string exploded by
- "weechat_string_explode" function
- </para>
- </listitem>
- <listitem>
- <para>
- <option>separator</option>: string used to separate strings
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: string built with exploded string.
- </para>
- <para>
- Note: result has to be free by a call to "free" after use.
- </para>
- <para>
- Example:
- <screen>
-char **argv;
-int argc;
-argv = weechat_string_explode ("abc def ghi", " ", 0, 0, &amp;argc);
-char *string = weechat_string_build_with_exploded (argv, ";");
-/* string == "abc;def;ghi" */
- </screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_split_command">
- <title>weechat_string_split_command</title>
-
- <para>
- Prototype:
- <command>
- char **weechat_string_split_command (const char *command,
- char separator)
- </command>
- </para>
- <para>
- Split a list of commands separated by 'separator' (which can be escaped
- by '\' in string).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>command</option>: command to split
- </para>
- </listitem>
- <listitem>
- <para>
- <option>separator</option>: separator
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: array of strings, NULL if problem.
- </para>
- <para>
- Note: result has to be free by a call to
- "weechat_string_free_splitted_command" after use.
- </para>
- <para>
- Example:
- <screen>char **argv = weechat_string_split_command ("/command1;/command2", ';');</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_string_splitted_command">
- <title>weechat_string_free_splitted_command</title>
-
- <para>
- Prototype:
- <command>
- void weechat_string_free_splitted_command (char **splitted_command)
- </command>
- </para>
- <para>
- Free memory used by a splitted command.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>splitted_command</option>: command splitted by
- "weechat_string_split_commaand" function
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>
-char **argv = weechat_string_split_command ("/command1;/command2", ';');
-...
-weechat_string_free_splitted_command (argv);
- </screen>
- </para>
- </section>
-
- </section>
-
- <!-- ==============================[ UTF-8 ]============================= -->
-
- <section id="secAPI_utf8">
- <title>UTF-8</title>
-
- <para>
- Some UTF-8 string functions.
- </para>
-
- <section id="secAPI_weechat_utf8_has_8bits">
- <title>weechat_utf8_has_8bits</title>
-
- <para>
- Prototype:
- <command>
- int weechat_utf8_has_8bits (const char *string)
- </command>
- </para>
- <para>
- Check if a string has 8-bits chars.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: 1 if string has 8-buts chars, 0 if only 7-bits chars.
- </para>
- <para>
- Example:
- <screen>if (weechat_utf8_has_8bits (string)) ...</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_is_valid">
- <title>weechat_utf8_is_valid</title>
-
- <para>
- Prototype:
- <command>
- int weechat_utf8_is_valid (const char *string, char **error)
- </command>
- </para>
- <para>
- Check if a string is UTF-8 valid.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>error</option>: if not NULL, it is set with first non
- valid UTF-8 char in string, if any
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: 1 if UTF-8 string is valid, 0 otherwise.
- </para>
- <para>
- Example:
- <screen>
-char *error;
-if (weechat_utf8_is_valid (string, &amp;error)) ...
- </screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_normalize">
- <title>weechat_utf8_normalize</title>
-
- <para>
- Prototype:
- <command>
- void weechat_utf8_normalize (const char *string, char replacement)
- </command>
- </para>
- <para>
- Normalize UTF-8 string: remove non UTF-8 chars and replace them by a
- char
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>replacement</option>: replacement char for non UTF-8 chars
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>weechat_utf8_normalize (string, '?');</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_prev_char">
- <title>weechat_utf8_prev_char</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_utf8_prev_char (const char *string_start,
- const char *string)
- </command>
- </para>
- <para>
- Return previous UTF-8 char in a string.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string_start</option>: start of string (function will not
- return a char before this pointer)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>string</option>: pointer to string (must be >=
- string_start)
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: pointer to previous UTF-8 char, NULL if not found
- (start of string reached)
- </para>
- <para>
- Example:
- <screen>char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_next_char">
- <title>weechat_utf8_next_char</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_utf8_next_char (const char *string)
- </command>
- </para>
- <para>
- Return next UTF-8 char in a string.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: pointer to next UTF-8 char, NULL if not found
- (end of string reached)
- </para>
- <para>
- Example:
- <screen>char *next_char = weechat_utf8_next_char (string);</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_char_size">
- <title>weechat_utf8_char_size</title>
-
- <para>
- Prototype:
- <command>
- int weechat_utf8_char_size (const char *string)
- </command>
- </para>
- <para>
- Return UTF-8 char size (in bytes).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: UTF-8 char size (in bytes).
- </para>
- <para>
- Example:
- <screen>int char_size = weechat_utf8_char_size ("être"); /* == 2 */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_strlen">
- <title>weechat_utf8_strlen</title>
-
- <para>
- Prototype:
- <command>
- int weechat_utf8_strlen (const char *string)
- </command>
- </para>
- <para>
- Return UTF-8 string length (multi-byte char is considered as 1 char).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: UTF-8 string length (number of real chars).
- </para>
- <para>
- Example:
- <screen>int length = weechat_utf8_strlen ("chêne"); /* == 5 */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_strnlen">
- <title>weechat_utf8_strnlen</title>
-
- <para>
- Prototype:
- <command>
- int weechat_utf8_strnlen (const char *string, int bytes)
- </command>
- </para>
- <para>
- Return UTF-8 string length (multi-byte char is considered as 1 char),
- for max bytes in string
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>bytes</option>: max bytes in string
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: UTF-8 string length (number of real chars).
- </para>
- <para>
- Example:
- <screen>int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_strlen_screen">
- <title>weechat_utf8_strlen_screen</title>
-
- <para>
- Prototype:
- <command>
- int weechat_utf8_strlen_screen (const char *string)
- </command>
- </para>
- <para>
- Return number of chars needed on screen to display UTF-8 string.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: number of chars needed on screen to display UTF-8 string.
- </para>
- <para>
- Example:
- <screen>int length_on_screen = weechat_utf8_strlen_screen ("&#x4E1C;"); /* == 2 */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_charcasecmp">
- <title>weechat_utf8_charcasecmp</title>
-
- <para>
- Prototype:
- <command>
- int weechat_utf8_charcasecmp (const char *string1,
- const char *string2)
- </command>
- </para>
- <para>
- Compare two UTF-8 chars (case is ignored).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string1</option>: first string for comparison
- </para>
- </listitem>
- <listitem>
- <para>
- <option>string2</option>: second string for comparison
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: difference between first char of each string: negative if
- char1 &lt; char2, zero if char1 == char2, positive if char1 &gt; char2
- </para>
- <para>
- Example:
- <screen>if (weechat_utf8_charcasecmp (string1, string2) != 0) ...</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_char_size_screen">
- <title>weechat_utf8_char_size_screen</title>
-
- <para>
- Prototype:
- <command>
- int weechat_utf8_char_size_screen (const char *string)
- </command>
- </para>
- <para>
- Return number of chars needed on screen to display UTF-8 char.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: number of chars needed on screen to display UTF-8 char.
- </para>
- <para>
- Example:
- <screen>int length_on_screen = weechat_utf8_char_size_screen (string)</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_add_offset">
- <title>weechat_utf8_add_offset</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_utf8_add_offset (const char *string, int offset)
- </command>
- </para>
- <para>
- Move forward N chars in an UTF-8 string.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>offset</option>: number of chars
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: pointer to string, N chars after (NULL if it's not
- reachable).
- </para>
- <para>
- Example:
- <screen>char *ptr = weechat_utf8_add_offset ("chêne", 3); /* points to "ne" */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_real_pos">
- <title>weechat_utf8_real_pos</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_utf8_real_pos (const char *string, int pos)
- </command>
- </para>
- <para>
- Get real position in UTF-8 string.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>pos</option>: position in chars
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: real position (in bytes) for "pos" chars in string.
- </para>
- <para>
- Example:
- <screen>int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_utf8_pos">
- <title>weechat_utf8_pos</title>
-
- <para>
- Prototype:
- <command>
- char *weechat_utf8_pos (const char *string, int real_pos)
- </command>
- </para>
- <para>
- Get position in UTF-8 string.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>string</option>: string
- </para>
- </listitem>
- <listitem>
- <para>
- <option>real_pos</option>: position in bytes
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: position (in chars) for "real_pos" bytes in string.
- </para>
- <para>
- Example:
- <screen>int pos = weechat_utf8_real_pos ("chêne", 4); /* == 3 */</screen>
- </para>
- </section>
-
- </section>
-
- <!-- ===========================[ directories ]========================== -->
-
- <section id="secAPI_directories">
- <title>Directories</title>
-
- <para>
- Some functions related to directories.
- </para>
-
- <section id="secAPI_weechat_mkdir_home">
- <title>weechat_mkdir_home</title>
-
- <para>
- Prototype:
- <command>
- int weechat_mkdir_home (char *directory, int mode)
- </command>
- </para>
- <para>
- Create a directory in WeeChat home.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>directory</option>: directory to create
- </para>
- </listitem>
- <listitem>
- <para>
- <option>mode</option>: mode for new directory
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: 1 if directory was successfully created, 0 if an
- error occurred.
- </para>
- <para>
- Example:
- <screen>if (!weechat_mkdir_home ("temp")) ... </screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_mkdir">
- <title>weechat_mkdir</title>
-
- <para>
- Prototype:
- <command>
- int weechat_mkdir (char *directory, int mode)
- </command>
- </para>
- <para>
- Create a directory.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>directory</option>: directory to create
- </para>
- </listitem>
- <listitem>
- <para>
- <option>mode</option>: mode for new directory
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: 1 if directory was successfully created, 0 if an
- error occurred.
- </para>
- <para>
- Example:
- <screen>if (!weechat_mkdir ("/tmp/mydir")) ... </screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_exec_on_files">
- <title>weechat_exec_on_files</title>
-
- <para>
- Prototype:
- <command>
- void weechat_exec_on_files (const char *directory, void *data,
- int (*callback)(void *data, const char *filename))
- </command>
- </para>
- <para>
- Find files in a directory and execute a callback on each file.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>directory</option>: directory for searching files
- </para>
- </listitem>
- <listitem>
- <para>
- <option>data</option>: pointer given to callback when calling it
- found
- </para>
- </listitem>
- <listitem>
- <para>
- <option>callback</option>: function called for each file
- found
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
-<screen>
-int callback (void *data, const char *filename)
-{
- /* ... */
- return 1;
-}
-...
-plugin->exec_on_files (plugin, "/tmp", &amp;callback);
-</screen>
- </para>
- </section>
-
- </section>
-
- <!-- ==============================[ util ]============================== -->
-
- <section id="secAPI_util">
- <title>Util</title>
-
- <para>
- Some useful functions.
- </para>
-
- <section id="secAPI_weechat_timeval_cmp">
- <title>weechat_timeval_cmp</title>
-
- <para>
- Prototype:
- <command>
- int weechat_timeval_cmp (struct timeval *tv1, struct timeval *tv2)
- </command>
- </para>
- <para>
- Compare 2 timeval structures.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>tv1</option>: first timeval structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>tv2</option>: second timeval structure
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: -1 if tv1 &lt; char2, zero if tv1 == tv2, +1 if tv1 &gt;
- tv2
- </para>
- <para>
- Example:
- <screen>if (weechat_timeval_cmp (&amp;tv1, &amp;tv2) > 0) ...</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_timeval_diff">
- <title>weechat_timeval_diff</title>
-
- <para>
- Prototype:
- <command>
- long weechat_timeval_diff (struct timeval *tv1, struct timeval *tv2)
- </command>
- </para>
- <para>
- Return difference (in milliseconds) between 2 timeval structures.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>tv1</option>: first timeval structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>tv2</option>: second timeval structure
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: difference in milliseconds.
- </para>
- <para>
- Example:
- <screen>long diff = weechat_timeval_diff (&amp;tv1, &amp;tv2);</screen>
- </para>
- </section>
-
- <section id="secAPI_weechat_timeval_add">
- <title>weechat_timeval_add</title>
-
- <para>
- Prototype:
- <command>
- void weechat_timeval_add (struct timeval *tv, long interval)
- </command>
- </para>
- <para>
- Add interval (in milliseconds) to a timeval structure.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>tv</option>: timeval structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>interval</option>: interval (in milliseconds)
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>weechat_timeval_add (&amp;tv, 2000); /* add 2 seconds */</screen>
- </para>
- </section>
-
- </section>
-
- To be continued...
-
- <!--
-
- <section id="secAPI_print">
- <title>print</title>
-
- <para>
- Prototype:
- <command>
- void print (t_weechat_plugin *plugin,
- char *server, char *channel, char *message, ...)
- </command>
- </para>
- <para>
- Display a message on a WeeChat buffer, identified by server and
- channel (both may be NULL for current buffer).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>server</option>: internal name of server to find
- buffer for message display (may be NULL)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>channel</option>: name of channel to find buffer
- for message display (may be NULL)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>message</option>: message
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- To display colored text, there are following codes:
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Code</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>0x02</entry>
- <entry>
- bold text
- </entry>
- </row>
- <row>
- <entry>0x03 + "xx"</entry>
- <entry>
- text color "<literal>xx</literal>"
- (see <xref linkend="secAPI_get_irc_color" /> for colors)
- </entry>
- </row>
- <row>
- <entry>0x03 + "xx,yy"</entry>
- <entry>
- text color "<literal>xx</literal>"
- and background "<literal>yy</literal>"
- (see <xref linkend="secAPI_get_irc_color" /> for colors)
- </entry>
- </row>
- <row>
- <entry>0x0F</entry>
- <entry>
- disable color and attributes
- </entry>
- </row>
- <row>
- <entry>0x12</entry>
- <entry>
- reverse video (revert text color with background)
- </entry>
- </row>
- <row>
- <entry>0x1F</entry>
- <entry>
- underlined text
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- Note: the same code (without number for 0x03) may be used to stop
- the attribute.
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Examples:
-<screen>
-plugin->print (plugin, NULL, NULL, "hello");
-plugin->print (plugin, NULL, "#weechat", "hello");
-plugin->print (plugin, "freenode", "#weechat", "hello");
-plugin->print (plugin, NULL, NULL,
- "test: \x02 bold \x0F\x03%02d blue \x03%02d green",
- plugin->get_irc_color (plugin, "blue"),
- plugin->get_irc_color (plugin, "green"));
-</screen>
- </para>
- </section>
-
- <section id="secAPI_print_server">
- <title>print_server</title>
-
- <para>
- Prototype:
- <command>
- void print_server (t_weechat_plugin *plugin,
- char *message, ...)
- </command>
- </para>
- <para>
- Display a message on current server buffer.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>message</option>: message
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- To display colored text, see <xref linkend="secAPI_print" />.
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example: <screen>plugin->print_server (plugin, "hello");</screen>
- </para>
- </section>
-
- <section id="secAPI_log">
- <title>log</title>
-
- <para>
- Prototype:
- <command>
- void log (t_weechat_plugin *plugin,
- char *server, char *channel, char *message, ...)
- </command>
- </para>
- <para>
- Write a message in log file for a server or a channel.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>server</option>: internal name of server to find
- buffer for log (may be NULL)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>channel</option>: name of channel to find buffer
- for log (may be NULL)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>message</option>: message
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
-<screen>
-plugin->log (plugin, "freenode", "#weechat", "test");
-</screen>
- </para>
- </section>
-
- <section id="secAPI_msg_handler_add">
- <title>msg_handler_add</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_handler *msg_handler_add (t_weechat_plugin
- *plugin, char *message, t_plugin_handler_func *function,
- char *handler_args, void *handler_pointer)
- </command>
- </para>
- <para>
- Add an IRC message handler, called when an IRC message is
- received.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>message</option>: name of IRC message ("*" for all
- messages).
- To know list of IRC messages, please consult
- <acronym>RFC</acronym>s
- <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink>
- and
- <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink>.
- Moreover you can use a special name, prefixed by "weechat_"
- to catch special events, as written in table below:
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Name</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>weechat_pv</literal></entry>
- <entry>private message received</entry>
- </row>
- <row>
- <entry><literal>weechat_highlight</literal></entry>
- <entry>
- message with highlight (on a channel or pv)
- </entry>
- </row>
- <row>
- <entry><literal>weechat_ctcp</literal></entry>
- <entry>
- CTCP message received (VERSION, PING, ..)
- </entry>
- </row>
- <row>
- <entry><literal>weechat_dcc</literal></entry>
- <entry>
- DCC message received (chat or file)
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </listitem>
- <listitem>
- <para>
- <option>function</option>: function called when message
- is received
- </para>
- <para>
- It uses following prototype:
- <command>
- int my_function (t_weechat_plugin *plugin,
- int argc, char **argv,
- char *handler_args, void *handler_pointer)
- </command>
- </para>
- <para>
- Argument argc is set to 3, following values are set in
- argv array:
- <itemizedlist>
- <listitem>
- <para>argv[0] = server name</para>
- </listitem>
- <listitem>
- <para>argv[1] = IRC message</para>
- </listitem>
- <listitem>
- <para>argv[2] = command arguments</para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler_args</option>: arguments given to function
- when called
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler_pointer</option>: pointer given to function
- when called
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: pointer to new message handler.
- </para>
- <para>
- Note: function called when message is received has to return
- one of following values:
- <itemizedlist>
- <listitem>
- <para>
- <literal>PLUGIN_RC_KO</literal>: function failed
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>PLUGIN_RC_OK</literal>: function successfully
- completed
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>PLUGIN_RC_OK_IGNORE_WEECHAT</literal>: message
- will not be sent to WeeChat
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>PLUGIN_RC_OK_IGNORE_PLUGINS</literal>: message
- will not be sent to other plugins
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>PLUGIN_RC_OK_IGNORE_ALL</literal>: message
- will not be sent to WeeChat neither other plugins
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>PLUGIN_RC_OK_WITH_HIGHLIGHT</literal>: function
- successfully completed and make "highlight" on received
- message
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Example:
-<screen>
-int msg_kick (t_weechat_plugin *plugin, int argc, char **argv,
- char *handler_args, void *handler_pointer)
-{
- plugin->print (plugin, argv[0], NULL, "KICK received");
- return PLUGIN_RC_OK;
-}
-...
-t_plugin_handler *msg_handler;
-msg_handler = plugin->msg_handler_add (plugin, "KICK",
- &amp;msg_kick, NULL, NULL);
-</screen>
- </para>
- </section>
-
- <section id="secAPI_cmd_handler_add">
- <title>cmd_handler_add</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_handler *cmd_handler_add (t_weechat_plugin
- *plugin, char *command, char *description, char *arguments,
- char *arguments_description, char *completion_template,
- t_plugin_handler_func *fonction, char *handler_args,
- void *handler_pointer)
- </command>
- </para>
- <para>
- Add a WeeChat command handler, called when user uses command
- (for example /command).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>command</option>: the new command name, which
- may be an existing command (be careful, replaced command
- will not be available until plugin is unloaded)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>description</option>: short command description
- (displayed by /help command)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>arguments</option>: short description of command
- arguments (displayed by /help command)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>arguments_description</option>: long description
- of command arguments (displayed by /help command)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>completion_template</option>: template for
- completion, like "<literal>abc|%w def|%i</literal>"
- which means "abc" or a WeeChat command for first argument,
- "def" or IRC command for second.
- An empty string lets WeeChat complete any argument with
- a nick from current channel, NULL or "-" disable completion
- for all command arguments.
- </para>
- <para>
- Following codes can be used:
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Code</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>%-</literal></entry>
- <entry>no completion for argument</entry>
- </row>
- <row>
- <entry><literal>%*</literal></entry>
- <entry>
- repeat last completion for all following arguments
- (this code has to be at the end of completion
- template, preceded by "|")
- </entry>
- </row>
- <row>
- <entry><literal>%a</literal></entry>
- <entry>alias</entry>
- </row>
- <row>
- <entry><literal>%A</literal></entry>
- <entry>
- alias and commands (WeeChat, IRC and plugins)
- </entry>
- </row>
- <row>
- <entry><literal>%c</literal></entry>
- <entry>current channel</entry>
- </row>
- <row>
- <entry><literal>%C</literal></entry>
- <entry>all channels (including queries)</entry>
- </row>
- <row>
- <entry><literal>%f</literal></entry>
- <entry>file name</entry>
- </row>
- <row>
- <entry><literal>%h</literal></entry>
- <entry>plugins commands</entry>
- </row>
- <row>
- <entry><literal>%i</literal></entry>
- <entry>IRC commands (sent)</entry>
- </row>
- <row>
- <entry><literal>%I</literal></entry>
- <entry>IRC commands (received)</entry>
- </row>
- <row>
- <entry><literal>%k</literal></entry>
- <entry>key functions</entry>
- </row>
- <row>
- <entry><literal>%m</literal></entry>
- <entry>nick on current server</entry>
- </row>
- <row>
- <entry><literal>%M</literal></entry>
- <entry>
- nicks on current server (on all open channels)
- </entry>
- </row>
- <row>
- <entry><literal>%n</literal></entry>
- <entry>nicks of current channel</entry>
- </row>
- <row>
- <entry><literal>%N</literal></entry>
- <entry>nicks and hostnames of current channel</entry>
- </row>
- <row>
- <entry><literal>%o</literal></entry>
- <entry>setup options</entry>
- </row>
- <row>
- <entry><literal>%O</literal></entry>
- <entry>plugin options</entry>
- </row>
- <row>
- <entry><literal>%p</literal></entry>
- <entry>default "part" message</entry>
- </row>
- <row>
- <entry><literal>%q</literal></entry>
- <entry>default "quit" message</entry>
- </row>
- <row>
- <entry><literal>%s</literal></entry>
- <entry>current server name</entry>
- </row>
- <row>
- <entry><literal>%S</literal></entry>
- <entry>all servers names</entry>
- </row>
- <row>
- <entry><literal>%t</literal></entry>
- <entry>topic of current channel</entry>
- </row>
- <row>
- <entry><literal>%v</literal></entry>
- <entry>setup option value</entry>
- </row>
- <row>
- <entry><literal>%V</literal></entry>
- <entry>plugin option value</entry>
- </row>
- <row>
- <entry><literal>%w</literal></entry>
- <entry>WeeChat commands</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </listitem>
- <listitem>
- <para>
- <option>function</option>: function called when command
- is executed
- </para>
- <para>
- It uses following prototype:
- <command>
- int my_function (t_weechat_plugin *plugin,
- int argc, char **argv,
- char *handler_args, void *handler_pointer)
- </command>
- </para>
- <para>
- Argument argc is set to 3, following values are set in
- argc array:
- <itemizedlist>
- <listitem>
- <para>argv[0] = server name</para>
- </listitem>
- <listitem>
- <para>argv[1] = command</para>
- </listitem>
- <listitem>
- <para>argv[2] = command arguments</para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler_args</option>: arguments given to function
- when called
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler_pointer</option>: pointer given to function
- when called
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: pointer to new command handler.
- </para>
- <para>
- Note: function called when command is executed has to return
- one of following values:
- <itemizedlist>
- <listitem>
- <para>
- <literal>PLUGIN_RC_KO</literal>: function failed
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>PLUGIN_RC_OK</literal>: function successfully
- completed
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Example:
-<screen>
-int cmd_test (t_weechat_plugin *plugin, int argc, char **argv,
- char *handler_args, void *handler_pointer)
-{
- plugin->print (plugin, argv[0], NULL,
- "test command, nick: %s",
- (argv[2]) ? argv[2] : "none");
- return PLUGIN_RC_OK;
-}
-...
-t_plugin_handler *cmd_handler;
-cmd_handler = plugin->cmd_handler_add (plugin, "test", "Test command",
- "[nick]", "nick: nick of channel",
- "%n", &amp;cmd_test, NULL, NULL);
-</screen>
- </para>
- </section>
-
- <section id="secAPI_timer_handler_add">
- <title>timer_handler_add</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_handler *timer_handler_add (t_weechat_plugin
- *plugin, int interval, t_plugin_handler_func *function,
- char *handler_args, void *handler_pointer)
- </command>
- </para>
- <para>
- Add a timer handler which periodically calls a function.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>interval</option>: interval (in seconds) between
- two calls of function.
- </para>
- </listitem>
- <listitem>
- <para>
- <option>function</option>: function called
- </para>
- <para>
- It uses following prototype:
- <command>
- int my_function (t_weechat_plugin *plugin,
- int argc, char **argv,
- char *handler_args, void *handler_pointer)
- </command>
- </para>
- <para>
- Argument argc is set to 0, and argv is set to NULL.
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler_args</option>: arguments given to function
- when called
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler_pointer</option>: pointer given to function
- when called
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: pointer to new timer handler.
- </para>
- <para>
- Note: function called has to return one of following values:
- <itemizedlist>
- <listitem>
- <para>
- <literal>PLUGIN_RC_KO</literal>: function failed
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>PLUGIN_RC_OK</literal>: function successfully
- completed
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Example:
-<screen>
-int my_timer (t_weechat_plugin *plugin, int argc, char **argv,
- char *handler_args, void *handler_pointer)
-{
- plugin->print (plugin, NULL, NULL, "my timer");
- return PLUGIN_RC_OK;
-}
-...
-t_plugin_handler *timer_handler;
-timer_handler = plugin->timer_handler_add (plugin, 60, &amp;my_timer);
-</screen>
- </para>
- </section>
-
- <section id="secAPI_keyboard_handler_add">
- <title>keyboard_handler_add</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_handler *keyboard_handler_add (t_weechat_plugin
- *plugin, t_plugin_handler_func *function,
- char *handler_args, void *handler_pointer)
- </command>
- </para>
- <para>
- Add a keyboard handler, called for any key pressed.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>function</option>: function called
- </para>
- <para>
- It uses following prototype:
- <command>
- int my_function (t_weechat_plugin *plugin,
- int argc, char **argv,
- char *handler_args, void *handler_pointer)
- </command>
- </para>
- <para>
- Argument argc is set to 3, following values are set in
- argc array:
- <itemizedlist>
- <listitem>
- <para>
- argv[0] = key pressed (name of internal function or
- '*' followed by a key code)
- </para>
- </listitem>
- <listitem>
- <para>
- argv[1] = command line before key action
- </para>
- </listitem>
- <listitem>
- <para>
- argv[2] = command line after key action
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler_args</option>: arguments given to function
- when called
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler_pointer</option>: pointer given to function
- when called
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: pointer to new message handler.
- </para>
- <para>
- Note: function called has to return one of following values:
- <itemizedlist>
- <listitem>
- <para>
- <literal>PLUGIN_RC_KO</literal>: function failed
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>PLUGIN_RC_OK</literal>: function successfully
- completed
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Example:
-<screen>
-int my_keyb (t_weechat_plugin *plugin, int argc, char **argv,
- char *handler_args, void *handler_pointer)
-{
- if (argc == 2)
- {
- plugin->print (plugin, NULL, NULL, "key pressed: %s", argv[0]);
- if (argv[1] &amp;&amp; (argv[1][0] == '1'))
- plugin->print (plugin, NULL, NULL, "input text changed");
- else
- plugin->print (plugin, NULL, NULL, "input text not changed");
- }
- return PLUGIN_RC_OK;
-}
-...
-t_plugin_handler *keyb_handler;
-keyb_handler = plugin->keyboard_handler_add (plugin, &amp;my_keyb);
-</screen>
- </para>
- </section>
-
- <section id="secAPI_event_handler_add">
- <title>event_handler_add</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_handler *event_handler_add (t_weechat_plugin
- *plugin, char *event, t_plugin_handler_func *function,
- char *handler_args, void *handler_pointer)
- </command>
- </para>
- <para>
- Add an event handler, called when an event happens.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>event</option> : event (see table below)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>function</option>: function called
- </para>
- <para>
- It uses following prototype:
- <command>
- int my_function (t_weechat_plugin *plugin,
- int argc, char **argv,
- char *handler_args, void *handler_pointer)
- </command>
- </para>
- <para>
- Arguments depend on event (see table below).
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler_args</option>: arguments given to function
- when called
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler_pointer</option>: pointer given to function
- when called
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- List of events:
- <informaltable colsep="0" frame="none">
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Event</entry>
- <entry>Description</entry>
- <entry>Arguments</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>buffer_open</literal></entry>
- <entry>a buffer was open</entry>
- <entry>
- argc = 1, argv = { buffer number }
- </entry>
- </row>
- <row>
- <entry><literal>buffer_close</literal></entry>
- <entry>a buffer was closed</entry>
- <entry>
- argc = 1, argv = { buffer number }
- </entry>
- </row>
- <row>
- <entry><literal>buffer_move</literal></entry>
- <entry>a buffer was moved</entry>
- <entry>
- argc = 2, argv = { new buffer number, old number }
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Return value: pointer to new event handler.
- </para>
- <para>
- Note: function called has to return one of following values:
- <itemizedlist>
- <listitem>
- <para>
- <literal>PLUGIN_RC_KO</literal>: function failed
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>PLUGIN_RC_OK</literal>: function successfully
- completed
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Example:
-<screen>
-int my_event (t_weechat_plugin *plugin, int argc, char **argv,
- char *handler_args, void *handler_pointer)
-{
- plugin->print (plugin, NULL, NULL, "my_event");
- return PLUGIN_RC_OK;
-}
-...
-t_plugin_handler *event_handler;
-event_handler = plugin->event_handler_add (plugin, "buffer_open",
- &amp;my_event);
-</screen>
- </para>
- </section>
-
- <section id="secAPI_handler_remove">
- <title>handler_remove</title>
-
- <para>
- Prototype:
- <command>
- void handler_remove (t_weechat_plugin *plugin,
- t_plugin_handler *handler)
- </command>
- </para>
- <para>
- Remove a command or message handler.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>handler</option>: handler to remove
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->handler_remove (plugin, my_handler);</screen>
- </para>
- </section>
-
- <section id="secAPI_handler_remove_all">
- <title>handler_remove_all</title>
-
- <para>
- Prototype:
- <command>
- void handler_remove_all (t_weechat_plugin *plugin)
- </command>
- </para>
- <para>
- Remove all handlers for a plugin.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->handler_remove_all (plugin);</screen>
- </para>
- </section>
-
- <section id="secAPI_modifier_add">
- <title>modifier_add</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_modifier *modifier_add (t_weechat_plugin *plugin,
- char *type, char *message, t_plugin_modifier_func *function,
- char *modifier_args, void *modifier_pointer)
- </command>
- </para>
- <para>
- Add a message modifier.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>type</option>: modifier type:
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>irc_in</literal></entry>
- <entry>called for incoming IRC messages</entry>
- </row>
- <row>
- <entry><literal>irc_user</literal></entry>
- <entry>
- called for each user message (or command) (before
- WeeChat parses message)
- </entry>
- </row>
- <row>
- <entry><literal>irc_out</literal></entry>
- <entry>
- called for outgoing messages, immediately before
- sending it to IRC server (this includes messages
- sent automatically by WeeChat to server)
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </listitem>
- <listitem>
- <para>
- <option>message</option>: name of IRC message (used only for
- types "irc_in" and "irc_out").
- To know list of IRC messages, please consult
- <acronym>RFC</acronym>s
- <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink>
- and
- <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink>.
- Moreover, special value "*" means all messages (no filter).
- </para>
- </listitem>
- <listitem>
- <para>
- <option>function</option>: function called
- </para>
- <para>
- It uses following prototype:
- <command>
- int my_function (t_weechat_plugin *plugin,
- int argc, char **argv,
- char *modifier_args, void *modifier_pointer)
- </command>
- </para>
- <para>
- Argument argc is set to 2, following values are set in
- argv array:
- <itemizedlist>
- <listitem>
- <para>argv[0] = server name</para>
- </listitem>
- <listitem>
- <para>argv[1] = message</para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- <listitem>
- <para>
- <option>modifier_args</option>: arguments given to function
- when called
- </para>
- </listitem>
- <listitem>
- <para>
- <option>modifier_pointer</option>: pointer given to function
- when called
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: pointer to new message modifier.
- </para>
- <para>
- Note: function has to return modified string, or NULL if no
- changes are made to message.
- If function returns empty string, then message is dropped and
- will not be read at all by WeeChat (be careful when dropping
- messages!).
- Returned string must have been allocated by malloc() and will
- be freed (with call to free()) automatically by WeeChat after use.
- </para>
- <para>
- Example:
-<screen>
-char *adder (t_weechat_plugin *plugin, int argc, char **argv,
- char *modifier_args, void *modifier_pointer)
-{
- char *string;
- string = malloc (strlen (argv[1]) + 16);
- strcpy (string, argv[1]);
- strcat (string, "test");
- return string;
-}
-...
-t_plugin_modifier *modifier;
-modifier = plugin->modifier_add (plugin, "irc_in", "privmsg",
- &amp;adder, NULL, NULL);
-</screen>
- </para>
- </section>
-
- <section id="secAPI_modifier_remove">
- <title>modifier_remove</title>
-
- <para>
- Prototype:
- <command>
- void modifier_remove (t_weechat_plugin *plugin,
- t_plugin_modifier *modifier)
- </command>
- </para>
- <para>
- Remove a message modifier.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>modifier</option>: modifier to remove
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->modifier_remove (plugin, my_modifier);</screen>
- </para>
- </section>
-
- <section id="secAPI_modifier_remove_all">
- <title>modifier_remove_all</title>
-
- <para>
- Prototype:
- <command>
- void modifier_remove_all (t_weechat_plugin *plugin)
- </command>
- </para>
- <para>
- Remove all modifiers for a plugin.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->modifier_remove_all (plugin);</screen>
- </para>
- </section>
-
- <section id="secAPI_exec_command">
- <title>exec_command</title>
-
- <para>
- Prototype:
- <command>
- void exec_command (t_weechat_plugin
- *plugin, char *server, char *channel, char *command)
- </command>
- </para>
- <para>
- Execute a WeeChat command (or send a message to a channel).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>server</option>: internal name of server for
- executing command (may be NULL)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>channel</option>: name of channel for executing
- command (may be NULL)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>command</option>: command
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Examples:
-<screen>
-plugin->exec_command (plugin, NULL, NULL, "/help nick");
-plugin->exec_command (plugin, "freenode", "#weechat", "hello");
-</screen>
- </para>
- </section>
-
- <section id="secAPI_get_info">
- <title>get_info</title>
-
- <para>
- Prototype:
- <command>
- char *get_info (t_weechat_plugin *plugin,
- char *info, char *server)
- </command>
- </para>
- <para>
- Return an info about WeeChat or a channel.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>info</option> : name of info to read:
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Info</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>version</literal></entry>
- <entry>WeeChat's version</entry>
- </row>
- <row>
- <entry><literal>nick</literal></entry>
- <entry>nick</entry>
- </row>
- <row>
- <entry><literal>channel</literal></entry>
- <entry>
- name of channel (NULL for a server or private)
- </entry>
- </row>
- <row>
- <entry><literal>server</literal></entry>
- <entry>name of server</entry>
- </row>
- <row>
- <entry><literal>type</literal></entry>
- <entry>
- buffer type: 0=standard, 1=DCC, 2=raw IRC data
- </entry>
- </row>
- <row>
- <entry><literal>away</literal></entry>
- <entry>"away" flag</entry>
- </row>
- <row>
- <entry><literal>inactivity</literal></entry>
- <entry>
- number of seconds since last key was pressed
- </entry>
- </row>
- <row>
- <entry><literal>input</literal></entry>
- <entry>
- content of command line for current window
- </entry>
- </row>
- <row>
- <entry><literal>input_mask</literal></entry>
- <entry>
- content of color mask for command line
- </entry>
- </row>
- <row>
- <entry><literal>input_pos</literal></entry>
- <entry>
- cursor position in command line
- </entry>
- </row>
- <row>
- <entry><literal>weechat_dir</literal></entry>
- <entry>
- WeeChat home directory
- (by default: ~/.weechat/)
- </entry>
- </row>
- <row>
- <entry><literal>weechat_libdir</literal></entry>
- <entry>WeeChat system lib directory</entry>
- </row>
- <row>
- <entry><literal>weechat_sharedir</literal></entry>
- <entry>WeeChat system share directory</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </listitem>
- <listitem>
- <para>
- <option>server</option>: internal name of server for
- reading info (if needed)
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: information asked, NULL if not found.
- </para>
- <para>
- Note: result has to be free by a call to "free" function after
- use.
- </para>
- <para>
- Examples:
-<screen>
-char *version = plugin->get_info (plugin, "version", NULL);
-char *nick = plugin->get_info (plugin, "nick", "freenode");
-char *inactivity = plugin->get_info (plugin, "inactivity", NULL);
-
-plugin->print (plugin, NULL, NULL,
- "WeeChat version %s, you are %s on freenode "
- "(inactive for %s seconds)",
- version, nick, inactivity);
-
-if (version)
- free (version);
-if (nick)
- free (nick);
-if (inactivity)
- free (inactivity);
-</screen>
- </para>
- </section>
-
- <section id="secAPI_get_dcc_info">
- <title>get_dcc_info</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_info_dcc *get_dcc_info (t_weechat_plugin *plugin)
- </command>
- </para>
- <para>
- Return list of DCC currently active or finished.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: linked list of DCC.
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Type</entry>
- <entry>Field</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>char *</entry>
- <entry><literal>server</literal></entry>
- <entry>IRC server</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>channel</literal></entry>
- <entry>IRC channel</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>type</literal></entry>
- <entry>
- DCC type:
- 0 = chat received,
- 1 = chat sent,
- 2 = file received,
- 3 = file sent
- </entry>
- </row>
- <row>
- <entry>int*</entry>
- <entry><literal>status</literal></entry>
- <entry>
- DCC status:
- 0 = waiting,
- 1 = connecting,
- 2 = active,
- 3 = finished,
- 4 = failed,
- 5 = interrupted by user
- </entry>
- </row>
- <row>
- <entry>time_t</entry>
- <entry><literal>start_time</literal></entry>
- <entry>date/time of DCC creation</entry>
- </row>
- <row>
- <entry>time_t</entry>
- <entry><literal>start_transfer</literal></entry>
- <entry>date/time of DCC transfer start</entry>
- </row>
- <row>
- <entry>unsigned long</entry>
- <entry><literal>addr</literal></entry>
- <entry>IP address of remote user</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>port</literal></entry>
- <entry>port used for DCC</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>nick</literal></entry>
- <entry>remote nick</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>filename</literal></entry>
- <entry>file name</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>local_filename</literal></entry>
- <entry>local file name</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>filename_suffix</literal></entry>
- <entry>suffix if renaming file</entry>
- </row>
- <row>
- <entry>unsigned long</entry>
- <entry><literal>size</literal></entry>
- <entry>file size</entry>
- </row>
- <row>
- <entry>unsigned long</entry>
- <entry><literal>pos</literal></entry>
- <entry>position in file</entry>
- </row>
- <row>
- <entry>unsigned long</entry>
- <entry><literal>start_resume</literal></entry>
- <entry>start position after interruption</entry>
- </row>
- <row>
- <entry>unsigned long</entry>
- <entry><literal>bytes_per_sec</literal></entry>
- <entry>
- number of bytes per second since transfer start
- </entry>
- </row>
- <row>
- <entry>t_plugin_dcc_info *</entry>
- <entry><literal>prev_dcc</literal></entry>
- <entry>
- pointer to previous DCC info
- </entry>
- </row>
- <row>
- <entry>t_plugin_dcc_info *</entry>
- <entry><literal>next_dcc</literal></entry>
- <entry>
- pointer to next DCC info
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Note: result has to be free by a call to "free_dcc_info" function
- after use.
- </para>
- <para>
- Examples:
-<screen>
-t_plugin_dcc_info *dcc_info = plugin->get_dcc_info (plugin);
-for (ptr_dcc = dcc_info; ptr_dcc; ptr_dcc = ptr_dcc->next_dcc)
-{
- plugin->print_server (plugin, "DCC type=%d, with: %s",
- ptr_dcc->type, ptr_dcc->nick);
-}
-if (dcc_info)
- plugin->free_dcc_info (plugin, dcc_info);
-</screen>
- </para>
- </section>
-
- <section id="secAPI_free_dcc_info">
- <title>free_dcc_info</title>
-
- <para>
- Prototype:
- <command>
- void free_dcc_info (t_weechat_plugin *plugin,
- t_plugin_dcc_info *dcc_info)
- </command>
- </para>
- <para>
- Free memory used by a DCC list.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>dcc_info</option>: pointer to DCC list returned by
- "get_dcc_info" function
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->free_dcc_info (plugin, dcc_info);</screen>
- </para>
- </section>
-
- <section id="secAPI_get_server_info">
- <title>get_server_info</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_server_info *get_server_info (t_weechat_plugin *plugin)
- </command>
- </para>
- <para>
- Return list of IRC servers (connected or not).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: linked list of IRC servers.
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Type</entry>
- <entry>Field</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>char *</entry>
- <entry><literal>name</literal></entry>
- <entry>server internal name</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>autoconnect</literal></entry>
- <entry>1 if autoconnect at start-up, 0 otherwise</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>autoreconnect</literal></entry>
- <entry>
- 1 if autoreconnect when disconnected,
- 0 otherwise
- </entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>autoreconnect_delay</literal></entry>
- <entry>delay before trying again connection</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>command_line</literal></entry>
- <entry>
- 1 if server was on command line (so it is temporary),
- 0 otherwise
- </entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>address</literal></entry>
- <entry>server address (host or IP)</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>port</literal></entry>
- <entry>port</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>ipv6</literal></entry>
- <entry>IPv6 connection</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>ssl</literal></entry>
- <entry>SSL connection</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>password</literal></entry>
- <entry>server password</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>nick1</literal></entry>
- <entry>first nickname</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>nick2</literal></entry>
- <entry>alternate nickname</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>nick3</literal></entry>
- <entry>second alternate nickname</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>username</literal></entry>
- <entry>user name</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>real name</literal></entry>
- <entry>real name</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>command</literal></entry>
- <entry>command run once connected</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>command_delay</literal></entry>
- <entry>delay after execution of command</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>autojoin</literal></entry>
- <entry>channels joined automatically</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>autorejoin</literal></entry>
- <entry>
- 1 if channels are rejoined when kicked,
- 0 otherwise
- </entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>notify_levels</literal></entry>
- <entry>channels notify levels</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>charset_decode_iso</literal></entry>
- <entry>channels charsets for decoding ISO</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>charset_decode_utf</literal></entry>
- <entry>channels charsets for decoding UTF</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>charset_encode</literal></entry>
- <entry>channels charsets for encoding messages</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>is_connected</literal></entry>
- <entry>1 if connected to server, 0 otherwise</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>ssl_connected</literal></entry>
- <entry>1 if connected with SSL, 0 otherwise</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>nick</literal></entry>
- <entry>current nickname</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>is_away</literal></entry>
- <entry>1 if away, 0 otherwise</entry>
- </row>
- <row>
- <entry>time_t</entry>
- <entry><literal>away_time</literal></entry>
- <entry>time when user is marking as away</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>lag</literal></entry>
- <entry>lag (in milliseconds)</entry>
- </row>
- <row>
- <entry>t_plugin_server_info *</entry>
- <entry><literal>prev_server</literal></entry>
- <entry>pointer to previous server info</entry>
- </row>
- <row>
- <entry>t_plugin_server_info *</entry>
- <entry><literal>next_server</literal></entry>
- <entry>pointer to next server info</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Note: result has to be free by a call to "free_server_info"
- function after use.
- </para>
- <para>
- Example:
-<screen>
-t_plugin_server_info *server_info, *ptr_server_info;
-server_info = plugin->get_server_info (plugin);
-if (server_info)
-{
- for (ptr_server_info = server_info; ptr_server_info;
- ptr_server_info = ptr_server_info->next_server)
- {
- plugin->print (plugin, NULL, NULL,
- "server: %s, address: %s, port: %d %s",
- ptr_server_info->name,
- ptr_server_info->address,
- ptr_server_info->port,
- (ptr_server_info->is_connected) ? "(connected)" : "");
- }
- plugin->free_server_info (plugin, server_info);
-}
-</screen>
- </para>
- </section>
-
- <section id="secAPI_free_server_info">
- <title>free_server_info</title>
-
- <para>
- Prototype:
- <command>
- void free_server_info (t_weechat_plugin *plugin,
- t_plugin_server_info *server_info)
- </command>
- </para>
- <para>
- Free memory used by server info list.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>server_info</option>: pointer to server list
- returned by "get_server_info" function
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->free_server_info (plugin, server_info);</screen>
- </para>
- </section>
-
- <section id="secAPI_get_channel_info">
- <title>get_channel_info</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_channel_info *get_channel_info (t_weechat_plugin *plugin,
- char *server)
- </command>
- </para>
- <para>
- Return list of IRC channels for a server.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>server</option>: internal server name
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: linked list of IRC channels for server.
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Type</entry>
- <entry>Field</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>int</entry>
- <entry><literal>type</literal></entry>
- <entry>0 for a channel, 1 for a private</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>name</literal></entry>
- <entry>name of channel</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>topic</literal></entry>
- <entry>topic of channel</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>modes</literal></entry>
- <entry>channel modes</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>limit</literal></entry>
- <entry>user limit</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>key</literal></entry>
- <entry>channel key</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>nicks_count</literal></entry>
- <entry>number of nicks on channel</entry>
- </row>
- <row>
- <entry>t_plugin_channel_info *</entry>
- <entry><literal>prev_channel</literal></entry>
- <entry>pointer to previous channel info</entry>
- </row>
- <row>
- <entry>t_plugin_channel_info *</entry>
- <entry><literal>next_channel</literal></entry>
- <entry>pointer to next channel info</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Note: result has to be free by a call to "free_channel_info"
- function after use.
- </para>
- <para>
- Example:
-<screen>
-t_plugin_channel_info *channel_info, *ptr_chan_info;
-channel_info = plugin->get_channel_info (plugin, "freenode");
-if (channel_info)
-{
- for (ptr_chan_info = channel_info; ptr_chan_info;
- ptr_chan_info = ptr_chan_info->next_channel)
- {
- plugin->print (plugin, NULL, NULL,
- " %s (type %d)",
- ptr_chan_info->name,
- ptr_chan_info->type);
- }
- plugin->free_channel_info (plugin, channel_info);
-}
-</screen>
- </para>
- </section>
-
- <section id="secAPI_free_channel_info">
- <title>free_channel_info</title>
-
- <para>
- Prototype:
- <command>
- void free_channel_info (t_weechat_plugin *plugin,
- t_plugin_channel_info *channel_info)
- </command>
- </para>
- <para>
- Free memory used by channel info list.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>channel_info</option>: pointer to channel info list
- returned by "get_channel_info" function
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->free_channel_info (plugin, channel_info);</screen>
- </para>
- </section>
-
- <section id="secAPI_get_nick_info">
- <title>get_nick_info</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_nick_info *get_nick_info (t_weechat_plugin *plugin,
- char *server, char *channel)
- </command>
- </para>
- <para>
- Return list of nicks for a channel.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>server</option>: internal server name
- </para>
- </listitem>
- <listitem>
- <para>
- <option>channel</option>: channel name
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: linked list of nicks on channel.
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Type</entry>
- <entry>Field</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>char *</entry>
- <entry><literal>nick</literal></entry>
- <entry>nick name</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>host</literal></entry>
- <entry>hostname</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>flags</literal></entry>
- <entry>
- nick flags, binary "or" between values (1 = channel
- owner, 2 = channel admin, 4 = op, 8 = halfop,
- 16 = voice, 32 = away)
- </entry>
- </row>
- <row>
- <entry>t_plugin_nick_info *</entry>
- <entry><literal>prev_nick</literal></entry>
- <entry>pointer to previous nick info</entry>
- </row>
- <row>
- <entry>t_plugin_nick_info *</entry>
- <entry><literal>next_nick</literal></entry>
- <entry>pointer to next nick info</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Note: result has to be free by a call to "free_nick_info"
- function after use.
- </para>
- <para>
- Example:
-<screen>
-t_plugin_nick_info *nick_info, *ptr_nick_info;
-nick_info = plugin->get_nick_info (plugin, "freenode", "#weechat");
-if (nick_info)
-{
- for (ptr_nick_info = nick_info; ptr_nick_info;
- ptr_nick_info = ptr_nick_info->next_nick)
- {
- plugin->print (plugin, NULL, NULL,
- " %s (flags: %d)",
- ptr_nick_info->nick,
- ptr_nick_info->flags);
- }
- plugin->free_nick_info (plugin, nick_info);
-}
-</screen>
- </para>
- </section>
-
- <section id="secAPI_free_nick_info">
- <title>free_nick_info</title>
-
- <para>
- Prototype:
- <command>
- void free_nick_info (t_weechat_plugin *plugin,
- t_plugin_nick_info *nick_info)
- </command>
- </para>
- <para>
- Free memory used by nick info list.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>nick_info</option>: pointer to nick info list
- returned by "get_nick_info" function
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->free_nick_info (plugin, nick_info);</screen>
- </para>
- </section>
-
- <section id="secAPI_get_config">
- <title>get_config</title>
-
- <para>
- Prototype:
- <command>
- char *get_config (t_weechat_plugin *plugin, char *option)
- </command>
- </para>
- <para>
- Return value of a WeeChat config option.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>option</option>: name of option to read
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: option value, NULL if not found.
- </para>
- <para>
- Note: result has to be free by a call to "free" function after
- use.
- </para>
- <para>
- Examples:
-<screen>
-char *value1 = plugin->get_config (plugin, "look_set_title");
-char *value2 = plugin->get_config (plugin, "freenode.server_autojoin");
-</screen>
- </para>
- </section>
-
- <section id="secAPI_set_config">
- <title>set_config</title>
-
- <para>
- Prototype:
- <command>
- int set_config (t_weechat_plugin *plugin,
- char *option, char *value)
- </command>
- </para>
- <para>
- Update value of a WeeChat config option.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>option</option>: name of option to update
- </para>
- </listitem>
- <listitem>
- <para>
- <option>value</option>: new value for option
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: 1 if option was successfully updated, 0 if an
- error occurred.
- </para>
- <para>
- Example:
-<screen>
-plugin->set_config (plugin, "look_nicklist", "off");
-</screen>
- </para>
- </section>
-
- <section id="secAPI_get_plugin_config">
- <title>get_plugin_config</title>
-
- <para>
- Prototype:
- <command>
- char *get_plugin_config (t_weechat_plugin *plugin, char *option)
- </command>
- </para>
- <para>
- Return value of a plugin option.
- Option is read from file "<literal>~/.weechat/plugins.rc</literal>"
- and is like: "<literal>plugin.option=value</literal>"
- (note: plugin name is automatically added).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>option</option>: name of option to read
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: option value, NULL if not found.
- </para>
- <para>
- Note: result has to be free by a call to "free" function after
- use.
- </para>
- <para>
- Example:
-<screen>
-char *value = plugin->get_plugin_config (plugin, "my_var");
-</screen>
- </para>
- </section>
-
- <section id="secAPI_set_plugin_config">
- <title>set_plugin_config</title>
-
- <para>
- Prototype:
- <command>
- int set_plugin_config (t_weechat_plugin *plugin,
- char *option, char *value)
- </command>
- </para>
- <para>
- Update value of a plugin option.
- Option is written in file "<literal>~/.weechat/plugins.rc</literal>"
- and is like: "<literal>plugin.option=value</literal>"
- (note: plugin name is automatically added).
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>option</option>: name of option to update
- </para>
- </listitem>
- <listitem>
- <para>
- <option>value</option>: new value for option
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: 1 if option was successfully updated, 0 if an
- error occurred.
- </para>
- <para>
- Example:
-<screen>
-plugin->set_plugin_config (plugin, "my_var", "value");
-</screen>
- </para>
- </section>
-
- <section id="secAPI_get_irc_color">
- <title>get_irc_color</title>
-
- <para>
- Prototype:
- <command>
- int get_irc_color (t_weechat_plugin *plugin,
- char *color_name)
- </command>
- </para>
- <para>
- Get IRC color index with name.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>color_name</option>: color name
- Allowed colors are:
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Color name</entry>
- <entry>Value</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>white</entry>
- <entry>0</entry>
- </row>
- <row>
- <entry>black</entry>
- <entry>1</entry>
- </row>
- <row>
- <entry>blue</entry>
- <entry>2</entry>
- </row>
- <row>
- <entry>green</entry>
- <entry>3</entry>
- </row>
- <row>
- <entry>lightred</entry>
- <entry>4</entry>
- </row>
- <row>
- <entry>red</entry>
- <entry>5</entry>
- </row>
- <row>
- <entry>magenta</entry>
- <entry>6</entry>
- </row>
- <row>
- <entry>brown</entry>
- <entry>7</entry>
- </row>
- <row>
- <entry>yellow</entry>
- <entry>8</entry>
- </row>
- <row>
- <entry>lightgreen</entry>
- <entry>9</entry>
- </row>
- <row>
- <entry>cyan</entry>
- <entry>10</entry>
- </row>
- <row>
- <entry>lightcyan</entry>
- <entry>11</entry>
- </row>
- <row>
- <entry>lightblue</entry>
- <entry>12</entry>
- </row>
- <row>
- <entry>lightmagenta</entry>
- <entry>13</entry>
- </row>
- <row>
- <entry>gray</entry>
- <entry>14</entry>
- </row>
- <row>
- <entry>lightgray</entry>
- <entry>15</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: IRC color index, -1 if color is not found.
- </para>
- <para>
- Example:
-<screen>
-int color_blue = plugin->get_irc_color (plugin, "blue"); /* return 2 */
-</screen>
- </para>
- </section>
-
- <section id="secAPI_input_color">
- <title>input_color</title>
-
- <para>
- Prototype:
- <command>
- void input_color (t_weechat_plugin *plugin,
- int color, int start, int length)
- </command>
- </para>
- <para>
- Add color in input buffer.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>color</option>: color for text (if &lt; 0, then input
- buffer is refresh, and there's no change in input buffer
- content)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>start</option>: start position for color (if &lt; 0,
- then mask is reinitialized)
- </para>
- </listitem>
- <listitem>
- <para>
- <option>length</option>: length for color (if &lt;= 0,
- then mask is reinitialized)
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
-<screen>
-plugin->input_color (plugin, plugin->get_irc_color (plugin, "blue"), 10, 5);
-</screen>
- </para>
- </section>
-
- <section id="secAPI_get_window_info">
- <title>get_window_info</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_window_info *get_window_info (t_weechat_plugin *plugin)
- </command>
- </para>
- <para>
- Return list of WeeChat windows.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: linked list of WeeChat windows.
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Type</entry>
- <entry>Field</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>int</entry>
- <entry><literal>win_x</literal></entry>
- <entry>horizontal position of window</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>win_y</literal></entry>
- <entry>vertical position of window</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>win_width</literal></entry>
- <entry>width of window</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>win_height</literal></entry>
- <entry>height of window</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>win_width_pct</literal></entry>
- <entry>width % (compared to parent window)</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>win_height_pct</literal></entry>
- <entry>height % (compared to parent window)</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>num_buffer</literal></entry>
- <entry>number of displayed buffer</entry>
- </row>
- <row>
- <entry>t_plugin_window_info *</entry>
- <entry><literal>prev_window</literal></entry>
- <entry>pointer to previous window info</entry>
- </row>
- <row>
- <entry>t_plugin_window_info *</entry>
- <entry><literal>next_window</literal></entry>
- <entry>pointer to next window info</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Note: result has to be free by a call to "free_window_info"
- function after use.
- </para>
- <para>
- Example:
-<screen>
-t_plugin_window_info *window_info, *ptr_window;
-
-window_info = plugin->get_window_info (plugin);
-if (window_info)
-{
- for (ptr_window = window_info; ptr_window; ptr_window = ptr_window->next_window)
- {
- plugin->print (plugin, NULL, NULL, "window info");
- plugin->print (plugin, NULL, NULL, "(%d,%d), size: %dx%d, %%size: %d%%x%d%%",
- ptr_window->win_x, ptr_window->win_y,
- ptr_window->win_width, ptr_window->win_height,
- ptr_window->win_width_pct, ptr_window->win_height_pct);
- plugin->print (plugin, NULL, NULL, "num_buffer: %d", ptr_window->num_buffer);
- }
- plugin->free_window_info (plugin, window_info);
-}
-else
- plugin->print (plugin, NULL, NULL, "no window info!");
-</screen>
- </para>
- </section>
-
- <section id="secAPI_free_window_info">
- <title>free_window_info</title>
-
- <para>
- Prototype:
- <command>
- void free_window_info (t_weechat_plugin *plugin,
- t_plugin_window_info *window_info)
- </command>
- </para>
- <para>
- Free memory used by window info list.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>window_info</option>: pointer to window info list
- returned by "get_window_info" function
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->free_window_info (plugin, window_info);</screen>
- </para>
- </section>
-
- <section id="secAPI_get_buffer_info">
- <title>get_buffer_info</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_buffer_info *get_buffer_info (t_weechat_plugin *plugin)
- </command>
- </para>
- <para>
- Return list of WeeChat buffers.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: linked list of WeeChat buffers.
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Type</entry>
- <entry>Field</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>int</entry>
- <entry><literal>type</literal></entry>
- <entry>buffer type: 0=standard, 1=DCC, 2=raw IRC data</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>number</literal></entry>
- <entry>buffer number</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>num_displayed</literal></entry>
- <entry>number of windows displaying buffer</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>server_name</literal></entry>
- <entry>server name for buffer (may be NULL)</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>channel_name</literal></entry>
- <entry>channel name for buffer (may be NULL)</entry>
- </row>
- <row>
- <entry>int</entry>
- <entry><literal>notify_level</literal></entry>
- <entry>notify level for buffer</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>log_filename</literal></entry>
- <entry>log filename (NULL means not logging)</entry>
- </row>
- <row>
- <entry>t_plugin_buffer_info *</entry>
- <entry><literal>prev_buffer</literal></entry>
- <entry>pointer to previous buffer info</entry>
- </row>
- <row>
- <entry>t_plugin_buffer_info *</entry>
- <entry><literal>next_buffer</literal></entry>
- <entry>pointer to next buffer info</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Note: result has to be free by a call to "free_buffer_info"
- function after use.
- </para>
- <para>
- Example:
-<screen>
-t_plugin_buffer_info *buffer_info, *ptr_buffer;
-
-buffer_info = plugin->get_buffer_info (plugin);
-if (buffer_info)
-{
- for (ptr_buffer = buffer_info; ptr_buffer; ptr_buffer = ptr_buffer->next_buffer)
- {
- plugin->print (plugin, NULL, NULL, "buffer info");
- plugin->print (plugin, NULL, NULL, "type: %d", ptr_buffer->type);
- plugin->print (plugin, NULL, NULL, "number: %d", ptr_buffer->number);
- plugin->print (plugin, NULL, NULL, "num_displayed: %d", ptr_buffer->num_displayed);
- plugin->print (plugin, NULL, NULL, "server: %s", ptr_buffer->server_name);
- plugin->print (plugin, NULL, NULL, "channel: %s", ptr_buffer->channel_name);
- plugin->print (plugin, NULL, NULL, "notify level: %d", ptr_buffer->notify_level);
- plugin->print (plugin, NULL, NULL, "log filename: %s", ptr_buffer->log_filename);
- }
- plugin->free_buffer_info (plugin, buffer_info);
-}
-else
- plugin->print (plugin, NULL, NULL, "no buffer info!");
-</screen>
- </para>
- </section>
-
- <section id="secAPI_free_buffer_info">
- <title>free_buffer_info</title>
-
- <para>
- Prototype:
- <command>
- void free_buffer_info (t_weechat_plugin *plugin,
- t_plugin_buffer_info *buffer_info)
- </command>
- </para>
- <para>
- Free memory used by buffer info list.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>buffer_info</option>: pointer to buffer info list
- returned by "get_buffer_info" function
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->free_buffer_info (plugin, buffer_info);</screen>
- </para>
- </section>
-
- <section id="secAPI_get_buffer_data">
- <title>get_buffer_data</title>
-
- <para>
- Prototype:
- <command>
- t_plugin_buffer_data *get_buffer_info (t_weechat_plugin *plugin,
- char *server, char *channel)
- </command>
- </para>
- <para>
- Return content of buffer.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>server</option>: internal name of server
- </para>
- </listitem>
- <listitem>
- <para>
- <option>channel</option>: channel name
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: buffer content (linked list of lines).
- <informaltable colsep="0" frame="none">
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Type</entry>
- <entry>Field</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>time_t</entry>
- <entry><literal>date</literal></entry>
- <entry>date and time</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>nick</literal></entry>
- <entry>nick</entry>
- </row>
- <row>
- <entry>char *</entry>
- <entry><literal>data</literal></entry>
- <entry>line content (color codes are removed)</entry>
- </row>
- <row>
- <entry>t_plugin_buffer_line *</entry>
- <entry><literal>prev_line</literal></entry>
- <entry>pointer to previous line</entry>
- </row>
- <row>
- <entry>t_plugin_buffer_line *</entry>
- <entry><literal>next_line</literal></entry>
- <entry>pointer to next line</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- <para>
- Note: result has to be free by a call to "free_buffer_data"
- function after use.
- </para>
- <para>
- Example:
-<screen>
-t_plugin_buffer_line *buffer_line, *ptr_line;
-char text_time[256];
-
-buffer_line = plugin->get_buffer_data (plugin);
-if (buffer_line)
-{
- for (ptr_line = buffer_line; ptr_line; ptr_line = ptr_line->next_line)
- {
- strftime (text_time, sizeof (text_time), "%x %X", localtime (&amp;(ptr_line->date)));
- plugin->print (plugin, NULL, NULL, "date: %s, nick: %s, data: %s",
- text_time, ptr_line->nick, ptr_line->data);
- }
- plugin->free_buffer_data (plugin, buffer_line);
-}
-</screen>
- </para>
- </section>
-
- <section id="secAPI_free_buffer_data">
- <title>free_buffer_data</title>
-
- <para>
- Prototype:
- <command>
- void free_buffer_data (t_weechat_plugin *plugin,
- t_plugin_buffer_line *buffer_line)
- </command>
- </para>
- <para>
- Free memory used by buffer line list.
- </para>
- <para>
- Arguments:
- <itemizedlist>
- <listitem>
- <para>
- <option>plugin</option>: pointer to plugin structure
- </para>
- </listitem>
- <listitem>
- <para>
- <option>buffer_line</option>: pointer to buffer line list
- returned by "get_buffer_data" function
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Return value: none.
- </para>
- <para>
- Example:
- <screen>plugin->free_buffer_data (plugin, buffer_line);</screen>
- </para>
- </section>
-
- -->
-
-</section>
+</chapter>
diff --git a/doc/en/dev/plugin_c_api.en.xml b/doc/en/dev/plugin_c_api.en.xml
new file mode 100644
index 000000000..59402a34f
--- /dev/null
+++ b/doc/en/dev/plugin_c_api.en.xml
@@ -0,0 +1,7300 @@
+<?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/>.
+
+-->
+
+<section id="secPluginCApi">
+ <title>C plugin API</title>
+
+ <!-- =============================[ plugins ]============================ -->
+
+ <section id="secPluginCApi_plugins">
+ <title>Plugins</title>
+
+ <para>
+ Functions to get infos about plugins.
+ </para>
+
+ <section id="secPluginCApi_weechat_plugin_get_name">
+ <title>weechat_plugin_get_name</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_plugin_get_name (struct t_weechat_plugin *plugin);
+</programlisting>
+ </para>
+ <para>
+ Get plugin name (return "core" for WeeChat - NULL pointer).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: plugin pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+ <screen>char *name = weechat_plugin_get_name (plugin);</screen>
+ </para>
+ </section>
+
+ </section>
+
+ <!-- =============================[ strings ]============================ -->
+
+ <section id="secPluginCApi_strings">
+ <title>Strings</title>
+
+ <para>
+ Many string functions below are already available thru standard C
+ functions, but it's recommended to use functions in this API because
+ they are ok with UTF-8 and locale.
+ </para>
+
+ <section id="secPluginCApi_weechat_charset_set">
+ <title>weechat_charset_set</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_charset_set (const char *charset);
+</programlisting>
+ </para>
+ <para>
+ Set new plugin charset.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>charset</option>: new charset to use
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+ <screen>weechat_charset_set (plugin, "iso-8859-1");</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_iconv_to_internal">
+ <title>weechat_iconv_to_internal</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_iconv_to_internal (const char *charset, const char *string);
+</programlisting>
+ </para>
+ <para>
+ Convert string to WeeChat internal charset (UTF-8).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>charset</option>: charset to convert
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>string</option>: string to convert
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: converted string.
+ </para>
+ <note>
+ <para>
+ Result has to be free by a call to "free" after use.
+ </para>
+ </note>
+ <para>
+ Example:
+ <screen>char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string: é à");</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_iconv_from_internal">
+ <title>weechat_iconv_from_internal</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_iconv_from_internal (const char *charset, const char *string);
+</programlisting>
+ </para>
+ <para>
+ Convert string from internal WeeChat charset (UTF-8) to another.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>charset</option>: target charset
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>string</option>: string to convert
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: converted string.
+ </para>
+ <note>
+ <para>
+ Result has to be free by a call to "free" after use.
+ </para>
+ </note>
+ <para>
+ Example:
+ <screen>char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_gettext">
+ <title>weechat_gettext</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_gettext (const char *string);
+</programlisting>
+ </para>
+ <para>
+ Return translated string (depends on local language).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string to translate
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: translated string.
+ </para>
+ <para>
+ Example:
+ <screen>char *str = weechat_gettext ("hello !");</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_ngettext">
+ <title>weechat_ngettext</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_ngettext (const char *string, const char *plural, int count);
+</programlisting>
+ </para>
+ <para>
+ Return translated string, using single or plural form, according to
+ count.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>single</option>: string to translate (single form)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>plural</option>: string to translate (plural form)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>count</option>: used to choose between single and plural
+ form
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: translated string.
+ </para>
+ <para>
+ Example:
+ <screen>char *str = weechat_ngettext ("file", "files", num_files);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_strndup">
+ <title>weechat_strndup</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_strndup (const char *string, int length);
+</programlisting>
+ </para>
+ <para>
+ Return duplicated string, with max "length" chars.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string to duplicate
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>length</option>: max chars to duplicate
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: duplicated string.
+ </para>
+ <note>
+ <para>
+ Result has to be free by a call to "free" after use.
+ </para>
+ </note>
+ <para>
+ Example:
+ <screen>char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_tolower">
+ <title>weechat_string_tolower</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_string_tolower (const char *string);
+</programlisting>
+ </para>
+ <para>
+ Convert UTF-8 string to lower case.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string to convert
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>weechat_string_tolower ("AbCdEé"); /* result: "abcdeé" */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_toupper">
+ <title>weechat_string_toupper</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_string_toupper (const char *string);
+</programlisting>
+ </para>
+ <para>
+ Convert UTF-8 string to upper case.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string to convert
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>weechat_string_toupper ("AbCdEé"); /* result: "ABCDEé" */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_strcasecmp">
+ <title>weechat_strcasecmp</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_strcasecmp (const char *string1, const char *string2);
+</programlisting>
+ </para>
+ <para>
+ Locale and case independent string comparison.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string1</option>: first string for comparison
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>string2</option>: second string for comparison
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: difference between two strings: negative if
+ string1 &lt; string2, zero if string1 == string2, positive if
+ string1 &gt; string2
+ </para>
+ <para>
+ Example:
+ <screen>int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */ </screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_strncasecmp">
+ <title>weechat_strncasecmp</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_strncasecmp (const char *string1, const char *string2, int max);
+</programlisting>
+ </para>
+ <para>
+ Locale and case independent string comparison, for "max" chars.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string1</option>: first string for comparison
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>string2</option>: second string for comparison
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>max</option>: max number of chars for comparison
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: difference between two strings: negative if
+ string1 &lt; string2, zero if string1 == string2, positive if
+ string1 &gt; string2
+ </para>
+ <para>
+ Example:
+ <screen>int diff = weechat_strncasecmp ("aaa", "CCC", 2); /* == -2 */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_strcmp_ignore_chars">
+ <title>weechat_strcmp_ignore_chars</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_strcmp_ignore_chars (const char *string1, const char *string2,
+ const char *chars_ignored, int case_sensitive);
+</programlisting>
+ </para>
+ <para>
+ Locale (and optionally case independent) string comparison, ignoring
+ some chars.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string1</option>: first string for comparison
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>string2</option>: second string for comparison
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>chars_ignored</option>: string with chars to ignore
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>case_sensitive</option>: 1 for case sensitive comparison,
+ 0 otherwise
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: difference between two strings: negative if
+ string1 &lt; string2, zero if string1 == string2, positive if
+ string1 &gt; string2
+ </para>
+ <para>
+ Example:
+ <screen>int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_strcasestr">
+ <title>weechat_strcasestr</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_strcasestr (const char *string, const char *search);
+</programlisting>
+ </para>
+ <para>
+ Locale and case independent string search.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>search</option>: string to search in "string"
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to string found, or NULL if not found
+ </para>
+ <para>
+ Example:
+ <screen>char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_match">
+ <title>weechat_string_match</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_string_match (const char *string, const char *mask,
+ int case_sensitive);
+</programlisting>
+ </para>
+ <para>
+ Check if a string matches a mask. Mask may begin or end with "*" (no
+ other "*" are allowed inside mask).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>mask</option>: mask
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>case_sensitive</option>: 1 for case sensitive search,
+ otherwise 0
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if string matches mask, otherwise 0.
+ </para>
+ <para>
+ Examples:
+<screen>
+int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */
+int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */
+int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_replace">
+ <title>weechat_string_replace</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_string_replace (const char *string, const char *search,
+ const char *replace);
+</programlisting>
+ </para>
+ <para>
+ Replace "search" string by new one in a string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>search</option>: string to replace
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>replace</option>: replacement for "search" string
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: string with "search" replaced by "replace".
+ </para>
+ <note>
+ <para>
+ Result has to be free by a call to "free" after use.
+ </para>
+ </note>
+ <para>
+ Example:
+ <screen>char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_remove_quotes">
+ <title>weechat_string_remove_quotes</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_string_remove_quotes (const char *string, const char *quotes);
+</programlisting>
+ </para>
+ <para>
+ Remove quotes at beginning/end of string (ignore spaces if there are
+ before first quote or after last quote).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>quotes</option>: string with list of quotes
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: string without quotes at beginning/end.
+ </para>
+ <note>
+ <para>
+ Result has to be free by a call to "free" after use.
+ </para>
+ </note>
+ <para>
+ Example:
+ <screen>char *str = weechat_string_remove_quotes (string, " 'abc' ", "'"); /* result: "abc" */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_strip">
+ <title>weechat_string_strip</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_string_strip (const char *string, int left, int right,
+ const char *chars);
+</programlisting>
+ </para>
+ <para>
+ Strip chars at beginning and/or end of string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>left</option>: strip left chars if different from 0
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>right</option>: strip right chars if different from 0
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>chars</option>: string with chars to strip
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: stripped string.
+ </para>
+ <note>
+ <para>
+ Result has to be free by a call to "free" after use.
+ </para>
+ </note>
+ <para>
+ Example:
+ <screen>char *str = weechat_strip (string, " ", 0, 1); /* remove spaces at end of string */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_has_highlight">
+ <title>weechat_string_has_highlight</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_string_has_highlight (const char *string,
+ const char highlight_words);
+</programlisting>
+ </para>
+ <para>
+ Check if a string has highlights, using list of highlight words.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>highlight_words</option>: list of highlight words,
+ separated by comma
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if string has one or more highlights, 0 otherwise.
+ </para>
+ <para>
+ Example:
+ <screen>if (weechat_string_has_highlight (string, "word1,word2")) ...</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_mask_to_regex">
+ <title>weechat_string_mask_to_regex</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_string_mask_to_regex (const char *mask);
+</programlisting>
+ </para>
+ <para>
+ Return a regex, built with a mask, where only special char is "*".
+ All special chars for regex are escaped.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>mask</option>: mask
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: regex.
+ </para>
+ <para>
+ Example:
+ <screen>char *regex = weechat_string_mask_to_regex ("test*mask");</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_explode">
+ <title>weechat_string_explode</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char **weechat_string_explode (const char *string,
+ const char *separators, int keep_eol,
+ int num_items_max, int *num_items);
+</programlisting>
+ </para>
+ <para>
+ Explode a string according to one or more delimiter(s).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string to explode
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>separators</option>: delimiters used for explosion
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>keep_eol</option>: if different from 0, then each
+ argument will contain all string until end of line (see example
+ below)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>num_items_max</option>: maximum number of items
+ created (0 = no limit)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>num_items</option>: pointer to int which will
+ contain number of items created
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: array of strings, NULL if problem.
+ </para>
+ <note>
+ <para>
+ Result has to be free by a call to "weechat_string_free_exploded"
+ after use.
+ </para>
+ </note>
+ <para>
+ Examples:
+ <screen>
+char **argv;
+int argc;
+argv = weechat_string_explode ("abc de fghi", " ", 0, 0, &amp;argc);
+/* result: argv[0] == "abc"
+ argv[1] == "de"
+ argv[2] == "fghi"
+ argv[3] == NULL
+ argc == 3
+*/
+weechat_string_free_exploded (argv);
+
+argv = weechat_string_explode ("abc de fghi", " ", 1, 0, &amp;argc);
+/* result: argv[0] == "abc de fghi"
+ argv[1] == "de fghi"
+ argv[2] == "fghi"
+ argv[3] == NULL
+ argc == 3
+*/
+weechat_string_free_exploded (argv);
+ </screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_free_exploded">
+ <title>weechat_string_free_exploded</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_string_free_exploded (char **exploded_string);
+</programlisting>
+ </para>
+ <para>
+ Free memory used by a string explosion.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>exploded_string</option>: string exploded by
+ "weechat_string_explode" function
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>
+char *argv;
+int argc;
+argv = weechat_string_explode (string, " ", 0, 0, &amp;argc);
+...
+weechat_string_free_exploded (, argv);
+ </screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_build_with_exploded">
+ <title>weechat_string_build_with_exploded</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char **weechat_string_build_with_exploded (char **exploded_string,
+ const char *separator);
+</programlisting>
+ </para>
+ <para>
+ Build a string with exploded string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>exploded_string</option>: string exploded by
+ "weechat_string_explode" function
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>separator</option>: string used to separate strings
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: string built with exploded string.
+ </para>
+ <note>
+ <para>
+ Result has to be free by a call to "free" after use.
+ </para>
+ </note>
+ <para>
+ Example:
+ <screen>
+char **argv;
+int argc;
+argv = weechat_string_explode ("abc def ghi", " ", 0, 0, &amp;argc);
+char *string = weechat_string_build_with_exploded (argv, ";");
+/* string == "abc;def;ghi" */
+ </screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_split_command">
+ <title>weechat_string_split_command</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char **weechat_string_split_command (const char *command, char separator);
+</programlisting>
+ </para>
+ <para>
+ Split a list of commands separated by 'separator' (which can be escaped
+ by '\' in string).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>command</option>: command to split
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>separator</option>: separator
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: array of strings, NULL if problem.
+ </para>
+ <note>
+ <para>
+ Result has to be free by a call to
+ "weechat_string_free_splitted_command" after use.
+ </para>
+ </note>
+ <para>
+ Example:
+ <screen>char **argv = weechat_string_split_command ("/command1;/command2", ';');</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_string_splitted_command">
+ <title>weechat_string_free_splitted_command</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_string_free_splitted_command (char **splitted_command);
+</programlisting>
+ </para>
+ <para>
+ Free memory used by a splitted command.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>splitted_command</option>: command splitted by
+ "weechat_string_split_commaand" function
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>
+char **argv = weechat_string_split_command ("/command1;/command2", ';');
+...
+weechat_string_free_splitted_command (argv);
+ </screen>
+ </para>
+ </section>
+
+ </section>
+
+ <!-- ==============================[ UTF-8 ]============================= -->
+
+ <section id="secPluginCApi_utf8">
+ <title>UTF-8</title>
+
+ <para>
+ Some UTF-8 string functions.
+ </para>
+
+ <section id="secPluginCApi_weechat_utf8_has_8bits">
+ <title>weechat_utf8_has_8bits</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_utf8_has_8bits (const char *string);
+</programlisting>
+ </para>
+ <para>
+ Check if a string has 8-bits chars.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if string has 8-buts chars, 0 if only 7-bits chars.
+ </para>
+ <para>
+ Example:
+ <screen>if (weechat_utf8_has_8bits (string)) ...</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_is_valid">
+ <title>weechat_utf8_is_valid</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_utf8_is_valid (const char *string, char **error);
+</programlisting>
+ </para>
+ <para>
+ Check if a string is UTF-8 valid.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>error</option>: if not NULL, it is set with first non
+ valid UTF-8 char in string, if any
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if UTF-8 string is valid, 0 otherwise.
+ </para>
+ <para>
+ Example:
+ <screen>
+char *error;
+if (weechat_utf8_is_valid (string, &amp;error)) ...
+ </screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_normalize">
+ <title>weechat_utf8_normalize</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_utf8_normalize (const char *string, char replacement);
+</programlisting>
+ </para>
+ <para>
+ Normalize UTF-8 string: remove non UTF-8 chars and replace them by a
+ char
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>replacement</option>: replacement char for non UTF-8 chars
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>weechat_utf8_normalize (string, '?');</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_prev_char">
+ <title>weechat_utf8_prev_char</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_utf8_prev_char (const char *string_start, const char *string);
+</programlisting>
+ </para>
+ <para>
+ Return previous UTF-8 char in a string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string_start</option>: start of string (function will not
+ return a char before this pointer)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>string</option>: pointer to string (must be >=
+ string_start)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to previous UTF-8 char, NULL if not found
+ (start of string reached)
+ </para>
+ <para>
+ Example:
+ <screen>char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_next_char">
+ <title>weechat_utf8_next_char</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_utf8_next_char (const char *string);
+</programlisting>
+ </para>
+ <para>
+ Return next UTF-8 char in a string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to next UTF-8 char, NULL if not found
+ (end of string reached)
+ </para>
+ <para>
+ Example:
+ <screen>char *next_char = weechat_utf8_next_char (string);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_char_size">
+ <title>weechat_utf8_char_size</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_utf8_char_size (const char *string);
+</programlisting>
+ </para>
+ <para>
+ Return UTF-8 char size (in bytes).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: UTF-8 char size (in bytes).
+ </para>
+ <para>
+ Example:
+ <screen>int char_size = weechat_utf8_char_size ("être"); /* == 2 */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_strlen">
+ <title>weechat_utf8_strlen</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_utf8_strlen (const char *string);
+</programlisting>
+ </para>
+ <para>
+ Return UTF-8 string length (multi-byte char is considered as 1 char).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: UTF-8 string length (number of real chars).
+ </para>
+ <para>
+ Example:
+ <screen>int length = weechat_utf8_strlen ("chêne"); /* == 5 */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_strnlen">
+ <title>weechat_utf8_strnlen</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_utf8_strnlen (const char *string, int bytes);
+</programlisting>
+ </para>
+ <para>
+ Return UTF-8 string length (multi-byte char is considered as 1 char),
+ for max bytes in string
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>bytes</option>: max bytes in string
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: UTF-8 string length (number of real chars).
+ </para>
+ <para>
+ Example:
+ <screen>int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_strlen_screen">
+ <title>weechat_utf8_strlen_screen</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_utf8_strlen_screen (const char *string);
+</programlisting>
+ </para>
+ <para>
+ Return number of chars needed on screen to display UTF-8 string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: number of chars needed on screen to display UTF-8 string.
+ </para>
+ <para>
+ Example:
+ <screen>int length_on_screen = weechat_utf8_strlen_screen ("&#x4E1C;"); /* == 2 */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_charcasecmp">
+ <title>weechat_utf8_charcasecmp</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_utf8_charcasecmp (const char *string1, const char *string2);
+</programlisting>
+ </para>
+ <para>
+ Compare two UTF-8 chars (case is ignored).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string1</option>: first string for comparison
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>string2</option>: second string for comparison
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: difference between first char of each string: negative if
+ char1 &lt; char2, zero if char1 == char2, positive if char1 &gt; char2
+ </para>
+ <para>
+ Example:
+ <screen>if (weechat_utf8_charcasecmp (string1, string2) != 0) ...</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_char_size_screen">
+ <title>weechat_utf8_char_size_screen</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_utf8_char_size_screen (const char *string);
+</programlisting>
+ </para>
+ <para>
+ Return number of chars needed on screen to display UTF-8 char.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: number of chars needed on screen to display UTF-8 char.
+ </para>
+ <para>
+ Example:
+ <screen>int length_on_screen = weechat_utf8_char_size_screen (string)</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_add_offset">
+ <title>weechat_utf8_add_offset</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_utf8_add_offset (const char *string, int offset);
+</programlisting>
+ </para>
+ <para>
+ Move forward N chars in an UTF-8 string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>offset</option>: number of chars
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to string, N chars after (NULL if it's not
+ reachable).
+ </para>
+ <para>
+ Example:
+ <screen>char *ptr = weechat_utf8_add_offset ("chêne", 3); /* points to "ne" */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_real_pos">
+ <title>weechat_utf8_real_pos</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_utf8_real_pos (const char *string, int pos);
+</programlisting>
+ </para>
+ <para>
+ Get real position in UTF-8 string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>pos</option>: position in chars
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: real position (in bytes) for "pos" chars in string.
+ </para>
+ <para>
+ Example:
+ <screen>int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_utf8_pos">
+ <title>weechat_utf8_pos</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_utf8_pos (const char *string, int real_pos);
+</programlisting>
+ </para>
+ <para>
+ Get position in UTF-8 string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>string</option>: string
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>real_pos</option>: position in bytes
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: position (in chars) for "real_pos" bytes in string.
+ </para>
+ <para>
+ Example:
+ <screen>int pos = weechat_utf8_real_pos ("chêne", 4); /* == 3 */</screen>
+ </para>
+ </section>
+
+ </section>
+
+ <!-- ===========================[ directories ]========================== -->
+
+ <section id="secPluginCApi_directories">
+ <title>Directories</title>
+
+ <para>
+ Some functions related to directories.
+ </para>
+
+ <section id="secPluginCApi_weechat_mkdir_home">
+ <title>weechat_mkdir_home</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_mkdir_home (char *directory, int mode);
+</programlisting>
+ </para>
+ <para>
+ Create a directory in WeeChat home.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>directory</option>: directory to create
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>mode</option>: mode for new directory
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if directory was successfully created, 0 if an
+ error occurred.
+ </para>
+ <para>
+ Example:
+ <screen>if (!weechat_mkdir_home ("temp")) ... </screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_mkdir">
+ <title>weechat_mkdir</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_mkdir (char *directory, int mode);
+</programlisting>
+ </para>
+ <para>
+ Create a directory.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>directory</option>: directory to create
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>mode</option>: mode for new directory
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if directory was successfully created, 0 if an
+ error occurred.
+ </para>
+ <para>
+ Example:
+ <screen>if (!weechat_mkdir ("/tmp/mydir")) ... </screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_mkdir_parents">
+ <title>weechat_mkdir_parents</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_mkdir_parents (char *directory, int mode);
+</programlisting>
+ </para>
+ <para>
+ Create a directory and make parent directories as needed.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>directory</option>: directory to create
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>mode</option>: mode for new directory (and parents)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if directory was successfully created, 0 if an
+ error occurred.
+ </para>
+ <para>
+ Example:
+ <screen>if (!weechat_mkdir_parents ("/tmp/my/dir")) ... </screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_exec_on_files">
+ <title>weechat_exec_on_files</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_exec_on_files (const char *directory, void *data,
+ int (*callback)(void *data, const char *filename));
+</programlisting>
+ </para>
+ <para>
+ Find files in a directory and execute a callback on each file.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>directory</option>: directory for searching files
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>data</option>: pointer given to callback when calling it
+ found
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback</option>: function called for each file
+ found
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+<screen>
+int callback (void *data, const char *filename)
+{
+ /* ... */
+ return 1;
+}
+...
+plugin->exec_on_files (plugin, "/tmp", &amp;callback);
+</screen>
+ </para>
+ </section>
+
+ </section>
+
+ <!-- ==============================[ util ]============================== -->
+
+ <section id="secPluginCApi_util">
+ <title>Util</title>
+
+ <para>
+ Some useful functions.
+ </para>
+
+ <section id="secPluginCApi_weechat_timeval_cmp">
+ <title>weechat_timeval_cmp</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_timeval_cmp (struct timeval *tv1, struct timeval *tv2);
+</programlisting>
+ </para>
+ <para>
+ Compare 2 timeval structures.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>tv1</option>: first timeval structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>tv2</option>: second timeval structure
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: -1 if tv1 &lt; char2, zero if tv1 == tv2, +1 if tv1 &gt;
+ tv2
+ </para>
+ <para>
+ Example:
+ <screen>if (weechat_timeval_cmp (&amp;tv1, &amp;tv2) > 0) ...</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_timeval_diff">
+ <title>weechat_timeval_diff</title>
+
+ <para>
+ Prototype:
+<programlisting>
+long weechat_timeval_diff (struct timeval *tv1, struct timeval *tv2);
+</programlisting>
+ </para>
+ <para>
+ Return difference (in milliseconds) between 2 timeval structures.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>tv1</option>: first timeval structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>tv2</option>: second timeval structure
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: difference in milliseconds.
+ </para>
+ <para>
+ Example:
+ <screen>long diff = weechat_timeval_diff (&amp;tv1, &amp;tv2);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_timeval_add">
+ <title>weechat_timeval_add</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_timeval_add (struct timeval *tv, long interval);
+</programlisting>
+ </para>
+ <para>
+ Add interval (in milliseconds) to a timeval structure.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>tv</option>: timeval structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>interval</option>: interval (in milliseconds)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>weechat_timeval_add (&amp;tv, 2000); /* add 2 seconds */</screen>
+ </para>
+ </section>
+
+ </section>
+
+ <!-- ==========================[ sorted list ]=========================== -->
+
+ <section id="secPluginCApi_sorted_list">
+ <title>Sorted lists</title>
+
+ <para>
+ Sorted list functions.
+ </para>
+
+ <section id="secPluginCApi_weechat_list_new">
+ <title>weechat_list_new</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_weelist *weechat_list_new ();
+</programlisting>
+ </para>
+ <para>
+ Create a new list.
+ </para>
+ <para>
+ Return value: pointer to new list.
+ </para>
+ <para>
+ Example:
+ <screen>struct t_weelist *list = weechat_list_new ();</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_add">
+ <title>weechat_list_add</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_weelist_item *weechat_list_add (struct t_weelist *weelist,
+ const char *data, const char *where);
+</programlisting>
+ </para>
+ <para>
+ Add an item in a list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>weelist</option>: list pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>data</option>: data to insert in list
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>where</option>: position in list (constants are:
+ WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING or
+ WEECHAT_LIST_POS_END)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to new item.
+ </para>
+ <para>
+ Example:
+ <screen>weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_search">
+ <title>weechat_list_search</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_weelist_item *weechat_list_search (struct t_weelist *weelist,
+ const char *data);
+</programlisting>
+ </para>
+ <para>
+ Search an item in a list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>weelist</option>: list pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>data</option>: data to search in list
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to item found, NULL if item was not found.
+ </para>
+ <para>
+ Example:
+ <screen>struct t_weelist_item *item = weechat_list_search (list, "my data");</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_casesearch">
+ <title>weechat_list_casesearch</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist,
+ const char *data);
+</programlisting>
+ </para>
+ <para>
+ Search an item in a list (case sensitive search).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>weelist</option>: list pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>data</option>: data to search in list
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to item found, NULL if item was not found.
+ </para>
+ <para>
+ Example:
+ <screen>struct t_weelist_item *item = weechat_list_casesearch (list, "my data");</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_get">
+ <title>weechat_list_get</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_weelist_item *weechat_list_get (struct t_weelist *weelist,
+ int position);
+</programlisting>
+ </para>
+ <para>
+ Get an item in a list by position.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>weelist</option>: list pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>position</option>: position in list (0 is first item)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to item found, NULL if item position was not
+ found.
+ </para>
+ <para>
+ Example:
+ <screen>struct t_weelist_item *item = weechat_list_get (list, 0); /* first item */</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_set">
+ <title>weechat_list_set</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_list_set (struct t_weelist_item *item, const char *value);
+</programlisting>
+ </para>
+ <para>
+ Set new value for an item.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>item</option>: item pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>value</option>: new value for item
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+ <screen>weechat_list_set (item, "new data");/</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_next">
+ <title>weechat_list_next</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);
+</programlisting>
+ </para>
+ <para>
+ Get next item in list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>item</option>: item pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to next item, NULL if pointer was last item in
+ list.
+ </para>
+ <para>
+ Example:
+ <screen>struct t_weelist_item *next_item = weechat_list_next_item (item);/</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_prev">
+ <title>weechat_list_prev</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);
+</programlisting>
+ </para>
+ <para>
+ Get previous item in list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>item</option>: item pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to previous item, NULL if pointer was first item
+ in list.
+ </para>
+ <para>
+ Example:
+ <screen>struct t_weelist_item *prev_item = weechat_list_prev_item (item);/</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_string">
+ <title>weechat_list_string</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_list_string (struct t_weelist_item *item);
+</programlisting>
+ </para>
+ <para>
+ Get string value of an item.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>item</option>: item pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: string value of item.
+ </para>
+ <para>
+ Example:
+ <screen>char *value = weechat_list_string (item);/</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_size">
+ <title>weechat_list_size</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_list_size (struct t_weelist *weelist);
+</programlisting>
+ </para>
+ <para>
+ Get size of list (number of items).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>weelist</option>: list pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: size of list (number of items), 0 if list is empty.
+ </para>
+ <para>
+ Example:
+ <screen>int size = weechat_list_size (list);/</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_remove">
+ <title>weechat_list_remove</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_list_remove (struct t_weelist *weelist,
+ struct t_weelist_item *item);
+</programlisting>
+ </para>
+ <para>
+ Remove an item in a list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>list</option>: list pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>item</option>: item pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+ <screen>weechat_list_remove (list, item);/</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_remove_all">
+ <title>weechat_list_remove_all</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_list_remove_all (struct t_weelist *weelist);
+</programlisting>
+ </para>
+ <para>
+ Remove all items in a list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>list</option>: list pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+ <screen>weechat_list_remove_all (list);/</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_list_free">
+ <title>weechat_list_free</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_list_free (struct t_weelist *weelist);
+</programlisting>
+ </para>
+ <para>
+ Free a list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>list</option>: list pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+ <screen>weechat_list_free (list);/</screen>
+ </para>
+ </section>
+
+ </section>
+
+ <!-- ==========================[ config files ]========================== -->
+
+ <section id="secPluginCApi_configuration_files">
+ <title>Configuration files</title>
+
+ <para>
+ Functions for configuration files.
+ </para>
+
+ <section id="secPluginCApi_weechat_config_new">
+ <title>weechat_config_new</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_config_file *weechat_config_new (const char *name,
+ int (*callback_reload)(void *data,
+ struct t_config_file *config_file),
+ void *callback_reload_data);
+</programlisting>
+ </para>
+ <para>
+ Create a new configuration file.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>name</option>: name of configuration file (without path
+ or extension)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_reload</option>: callback called when
+ configuration file is reloaded with /reload (optional, may be
+ NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_reload_data</option>: pointer given to reload
+ callback when it is called by WeeChat
+ NULL)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to new configuration file, NULL if an error
+ occured.
+ </para>
+ <note>
+ <para>
+ File is NOT created by this function. It will be created by call to
+ function <xref linkend="secPluginCApi_weechat_config_write" /> (you
+ should do that only after adding some sections (with
+ <xref linkend="secPluginCApi_weechat_config_new_section" />) and
+ options (with
+ <xref linkend="secPluginCApi_weechat_config_new_option" />).
+ </para>
+ </note>
+ <para>
+ Example:
+<screen>
+int
+my_config_reload_cb (void *data, struct t_config_file *config_file)
+{
+ /* ... */
+
+ return WEECHAT_RC_OK;
+}
+
+struct t_config_file *config_file = weechat_config_new ("test", &amp;my_config_reload_cb, NULL);
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_new_section">
+ <title>weechat_config_new_section</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_config_section *weechat_config_new_section (struct t_config_file *config_file,
+ const char *name,
+ int user_can_add_options,
+ int user_can_delete_options,
+ int (*callback_read)(void *data,
+ struct t_config_file *config_file,
+ struct t_config_section *section,
+ const char *option_name,
+ const char *value),
+ void *callback_read_data,
+ int (*callback_write)(void *data,
+ struct t_config_file *config_file,
+ struct t_config_section *section, const char *option_name),
+ void *callback_write_data,
+ int (*callback_write_default)(void *data,
+ struct t_config_file *config_file,
+ const char *section_name);
+ void *callback_write_default_data,
+ int (*callback_create_option)(void *data,
+ struct t_config_file *config_file,
+ struct t_config_section *section,
+ const char *option_name,
+ const char *value),
+ void *callback_create_option_data,
+ int (*callback_delete_option)(void *data,
+ struct t_config_file *config_file,
+ struct t_config_section *section,
+ struct t_config_option *option),
+ void *callback_delete_option_data);
+</programlisting>
+ </para>
+ <para>
+ Create a new section in configuration file.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>config_file</option>: configuration file pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>name</option>: name of section
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>user_can_add_options</option>: 1 if user can add options
+ in section, or 0 if it is forbidden
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>user_can_delete_options</option>: 1 if user can delete
+ options in section, or 0 if it is forbidden
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_read</option>: callback called when an option
+ in section is read from disk (should be NULL for most cases,
+ except if options in your section need custom function)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_read_data</option>: pointer given to read
+ callback when it is called by WeeChat
+ NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_write</option>: callback called when section
+ is written in file (should be NULL for most cases, except if your
+ section needs to be written by a custom function)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_write_data</option>: pointer given to write
+ callback when it is called by WeeChat
+ NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_write_default</option>: callback called when
+ default values for section must be written in file
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_write_default_data</option>: pointer given to
+ write_default callback when it is called by WeeChat
+ NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_create_option</option>: callback called when a
+ new option is created in section (NULL if section does not allow
+ new options to be created)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_create_option_data</option>: pointer given to
+ create_option callback when it is called by WeeChat
+ NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_delete_option</option>: callback called when an
+ option is deleted (NULL if section does not allow options to be
+ deleted)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_delete_option_data</option>: pointer given to
+ delete_option callback when it is called by WeeChat
+ NULL)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to new section in configuration file, NULL if an
+ error occured.
+ </para>
+ <para>
+ Example:
+<screen>
+int
+my_section_read_cb (void *data, struct t_config_file *config_file,
+ struct t_config_section *section, const char *option_name,
+ const char *value)
+{
+ /* ... */
+
+ return WEECHAT_RC_OK;
+}
+
+int
+my_section_write_cb (void *data, struct t_config_file *config_file,
+ const char *section_name)
+{
+ /* ... */
+
+ return WEECHAT_RC_OK;
+}
+
+int
+my_section_write_default_cb (void *data, struct t_config_file *config_file,
+ const char *section_name)
+{
+ /* ... */
+
+ return WEECHAT_RC_OK;
+}
+
+int
+my_section_create_option_cb (void *data, struct t_config_file *config_file,
+ struct t_config_section *section,
+ const char *option_name, const char *value)
+{
+ /* ... */
+
+ return WEECHAT_RC_OK;
+}
+
+int
+my_section_delete_option_cb (void *data, struct t_config_file *config_file,
+ struct t_config_section *section,
+ struct t_config_option *option)
+{
+ /* ... */
+
+ return WEECHAT_RC_OK;
+}
+
+/* standard section, user can not add/delete options */
+struct t_config_section *new_section1 = weechat_config_new ("section1", 0, 0,
+ NULL, NULL, /* read callback */
+ NULL, NULL, /* write callback */
+ NULL, NULL, /* write default callback */
+ NULL, NULL, /* create option callback */
+ NULL, NULL); /* delete option callback */
+
+/* special section, user can add/delete options, and options need
+ callback to be read/written */
+struct t_config_section *new_section2 = weechat_config_new ("section2", 1, 1,
+ &amp;my_section_read_cb, NULL,
+ &amp;my_section_write_cb, NULL,
+ &amp;my_section_write_default_cb, NULL,
+ &amp;my_section_create_option_cb, NULL,
+ &amp;my_section_delete_option_cb, NULL);
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_search_section">
+ <title>weechat_config_search_section</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_config_section *weechat_config_search_section (struct t_config_file *config_file,
+ const char *section_name);
+</programlisting>
+ </para>
+ <para>
+ Search a section in a configuration file.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>config_file</option>: configuration file pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>section_name</option>: name of section to search
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to section found, NULL if section was not found.
+ </para>
+ <para>
+ Example:
+<screen>
+struct t_config_section *section = weechat_config_search_section (config_file, "section");
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_new_option">
+ <title>weechat_config_new_option</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_config_option *weechat_config_new_option (struct t_config_file *config_file,
+ struct t_config_section *section,
+ const char *name,
+ const char *type,
+ const char *description,
+ const char *string_values,
+ int min,
+ int max,
+ const chat *default_value,
+ const char *value,
+ int (*callback_check_value)(void *data,
+ struct t_config_option *option,
+ const char *value),
+ void *callback_check_value_data,
+ int (*callback_change)(void *data,
+ struct t_config_option *option),
+ void *callback_change_data,
+ int (*callback_delete)(void *data,
+ struct t_config_option *option),
+ void *callback_delete_data);
+</programlisting>
+ </para>
+ <para>
+ Create a new option in a section of a configuration file.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>config_file</option>: configuration file pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>section</option>: section pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>name</option>: name of option
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>type</option>: type of option, one of:
+ <itemizedlist>
+ <listitem>
+ <para>boolean</para>
+ </listitem>
+ <listitem>
+ <para>integer</para>
+ </listitem>
+ <listitem>
+ <para>string</para>
+ </listitem>
+ <listitem>
+ <para>color</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>description</option>: description of option
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>string_values</option>: values as string (separated by
+ "|"), used for type integer (optional)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>min</option>: minimum value (for integer)
+ NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>max</option>: maximum value (for integer)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>default_value</option>: default value for option (used
+ when option is reset)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>value</option>: value for option
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_check_value</option>: callback called to check
+ new value for an option (optional)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_check_value_data</option>: pointer given to
+ check_value callback when it is called by WeeChat
+ NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_change</option>: callback called when value of
+ option has changed (optional)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_change_data</option>: pointer given to change
+ callback when it is called by WeeChat
+ NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_delete</option>: callback called when option
+ will be deleted (optional)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>callback_delete_data</option>: pointer given to delete
+ callback when it is called by WeeChat
+ NULL)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to new option in section, NULL if an error
+ occured.
+ </para>
+ <para>
+ Example:
+<screen>
+/* boolean */
+struct t_config_option *option1 =
+ weechat_config_new_option (config_file, section,
+ "option1", "My option, type boolean"
+ NULL, /* string values */
+ 0, 0, /* min, max */
+ "on", /* default */
+ "on", /* value */
+ NULL, NULL, /* check callback */
+ NULL, NULL, /* change callback */
+ NULL, NULL); /* delete callback */
+
+/* integer */
+struct t_config_option *option2 =
+ weechat_config_new_option (config_file, section,
+ "option2", "My option, type integer"
+ NULL, /* string values */
+ 0, 100, /* min, max */
+ "15", /* default */
+ "15", /* value */
+ NULL, NULL, /* check callback */
+ NULL, NULL, /* change callback */
+ NULL, NULL); /* delete callback */
+
+/* integer (with string values) */
+struct t_config_option *option3 =
+ weechat_config_new_option (config_file, section,
+ "option3", "My option, type integer (with string values)"
+ "top|bottom|left|right", /* string values */
+ 0, 0, /* min, max */
+ "bottom", /* default */
+ "bottom", /* value */
+ NULL, NULL, /* check callback */
+ NULL, NULL, /* change callback */
+ NULL, NULL); /* delete callback */
+
+/* string */
+struct t_config_option *option4 =
+ weechat_config_new_option (config_file, section,
+ "option4", "My option, type string"
+ NULL, /* string values */
+ 0, 0, /* min, max */
+ "test", /* default */
+ "test", /* value */
+ NULL, NULL, /* check callback */
+ NULL, NULL, /* change callback */
+ NULL, NULL); /* delete callback */
+
+/* color */
+struct t_config_option *option5 =
+ weechat_config_new_option (config_file, section,
+ "option5", "My option, type color"
+ NULL, /* string values */
+ 0, 0, /* min, max */
+ "lightblue", /* default */
+ "lightblue", /* value */
+ NULL, NULL, /* check callback */
+ NULL, NULL, /* change callback */
+ NULL, NULL); /* delete callback */
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_search_option">
+ <title>weechat_config_search_option</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_config_option *weechat_config_search_option (struct t_config_file *config_file,
+ struct t_config_section *section,
+ const char *option_name);
+</programlisting>
+ </para>
+ <para>
+ Search an option in a section of a configuration file.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>config_file</option>: configuration file pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>section</option>: section pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>option_name</option>: name of option to search
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to option found, NULL if option was not found.
+ </para>
+ <para>
+ Example:
+<screen>
+struct t_config_option *option = weechat_config_search_option (config_file, section, "option");
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_search_with_string">
+ <title>weechat_config_search_with_string</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_config_search_with_string (const char *option_name,
+ struct t_config_file **config_file,
+ struct t_config_section **section,
+ struct t_config_option **option);
+</programlisting>
+ </para>
+ <para>
+ Search an option in in a configuration file with string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option_name</option>: full option name (format:
+ "file.section.option")
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>config_file</option>: pointer to a configuration file
+ pointer, will be set to configuration file of option, if found
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>section</option>: pointer to a section pointer, will be
+ set to section of option, if found
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>option</option>: pointer to an option pointer, will be
+ set to option pointer, if found
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+struct t_config_file *ptr_config_file;
+struct t_config_section *ptr_section;
+struct t_config_option *ptr_option;
+
+weechat_config_search_with_string ("file.section.option",
+ &amp;ptr_config_file, &amp;ptr_section, &amp;ptr_option);
+if (ptr_option)
+{
+ /* option found */
+ /* ... */
+}
+else
+{
+ /* option not found */
+ /* ... */
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_string_to_boolean">
+ <title>weechat_config_string_to_boolean</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_config_string_to_boolean (const char *text);
+</programlisting>
+ </para>
+ <para>
+ Check if a text is "true" or "false".
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>text</option>: text to analyze
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if text is "true" ("on", "yes", "y", "true", "t", "1"),
+ or 0 if text is "false" ("off", "no", "n", "false", "f", "0").
+ </para>
+ <para>
+ Example:
+<screen>
+if (weechat_config_string_to_boolean ("on"))
+{
+ /* true */
+ /* ... */
+}
+else
+{
+ /* false */
+ /* never executed! */
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_option_reset">
+ <title>weechat_config_option_reset</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_config_option_reset (struct t_config_option *option,
+ int run_callback);
+</programlisting>
+ </para>
+ <para>
+ Reset an option to its default value.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option</option>: option pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>run_callback</option>: 1 for calling change callback if
+ option is changed, 0 otherwise
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has
+ been reset, WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not
+ changed, WEECHAT_CONFIG_OPTION_SET_ERROR if an error occured.
+ </para>
+ <para>
+ Example:
+<screen>
+switch (weechat_config_option_reset (option, 1))
+{
+ case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
+ /* .... */
+ break;
+ case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
+ /* .... */
+ break;
+ case WEECHAT_CONFIG_OPTION_SET_ERROR:
+ /* .... */
+ break;
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_option_set">
+ <title>weechat_config_option_set</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_config_option_set (struct t_config_option *option,
+ const char *value, int run_callback);
+</programlisting>
+ </para>
+ <para>
+ Set new value for an option.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option</option>: option pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>value</option>: new value for option
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>run_callback</option>: 1 for calling change callback if
+ option is changed, 0 otherwise
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has
+ been reset, WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not
+ changed, WEECHAT_CONFIG_OPTION_SET_ERROR if an error occured.
+ </para>
+ <para>
+ Example:
+<screen>
+switch (weechat_config_option_set (option, "new_value", 1))
+{
+ case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
+ /* .... */
+ break;
+ case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
+ /* .... */
+ break;
+ case WEECHAT_CONFIG_OPTION_SET_ERROR:
+ /* .... */
+ break;
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_option_unset">
+ <title>weechat_config_option_unset</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_config_option_unset (struct t_config_option *option);
+</programlisting>
+ </para>
+ <para>
+ Unset/reset option.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option</option>: option pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET if option value
+ has not been reset, WEECHAT_CONFIG_OPTION_UNSET_OK_RESET if option
+ value has been reset, WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED if option
+ has been removed, WEECHAT_CONFIG_OPTION_UNSET_ERROR if an error
+ occured.
+ </para>
+ <para>
+ Example:
+<screen>
+switch (weechat_config_option_unset (option))
+{
+ case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
+ /* .... */
+ break;
+ case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
+ /* .... */
+ break;
+ case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
+ /* .... */
+ break;
+ case WEECHAT_CONFIG_OPTION_UNSET_ERROR:
+ /* .... */
+ break;
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_option_rename">
+ <title>weechat_config_option_rename</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_config_option_rename (struct t_config_option *option,
+ const char *new_name);
+</programlisting>
+ </para>
+ <para>
+ Rename an option.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option</option>: option pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>new_name</option>: new name for option
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+weechat_config_option_rename (option, "new_name");
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_option_get_pointer">
+ <title>weechat_config_option_get_pointer</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void *weechat_config_option_get_pointer (struct t_config_option *option,
+ const char *property);
+</programlisting>
+ </para>
+ <para>
+ Get a pointer on an option property.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option</option>: option pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>property</option>: property name:
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Property</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>config_file</entry>
+ <entry>struct t_config_file *</entry>
+ <entry>configuration file pointer</entry>
+ </row>
+ <row>
+ <entry>section</entry>
+ <entry>struct t_config_section *</entry>
+ <entry>section pointer</entry>
+ </row>
+ <row>
+ <entry>name</entry>
+ <entry>char *</entry>
+ <entry>option name</entry>
+ </row>
+ <row>
+ <entry>type</entry>
+ <entry>int</entry>
+ <entry>option type</entry>
+ </row>
+ <row>
+ <entry>description</entry>
+ <entry>char *</entry>
+ <entry>option description</entry>
+ </row>
+ <row>
+ <entry>string_values</entry>
+ <entry>char **</entry>
+ <entry>string values</entry>
+ </row>
+ <row>
+ <entry>min</entry>
+ <entry>int</entry>
+ <entry>minimum value</entry>
+ </row>
+ <row>
+ <entry>max</entry>
+ <entry>int</entry>
+ <entry>maximum value</entry>
+ </row>
+ <row>
+ <entry>default_value</entry>
+ <entry>(depends on type)</entry>
+ <entry>default value</entry>
+ </row>
+ <row>
+ <entry>value</entry>
+ <entry>(depends on type)</entry>
+ <entry>current value</entry>
+ </row>
+ <row>
+ <entry>prev_option</entry>
+ <entry>struct t_config_option *</entry>
+ <entry>previous option pointer</entry>
+ </row>
+ <row>
+ <entry>next_option</entry>
+ <entry>struct t_config_option *</entry>
+ <entry>next option pointer</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+char *description = weechat_config_option_get_pointer (option, "description");
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_boolean">
+ <title>weechat_config_boolean</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_config_boolean (struct t_config_option *option);
+</programlisting>
+ </para>
+ <para>
+ Get boolean value of option.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option</option>: option pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: boolean value of option (0 or 1).
+ </para>
+ <para>
+ Example:
+<screen>
+if (weechat_config_boolean (option))
+{
+ /* true */
+}
+else
+{
+ /* false */
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_integer">
+ <title>weechat_config_integer</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_config_integer (struct t_config_option *option);
+</programlisting>
+ </para>
+ <para>
+ Get integer value of option.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option</option>: option pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: integer value of option.
+ </para>
+ <para>
+ Example:
+ <screen>int value = weechat_config_boolean (option);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_string">
+ <title>weechat_config_string</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_config_string (struct t_config_option *option);
+</programlisting>
+ </para>
+ <para>
+ Get string value of option.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option</option>: option pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: string value of option.
+ </para>
+ <para>
+ Example:
+ <screen>char *value = weechat_config_string (option);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_string">
+ <title>weechat_config_string</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_config_color (struct t_config_option *option);
+</programlisting>
+ </para>
+ <para>
+ Get color value of option.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option</option>: option pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: color value of option (string with name of color).
+ </para>
+ <para>
+ Example:
+ <screen>char *color = weechat_config_color (option);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_write_line">
+ <title>weechat_config_write_line</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_config_write_line (struct t_config_file *config_file,
+ const char *option_name,
+ const char *value, ...);
+</programlisting>
+ </para>
+ <para>
+ Write a line in a configuration file (this function should be called
+ only in "write" or "write_default" callbacks for a section).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>config_file</option>: configuration file pointer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>option_name</option>: option name
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>value</option>: value
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+int
+my_section_write_cb (void *data, struct t_config_file *config_file,
+ const char *section_name)
+{
+ weechat_config_write_line (config_file, "option", "%s;%d",
+ "value", 123);
+
+ return WEECHAT_RC_OK;
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_write">
+ <title>weechat_config_write</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_config_write (struct t_config_file *config_file);
+</programlisting>
+ </para>
+ <para>
+ Write configuration file to disk.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>config_file</option>: configuration file pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: WEECHAT_CONFIG_WRITE_OK if configuration was written,
+ WEECHAT_CONFIG_WRITE_ERROR if an error occured,
+ WEECHAT_CONFIG_WRITE_MEMORY_ERROR if there was not enough memory.
+ </para>
+ <para>
+ Example:
+<screen>
+switch (weechat_config_write (config_file))
+{
+ case WEECHAT_CONFIG_WRITE_OK:
+ /* ... */
+ break;
+ case WEECHAT_CONFIG_WRITE_ERROR:
+ /* ... */
+ break;
+ case WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
+ /* ... */
+ break;
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_read">
+ <title>weechat_config_read</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_config_read (struct t_config_file *config_file);
+</programlisting>
+ </para>
+ <para>
+ Read configuration file from disk.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>config_file</option>: configuration file pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: WEECHAT_CONFIG_READ_OK if configuration was loaded,
+ WEECHAT_CONFIG_READ_MEMORY_ERROR if there was not enough memory,
+ WEECHAT_CONFIG_READ_FILE_NOT_FOUND if file was not found.
+ </para>
+ <para>
+ Example:
+<screen>
+switch (weechat_config_read (config_file))
+{
+ case WEECHAT_CONFIG_READ_OK:
+ /* ... */
+ break;
+ case WEECHAT_CONFIG_READ_MEMORY_ERROR:
+ /* ... */
+ break;
+ case WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
+ /* ... */
+ break;
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_reload">
+ <title>weechat_config_reload</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_config_reload (struct t_config_file *config_file);
+</programlisting>
+ </para>
+ <para>
+ Reload configuration file from disk.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>config_file</option>: configuration file pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: WEECHAT_CONFIG_READ_OK if configuration was reloaded,
+ WEECHAT_CONFIG_READ_MEMORY_ERROR if there was not enough memory,
+ WEECHAT_CONFIG_READ_FILE_NOT_FOUND if file was not found.
+ </para>
+ <para>
+ Example:
+<screen>
+switch (weechat_config_reload (config_file))
+{
+ case WEECHAT_CONFIG_READ_OK:
+ /* ... */
+ break;
+ case WEECHAT_CONFIG_READ_MEMORY_ERROR:
+ /* ... */
+ break;
+ case WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
+ /* ... */
+ break;
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_option_free">
+ <title>weechat_config_option_free</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_config_option_free (struct t_config_option *option);
+</programlisting>
+ </para>
+ <para>
+ Free an option.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option</option>: option pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+ <screen>weechat_config_option_free (option);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_section_free_options">
+ <title>weechat_config_section_free_options</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_config_section_free_options (struct t_config_section *section);
+</programlisting>
+ </para>
+ <para>
+ Free all options in a section.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>section</option>: section pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+ <screen>weechat_config_section_free_options (section);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_section_free">
+ <title>weechat_config_section_free</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_config_section_free (struct t_config_section *section);
+</programlisting>
+ </para>
+ <para>
+ Free a section.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>section</option>: section pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+ <screen>weechat_config_section_free (section);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_free">
+ <title>weechat_config_free</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_config_free (struct t_config_file *config_file);
+</programlisting>
+ </para>
+ <para>
+ Free a configuration file.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>config_file</option>: configuration file pointer
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+ <screen>weechat_config_free (config_file);</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_get">
+ <title>weechat_config_get</title>
+
+ <para>
+ Prototype:
+<programlisting>
+struct t_config_option *weechat_config_get (const char *option_name);
+</programlisting>
+ </para>
+ <para>
+ Search an option in in a configuration file with string.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option_name</option>: full option name (format:
+ "file.section.option")
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to option found, NULL if option was not found.
+ </para>
+ <para>
+ Example:
+<screen>
+struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_get_plugin">
+ <title>weechat_config_get_plugin</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_config_get_plugin (const char *option_name);
+</programlisting>
+ </para>
+ <para>
+ Search an option in plugins configuration file (plugins.conf), by
+ adding prefix with current plugin name.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option_name</option>: option name, WeeChat will add
+ prefix "plugins.var.xxxx." (where xxxx is current plugin name).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to option found, NULL if option was not found.
+ </para>
+ <para>
+ Example:
+<screen>
+/* if current plugin is "test", then look for value of option
+ "plugins.var.test.option" in plugins.conf file */
+char *value = weechat_config_get_plugin ("option");
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_config_set_plugin">
+ <title>weechat_config_set_plugin</title>
+
+ <para>
+ Prototype:
+<programlisting>
+int weechat_config_set_plugin (const char *option_name, const char *value);
+</programlisting>
+ </para>
+ <para>
+ Set value for option in in plugins configuration file (plugins.conf).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>option_name</option>: option name, WeeChat will add
+ prefix "plugins.var.xxxx." (where xxxx is current plugin name).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if ok, 0 if an error occured.
+ </para>
+ <para>
+ Example:
+<screen>
+weechat_config_set_plugin ("option", "test_value");
+</screen>
+ </para>
+ </section>
+
+ </section>
+
+ <!-- ============================[ display ]============================= -->
+
+ <section id="secPluginCApi_display">
+ <title>Display</title>
+
+ <para>
+ Functions to display text in buffers.
+ </para>
+
+ <section id="secPluginCApi_weechat_prefix">
+ <title>weechat_prefix</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_prefix (const char *prefix);
+</programlisting>
+ </para>
+ <para>
+ Get a prefix.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>prefix</option>: name of prefix:
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Prefix</entry>
+ <entry>Default value</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>error</entry>
+ <entry>=!=</entry>
+ <entry>error message</entry>
+ </row>
+ <row>
+ <entry>network</entry>
+ <entry>--</entry>
+ <entry>message from network</entry>
+ </row>
+ <row>
+ <entry>action</entry>
+ <entry>*</entry>
+ <entry>self action</entry>
+ </row>
+ <row>
+ <entry>join</entry>
+ <entry>--&gt;</entry>
+ <entry>someone joins current chat</entry>
+ </row>
+ <row>
+ <entry>quit</entry>
+ <entry>&lt;--</entry>
+ <entry>someone leaves current chat</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: prefix value, empty string if prefix is not found
+ (not NULL).
+ </para>
+ <para>
+ Example:
+<screen>
+weechat_printf (NULL, "%sThis is an error...",
+ weechat_prefix ("error"));
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_color">
+ <title>weechat_color</title>
+
+ <para>
+ Prototype:
+<programlisting>
+char *weechat_color (const char *color_name);
+</programlisting>
+ </para>
+ <para>
+ Get a string color code for display.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>color_name</option>: name of color: may be a WeeChat
+ color name (from weechat.color.xxx), or a color with optional
+ background (separated by comma).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: string with color code, or a "reset color" code if color
+ is not found.
+ </para>
+ <para>
+ Example:
+<screen>
+weechat_printf (NULL, "Color: %sblue %schat default %sred on green",
+ weechat_color ("blue"),
+ weechat_color ("chat"),
+ weechat_color ("red,green"));
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_printf">
+ <title>weechat_printf</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);
+</programlisting>
+ </para>
+ <para>
+ Display a message on a buffer.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>buffer</option>: buffer pointer, if NULL, message is
+ displayed on WeeChat buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>message</option>: message to display
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+weechat_printf (NULL, "Hello on WeeChat buffer");
+weechat_printf (buffer, "Hello on this buffer");
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_printf_date">
+ <title>weechat_printf_date</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_printf_date (struct t_gui_buffer *buffer, time_t date,
+ const char *message, ...);
+</programlisting>
+ </para>
+ <para>
+ Display a message on a buffer, using a custom date.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>buffer</option>: buffer pointer, if NULL, message is
+ displayed on WeeChat buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>date</option>: date for message
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>message</option>: message to display
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+weechat_printf (NULL, time (NULL) - 120, "Hello, 2 minutes ago");
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_printf_tags">
+ <title>weechat_printf_tags</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_printf_tags (struct t_gui_buffer *buffer, const char *tags,
+ const char *message, ...);
+</programlisting>
+ </para>
+ <para>
+ Display a message on a buffer, using a custom tags.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>buffer</option>: buffer pointer, if NULL, message is
+ displayed on WeeChat buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>tags</option>: tags for message, separated by a comma
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>message</option>: message to display
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+weechat_printf_tags (NULL, "notify_message", "Hello with a message notify tag");
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_printf_date_tags">
+ <title>weechat_printf_date_tags</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date,
+ const char *tags, const char *message, ...);
+</programlisting>
+ </para>
+ <para>
+ Display a message on a buffer, using a custom date and tags.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>buffer</option>: buffer pointer, if NULL, message is
+ displayed on WeeChat buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>date</option>: date for message
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>tags</option>: tags for message, separated by a comma
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>message</option>: message to display
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
+ "Hello, 2 minutes ago, with a message notify tag");
+</screen>
+ </para>
+ </section>
+
+ <section id="secPluginCApi_weechat_printf_y">
+ <title>weechat_printf_y</title>
+
+ <para>
+ Prototype:
+<programlisting>
+void weechat_printf_y (struct t_gui_buffer *buffer, int y,
+ const char *message, ...);
+</programlisting>
+ </para>
+ <para>
+ Display a message on a line of a buffer with free content (see
+ <xref linkend="secPluginCApi_weechat_buffer_set" />).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>buffer</option>: buffer pointer, if NULL, message is
+ displayed on WeeChat buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>y</option>: line number (0 for first line)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>message</option>: message to display
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+weechat_printf_y (buffer, 2, "My message on third line");
+</screen>
+ </para>
+ </section>
+
+ </section>
+
+ <!-- ============================[ buffers ]============================= -->
+
+ <section id="secPluginCApi_buffers">
+ <title>Buffers</title>
+
+ <para>
+ Functions to create/query/close buffers.
+ </para>
+
+ <para>
+ Missing doc!
+ </para>
+
+ </section>
+
+ <!-- ============================[ nicklist ]============================ -->
+
+ <section id="secPluginCApi_nicklist">
+ <title>Nicklist</title>
+
+ <para>
+ Functions for buffer nicklist.
+ </para>
+
+ <para>
+ Missing doc!
+ </para>
+
+ </section>
+
+ <!-- ==============================[ bars ]============================== -->
+
+ <section id="secPluginCApi_bars">
+ <title>Bars</title>
+
+ <para>
+ Functions for bars.
+ </para>
+
+ <para>
+ Missing doc!
+ </para>
+
+ </section>
+
+ <!-- ============================[ commands ]============================ -->
+
+ <section id="secPluginCApi_commands">
+ <title>Commands</title>
+
+ <para>
+ Functions for executing WeeChat commands.
+ </para>
+
+ <para>
+ Missing doc!
+ </para>
+
+ </section>
+
+ <!-- ============================[ network ]============================= -->
+
+ <section id="secPluginCApi_network">
+ <title>Network</title>
+
+ <para>
+ Network functions.
+ </para>
+
+ <para>
+ Missing doc!
+ </para>
+
+ </section>
+
+ <!-- =============================[ infos ]============================== -->
+
+ <section id="secPluginCApi_infos">
+ <title>Infos</title>
+
+ <para>
+ Functions to get infos.
+ </para>
+
+ <para>
+ Missing doc!
+ </para>
+
+ </section>
+
+ <!-- ===========================[ infolists ]============================ -->
+
+ <section id="secPluginCApi_infolists">
+ <title>Infolists</title>
+
+ <para>
+ Functions for infolists.
+ </para>
+
+ <para>
+ Missing doc!
+ </para>
+
+ </section>
+
+ <!-- ============================[ upgrade ]============================= -->
+
+ <section id="secPluginCApi_upgrade">
+ <title>Upgrade</title>
+
+ <para>
+ Functions for WeeChat upgrading.
+ </para>
+
+ <para>
+ Missing doc!
+ </para>
+
+ </section>
+
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+ <!-- ==================================================================== -->
+
+
+ <!--
+ To be continued...
+
+
+
+ <section id="secAPI_print">
+ <title>print</title>
+
+ <para>
+ Prototype:
+ <command>
+ void print (t_weechat_plugin *plugin,
+ char *server, char *channel, char *message, ...)
+ </command>
+ </para>
+ <para>
+ Display a message on a WeeChat buffer, identified by server and
+ channel (both may be NULL for current buffer).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>server</option>: internal name of server to find
+ buffer for message display (may be NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>channel</option>: name of channel to find buffer
+ for message display (may be NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>message</option>: message
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ To display colored text, there are following codes:
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Code</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>0x02</entry>
+ <entry>
+ bold text
+ </entry>
+ </row>
+ <row>
+ <entry>0x03 + "xx"</entry>
+ <entry>
+ text color "<literal>xx</literal>"
+ (see <xref linkend="secAPI_get_irc_color" /> for colors)
+ </entry>
+ </row>
+ <row>
+ <entry>0x03 + "xx,yy"</entry>
+ <entry>
+ text color "<literal>xx</literal>"
+ and background "<literal>yy</literal>"
+ (see <xref linkend="secAPI_get_irc_color" /> for colors)
+ </entry>
+ </row>
+ <row>
+ <entry>0x0F</entry>
+ <entry>
+ disable color and attributes
+ </entry>
+ </row>
+ <row>
+ <entry>0x12</entry>
+ <entry>
+ reverse video (revert text color with background)
+ </entry>
+ </row>
+ <row>
+ <entry>0x1F</entry>
+ <entry>
+ underlined text
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ Note: the same code (without number for 0x03) may be used to stop
+ the attribute.
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Examples:
+<screen>
+plugin->print (plugin, NULL, NULL, "hello");
+plugin->print (plugin, NULL, "#weechat", "hello");
+plugin->print (plugin, "freenode", "#weechat", "hello");
+plugin->print (plugin, NULL, NULL,
+ "test: \x02 bold \x0F\x03%02d blue \x03%02d green",
+ plugin->get_irc_color (plugin, "blue"),
+ plugin->get_irc_color (plugin, "green"));
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_print_server">
+ <title>print_server</title>
+
+ <para>
+ Prototype:
+ <command>
+ void print_server (t_weechat_plugin *plugin,
+ char *message, ...)
+ </command>
+ </para>
+ <para>
+ Display a message on current server buffer.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>message</option>: message
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ To display colored text, see <xref linkend="secAPI_print" />.
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example: <screen>plugin->print_server (plugin, "hello");</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_log">
+ <title>log</title>
+
+ <para>
+ Prototype:
+ <command>
+ void log (t_weechat_plugin *plugin,
+ char *server, char *channel, char *message, ...)
+ </command>
+ </para>
+ <para>
+ Write a message in log file for a server or a channel.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>server</option>: internal name of server to find
+ buffer for log (may be NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>channel</option>: name of channel to find buffer
+ for log (may be NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>message</option>: message
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+<screen>
+plugin->log (plugin, "freenode", "#weechat", "test");
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_msg_handler_add">
+ <title>msg_handler_add</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_handler *msg_handler_add (t_weechat_plugin
+ *plugin, char *message, t_plugin_handler_func *function,
+ char *handler_args, void *handler_pointer)
+ </command>
+ </para>
+ <para>
+ Add an IRC message handler, called when an IRC message is
+ received.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>message</option>: name of IRC message ("*" for all
+ messages).
+ To know list of IRC messages, please consult
+ <acronym>RFC</acronym>s
+ <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink>
+ and
+ <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink>.
+ Moreover you can use a special name, prefixed by "weechat_"
+ to catch special events, as written in table below:
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>weechat_pv</literal></entry>
+ <entry>private message received</entry>
+ </row>
+ <row>
+ <entry><literal>weechat_highlight</literal></entry>
+ <entry>
+ message with highlight (on a channel or pv)
+ </entry>
+ </row>
+ <row>
+ <entry><literal>weechat_ctcp</literal></entry>
+ <entry>
+ CTCP message received (VERSION, PING, ..)
+ </entry>
+ </row>
+ <row>
+ <entry><literal>weechat_dcc</literal></entry>
+ <entry>
+ DCC message received (chat or file)
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>function</option>: function called when message
+ is received
+ </para>
+ <para>
+ It uses following prototype:
+ <command>
+ int my_function (t_weechat_plugin *plugin,
+ int argc, char **argv,
+ char *handler_args, void *handler_pointer)
+ </command>
+ </para>
+ <para>
+ Argument argc is set to 3, following values are set in
+ argv array:
+ <itemizedlist>
+ <listitem>
+ <para>argv[0] = server name</para>
+ </listitem>
+ <listitem>
+ <para>argv[1] = IRC message</para>
+ </listitem>
+ <listitem>
+ <para>argv[2] = command arguments</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler_args</option>: arguments given to function
+ when called
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler_pointer</option>: pointer given to function
+ when called
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to new message handler.
+ </para>
+ <para>
+ Note: function called when message is received has to return
+ one of following values:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_KO</literal>: function failed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_OK</literal>: function successfully
+ completed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_OK_IGNORE_WEECHAT</literal>: message
+ will not be sent to WeeChat
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_OK_IGNORE_PLUGINS</literal>: message
+ will not be sent to other plugins
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_OK_IGNORE_ALL</literal>: message
+ will not be sent to WeeChat neither other plugins
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_OK_WITH_HIGHLIGHT</literal>: function
+ successfully completed and make "highlight" on received
+ message
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+int msg_kick (t_weechat_plugin *plugin, int argc, char **argv,
+ char *handler_args, void *handler_pointer)
+{
+ plugin->print (plugin, argv[0], NULL, "KICK received");
+ return PLUGIN_RC_OK;
+}
+...
+t_plugin_handler *msg_handler;
+msg_handler = plugin->msg_handler_add (plugin, "KICK",
+ &amp;msg_kick, NULL, NULL);
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_cmd_handler_add">
+ <title>cmd_handler_add</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_handler *cmd_handler_add (t_weechat_plugin
+ *plugin, char *command, char *description, char *arguments,
+ char *arguments_description, char *completion_template,
+ t_plugin_handler_func *fonction, char *handler_args,
+ void *handler_pointer)
+ </command>
+ </para>
+ <para>
+ Add a WeeChat command handler, called when user uses command
+ (for example /command).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>command</option>: the new command name, which
+ may be an existing command (be careful, replaced command
+ will not be available until plugin is unloaded)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>description</option>: short command description
+ (displayed by /help command)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>arguments</option>: short description of command
+ arguments (displayed by /help command)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>arguments_description</option>: long description
+ of command arguments (displayed by /help command)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>completion_template</option>: template for
+ completion, like "<literal>abc|%w def|%i</literal>"
+ which means "abc" or a WeeChat command for first argument,
+ "def" or IRC command for second.
+ An empty string lets WeeChat complete any argument with
+ a nick from current channel, NULL or "-" disable completion
+ for all command arguments.
+ </para>
+ <para>
+ Following codes can be used:
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Code</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>%-</literal></entry>
+ <entry>no completion for argument</entry>
+ </row>
+ <row>
+ <entry><literal>%*</literal></entry>
+ <entry>
+ repeat last completion for all following arguments
+ (this code has to be at the end of completion
+ template, preceded by "|")
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%a</literal></entry>
+ <entry>alias</entry>
+ </row>
+ <row>
+ <entry><literal>%A</literal></entry>
+ <entry>
+ alias and commands (WeeChat, IRC and plugins)
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%c</literal></entry>
+ <entry>current channel</entry>
+ </row>
+ <row>
+ <entry><literal>%C</literal></entry>
+ <entry>all channels (including queries)</entry>
+ </row>
+ <row>
+ <entry><literal>%f</literal></entry>
+ <entry>file name</entry>
+ </row>
+ <row>
+ <entry><literal>%h</literal></entry>
+ <entry>plugins commands</entry>
+ </row>
+ <row>
+ <entry><literal>%i</literal></entry>
+ <entry>IRC commands (sent)</entry>
+ </row>
+ <row>
+ <entry><literal>%I</literal></entry>
+ <entry>IRC commands (received)</entry>
+ </row>
+ <row>
+ <entry><literal>%k</literal></entry>
+ <entry>key functions</entry>
+ </row>
+ <row>
+ <entry><literal>%m</literal></entry>
+ <entry>nick on current server</entry>
+ </row>
+ <row>
+ <entry><literal>%M</literal></entry>
+ <entry>
+ nicks on current server (on all open channels)
+ </entry>
+ </row>
+ <row>
+ <entry><literal>%n</literal></entry>
+ <entry>nicks of current channel</entry>
+ </row>
+ <row>
+ <entry><literal>%N</literal></entry>
+ <entry>nicks and hostnames of current channel</entry>
+ </row>
+ <row>
+ <entry><literal>%o</literal></entry>
+ <entry>setup options</entry>
+ </row>
+ <row>
+ <entry><literal>%O</literal></entry>
+ <entry>plugin options</entry>
+ </row>
+ <row>
+ <entry><literal>%p</literal></entry>
+ <entry>default "part" message</entry>
+ </row>
+ <row>
+ <entry><literal>%q</literal></entry>
+ <entry>default "quit" message</entry>
+ </row>
+ <row>
+ <entry><literal>%s</literal></entry>
+ <entry>current server name</entry>
+ </row>
+ <row>
+ <entry><literal>%S</literal></entry>
+ <entry>all servers names</entry>
+ </row>
+ <row>
+ <entry><literal>%t</literal></entry>
+ <entry>topic of current channel</entry>
+ </row>
+ <row>
+ <entry><literal>%v</literal></entry>
+ <entry>setup option value</entry>
+ </row>
+ <row>
+ <entry><literal>%V</literal></entry>
+ <entry>plugin option value</entry>
+ </row>
+ <row>
+ <entry><literal>%w</literal></entry>
+ <entry>WeeChat commands</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>function</option>: function called when command
+ is executed
+ </para>
+ <para>
+ It uses following prototype:
+ <command>
+ int my_function (t_weechat_plugin *plugin,
+ int argc, char **argv,
+ char *handler_args, void *handler_pointer)
+ </command>
+ </para>
+ <para>
+ Argument argc is set to 3, following values are set in
+ argc array:
+ <itemizedlist>
+ <listitem>
+ <para>argv[0] = server name</para>
+ </listitem>
+ <listitem>
+ <para>argv[1] = command</para>
+ </listitem>
+ <listitem>
+ <para>argv[2] = command arguments</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler_args</option>: arguments given to function
+ when called
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler_pointer</option>: pointer given to function
+ when called
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to new command handler.
+ </para>
+ <para>
+ Note: function called when command is executed has to return
+ one of following values:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_KO</literal>: function failed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_OK</literal>: function successfully
+ completed
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+int cmd_test (t_weechat_plugin *plugin, int argc, char **argv,
+ char *handler_args, void *handler_pointer)
+{
+ plugin->print (plugin, argv[0], NULL,
+ "test command, nick: %s",
+ (argv[2]) ? argv[2] : "none");
+ return PLUGIN_RC_OK;
+}
+...
+t_plugin_handler *cmd_handler;
+cmd_handler = plugin->cmd_handler_add (plugin, "test", "Test command",
+ "[nick]", "nick: nick of channel",
+ "%n", &amp;cmd_test, NULL, NULL);
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_timer_handler_add">
+ <title>timer_handler_add</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_handler *timer_handler_add (t_weechat_plugin
+ *plugin, int interval, t_plugin_handler_func *function,
+ char *handler_args, void *handler_pointer)
+ </command>
+ </para>
+ <para>
+ Add a timer handler which periodically calls a function.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>interval</option>: interval (in seconds) between
+ two calls of function.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>function</option>: function called
+ </para>
+ <para>
+ It uses following prototype:
+ <command>
+ int my_function (t_weechat_plugin *plugin,
+ int argc, char **argv,
+ char *handler_args, void *handler_pointer)
+ </command>
+ </para>
+ <para>
+ Argument argc is set to 0, and argv is set to NULL.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler_args</option>: arguments given to function
+ when called
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler_pointer</option>: pointer given to function
+ when called
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to new timer handler.
+ </para>
+ <para>
+ Note: function called has to return one of following values:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_KO</literal>: function failed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_OK</literal>: function successfully
+ completed
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+int my_timer (t_weechat_plugin *plugin, int argc, char **argv,
+ char *handler_args, void *handler_pointer)
+{
+ plugin->print (plugin, NULL, NULL, "my timer");
+ return PLUGIN_RC_OK;
+}
+...
+t_plugin_handler *timer_handler;
+timer_handler = plugin->timer_handler_add (plugin, 60, &amp;my_timer);
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_keyboard_handler_add">
+ <title>keyboard_handler_add</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_handler *keyboard_handler_add (t_weechat_plugin
+ *plugin, t_plugin_handler_func *function,
+ char *handler_args, void *handler_pointer)
+ </command>
+ </para>
+ <para>
+ Add a keyboard handler, called for any key pressed.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>function</option>: function called
+ </para>
+ <para>
+ It uses following prototype:
+ <command>
+ int my_function (t_weechat_plugin *plugin,
+ int argc, char **argv,
+ char *handler_args, void *handler_pointer)
+ </command>
+ </para>
+ <para>
+ Argument argc is set to 3, following values are set in
+ argc array:
+ <itemizedlist>
+ <listitem>
+ <para>
+ argv[0] = key pressed (name of internal function or
+ '*' followed by a key code)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ argv[1] = command line before key action
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ argv[2] = command line after key action
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler_args</option>: arguments given to function
+ when called
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler_pointer</option>: pointer given to function
+ when called
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to new message handler.
+ </para>
+ <para>
+ Note: function called has to return one of following values:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_KO</literal>: function failed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_OK</literal>: function successfully
+ completed
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+int my_keyb (t_weechat_plugin *plugin, int argc, char **argv,
+ char *handler_args, void *handler_pointer)
+{
+ if (argc == 2)
+ {
+ plugin->print (plugin, NULL, NULL, "key pressed: %s", argv[0]);
+ if (argv[1] &amp;&amp; (argv[1][0] == '1'))
+ plugin->print (plugin, NULL, NULL, "input text changed");
+ else
+ plugin->print (plugin, NULL, NULL, "input text not changed");
+ }
+ return PLUGIN_RC_OK;
+}
+...
+t_plugin_handler *keyb_handler;
+keyb_handler = plugin->keyboard_handler_add (plugin, &amp;my_keyb);
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_event_handler_add">
+ <title>event_handler_add</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_handler *event_handler_add (t_weechat_plugin
+ *plugin, char *event, t_plugin_handler_func *function,
+ char *handler_args, void *handler_pointer)
+ </command>
+ </para>
+ <para>
+ Add an event handler, called when an event happens.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>event</option> : event (see table below)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>function</option>: function called
+ </para>
+ <para>
+ It uses following prototype:
+ <command>
+ int my_function (t_weechat_plugin *plugin,
+ int argc, char **argv,
+ char *handler_args, void *handler_pointer)
+ </command>
+ </para>
+ <para>
+ Arguments depend on event (see table below).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler_args</option>: arguments given to function
+ when called
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler_pointer</option>: pointer given to function
+ when called
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ List of events:
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Event</entry>
+ <entry>Description</entry>
+ <entry>Arguments</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>buffer_open</literal></entry>
+ <entry>a buffer was open</entry>
+ <entry>
+ argc = 1, argv = { buffer number }
+ </entry>
+ </row>
+ <row>
+ <entry><literal>buffer_close</literal></entry>
+ <entry>a buffer was closed</entry>
+ <entry>
+ argc = 1, argv = { buffer number }
+ </entry>
+ </row>
+ <row>
+ <entry><literal>buffer_move</literal></entry>
+ <entry>a buffer was moved</entry>
+ <entry>
+ argc = 2, argv = { new buffer number, old number }
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Return value: pointer to new event handler.
+ </para>
+ <para>
+ Note: function called has to return one of following values:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_KO</literal>: function failed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>PLUGIN_RC_OK</literal>: function successfully
+ completed
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Example:
+<screen>
+int my_event (t_weechat_plugin *plugin, int argc, char **argv,
+ char *handler_args, void *handler_pointer)
+{
+ plugin->print (plugin, NULL, NULL, "my_event");
+ return PLUGIN_RC_OK;
+}
+...
+t_plugin_handler *event_handler;
+event_handler = plugin->event_handler_add (plugin, "buffer_open",
+ &amp;my_event);
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_handler_remove">
+ <title>handler_remove</title>
+
+ <para>
+ Prototype:
+ <command>
+ void handler_remove (t_weechat_plugin *plugin,
+ t_plugin_handler *handler)
+ </command>
+ </para>
+ <para>
+ Remove a command or message handler.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>handler</option>: handler to remove
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->handler_remove (plugin, my_handler);</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_handler_remove_all">
+ <title>handler_remove_all</title>
+
+ <para>
+ Prototype:
+ <command>
+ void handler_remove_all (t_weechat_plugin *plugin)
+ </command>
+ </para>
+ <para>
+ Remove all handlers for a plugin.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->handler_remove_all (plugin);</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_modifier_add">
+ <title>modifier_add</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_modifier *modifier_add (t_weechat_plugin *plugin,
+ char *type, char *message, t_plugin_modifier_func *function,
+ char *modifier_args, void *modifier_pointer)
+ </command>
+ </para>
+ <para>
+ Add a message modifier.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>type</option>: modifier type:
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>irc_in</literal></entry>
+ <entry>called for incoming IRC messages</entry>
+ </row>
+ <row>
+ <entry><literal>irc_user</literal></entry>
+ <entry>
+ called for each user message (or command) (before
+ WeeChat parses message)
+ </entry>
+ </row>
+ <row>
+ <entry><literal>irc_out</literal></entry>
+ <entry>
+ called for outgoing messages, immediately before
+ sending it to IRC server (this includes messages
+ sent automatically by WeeChat to server)
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>message</option>: name of IRC message (used only for
+ types "irc_in" and "irc_out").
+ To know list of IRC messages, please consult
+ <acronym>RFC</acronym>s
+ <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink>
+ and
+ <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink>.
+ Moreover, special value "*" means all messages (no filter).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>function</option>: function called
+ </para>
+ <para>
+ It uses following prototype:
+ <command>
+ int my_function (t_weechat_plugin *plugin,
+ int argc, char **argv,
+ char *modifier_args, void *modifier_pointer)
+ </command>
+ </para>
+ <para>
+ Argument argc is set to 2, following values are set in
+ argv array:
+ <itemizedlist>
+ <listitem>
+ <para>argv[0] = server name</para>
+ </listitem>
+ <listitem>
+ <para>argv[1] = message</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>modifier_args</option>: arguments given to function
+ when called
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>modifier_pointer</option>: pointer given to function
+ when called
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: pointer to new message modifier.
+ </para>
+ <para>
+ Note: function has to return modified string, or NULL if no
+ changes are made to message.
+ If function returns empty string, then message is dropped and
+ will not be read at all by WeeChat (be careful when dropping
+ messages!).
+ Returned string must have been allocated by malloc() and will
+ be freed (with call to free()) automatically by WeeChat after use.
+ </para>
+ <para>
+ Example:
+<screen>
+char *adder (t_weechat_plugin *plugin, int argc, char **argv,
+ char *modifier_args, void *modifier_pointer)
+{
+ char *string;
+ string = malloc (strlen (argv[1]) + 16);
+ strcpy (string, argv[1]);
+ strcat (string, "test");
+ return string;
+}
+...
+t_plugin_modifier *modifier;
+modifier = plugin->modifier_add (plugin, "irc_in", "privmsg",
+ &amp;adder, NULL, NULL);
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_modifier_remove">
+ <title>modifier_remove</title>
+
+ <para>
+ Prototype:
+ <command>
+ void modifier_remove (t_weechat_plugin *plugin,
+ t_plugin_modifier *modifier)
+ </command>
+ </para>
+ <para>
+ Remove a message modifier.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>modifier</option>: modifier to remove
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->modifier_remove (plugin, my_modifier);</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_modifier_remove_all">
+ <title>modifier_remove_all</title>
+
+ <para>
+ Prototype:
+ <command>
+ void modifier_remove_all (t_weechat_plugin *plugin)
+ </command>
+ </para>
+ <para>
+ Remove all modifiers for a plugin.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->modifier_remove_all (plugin);</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_exec_command">
+ <title>exec_command</title>
+
+ <para>
+ Prototype:
+ <command>
+ void exec_command (t_weechat_plugin
+ *plugin, char *server, char *channel, char *command)
+ </command>
+ </para>
+ <para>
+ Execute a WeeChat command (or send a message to a channel).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>server</option>: internal name of server for
+ executing command (may be NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>channel</option>: name of channel for executing
+ command (may be NULL)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>command</option>: command
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Examples:
+<screen>
+plugin->exec_command (plugin, NULL, NULL, "/help nick");
+plugin->exec_command (plugin, "freenode", "#weechat", "hello");
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_info">
+ <title>get_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ char *get_info (t_weechat_plugin *plugin,
+ char *info, char *server)
+ </command>
+ </para>
+ <para>
+ Return an info about WeeChat or a channel.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>info</option> : name of info to read:
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Info</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>version</literal></entry>
+ <entry>WeeChat's version</entry>
+ </row>
+ <row>
+ <entry><literal>nick</literal></entry>
+ <entry>nick</entry>
+ </row>
+ <row>
+ <entry><literal>channel</literal></entry>
+ <entry>
+ name of channel (NULL for a server or private)
+ </entry>
+ </row>
+ <row>
+ <entry><literal>server</literal></entry>
+ <entry>name of server</entry>
+ </row>
+ <row>
+ <entry><literal>type</literal></entry>
+ <entry>
+ buffer type: 0=standard, 1=DCC, 2=raw IRC data
+ </entry>
+ </row>
+ <row>
+ <entry><literal>away</literal></entry>
+ <entry>"away" flag</entry>
+ </row>
+ <row>
+ <entry><literal>inactivity</literal></entry>
+ <entry>
+ number of seconds since last key was pressed
+ </entry>
+ </row>
+ <row>
+ <entry><literal>input</literal></entry>
+ <entry>
+ content of command line for current window
+ </entry>
+ </row>
+ <row>
+ <entry><literal>input_mask</literal></entry>
+ <entry>
+ content of color mask for command line
+ </entry>
+ </row>
+ <row>
+ <entry><literal>input_pos</literal></entry>
+ <entry>
+ cursor position in command line
+ </entry>
+ </row>
+ <row>
+ <entry><literal>weechat_dir</literal></entry>
+ <entry>
+ WeeChat home directory
+ (by default: ~/.weechat/)
+ </entry>
+ </row>
+ <row>
+ <entry><literal>weechat_libdir</literal></entry>
+ <entry>WeeChat system lib directory</entry>
+ </row>
+ <row>
+ <entry><literal>weechat_sharedir</literal></entry>
+ <entry>WeeChat system share directory</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>server</option>: internal name of server for
+ reading info (if needed)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: information asked, NULL if not found.
+ </para>
+ <para>
+ Note: result has to be free by a call to "free" function after
+ use.
+ </para>
+ <para>
+ Examples:
+<screen>
+char *version = plugin->get_info (plugin, "version", NULL);
+char *nick = plugin->get_info (plugin, "nick", "freenode");
+char *inactivity = plugin->get_info (plugin, "inactivity", NULL);
+
+plugin->print (plugin, NULL, NULL,
+ "WeeChat version %s, you are %s on freenode "
+ "(inactive for %s seconds)",
+ version, nick, inactivity);
+
+if (version)
+ free (version);
+if (nick)
+ free (nick);
+if (inactivity)
+ free (inactivity);
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_dcc_info">
+ <title>get_dcc_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_info_dcc *get_dcc_info (t_weechat_plugin *plugin)
+ </command>
+ </para>
+ <para>
+ Return list of DCC currently active or finished.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: linked list of DCC.
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Field</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>server</literal></entry>
+ <entry>IRC server</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>channel</literal></entry>
+ <entry>IRC channel</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>type</literal></entry>
+ <entry>
+ DCC type:
+ 0 = chat received,
+ 1 = chat sent,
+ 2 = file received,
+ 3 = file sent
+ </entry>
+ </row>
+ <row>
+ <entry>int*</entry>
+ <entry><literal>status</literal></entry>
+ <entry>
+ DCC status:
+ 0 = waiting,
+ 1 = connecting,
+ 2 = active,
+ 3 = finished,
+ 4 = failed,
+ 5 = interrupted by user
+ </entry>
+ </row>
+ <row>
+ <entry>time_t</entry>
+ <entry><literal>start_time</literal></entry>
+ <entry>date/time of DCC creation</entry>
+ </row>
+ <row>
+ <entry>time_t</entry>
+ <entry><literal>start_transfer</literal></entry>
+ <entry>date/time of DCC transfer start</entry>
+ </row>
+ <row>
+ <entry>unsigned long</entry>
+ <entry><literal>addr</literal></entry>
+ <entry>IP address of remote user</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>port</literal></entry>
+ <entry>port used for DCC</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>nick</literal></entry>
+ <entry>remote nick</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>filename</literal></entry>
+ <entry>file name</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>local_filename</literal></entry>
+ <entry>local file name</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>filename_suffix</literal></entry>
+ <entry>suffix if renaming file</entry>
+ </row>
+ <row>
+ <entry>unsigned long</entry>
+ <entry><literal>size</literal></entry>
+ <entry>file size</entry>
+ </row>
+ <row>
+ <entry>unsigned long</entry>
+ <entry><literal>pos</literal></entry>
+ <entry>position in file</entry>
+ </row>
+ <row>
+ <entry>unsigned long</entry>
+ <entry><literal>start_resume</literal></entry>
+ <entry>start position after interruption</entry>
+ </row>
+ <row>
+ <entry>unsigned long</entry>
+ <entry><literal>bytes_per_sec</literal></entry>
+ <entry>
+ number of bytes per second since transfer start
+ </entry>
+ </row>
+ <row>
+ <entry>t_plugin_dcc_info *</entry>
+ <entry><literal>prev_dcc</literal></entry>
+ <entry>
+ pointer to previous DCC info
+ </entry>
+ </row>
+ <row>
+ <entry>t_plugin_dcc_info *</entry>
+ <entry><literal>next_dcc</literal></entry>
+ <entry>
+ pointer to next DCC info
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Note: result has to be free by a call to "free_dcc_info" function
+ after use.
+ </para>
+ <para>
+ Examples:
+<screen>
+t_plugin_dcc_info *dcc_info = plugin->get_dcc_info (plugin);
+for (ptr_dcc = dcc_info; ptr_dcc; ptr_dcc = ptr_dcc->next_dcc)
+{
+ plugin->print_server (plugin, "DCC type=%d, with: %s",
+ ptr_dcc->type, ptr_dcc->nick);
+}
+if (dcc_info)
+ plugin->free_dcc_info (plugin, dcc_info);
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_free_dcc_info">
+ <title>free_dcc_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ void free_dcc_info (t_weechat_plugin *plugin,
+ t_plugin_dcc_info *dcc_info)
+ </command>
+ </para>
+ <para>
+ Free memory used by a DCC list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>dcc_info</option>: pointer to DCC list returned by
+ "get_dcc_info" function
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->free_dcc_info (plugin, dcc_info);</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_server_info">
+ <title>get_server_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_server_info *get_server_info (t_weechat_plugin *plugin)
+ </command>
+ </para>
+ <para>
+ Return list of IRC servers (connected or not).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: linked list of IRC servers.
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Field</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>name</literal></entry>
+ <entry>server internal name</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>autoconnect</literal></entry>
+ <entry>1 if autoconnect at start-up, 0 otherwise</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>autoreconnect</literal></entry>
+ <entry>
+ 1 if autoreconnect when disconnected,
+ 0 otherwise
+ </entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>autoreconnect_delay</literal></entry>
+ <entry>delay before trying again connection</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>command_line</literal></entry>
+ <entry>
+ 1 if server was on command line (so it is temporary),
+ 0 otherwise
+ </entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>address</literal></entry>
+ <entry>server address (host or IP)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>port</literal></entry>
+ <entry>port</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>ipv6</literal></entry>
+ <entry>IPv6 connection</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>ssl</literal></entry>
+ <entry>SSL connection</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>password</literal></entry>
+ <entry>server password</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>nick1</literal></entry>
+ <entry>first nickname</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>nick2</literal></entry>
+ <entry>alternate nickname</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>nick3</literal></entry>
+ <entry>second alternate nickname</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>username</literal></entry>
+ <entry>user name</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>real name</literal></entry>
+ <entry>real name</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>command</literal></entry>
+ <entry>command run once connected</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>command_delay</literal></entry>
+ <entry>delay after execution of command</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>autojoin</literal></entry>
+ <entry>channels joined automatically</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>autorejoin</literal></entry>
+ <entry>
+ 1 if channels are rejoined when kicked,
+ 0 otherwise
+ </entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>notify_levels</literal></entry>
+ <entry>channels notify levels</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>charset_decode_iso</literal></entry>
+ <entry>channels charsets for decoding ISO</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>charset_decode_utf</literal></entry>
+ <entry>channels charsets for decoding UTF</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>charset_encode</literal></entry>
+ <entry>channels charsets for encoding messages</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>is_connected</literal></entry>
+ <entry>1 if connected to server, 0 otherwise</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>ssl_connected</literal></entry>
+ <entry>1 if connected with SSL, 0 otherwise</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>nick</literal></entry>
+ <entry>current nickname</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>is_away</literal></entry>
+ <entry>1 if away, 0 otherwise</entry>
+ </row>
+ <row>
+ <entry>time_t</entry>
+ <entry><literal>away_time</literal></entry>
+ <entry>time when user is marking as away</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>lag</literal></entry>
+ <entry>lag (in milliseconds)</entry>
+ </row>
+ <row>
+ <entry>t_plugin_server_info *</entry>
+ <entry><literal>prev_server</literal></entry>
+ <entry>pointer to previous server info</entry>
+ </row>
+ <row>
+ <entry>t_plugin_server_info *</entry>
+ <entry><literal>next_server</literal></entry>
+ <entry>pointer to next server info</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Note: result has to be free by a call to "free_server_info"
+ function after use.
+ </para>
+ <para>
+ Example:
+<screen>
+t_plugin_server_info *server_info, *ptr_server_info;
+server_info = plugin->get_server_info (plugin);
+if (server_info)
+{
+ for (ptr_server_info = server_info; ptr_server_info;
+ ptr_server_info = ptr_server_info->next_server)
+ {
+ plugin->print (plugin, NULL, NULL,
+ "server: %s, address: %s, port: %d %s",
+ ptr_server_info->name,
+ ptr_server_info->address,
+ ptr_server_info->port,
+ (ptr_server_info->is_connected) ? "(connected)" : "");
+ }
+ plugin->free_server_info (plugin, server_info);
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_free_server_info">
+ <title>free_server_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ void free_server_info (t_weechat_plugin *plugin,
+ t_plugin_server_info *server_info)
+ </command>
+ </para>
+ <para>
+ Free memory used by server info list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>server_info</option>: pointer to server list
+ returned by "get_server_info" function
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->free_server_info (plugin, server_info);</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_channel_info">
+ <title>get_channel_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_channel_info *get_channel_info (t_weechat_plugin *plugin,
+ char *server)
+ </command>
+ </para>
+ <para>
+ Return list of IRC channels for a server.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>server</option>: internal server name
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: linked list of IRC channels for server.
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Field</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry><literal>type</literal></entry>
+ <entry>0 for a channel, 1 for a private</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>name</literal></entry>
+ <entry>name of channel</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>topic</literal></entry>
+ <entry>topic of channel</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>modes</literal></entry>
+ <entry>channel modes</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>limit</literal></entry>
+ <entry>user limit</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>key</literal></entry>
+ <entry>channel key</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>nicks_count</literal></entry>
+ <entry>number of nicks on channel</entry>
+ </row>
+ <row>
+ <entry>t_plugin_channel_info *</entry>
+ <entry><literal>prev_channel</literal></entry>
+ <entry>pointer to previous channel info</entry>
+ </row>
+ <row>
+ <entry>t_plugin_channel_info *</entry>
+ <entry><literal>next_channel</literal></entry>
+ <entry>pointer to next channel info</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Note: result has to be free by a call to "free_channel_info"
+ function after use.
+ </para>
+ <para>
+ Example:
+<screen>
+t_plugin_channel_info *channel_info, *ptr_chan_info;
+channel_info = plugin->get_channel_info (plugin, "freenode");
+if (channel_info)
+{
+ for (ptr_chan_info = channel_info; ptr_chan_info;
+ ptr_chan_info = ptr_chan_info->next_channel)
+ {
+ plugin->print (plugin, NULL, NULL,
+ " %s (type %d)",
+ ptr_chan_info->name,
+ ptr_chan_info->type);
+ }
+ plugin->free_channel_info (plugin, channel_info);
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_free_channel_info">
+ <title>free_channel_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ void free_channel_info (t_weechat_plugin *plugin,
+ t_plugin_channel_info *channel_info)
+ </command>
+ </para>
+ <para>
+ Free memory used by channel info list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>channel_info</option>: pointer to channel info list
+ returned by "get_channel_info" function
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->free_channel_info (plugin, channel_info);</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_nick_info">
+ <title>get_nick_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_nick_info *get_nick_info (t_weechat_plugin *plugin,
+ char *server, char *channel)
+ </command>
+ </para>
+ <para>
+ Return list of nicks for a channel.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>server</option>: internal server name
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>channel</option>: channel name
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: linked list of nicks on channel.
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Field</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>nick</literal></entry>
+ <entry>nick name</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>host</literal></entry>
+ <entry>hostname</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>flags</literal></entry>
+ <entry>
+ nick flags, binary "or" between values (1 = channel
+ owner, 2 = channel admin, 4 = op, 8 = halfop,
+ 16 = voice, 32 = away)
+ </entry>
+ </row>
+ <row>
+ <entry>t_plugin_nick_info *</entry>
+ <entry><literal>prev_nick</literal></entry>
+ <entry>pointer to previous nick info</entry>
+ </row>
+ <row>
+ <entry>t_plugin_nick_info *</entry>
+ <entry><literal>next_nick</literal></entry>
+ <entry>pointer to next nick info</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Note: result has to be free by a call to "free_nick_info"
+ function after use.
+ </para>
+ <para>
+ Example:
+<screen>
+t_plugin_nick_info *nick_info, *ptr_nick_info;
+nick_info = plugin->get_nick_info (plugin, "freenode", "#weechat");
+if (nick_info)
+{
+ for (ptr_nick_info = nick_info; ptr_nick_info;
+ ptr_nick_info = ptr_nick_info->next_nick)
+ {
+ plugin->print (plugin, NULL, NULL,
+ " %s (flags: %d)",
+ ptr_nick_info->nick,
+ ptr_nick_info->flags);
+ }
+ plugin->free_nick_info (plugin, nick_info);
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_free_nick_info">
+ <title>free_nick_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ void free_nick_info (t_weechat_plugin *plugin,
+ t_plugin_nick_info *nick_info)
+ </command>
+ </para>
+ <para>
+ Free memory used by nick info list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>nick_info</option>: pointer to nick info list
+ returned by "get_nick_info" function
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->free_nick_info (plugin, nick_info);</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_config">
+ <title>get_config</title>
+
+ <para>
+ Prototype:
+ <command>
+ char *get_config (t_weechat_plugin *plugin, char *option)
+ </command>
+ </para>
+ <para>
+ Return value of a WeeChat config option.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>option</option>: name of option to read
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: option value, NULL if not found.
+ </para>
+ <para>
+ Note: result has to be free by a call to "free" function after
+ use.
+ </para>
+ <para>
+ Examples:
+<screen>
+char *value1 = plugin->get_config (plugin, "look_set_title");
+char *value2 = plugin->get_config (plugin, "freenode.server_autojoin");
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_set_config">
+ <title>set_config</title>
+
+ <para>
+ Prototype:
+ <command>
+ int set_config (t_weechat_plugin *plugin,
+ char *option, char *value)
+ </command>
+ </para>
+ <para>
+ Update value of a WeeChat config option.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>option</option>: name of option to update
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>value</option>: new value for option
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if option was successfully updated, 0 if an
+ error occurred.
+ </para>
+ <para>
+ Example:
+<screen>
+plugin->set_config (plugin, "look_nicklist", "off");
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_plugin_config">
+ <title>get_plugin_config</title>
+
+ <para>
+ Prototype:
+ <command>
+ char *get_plugin_config (t_weechat_plugin *plugin, char *option)
+ </command>
+ </para>
+ <para>
+ Return value of a plugin option.
+ Option is read from file "<literal>~/.weechat/plugins.rc</literal>"
+ and is like: "<literal>plugin.option=value</literal>"
+ (note: plugin name is automatically added).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>option</option>: name of option to read
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: option value, NULL if not found.
+ </para>
+ <para>
+ Note: result has to be free by a call to "free" function after
+ use.
+ </para>
+ <para>
+ Example:
+<screen>
+char *value = plugin->get_plugin_config (plugin, "my_var");
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_set_plugin_config">
+ <title>set_plugin_config</title>
+
+ <para>
+ Prototype:
+ <command>
+ int set_plugin_config (t_weechat_plugin *plugin,
+ char *option, char *value)
+ </command>
+ </para>
+ <para>
+ Update value of a plugin option.
+ Option is written in file "<literal>~/.weechat/plugins.rc</literal>"
+ and is like: "<literal>plugin.option=value</literal>"
+ (note: plugin name is automatically added).
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>option</option>: name of option to update
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>value</option>: new value for option
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: 1 if option was successfully updated, 0 if an
+ error occurred.
+ </para>
+ <para>
+ Example:
+<screen>
+plugin->set_plugin_config (plugin, "my_var", "value");
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_irc_color">
+ <title>get_irc_color</title>
+
+ <para>
+ Prototype:
+ <command>
+ int get_irc_color (t_weechat_plugin *plugin,
+ char *color_name)
+ </command>
+ </para>
+ <para>
+ Get IRC color index with name.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>color_name</option>: color name
+ Allowed colors are:
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Color name</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>white</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry>black</entry>
+ <entry>1</entry>
+ </row>
+ <row>
+ <entry>blue</entry>
+ <entry>2</entry>
+ </row>
+ <row>
+ <entry>green</entry>
+ <entry>3</entry>
+ </row>
+ <row>
+ <entry>lightred</entry>
+ <entry>4</entry>
+ </row>
+ <row>
+ <entry>red</entry>
+ <entry>5</entry>
+ </row>
+ <row>
+ <entry>magenta</entry>
+ <entry>6</entry>
+ </row>
+ <row>
+ <entry>brown</entry>
+ <entry>7</entry>
+ </row>
+ <row>
+ <entry>yellow</entry>
+ <entry>8</entry>
+ </row>
+ <row>
+ <entry>lightgreen</entry>
+ <entry>9</entry>
+ </row>
+ <row>
+ <entry>cyan</entry>
+ <entry>10</entry>
+ </row>
+ <row>
+ <entry>lightcyan</entry>
+ <entry>11</entry>
+ </row>
+ <row>
+ <entry>lightblue</entry>
+ <entry>12</entry>
+ </row>
+ <row>
+ <entry>lightmagenta</entry>
+ <entry>13</entry>
+ </row>
+ <row>
+ <entry>gray</entry>
+ <entry>14</entry>
+ </row>
+ <row>
+ <entry>lightgray</entry>
+ <entry>15</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: IRC color index, -1 if color is not found.
+ </para>
+ <para>
+ Example:
+<screen>
+int color_blue = plugin->get_irc_color (plugin, "blue"); /* return 2 */
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_input_color">
+ <title>input_color</title>
+
+ <para>
+ Prototype:
+ <command>
+ void input_color (t_weechat_plugin *plugin,
+ int color, int start, int length)
+ </command>
+ </para>
+ <para>
+ Add color in input buffer.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>color</option>: color for text (if &lt; 0, then input
+ buffer is refresh, and there's no change in input buffer
+ content)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>start</option>: start position for color (if &lt; 0,
+ then mask is reinitialized)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>length</option>: length for color (if &lt;= 0,
+ then mask is reinitialized)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+<screen>
+plugin->input_color (plugin, plugin->get_irc_color (plugin, "blue"), 10, 5);
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_window_info">
+ <title>get_window_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_window_info *get_window_info (t_weechat_plugin *plugin)
+ </command>
+ </para>
+ <para>
+ Return list of WeeChat windows.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: linked list of WeeChat windows.
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Field</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry><literal>win_x</literal></entry>
+ <entry>horizontal position of window</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>win_y</literal></entry>
+ <entry>vertical position of window</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>win_width</literal></entry>
+ <entry>width of window</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>win_height</literal></entry>
+ <entry>height of window</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>win_width_pct</literal></entry>
+ <entry>width % (compared to parent window)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>win_height_pct</literal></entry>
+ <entry>height % (compared to parent window)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>num_buffer</literal></entry>
+ <entry>number of displayed buffer</entry>
+ </row>
+ <row>
+ <entry>t_plugin_window_info *</entry>
+ <entry><literal>prev_window</literal></entry>
+ <entry>pointer to previous window info</entry>
+ </row>
+ <row>
+ <entry>t_plugin_window_info *</entry>
+ <entry><literal>next_window</literal></entry>
+ <entry>pointer to next window info</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Note: result has to be free by a call to "free_window_info"
+ function after use.
+ </para>
+ <para>
+ Example:
+<screen>
+t_plugin_window_info *window_info, *ptr_window;
+
+window_info = plugin->get_window_info (plugin);
+if (window_info)
+{
+ for (ptr_window = window_info; ptr_window; ptr_window = ptr_window->next_window)
+ {
+ plugin->print (plugin, NULL, NULL, "window info");
+ plugin->print (plugin, NULL, NULL, "(%d,%d), size: %dx%d, %%size: %d%%x%d%%",
+ ptr_window->win_x, ptr_window->win_y,
+ ptr_window->win_width, ptr_window->win_height,
+ ptr_window->win_width_pct, ptr_window->win_height_pct);
+ plugin->print (plugin, NULL, NULL, "num_buffer: %d", ptr_window->num_buffer);
+ }
+ plugin->free_window_info (plugin, window_info);
+}
+else
+ plugin->print (plugin, NULL, NULL, "no window info!");
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_free_window_info">
+ <title>free_window_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ void free_window_info (t_weechat_plugin *plugin,
+ t_plugin_window_info *window_info)
+ </command>
+ </para>
+ <para>
+ Free memory used by window info list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>window_info</option>: pointer to window info list
+ returned by "get_window_info" function
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->free_window_info (plugin, window_info);</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_buffer_info">
+ <title>get_buffer_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_buffer_info *get_buffer_info (t_weechat_plugin *plugin)
+ </command>
+ </para>
+ <para>
+ Return list of WeeChat buffers.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: linked list of WeeChat buffers.
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Field</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>int</entry>
+ <entry><literal>type</literal></entry>
+ <entry>buffer type: 0=standard, 1=DCC, 2=raw IRC data</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>number</literal></entry>
+ <entry>buffer number</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>num_displayed</literal></entry>
+ <entry>number of windows displaying buffer</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>server_name</literal></entry>
+ <entry>server name for buffer (may be NULL)</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>channel_name</literal></entry>
+ <entry>channel name for buffer (may be NULL)</entry>
+ </row>
+ <row>
+ <entry>int</entry>
+ <entry><literal>notify_level</literal></entry>
+ <entry>notify level for buffer</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>log_filename</literal></entry>
+ <entry>log filename (NULL means not logging)</entry>
+ </row>
+ <row>
+ <entry>t_plugin_buffer_info *</entry>
+ <entry><literal>prev_buffer</literal></entry>
+ <entry>pointer to previous buffer info</entry>
+ </row>
+ <row>
+ <entry>t_plugin_buffer_info *</entry>
+ <entry><literal>next_buffer</literal></entry>
+ <entry>pointer to next buffer info</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Note: result has to be free by a call to "free_buffer_info"
+ function after use.
+ </para>
+ <para>
+ Example:
+<screen>
+t_plugin_buffer_info *buffer_info, *ptr_buffer;
+
+buffer_info = plugin->get_buffer_info (plugin);
+if (buffer_info)
+{
+ for (ptr_buffer = buffer_info; ptr_buffer; ptr_buffer = ptr_buffer->next_buffer)
+ {
+ plugin->print (plugin, NULL, NULL, "buffer info");
+ plugin->print (plugin, NULL, NULL, "type: %d", ptr_buffer->type);
+ plugin->print (plugin, NULL, NULL, "number: %d", ptr_buffer->number);
+ plugin->print (plugin, NULL, NULL, "num_displayed: %d", ptr_buffer->num_displayed);
+ plugin->print (plugin, NULL, NULL, "server: %s", ptr_buffer->server_name);
+ plugin->print (plugin, NULL, NULL, "channel: %s", ptr_buffer->channel_name);
+ plugin->print (plugin, NULL, NULL, "notify level: %d", ptr_buffer->notify_level);
+ plugin->print (plugin, NULL, NULL, "log filename: %s", ptr_buffer->log_filename);
+ }
+ plugin->free_buffer_info (plugin, buffer_info);
+}
+else
+ plugin->print (plugin, NULL, NULL, "no buffer info!");
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_free_buffer_info">
+ <title>free_buffer_info</title>
+
+ <para>
+ Prototype:
+ <command>
+ void free_buffer_info (t_weechat_plugin *plugin,
+ t_plugin_buffer_info *buffer_info)
+ </command>
+ </para>
+ <para>
+ Free memory used by buffer info list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>buffer_info</option>: pointer to buffer info list
+ returned by "get_buffer_info" function
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->free_buffer_info (plugin, buffer_info);</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_get_buffer_data">
+ <title>get_buffer_data</title>
+
+ <para>
+ Prototype:
+ <command>
+ t_plugin_buffer_data *get_buffer_info (t_weechat_plugin *plugin,
+ char *server, char *channel)
+ </command>
+ </para>
+ <para>
+ Return content of buffer.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>server</option>: internal name of server
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>channel</option>: channel name
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: buffer content (linked list of lines).
+ <informaltable colsep="0" frame="none">
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Field</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>time_t</entry>
+ <entry><literal>date</literal></entry>
+ <entry>date and time</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>nick</literal></entry>
+ <entry>nick</entry>
+ </row>
+ <row>
+ <entry>char *</entry>
+ <entry><literal>data</literal></entry>
+ <entry>line content (color codes are removed)</entry>
+ </row>
+ <row>
+ <entry>t_plugin_buffer_line *</entry>
+ <entry><literal>prev_line</literal></entry>
+ <entry>pointer to previous line</entry>
+ </row>
+ <row>
+ <entry>t_plugin_buffer_line *</entry>
+ <entry><literal>next_line</literal></entry>
+ <entry>pointer to next line</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ <para>
+ Note: result has to be free by a call to "free_buffer_data"
+ function after use.
+ </para>
+ <para>
+ Example:
+<screen>
+t_plugin_buffer_line *buffer_line, *ptr_line;
+char text_time[256];
+
+buffer_line = plugin->get_buffer_data (plugin);
+if (buffer_line)
+{
+ for (ptr_line = buffer_line; ptr_line; ptr_line = ptr_line->next_line)
+ {
+ strftime (text_time, sizeof (text_time), "%x %X", localtime (&amp;(ptr_line->date)));
+ plugin->print (plugin, NULL, NULL, "date: %s, nick: %s, data: %s",
+ text_time, ptr_line->nick, ptr_line->data);
+ }
+ plugin->free_buffer_data (plugin, buffer_line);
+}
+</screen>
+ </para>
+ </section>
+
+ <section id="secAPI_free_buffer_data">
+ <title>free_buffer_data</title>
+
+ <para>
+ Prototype:
+ <command>
+ void free_buffer_data (t_weechat_plugin *plugin,
+ t_plugin_buffer_line *buffer_line)
+ </command>
+ </para>
+ <para>
+ Free memory used by buffer line list.
+ </para>
+ <para>
+ Arguments:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <option>plugin</option>: pointer to plugin structure
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <option>buffer_line</option>: pointer to buffer line list
+ returned by "get_buffer_data" function
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Return value: none.
+ </para>
+ <para>
+ Example:
+ <screen>plugin->free_buffer_data (plugin, buffer_line);</screen>
+ </para>
+ </section>
+
+ -->
+
+</section>
diff --git a/doc/en/dev/plugin_scripts.en.xml b/doc/en/dev/plugin_script_api.en.xml
index a4aa2ea7a..a1b13e537 100644
--- a/doc/en/dev/plugin_scripts.en.xml
+++ b/doc/en/dev/plugin_script_api.en.xml
@@ -21,8 +21,10 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
-->
-<section id="secScriptsPlugins">
- <title>Scripts plugins</title>
+<section id="secScriptPluginAPI">
+ <title>Script plugin API</title>
+
+ <!--
<para>
Four plugins are provided with WeeChat to use script languages:
@@ -2846,4 +2848,6 @@ end
</section>
+ -->
+
</section>
diff --git a/doc/en/dev/plugins.en.xml b/doc/en/dev/plugins.en.xml
index fd2e2f7db..6b8456114 100644
--- a/doc/en/dev/plugins.en.xml
+++ b/doc/en/dev/plugins.en.xml
@@ -129,8 +129,6 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
</informaltable>
</para>
- &plugin_api.en.xml;
-
<section id="secCompilePlugin">
<title>Compile plugin</title>
@@ -237,14 +235,4 @@ weechat_plugin_end (struct t_weechat_plugin *plugin)
</section>
- &plugin_irc.en.xml;
-
- <!-- &plugin_charset.en.xml; -->
-
- &plugin_fifo.en.xml;
-
- <!-- &plugin_scripts.en.xml; -->
-
- &plugin_xfer.en.xml;
-
</chapter>
diff --git a/doc/en/dev/weechat_dev.en.xml b/doc/en/dev/weechat_dev.en.xml
index e21d3cf0e..c7c361fcb 100644
--- a/doc/en/dev/weechat_dev.en.xml
+++ b/doc/en/dev/weechat_dev.en.xml
@@ -30,11 +30,12 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
%include_autogen.xml;
<!-- ***** written by hand: ***** -->
- <!ENTITY intro.en.xml SYSTEM "intro.en.xml">
- <!ENTITY plugins.en.xml SYSTEM "plugins.en.xml">
- <!ENTITY plugin_api.en.xml SYSTEM "plugin_api.en.xml">
- <!ENTITY plugin_scripts.en.xml SYSTEM "plugin_scripts.en.xml">
- <!ENTITY authors.en.xml SYSTEM "authors.en.xml">
+ <!ENTITY intro.en.xml SYSTEM "intro.en.xml">
+ <!ENTITY plugins.en.xml SYSTEM "plugins.en.xml">
+ <!ENTITY plugin_api.en.xml SYSTEM "plugin_api.en.xml">
+ <!ENTITY plugin_c_api.en.xml SYSTEM "plugin_c_api.en.xml">
+ <!ENTITY plugin_script_api.en.xml SYSTEM "plugin_script_api.en.xml">
+ <!ENTITY authors.en.xml SYSTEM "authors.en.xml">
]>
<book lang="en">
@@ -94,7 +95,9 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
&intro.en.xml;
- <!-- &plugins.en.xml; -->
+ &plugins.en.xml;
+
+ &plugin_api.en.xml;
&authors.en.xml;