blackbeard420/weechat
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
weechat/doc/en/dev/plugin_c_api.en.xml
Sebastien Helleu 861bc2fbfd Add some API functions in Developer guide
2008-11-10 18:05:48 +01:00

8359 lines
234 KiB
XML
Raw Blame History

<?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, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>char *</entry>
<entry>filename</entry>
<entry>filename found</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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), arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_config_file *</entry>
<entry>config_file</entry>
<entry>configuration file pointer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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),
arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_config_file *</entry>
<entry>config_file</entry>
<entry>configuration file pointer</entry>
</row>
<row>
<entry>struct t_config_section *</entry>
<entry>section</entry>
<entry>section pointer</entry>
</row>
<row>
<entry>const char *</entry>
<entry>option_name</entry>
<entry>name of option</entry>
</row>
<row>
<entry>const char *</entry>
<entry>value</entry>
<entry>value</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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), arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_config_file *</entry>
<entry>config_file</entry>
<entry>configuration file pointer</entry>
</row>
<row>
<entry>struct t_config_section *</entry>
<entry>section</entry>
<entry>section pointer</entry>
</row>
<row>
<entry>const char *</entry>
<entry>option_name</entry>
<entry>name of option</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_config_file *</entry>
<entry>config_file</entry>
<entry>configuration file pointer</entry>
</row>
<row>
<entry>char *</entry>
<entry>section_name</entry>
<entry>name of section</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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), arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_config_file *</entry>
<entry>config_file</entry>
<entry>configuration file pointer</entry>
</row>
<row>
<entry>struct t_config_section *</entry>
<entry>section</entry>
<entry>section pointer</entry>
</row>
<row>
<entry>const char *</entry>
<entry>option_name</entry>
<entry>name of option</entry>
</row>
<row>
<entry>const char *</entry>
<entry>value</entry>
<entry>value</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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), arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_config_file *</entry>
<entry>config_file</entry>
<entry>configuration file pointer</entry>
</row>
<row>
<entry>struct t_config_section *</entry>
<entry>section</entry>
<entry>section pointer</entry>
</row>
<row>
<entry>struct t_config_option *option</entry>
<entry>option</entry>
<entry>option pointer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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), arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_config_option *</entry>
<entry>option</entry>
<entry>option pointer</entry>
</row>
<row>
<entry>const char *</entry>
<entry>value</entry>
<entry>new value for option</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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), arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_config_option *</entry>
<entry>option</entry>
<entry>option pointer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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), arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_config_option *</entry>
<entry>option</entry>
<entry>option pointer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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>
<!-- =============================[ hooks ]============================== -->
<section id="secPluginCApi_hooks">
<title>Hooks</title>
<para>
Functions to hook/unhook something.
</para>
<section id="secPluginCApi_weechat_hook_command">
<title>weechat_hook_command</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_command (
const char *command,
const char *description,
const char *args,
const char *args_description,
const char *completion,
int (*callback)(void *data,
struct t_gui_buffer *buffer,
int argc, char **argv,
char **argv_eol),
void *callback_data);
</programlisting>
</para>
<para>
Hook a command.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>command</option>: new command name
</para>
</listitem>
<listitem>
<para>
<option>description</option>: description of command (displayed
with <command>/help command</command>)
</para>
</listitem>
<listitem>
<para>
<option>args</option>: arguments for command (displayed with
<command>/help command</command>)
</para>
</listitem>
<listitem>
<para>
<option>args_description</option>: description of arguments
(displayed with <command>/help command</command>)
</para>
</listitem>
<listitem>
<para>
<option>completion</option>: completion template for command:
list of completions for each arguments, separated by space. Many
completions are possible for one argument, separated by "|".
Default completion codes are:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Code</entry>
<entry>Completion</entry>
</row>
</thead>
<tbody>
<row>
<entry>%-</entry>
<entry>Stop completion</entry>
</row>
<row>
<entry>%*</entry>
<entry>Repeat last completion</entry>
</row>
<row>
<entry>%b</entry>
<entry>Buffers names</entry>
</row>
<row>
<entry>%c</entry>
<entry>Configuration files</entry>
</row>
<row>
<entry>%f</entry>
<entry>Filename</entry>
</row>
<row>
<entry>%F</entry>
<entry>Filters</entry>
</row>
<row>
<entry>%h</entry>
<entry>Commands hooked</entry>
</row>
<row>
<entry>%i</entry>
<entry>Infos hooked</entry>
</row>
<row>
<entry>%I</entry>
<entry>Infolists hooked</entry>
</row>
<row>
<entry>%n</entry>
<entry>Nick</entry>
</row>
<row>
<entry>%o</entry>
<entry>Configuration option</entry>
</row>
<row>
<entry>%p</entry>
<entry>Plugin name</entry>
</row>
<row>
<entry>%P</entry>
<entry>Plygin commands</entry>
</row>
<row>
<entry>%r</entry>
<entry>Bar names</entry>
</row>
<row>
<entry>%v</entry>
<entry>Value of configuration opeion</entry>
</row>
<row>
<entry>%w</entry>
<entry>WeeChat commands</entry>
</row>
<row>
<entry>%(xxx)</entry>
<entry>Custom completion by plugin (xxx is a completion
code added by a plugin)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when command is used,
arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_gui_buffer *</entry>
<entry>buffer</entry>
<entry>buffer where command is executed</entry>
</row>
<row>
<entry>int</entry>
<entry>argc</entry>
<entry>argument count</entry>
</row>
<row>
<entry>char **</entry>
<entry>argv</entry>
<entry>arguments</entry>
</row>
<row>
<entry>char **</entry>
<entry>argv_eol</entry>
<entry>arguments (until end of line)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
For example, if command called is
<command>/command abc def ghi</command>, then argv and argv_eol
contain following values:
<itemizedlist>
<listitem><para>argv[0] == "abc"</para></listitem>
<listitem><para>argv[1] == "def"</para></listitem>
<listitem><para>argv[2] == "ghi"</para></listitem>
<listitem><para>argv_eol[0] == "abc def ghi"</para></listitem>
<listitem><para>argv_eol[1] == "def ghi"</para></listitem>
<listitem><para>argv_eol[2] == "ghi"</para></listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
<option>callback_data</option>: pointer given to callback when it
is called by WeeeChat
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
int
my_command_cb (void *data, struct t_gui_buffer *buffer, int argc,
char **argv, char **argv_eol)
{
/* ... */
return WEECHAT_RC_OK;
}
struct t_hook *my_command = weechat_hook_command ("mycommand",
"description of my command",
"[command [buffer]]",
"command: WeeChat or plugin command\n"
" buffer: buffer name",
"%w|%p %b", &amp;my_command_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_timer">
<title>weechat_hook_timer</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_timer (
long interval,
const char *align_second,
const char *max_calls,
int (*callback)(void *data),
void *callback_data);
</programlisting>
</para>
<para>
Hook a timer.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>interval</option>: interval between two calls
(milliseconds, so 1000 = 1 second)
</para>
</listitem>
<listitem>
<para>
<option>align_second</option>: alignment on a second: align timer
on a second. For example, if current time is 09:00, if
interval = 60000 (60 seconds), and align_second = 60, then timer
is called each minute when second is 00.
</para>
</listitem>
<listitem>
<para>
<option>max_calls</option>: number of calls to timer (if 0, then
timer has no end)
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when time is reached,
arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>callback_data</option>: pointer given to callback when it
is called by WeeeChat
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
int
my_timer_cb (void *data)
{
/* ... */
return WEECHAT_RC_OK;
}
/* timer called each 20 seconds */
struct t_hook *my_timer = weechat_hook_timer (20 * 1000, 0, 0,
&amp;my_timer_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_fd">
<title>weechat_hook_fd</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_fd (
int fd,
int flag_read,
int flag_write,
int flag_exception,
int (*callback)(void *data),
void *callback_data);
</programlisting>
</para>
<para>
Hook a file descriptor (file or socket).
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>fd</option>: file descriptor
</para>
</listitem>
<listitem>
<para>
<option>flag_read</option>: 1 for catching read event, 0 for
ignoring it
</para>
</listitem>
<listitem>
<para>
<option>flag_write</option>: 1 for catching write event, 0 for
ignoring it
</para>
</listitem>
<listitem>
<para>
<option>flag_exception</option>: 1 for catching exception event,
0 for ignoring it
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when a selected event
occurs, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>callback_data</option>: pointer given to callback when it
is called by WeeeChat
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
int
my_fd_cb (void *data)
{
/* ... */
return WEECHAT_RC_OK;
}
int sock = socket (AF_INET, SOCK_STREAM, 0);
/* set socket options */
/* ... */
/* hook socket */
struct t_hook *my_fd = weechat_hook_fd (sock,
1, 0, 0,
&amp;my_fd_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_connect">
<title>weechat_hook_connect</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_connect (
const char *address,
int port,
int sock,
int ipv6,
void *gnutls_sess,
const char *local_hostname,
int (*callback)(void *data,
int status,
const char *ip_address),
void *callback_data);
</programlisting>
</para>
<para>
Hook a connection (background connection to a remote host).
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>address</option>: name or IP address to connect to
</para>
</listitem>
<listitem>
<para>
<option>port</option>: port number
</para>
</listitem>
<listitem>
<para>
<option>sock</option>: socket used to connect
</para>
</listitem>
<listitem>
<para>
<option>ipv6</option>: 1 to use IPv6, 0 to use IPv4
</para>
</listitem>
<listitem>
<para>
<option>gnutls_sess</option>: GnuTLS session (optional)
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when connection is ok
or failed, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>int</entry>
<entry>status</entry>
<entry>
constant with connection status:
<itemizedlist>
<listitem>
<para>WEECHAT_HOOK_CONNECT_OK</para>
</listitem>
<listitem>
<para>WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND</para>
</listitem>
<listitem>
<para>WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND</para>
</listitem>
<listitem>
<para>WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED</para>
</listitem>
<listitem>
<para>WEECHAT_HOOK_CONNECT_PROXY_ERROR</para>
</listitem>
<listitem>
<para>WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR</para>
</listitem>
<listitem>
<para>WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR</para>
</listitem>
<listitem>
<para>WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR</para>
</listitem>
<listitem>
<para>WEECHAT_HOOK_CONNECT_MEMORY_ERROR</para>
</listitem>
</itemizedlist>
</entry>
</row>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>callback_data</option>: pointer given to callback when it
is called by WeeeChat
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
int
my_connect_cb (void *data, int status, const char *ip_address)
{
switch (status)
{
case WEECHAT_HOOK_CONNECT_OK:
/* ... */
break;
case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
/* ... */
break;
case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
/* ... */
break;
case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
/* ... */
break;
case WEECHAT_HOOK_CONNECT_PROXY_ERROR:
/* ... */
break;
case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
/* ... */
break;
case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
/* ... */
break;
case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
/* ... */
break;
case WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
/* ... */
break;
}
return WEECHAT_RC_OK;
}
struct t_hook *my_connect = weechat_hook_fd (sock,
1, 0, 0,
&amp;my_connect_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_print">
<title>weechat_hook_print</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_print (
struct t_gui_buffer *buffer,
const char *tags,
const char *message,
int strip_colors,
int (*callback)(void *data,
struct t_gui_buffer *buffer,
time_t date,
int tags_count,
const char **tags,
const char *prefix,
const char *message),
void *callback_data);
</programlisting>
</para>
<para>
Hook a message printed.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer, if NULL, messages from
any buffer are catched
</para>
</listitem>
<listitem>
<para>
<option>tags</option>: only messages with these tags (comma
separated list) will be catched (optional)
</para>
</listitem>
<listitem>
<para>
<option>message</option>: only messages with this string will be
catched (optional)
</para>
</listitem>
<listitem>
<para>
<option>strip_colors</option>: colors will be stripped from
message displayed, before calling callback
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when message is
printed, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>void *</entry>
<entry>data</entry>
<entry>pointer</entry>
</row>
<row>
<entry>struct t_gui_buffer *</entry>
<entry>buffer</entry>
<entry>buffer pointer</entry>
</row>
<row>
<entry>time_t</entry>
<entry>date</entry>
<entry>date</entry>
</row>
<row>
<entry>int</entry>
<entry>tags_count</entry>
<entry>number of tags for line</entry>
</row>
<row>
<entry>const char **</entry>
<entry>tags</entry>
<entry>tags for line</entry>
</row>
<row>
<entry>const char *</entry>
<entry>prefix</entry>
<entry>prefix</entry>
</row>
<row>
<entry>char *</entry>
<entry>message</entry>
<entry>message</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>callback_data</option>: pointer given to callback when it
is called by WeeeChat
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
int
my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date,
int tags_count, const char **tags,
const char *prefix, const char *message)
{
/* ... */
return WEECHAT_RC_OK;
}
/* catch all messages, on all buffers, without color */
struct t_hook *my_print = weechat_hook_print (NULL, NULL, NULL, 1,
&amp;my_print_cb, NULL);
</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>
Reference in New Issue View Git Blame Copy Permalink