pegasus/weechat
1
0
Fork 0
mirror of https://github.com/weechat/weechat.git synced 2026-06-25 20:36:38 +02:00
Code Activity
Files
79ea9b54beccc5997652e663ce512576f3d2f7e7
weechat/doc/de/dev/plugin_c_api.de.xml
T

10431 lines
298 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8"?>
<!--
WeeChat documentation (german version)
Copyright (c) 2003-2009 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">
<!-- TRANSLATION NEEDED -->
<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>const 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>
char *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>
char *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>
const 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>
const 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>
void 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>
void 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>
char *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 can 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_string_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>
int 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_split_command" after use.
</para>
</note>
<para>
Example:
<screen>char **argv = weechat_string_split_command ("/command1;/command2", ';');</screen>
</para>
</section>
<section id="secPluginCApi_weechat_string_split_command">
<title>weechat_string_free_split_command</title>
<para>
Prototype:
<programlisting>
void weechat_string_free_split_command (char **split_command);
</programlisting>
</para>
<para>
Free memory used by a split command.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>split_command</option>: command split 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_split_command (argv);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_string_format_size">
<title>weechat_string_format_size</title>
<para>
Prototype:
<programlisting>
char *weechat_string_format_size (unsigned long size);
</programlisting>
</para>
<para>
Build a string with formated size and translated unit.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>size</option>: size
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: string with formated size and translated unit.
</para>
<note>
<para>
Result has to be free by a call to "free" after use.
</para>
</note>
<para>
Example:
<screen>
char *str = weechat_string_format_size (0); /* str == "0 byte" (english locale) */
if (str)
free (str);
char *str = weechat_string_format_size (200); /* str == "200 bytes" (english locale) */
if (str)
free (str);
char *str = weechat_string_format_size (1536); /* str == "1.5 KB" (english locale) */
if (str)
free (str);
char *str = weechat_string_format_size (2097152); /* str == "2 MB" (english locale) */
if (str)
free (str);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_string_remove_color">
<title>weechat_string_remove_color</title>
<para>
Prototype:
<programlisting>
char *weechat_string_remove_color (const char *string, const char *replacement);
</programlisting>
</para>
<para>
Remove WeeChat colors from a string.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>string</option>: string
</para>
</listitem>
<listitem>
<para>
<option>replacement</option>: if not NULL and not empty, WeeChat
color codes are replaced by first char of this string, otherwise
WeeChat color codes and following chars (if related to color) are
removed from string
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: string without color.
</para>
<note>
<para>
Result has to be free by a call to "free" after use.
</para>
</note>
<para>
Example:
<screen>
char *str1 = weechat_string_remove_color (my_string1, NULL); /* remove colors and related chars */
char *str2 = weechat_string_remove_color (my_string2, "?"); /* replace color codes by "?" */
</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 id="secPluginCApi_weechat_utf8_strndup">
<title>weechat_utf8_strndup</title>
<para>
Prototype:
<programlisting>
char *weechat_utf8_strndup (const char *string, int max_chars);
</programlisting>
</para>
<para>
Return duplicate string, with max N chars.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>string</option>: string
</para>
</listitem>
<listitem>
<para>
<option>max_chars</option>: max chars
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: duplicated string, NULL if error.
</para>
<para>
Example:
<screen>char *string = weechat_utf8_strndup ("chêne", 3); /* returns "chê" */</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 it is
called by WeeChat
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called for each file
found, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>const 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,
void *user_data);
</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>
<listitem>
<para>
<option>user_data</option>: any pointer
</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, NULL);</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>
const 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, can be
NULL), arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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="3">
<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="3">
<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="3">
<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>const 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="3">
<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="3">
<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 char *default_value,
const char *value,
int null_value_allowed,
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>null_value_allowed</option>: 1 if null (undefined value)
is allowed for option, otherwise 0
</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="3">
<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="3">
<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="3">
<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 */
0, /* null value allowed */
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 */
0, /* null value allowed */
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 */
0, /* null value allowed */
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 */
1, /* null value allowed */
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 */
0, /* null value allowed */
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 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_set_null">
<title>weechat_config_option_set_null</title>
<para>
Prototype:
<programlisting>
int weechat_config_option_set_null (
struct t_config_option *option,
int run_callback);
</programlisting>
</para>
<para>
Set null (undefined value) for an option.
</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 (if it was not null), 0 otherwise
</para>
</listitem>
</itemizedlist>
</para>
<note>
<para>
You can set value to null only if option allows null value
(see <xref linkend="secPluginCApi_weechat_config_new_option" />).
</para>
</note>
<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_null (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_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="3">
<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>
Return value: pointer to property asked.
</para>
<para>
Example:
<screen>
char *description = weechat_config_option_get_pointer (option, "description");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_config_option_is_null">
<title>weechat_config_option_is_null</title>
<para>
Prototype:
<programlisting>
int weechat_config_option_is_null (struct t_config_option *option);
</programlisting>
</para>
<para>
Check if an option is null (undefined value).
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>option</option>: option pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
if (weechat_config_option_is_null (option))
{
/* value is null */
}
else
{
/* value is not null */
}
</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_boolean_default">
<title>weechat_config_boolean_default</title>
<para>
Prototype:
<programlisting>
int weechat_config_boolean_default (struct t_config_option *option);
</programlisting>
</para>
<para>
Get default boolean value of option.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>option</option>: option pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: default boolean value of option (0 or 1).
</para>
<para>
Example:
<screen>
if (weechat_config_boolean_default (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_integer (option);</screen>
</para>
</section>
<section id="secPluginCApi_weechat_config_integer_default">
<title>weechat_config_integer_default</title>
<para>
Prototype:
<programlisting>
int weechat_config_integer_default (struct t_config_option *option);
</programlisting>
</para>
<para>
Get default integer value of option.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>option</option>: option pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: default integer value of option.
</para>
<para>
Example:
<screen>int value = weechat_config_integer (option);</screen>
</para>
</section>
<section id="secPluginCApi_weechat_config_string">
<title>weechat_config_string</title>
<para>
Prototype:
<programlisting>
const 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_default">
<title>weechat_config_string_default</title>
<para>
Prototype:
<programlisting>
const char *weechat_config_string_default (struct t_config_option *option);
</programlisting>
</para>
<para>
Get default string value of option.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>option</option>: option pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: default string value of option.
</para>
<para>
Example:
<screen>char *value = weechat_config_string_default (option);</screen>
</para>
</section>
<section id="secPluginCApi_weechat_config_color">
<title>weechat_config_color</title>
<para>
Prototype:
<programlisting>
const 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_color_default">
<title>weechat_config_color_default</title>
<para>
Prototype:
<programlisting>
const char *weechat_config_color_default (struct t_config_option *option);
</programlisting>
</para>
<para>
Get default color value of option.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>option</option>: option pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: default color value of option (string with name of color).
</para>
<para>
Example:
<screen>char *color = weechat_config_color_default (option);</screen>
</para>
</section>
<section id="secPluginCApi_weechat_config_write_option">
<title>weechat_config_write_option</title>
<para>
Prototype:
<programlisting>
void weechat_config_write_option (
struct t_config_file *config_file,
struct t_config_option *option);
</programlisting>
</para>
<para>
Write a line in a configuration file with option and its value (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</option>: option pointer
</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, "my_section", NULL);
weechat_config_write_option (config_file, option);
return WEECHAT_RC_OK;
}
</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>
<note>
<para>
If value is NULL, then line with section name is written
(for example: "[section]").
</para>
</note>
<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, "my_section", NULL);
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 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>
const 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 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>
<listitem>
<para>
<option>value</option>: value for option
</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_OPTION_NOT_FOUND if option was not
found, WEECHAT_CONFIG_OPTION_SET_ERROR if other error occured.
</para>
<para>
Example:
<screen>
weechat_config_set_plugin ("option", "test_value");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_config_unset_plugin">
<title>weechat_config_unset_plugin</title>
<para>
Prototype:
<programlisting>
int weechat_config_unset_plugin (const char *option_name);
</programlisting>
</para>
<para>
Unset option 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: 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>
weechat_config_unset_plugin ("option");
</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>
const 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="3">
<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>
const 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: can be a WeeChat
color name (from weechat.color.xxx), a color with optional
background (separated by comma), attribute ("bold", "-bold",
"reverse", "-reverse", "italic", "-italic", "underline",
"-underline", ) or a bar color ("bar_fg", "bar_delim", "bar_bg").
</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 "|".
Many templates are possible for same command, separeted by "||".
Default completion codes are:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<thead>
<row>
<entry>Plugin</entry>
<entry>Code</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
&completions.xml;
</tbody>
</tgroup>
</informaltable>
Special codes:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Code</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>%%command</entry>
<entry>Reuse completion template from /command</entry>
</row>
<row>
<entry>%-</entry>
<entry>Stop completion</entry>
</row>
<row>
<entry>%*</entry>
<entry>Repeat last completion</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="3">
<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>
Return value: pointer to new hook, NULL if error occured.
</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;
}
/* this is an example, inspired by weechat command /filter */
struct t_hook *my_command_hook =
weechat_hook_command (/* command name */
"myfilter",
/* description */
"description of myfilter",
/* args */
"[list] | [enable|disable|toggle [name]] | "
"[add name plugin.buffer tags regex] | "
"[del name|-all]",
/* args description */
"description of arguments...",
/* completion */
"list"
" || enable %(filters_names)"
" || disable %(filters_names)"
" || toggle %(filters_names)"
" || add %(filters_names) %(buffers_plugins_names)|*"
" || del %(filters_names)|-all",
/* callback */
&amp;my_command_cb,
/* callback_data */
NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_command_run">
<title>weechat_hook_command_run</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_command_run (
const char *command,
int (*callback)(void *data,
struct t_gui_buffer *buffer,
const char *command),
void *callback_data);
</programlisting>
</para>
<para>
Hook a command when WeeChat runs it.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>command</option>: command to hook, may start or end with
"*" as joker
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when command is run,
arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>const char *</entry>
<entry>command</entry>
<entry>the command executed, with its arguments</entry>
</row>
</tbody>
</tgroup>
The callback can return WEECHAT_RC_OK or WEECHAT_RC_OK_EAT (ok
and "eat" command, will not be executed by WeeChat after
callback).
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>callback_data</option>: pointer given to callback when it
is called by WeeeChat
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
int
my_command_run_cb (void *data, struct t_gui_buffer *buffer,
const char *command)
{
weechat_printf (NULL,
"You wanted to complete? I'm eating the completion ahah!");
return WEECHAT_RC_OK_EAT;
}
struct t_hook *my_command_run_hook =
weechat_hook_command_run ("/input complete*",
&amp;my_command_run_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, int remaining_calls),
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="3">
<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>remaining_calls</entry>
<entry>remaining calls (-1 if timer has no end)</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>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
int
my_timer_cb (void *data, int remaining_calls)
{
/* ... */
return WEECHAT_RC_OK;
}
/* timer called each 20 seconds */
struct t_hook *my_timer_hook =
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, int fd),
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="3">
<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>fd</entry>
<entry>file descriptor</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>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
int
my_fd_cb (void *data, int fd)
{
/* ... */
return WEECHAT_RC_OK;
}
int sock = socket (AF_INET, SOCK_STREAM, 0);
/* set socket options */
/* ... */
/* hook socket */
struct t_hook *my_fd_hook =
weechat_hook_fd (sock, 1, 0, 0, &amp;my_fd_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_process">
<title>weechat_hook_process</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_process (
const char *command,
int timeout,
int (*callback)(void *data,
const char *command,
int return_code,
const char *stdout,
const char *stderr),
void *callback_data);
</programlisting>
</para>
<para>
Hook a process (with fork), and catch output.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>command</option>: command to launch in child process
</para>
</listitem>
<listitem>
<para>
<option>timeout</option>: timeout for command (in milliseconds):
after this timeout, child process is killed (0 means no timeout)
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when data from child
is available, or when child has ended, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>const char *</entry>
<entry>command</entry>
<entry>command executed by child</entry>
</row>
<row>
<entry>int</entry>
<entry>return_code</entry>
<entry>
if &gt;= 0, it's child (command) return code (it's last
call to this callback), if &lt; 0, it can be
WEECHAT_HOOK_PROCESS_OK_RUNNING (data available, but
child still running) or WEECHAT_HOOK_PROCESS_ERROR
(error when launching command).
</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>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
int
my_process_cb (void *data, const char *command, int return_code,
const char *stdout, const char *stderr)
{
if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
{
weechat_printf (NULL, "Error with command '%s'", command);
return;
}
if (return_code &gt;= 0)
{
weechat_printf (NULL, "return_code = %d", return_code);
}
if (stdout)
{
weechat_printf (NULL, "stdout: %s", stdout);
}
if (stderr)
{
weechat_printf (NULL, "stderr: %s", stderr);
}
return WEECHAT_RC_OK;
}
struct t_hook *my_process_hook =
weechat_hook_process ("ls", 5000, &amp;my_process_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="3">
<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>
Return value: pointer to new hook, NULL if error occured.
</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_hook =
weechat_hook_connect (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,
int displayed,
int highlight,
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 caught
</para>
</listitem>
<listitem>
<para>
<option>tags</option>: only messages with these tags (comma
separated list) will be caught (optional)
</para>
</listitem>
<listitem>
<para>
<option>message</option>: only messages with this string will be
caught (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="3">
<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>int</entry>
<entry>displayed</entry>
<entry>
1 if line is displayed, 0 if it is filtered
</entry>
</row>
<row>
<entry>int</entry>
<entry>highlight</entry>
<entry>1 if line has highlight, otherwise 0</entry>
</row>
<row>
<entry>const char *</entry>
<entry>prefix</entry>
<entry>prefix</entry>
</row>
<row>
<entry>const 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>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
int
my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date,
int tags_count, const char **tags,
int displayed, int highlight,
const char *prefix, const char *message)
{
/* ... */
return WEECHAT_RC_OK;
}
/* catch all messages, on all buffers, without color */
struct t_hook *my_print_hook =
weechat_hook_print (NULL, NULL, NULL, 1, &amp;my_print_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_signal">
<title>weechat_hook_signal</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_signal (
const char *signal,
int (*callback)(void *data,
const char *signal,
const char *type_data,
void *signal_data),
void *callback_data);
</programlisting>
</para>
<para>
Hook a signal.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>signal</option>: signal to catch. List of signals sent by
WeeChat or plugins:
<informaltable colsep="0" frame="none">
<tgroup cols="4">
<thead>
<row>
<entry>Plugin</entry>
<entry>Signal</entry>
<entry>Arguments</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>irc</entry>
<entry>xxx,irc_in_yyy (xxx is server name, yyy is command name)</entry>
<entry>string: message</entry>
<entry>irc message from server (before irc plugin uses it)</entry>
</row>
<row>
<entry>irc</entry>
<entry>xxx,irc_in2_yyy (xxx is server name, yyy is command name)</entry>
<entry>string: message</entry>
<entry>irc message from server (after irc plugin uses it)</entry>
</row>
<row>
<entry>irc</entry>
<entry>xxx,irc_out_yyy (xxx is server name, yyy is command name)</entry>
<entry>string: message</entry>
<entry>irc message sent to server</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_ctcp</entry>
<entry>string: message</entry>
<entry>CTCP received</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_dcc</entry>
<entry>string: message</entry>
<entry>new DCC</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_pv</entry>
<entry>string: message</entry>
<entry>private message received</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_channel_opened</entry>
<entry>pointer: buffer</entry>
<entry>channel opened</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_pvl_opened</entry>
<entry>pointer: buffer</entry>
<entry>private opened</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_server_connecting</entry>
<entry>string: server name</entry>
<entry>connecting to server</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_server_connected</entry>
<entry>string: server name</entry>
<entry>connected to server</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_server_disconnected</entry>
<entry>string: server name</entry>
<entry>disconnected from server</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_ignore_removing</entry>
<entry>pointer: ignore</entry>
<entry>removing ignore</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_ignore_removed</entry>
<entry>pointer: ignore</entry>
<entry>ignore removed</entry>
</row>
<row>
<entry>logger</entry>
<entry>logger_start</entry>
<entry>pointer: buffer</entry>
<entry>start logging for buffer</entry>
</row>
<row>
<entry>logger</entry>
<entry>logger_stop</entry>
<entry>pointer: buffer</entry>
<entry>stop logging for buffer</entry>
</row>
<row>
<entry>logger</entry>
<entry>logger_backlog</entry>
<entry>pointer: buffer</entry>
<entry>display backlog for buffer</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_closing</entry>
<entry>pointer: buffer</entry>
<entry>closing buffer</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_closed</entry>
<entry>pointer: buffer</entry>
<entry>buffer closed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_lines_hidden</entry>
<entry>pointer: buffer</entry>
<entry>lines hidden in buffer</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_localvar_added</entry>
<entry>pointer: buffer</entry>
<entry>local variable has been added</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_localvar_changed</entry>
<entry>pointer: buffer</entry>
<entry>local variable has changed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_localvar_removed</entry>
<entry>pointer: buffer</entry>
<entry>local variable has been removed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_moved</entry>
<entry>pointer: buffer</entry>
<entry>buffer moved</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_opened</entry>
<entry>pointer: buffer</entry>
<entry>buffer opened</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_renamed</entry>
<entry>pointer: buffer</entry>
<entry>buffer renamed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_switch</entry>
<entry>pointer: buffer</entry>
<entry>switching buffer</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_title_changed</entry>
<entry>pointer: buffer</entry>
<entry>title of buffer changed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>buffer_type_changed</entry>
<entry>pointer: buffer</entry>
<entry>type of buffer changed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>debug_dump</entry>
<entry>-</entry>
<entry>dump request</entry>
</row>
<row>
<entry>weechat</entry>
<entry>filter_added</entry>
<entry>pointer: new filter</entry>
<entry>filter added</entry>
</row>
<row>
<entry>weechat</entry>
<entry>filter_removing</entry>
<entry>pointer: filter</entry>
<entry>removing filter</entry>
</row>
<row>
<entry>weechat</entry>
<entry>filter_removed</entry>
<entry>pointer: filter</entry>
<entry>filter removed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>filters_enabled</entry>
<entry>-</entry>
<entry>filters enabled</entry>
</row>
<row>
<entry>weechat</entry>
<entry>filters_disabled</entry>
<entry>-</entry>
<entry>filters disabled</entry>
</row>
<row>
<entry>weechat</entry>
<entry>hotlist_changed</entry>
<entry>-</entry>
<entry>hotlist changed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>input_paste_pending</entry>
<entry>-</entry>
<entry>paste pending</entry>
</row>
<row>
<entry>weechat</entry>
<entry>input_search</entry>
<entry>-</entry>
<entry>input search</entry>
</row>
<row>
<entry>weechat</entry>
<entry>input_text_changed</entry>
<entry>-</entry>
<entry>input text changed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>input_text_cursor_moved</entry>
<entry>-</entry>
<entry>input text cursor moved</entry>
</row>
<row>
<entry>weechat</entry>
<entry>key_pressed</entry>
<entry>string: key pressed</entry>
<entry>key pressed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>nicklist_changed</entry>
<entry>-</entry>
<entry>nicklist has changed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>partial_completion</entry>
<entry>-</entry>
<entry>partial completion happened</entry>
</row>
<row>
<entry>weechat</entry>
<entry>quit</entry>
<entry>arguments for command /quit</entry>
<entry>command /quit issued by user</entry>
</row>
<row>
<entry>weechat</entry>
<entry>upgrade</entry>
<entry>-</entry>
<entry>command /upgrade issued by user</entry>
</row>
<row>
<entry>weechat</entry>
<entry>weechat_highlight</entry>
<entry>string: message with prefix</entry>
<entry>highlight displayed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>weechat_pv</entry>
<entry>string: message with prefix</entry>
<entry>private message displayed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>window_scrolled</entry>
<entry>pointer: window</entry>
<entry>scroll in window</entry>
</row>
<row>
<entry>weechat</entry>
<entry>window_unzooming</entry>
<entry>pointer: current window</entry>
<entry>unzooming window</entry>
</row>
<row>
<entry>weechat</entry>
<entry>window_unzoomed</entry>
<entry>pointer: current window</entry>
<entry>window unzoomed</entry>
</row>
<row>
<entry>weechat</entry>
<entry>window_zooming</entry>
<entry>pointer: current window</entry>
<entry>unzooming window</entry>
</row>
<row>
<entry>weechat</entry>
<entry>window_zoomed</entry>
<entry>pointer: current window</entry>
<entry>window unzoomed</entry>
</row>
<row>
<entry>xfer</entry>
<entry>xfer_add</entry>
<entry>pointer: infolist with xfer info</entry>
<entry>new xfer</entry>
</row>
<row>
<entry>xfer</entry>
<entry>xfer_send_ready</entry>
<entry>pointer: infolist with xfer info</entry>
<entry>xfer ready (file or chat, send)</entry>
</row>
<row>
<entry>xfer</entry>
<entry>xfer_accept_resume</entry>
<entry>pointer: infolist with xfer info</entry>
<entry>xfer accepts resume (send)</entry>
</row>
<row>
<entry>xfer</entry>
<entry>xfer_send_accept_resume</entry>
<entry>pointer: infolist with xfer info</entry>
<entry>xfer accepts resume (send)</entry>
</row>
<row>
<entry>xfer</entry>
<entry>xfer_start_resume</entry>
<entry>pointer: infolist with xfer info</entry>
<entry>start resume</entry>
</row>
<row>
<entry>xfer</entry>
<entry>xfer_resume_ready</entry>
<entry>pointer: infolist with xfer info</entry>
<entry>xfer resume ready</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when signal is
received, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>const char *</entry>
<entry>signal</entry>
<entry>signal received</entry>
</row>
<row>
<entry>const char *</entry>
<entry>type_data</entry>
<entry>
type of data sent with signal:
WEECHAT_HOOK_SIGNAL_STRING, WEECHAT_HOOK_SIGNAL_INT
or WEECHAT_HOOK_SIGNAL_POINTER
</entry>
</row>
<row>
<entry>void *</entry>
<entry>signal_data</entry>
<entry>data sent with signal</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>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
int
my_signal_cb (void *data, const char *signal, const char *type_data,
void *signal_data)
{
/* ... */
return WEECHAT_RC_OK;
}
/* catch signal "quit", sent by WeeChat when /quit command is executed */
struct t_hook *my_signal_hook =
weechat_hook_signal ("quit", &amp;my_signal_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_signal_send">
<title>weechat_hook_signal_send</title>
<para>
Prototype:
<programlisting>
void weechat_hook_signal_send (
const char *signal,
const char *type_data,
void *signal_data);
</programlisting>
</para>
<para>
Send a signal.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>signal</option>: signal to send
</para>
</listitem>
<listitem>
<para>
<option>type_data</option>: type of data sent with signal
(see <xref linkend="secPluginCApi_weechat_hook_signal" />)
</para>
</listitem>
<listitem>
<para>
<option>signal_data</option>: data sent with signal
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_config">
<title>weechat_hook_config</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_config (
const char *option,
int (*callback)(void *data,
const char *option,
const char *value),
void *callback_data);
</programlisting>
</para>
<para>
Hook a configuration option.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>option</option>: option, format is full name, as used
with /set command (for example:
<literal>weechat.look.item_time_format</literal>)
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when configuration
option is changed, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>const char *</entry>
<entry>option</entry>
<entry>name of option</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_data</option>: pointer given to callback when it
is called by WeeeChat
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
int
my_config_cb (void *data, const char *option, const char *value)
{
/* ... */
return WEECHAT_RC_OK;
}
/* catch changes to option "weechat.look.item_time_format" */
struct t_hook *my_config_hook =
weechat_hook_config ("weechat.look.item_time_format",
&amp;my_config_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_completion">
<title>weechat_hook_completion</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_completion (
const char *completion_item,
int (*callback)(void *data,
const char *completion_item,
struct t_gui_buffer *buffer,
struct t_gui_completion *completion),
void *callback_data);
</programlisting>
</para>
<para>
Hook a completion.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>completion_item</option>: name of completion item,
after you can use <literal>%(name)</literal> in a command hooked
(argument "<literal>completion</literal>", see
<xref linkend="secPluginCApi_weechat_hook_command" />)
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when completion item
is used (user is completing something using this item),
arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>const char *</entry>
<entry>completion_item</entry>
<entry>name of completion item</entry>
</row>
<row>
<entry>struct t_gui_buffer *</entry>
<entry>buffer</entry>
<entry>buffer where completion was done</entry>
</row>
<row>
<entry>struct t_gui_completion *</entry>
<entry>completion</entry>
<entry>
structure used to add words for completion
(see
<xref linkend="secPluginCApi_weechat_hook_completion_list_add" />)
</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>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
int
my_completion_cb (void *data, const char *completion_item,
struct t_gui_buffer *buffer,
struct t_gui_completion *completion)
{
/* ... */
return WEECHAT_RC_OK;
}
struct t_hook *my_completion_hook =
weechat_hook_completion ("myitem",
&amp;my_completion_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_completion_list_add">
<title>weechat_hook_completion_list_add</title>
<para>
Prototype:
<programlisting>
void weechat_hook_completion_list_add (
struct t_gui_completion *completion,
const char *word,
int nick_completion,
const char *where);
</programlisting>
</para>
<para>
Add a word for a completion.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>completion</option>: completion pointer
</para>
</listitem>
<listitem>
<para>
<option>word</option>: word to add
</para>
</listitem>
<listitem>
<para>
<option>nick_completion</option>: 1 if word is a nick, 0 if word
is not a nick
</para>
</listitem>
<listitem>
<para>
<option>where</option>: position where word will be inserted in
list: WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING or
WEECHAT_LIST_POS_END
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
int
my_completion_cb (void *data, const char *completion_item,
struct t_gui_buffer *buffer,
struct t_gui_completion *completion)
{
weechat_hook_completion_list_add (completion, "word1",
0, WEECHAT_LIST_POS_SORT);
weechat_hook_completion_list_add (completion, "test_word2",
0, WEECHAT_LIST_POS_SORT);
return WEECHAT_RC_OK;
}
struct t_hook *my_completion_hook =
weechat_hook_completion ("myitem",
&amp;my_completion_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_modifier">
<title>weechat_hook_modifier</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_modifier (
const char *modifier,
char *(*callback)(void *data,
const char *modifier,
const char *modifier_data,
const char *string),
void *callback_data);
</programlisting>
</para>
<para>
Hook a modifier.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>modifier</option>: modifier name, list of modifiers used
by Weechat or plugins:
<informaltable colsep="0" frame="none">
<tgroup cols="5">
<thead>
<row>
<entry>Plugin</entry>
<entry>Modifier</entry>
<entry>Modifier data</entry>
<entry>String</entry>
<entry>Output</entry>
</row>
</thead>
<tbody>
<row>
<entry>charset</entry>
<entry>charset_decode</entry>
<entry>plugin.buffer_name</entry>
<entry>any string</entry>
<entry>string decoded from charset found for plugin/buffer to UTF-8</entry>
</row>
<row>
<entry>charset</entry>
<entry>charset_encode</entry>
<entry>plugin.buffer_name</entry>
<entry>any string</entry>
<entry>string encoded from UTF-8 to charset found for plugin/buffer</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_color_decode</entry>
<entry>"1" to keep colors, "0" to remove colors</entry>
<entry>any string</entry>
<entry>string with WeeChat color codes, or without color</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_color_encode</entry>
<entry>"1" to keep colors, "0" to remove colors</entry>
<entry>any string, with user colors</entry>
<entry>string with IRC color codes, or without color</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_in_xxx (xxx is IRC command name)</entry>
<entry>server name</entry>
<entry>content of message received from IRC server</entry>
<entry>new content of message</entry>
</row>
<row>
<entry>irc</entry>
<entry>irc_out_xxx (xxx is IRC command name)</entry>
<entry>server name</entry>
<entry>content of message about to be sent to IRC server</entry>
<entry>new content of message</entry>
</row>
<row>
<entry>weechat</entry>
<entry>input_text_content</entry>
<entry>string with buffer pointer ("0x123..")</entry>
<entry>input buffer (from user)</entry>
<entry>new content of input buffer</entry>
</row>
<row>
<entry>weechat</entry>
<entry>input_text_display</entry>
<entry>string with buffer pointer ("0x123..")</entry>
<entry>input buffer (from user), without cursor tag</entry>
<entry>new content of input buffer, for display only (input buffer is not changed)</entry>
</row>
<row>
<entry>weechat</entry>
<entry>input_text_display_with_cursor</entry>
<entry>string with buffer pointer ("0x123..")</entry>
<entry>input buffer (from user), with cursor tag</entry>
<entry>new content of input buffer, for display only (input buffer is not changed)</entry>
</row>
<row>
<entry>weechat</entry>
<entry>weechat_print</entry>
<entry>plugin;buffer_name;tags</entry>
<entry>message printed</entry>
<entry>new message printed</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when modifier is
received, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>const char *</entry>
<entry>modifier</entry>
<entry>name of modifier</entry>
</row>
<row>
<entry>const char *</entry>
<entry>modifier_data</entry>
<entry>modifier data</entry>
</row>
<row>
<entry>const char *</entry>
<entry>string</entry>
<entry>
string to modify (function must return copy of this
string, no changes are allowed in this string)
</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>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
char *
my_modifier_cb (void *data, const char *modifier,
const char *modifier_data,
const char *string)
{
char *result;
int length;
if (!string)
return NULL;
length = strlen (string) + 4;
result = malloc (length);
if (result)
{
/* add "xxx" to any message printed */
snprintf (result, length, "%s xxx", string);
}
return result;
}
struct t_hook *my_modifier_hook =
weechat_hook_modifier ("weechat_print",
&amp;my_modifier_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_modifier_exec">
<title>weechat_hook_modifier_exec</title>
<para>
Prototype:
<programlisting>
char *weechat_hook_modifier_exec (
const char *modifier,
const char *modifier_data,
const char *string);
</programlisting>
</para>
<para>
Execute modifier(s).
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>modifier</option>: modifier name
</para>
</listitem>
<listitem>
<para>
<option>modifier_data</option>: modifier data
</para>
</listitem>
<listitem>
<para>
<option>string</option>: string to modify
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: string modified, NULL if no changes in string were
made by modifier(s).
</para>
<para>
Example:
<screen>
char *new_string =
weechat_hook_modifier_exec ("my_modifier", my_data, my_string);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_info">
<title>weechat_hook_info</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_info (
const char *info_name,
const char *description,
const char *(*callback)(void *data,
const char *info_name,
const char *arguments),
void *callback_data);
</programlisting>
</para>
<para>
Hook an information: callback will return pointer to info asked.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>info_name</option>: name of info
</para>
</listitem>
<listitem>
<para>
<option>description</option>: description
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when info is asked,
arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>const char *</entry>
<entry>info_name</entry>
<entry>name of info to return</entry>
</row>
<row>
<entry>const char *</entry>
<entry>arguments</entry>
<entry>additional arguments, depending on info</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>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
const char *
my_info_cb (void *data, const char *info_name, const char *arguments)
{
/* ... */
return pointer_to_string;
}
/* add info "my_info" */
struct t_hook *my_info =
weechat_hook_info ("my_info", "Some info about something",
&amp;my_info_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_hook_infolist">
<title>weechat_hook_infolist</title>
<para>
Prototype:
<programlisting>
struct t_hook *weechat_hook_infolist (
const char *infolist_name,
const char *description,
const char *(*callback)(void *data,
const char *infolist_name,
void *pointer,
const char *arguments),
void *callback_data);
</programlisting>
</para>
<para>
Hook an infolist: callback will return pointer to infolist asked.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist_name</option>: name of infolist
</para>
</listitem>
<listitem>
<para>
<option>description</option>: description
</para>
</listitem>
<listitem>
<para>
<option>callback</option>: function called when infolist is asked,
arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>const char *</entry>
<entry>infolist_name</entry>
<entry>name of infolist to return</entry>
</row>
<row>
<entry>void *</entry>
<entry>pointer</entry>
<entry>
pointer to an item infolist must return (to get only
one item in infolist)
</entry>
</row>
<row>
<entry>const char *</entry>
<entry>arguments</entry>
<entry>additional arguments, depending on infolist</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>
Return value: pointer to new hook, NULL if error occured.
</para>
<para>
Example:
<screen>
struct t_infolist *
my_infolist_cb (void *data, const char *infolist_name, void *pointer,
const char *arguments)
{
/* ... build infolist ... */
return my_infolist;
}
/* add info "my_infolist" */
struct t_hook *my_infolist =
weechat_hook_infolist ("my_infolist", "Infolist with some data",
&amp;my_infolist_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_unhook">
<title>weechat_unhook</title>
<para>
Prototype:
<programlisting>
void weechat_unhook (struct t_hook *hook);
</programlisting>
</para>
<para>
Unhook something hooked.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>hook</option>: something hooked with weechat_hook_xxxx()
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
struct t_hook *my_hook = weechat_hook_command (...);
/* ... */
weechat_unhook (my_hook);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_unhook_all">
<title>weechat_unhook_all</title>
<para>
Prototype:
<programlisting>
void weechat_unhook_all ();
</programlisting>
</para>
<para>
Unhook everything that has been hooked by current plugin.
</para>
<para>
Example:
<screen>
weechat_unhook_all ();
</screen>
</para>
</section>
</section>
<!-- ============================[ buffers ]============================= -->
<section id="secPluginCApi_buffers">
<title>Buffers</title>
<para>
Functions to create/query/close buffers.
</para>
<section id="secPluginCApi_weechat_buffer_new">
<title>weechat_buffer_new</title>
<para>
Prototype:
<programlisting>
struct t_gui_buffer *weechat_buffer_new (
const char *name,
int (*input_callback)(void *data,
struct t_gui_buffer *buffer,
const char *input_data),
void *input_callback_data,
int (*close_callback)(void *data,
struct t_gui_buffer *buffer),
void *close_callback_data);
</programlisting>
</para>
<para>
Open a new buffer.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>name</option>: name of buffer (must be unique)
</para>
</listitem>
<listitem>
<para>
<option>input_callback</option>: function called when input text
is entered on buffer, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>const char *</entry>
<entry>input_data</entry>
<entry>input data</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>input_callback_data</option>: pointer given to input
callback when it is called by WeeeChat
</para>
</listitem>
<listitem>
<para>
<option>close_callback</option>: function called when buffer is
closed, arguments:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<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>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>close_callback_data</option>: pointer given to close
callback when it is called by WeeeChat
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new buffer, NULL if error occured.
</para>
<para>
Example:
<screen>
int
my_input_cb (void *data, struct t_gui_buffer *buffer, const char *input_data)
{
weechat_printf (buffer, "Text: %s", input_data);
return WEECHAT_RC_OK;
}
int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
weechat_printf (NULL, "Buffer '%s' will be closed!",
weechat_buffer_get_string (buffer, "name"));
return WEECHAT_RC_OK;
}
struct t_gui_buffer *my_buffer =
weechat_buffer_new ("my_buffer",
&amp;my_input_cb, NULL, &amp;my_close_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_current_buffer">
<title>weechat_current_buffer</title>
<para>
Prototype:
<programlisting>
struct t_gui_buffer *weechat_current_buffer ();
</programlisting>
</para>
<para>
Return pointer to current buffer (buffer displayed by current window).
</para>
<para>
Return value: pointer to current buffer.
</para>
<para>
Example:
<screen>
struct t_gui_buffer *current_buffer = weechat_current_buffer ();
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_buffer_search">
<title>weechat_buffer_search</title>
<para>
Prototype:
<programlisting>
struct t_gui_buffer *weechat_buffer_search (const char *plugin, const char *name);
</programlisting>
</para>
<para>
Search a buffer by plugin and/or buffer name.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>plugin</option>: name of plugin
</para>
</listitem>
<listitem>
<para>
<option>name</option>: name of buffer. If it is NULL or empty
string, then current buffer is returned (buffer displayed by
current window).
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to buffer found, NULL if not found.
</para>
<para>
Example:
<screen>
struct t_gui_buffer *weechat_buffer = weechat_buffer_search ("core", "weechat");
struct t_gui_buffer *my_buffer = weechat_buffer_search ("myplugin", "my_buffer");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_buffer_clear">
<title>weechat_buffer_clear</title>
<para>
Prototype:
<programlisting>
void weechat_buffer_clear (struct t_gui_buffer *buffer);
</programlisting>
</para>
<para>
Clear content of a buffer.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
struct t_gui_buffer *my_buffer = weechat_buffer_search ("myplugin", "my_buffer");
if (my_buffer)
{
weechat_buffer_clear (my_buffer);
}
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_buffer_close">
<title>weechat_buffer_close</title>
<para>
Prototype:
<programlisting>
void weechat_buffer_close (struct t_gui_buffer *buffer)
</programlisting>
</para>
<para>
Close a buffer.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
struct t_gui_buffer *my_buffer =
weechat_buffer_new ("my_buffer",
&amp;my_input_cb, NULL, &amp;my_close_cb, NULL);
/* ... */
weechat_buffer_close (my_buffer);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_buffer_get_integer">
<title>weechat_buffer_get_integer</title>
<para>
Prototype:
<programlisting>
int weechat_buffer_get_integer (struct t_gui_buffer *buffer, const char *property);
</programlisting>
</para>
<para>
Get integer value of a buffer property.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>property</option>: property name:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>number</entry>
<entry>number of buffer (1 to # open buffers)</entry>
</row>
<row>
<entry>num_displayed</entry>
<entry>number of windows displaying buffer</entry>
</row>
<row>
<entry>notify</entry>
<entry>notify level for buffer</entry>
</row>
<row>
<entry>lines_hidden</entry>
<entry>
1 if at least one line is hidden on buffer
(filtered), or 0 if all lines are displayed
</entry>
</row>
<row>
<entry>prefix_max_length</entry>
<entry>max length for prefix in this buffer</entry>
</row>
<row>
<entry>time_for_each_line</entry>
<entry>
1 if time is displayed for each line in buffer
(default), 0 otherwise
</entry>
</row>
<row>
<entry>text_search</entry>
<entry>
text search type: 0 = disabled, 1 = backward, 2 = forward
</entry>
</row>
<row>
<entry>text_search_exact</entry>
<entry>1 if text search is exact (case sensitive)</entry>
</row>
<row>
<entry>text_search_found</entry>
<entry>1 if text found, 0 otherwise</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: integer value of property.
</para>
<para>
Example:
<screen>
weechat_printf (NULL, "my buffer number is: %d",
weechat_buffer_get_integer (my_buffer, "number"));
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_buffer_get_string">
<title>weechat_buffer_get_string</title>
<para>
Prototype:
<programlisting>
const char *weechat_buffer_get_string (struct t_gui_buffer *buffer, const char *property);
</programlisting>
</para>
<para>
Get string value of a buffer property.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>property</option>: property name:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>plugin</entry>
<entry>
name of plugin which created this buffer ("core" for
WeeChat main buffer)
</entry>
</row>
<row>
<entry>name</entry>
<entry>name of buffer</entry>
</row>
<row>
<entry>short_name</entry>
<entry>short name of buffer</entry>
</row>
<row>
<entry>tilte</entry>
<entry>title of buffer</entry>
</row>
<row>
<entry>input</entry>
<entry>input text</entry>
</row>
<row>
<entry>localvar_xxx</entry>
<entry>
get content of local varialbe "xxx" (replace
"xxx" by the name of variable you want to read)
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: string value of property.
</para>
<para>
Example:
<screen>
weechat_printf (NULL, "name / short name of buffer are: %s / %s",
weechat_buffer_get_string (my_buffer, "name"),
weechat_buffer_get_string (my_buffer, "short_name"));
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_buffer_get_pointer">
<title>weechat_buffer_get_pointer</title>
<para>
Prototype:
<programlisting>
const char *weechat_buffer_pointer (struct t_gui_buffer *buffer, const char *property);
</programlisting>
</para>
<para>
Get pointer value of a buffer property.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>property</option>: property name:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>plugin</entry>
<entry>plugin pointer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer value of property.
</para>
<para>
Example:
<screen>
weechat_printf (NULL, "plugin pointer of my buffer: %lx",
weechat_buffer_get_pointer (my_buffer, "plugin"));
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_buffer_set">
<title>weechat_buffer_set</title>
<para>
Prototype:
<programlisting>
void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property,
const char *value);
</programlisting>
</para>
<para>
Set string value of a buffer property.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>property</option>: property name:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Value</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>hotlist</entry>
<entry>
"+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE,
WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT
</entry>
<entry>
<para>
"+": enable hotlist (global setting, buffer pointer
is not used)
</para>
<para>
"-": disable hotlist (global setting, buffer pointer
is not used); when hotlist is disabled, messages
printed in buffers does not change hotlist (but
content of current hotlist is not cleared)
</para>
<para>
priority: add buffer to hotlist with this priority
</para>
</entry>
</row>
<row>
<entry>unread</entry>
<entry>N/A</entry>
<entry>
set unread marker on current line for buffer
</entry>
</row>
<row>
<entry>display</entry>
<entry>"1", "auto"</entry>
<entry>
swtich to this buffer in current window (if value is
"auto", then it's considered as auto-switch and read
marker is not reset for current buffer)
</entry>
</row>
<row>
<entry>name</entry>
<entry>any string</entry>
<entry>set new name for buffer</entry>
</row>
<row>
<entry>short_name</entry>
<entry>any string</entry>
<entry>set new short name for buffer</entry>
</row>
<row>
<entry>type</entry>
<entry>"formated" or "free"</entry>
<entry>
set type for buffer: "formated" (for printing
chat messages), or "free" for free content
</entry>
</row>
<row>
<entry>notify</entry>
<entry>"0", "1", "2", "3"</entry>
<entry>
set notify level for buffer: "0" = never add to hotlist,
"1" = add for highlights only, "2" = add for highlights
and messages, "3" = add for ell messages
</entry>
</row>
<row>
<entry>title</entry>
<entry>any string</entry>
<entry>set new title for buffer</entry>
</row>
<row>
<entry>time_for_each_line</entry>
<entry>"0" or "1"</entry>
<entry>
"0" to hide time for all lines in buffer, "1" to
see time for all lines (default for a new buffer)
</entry>
</row>
<row>
<entry>nicklist</entry>
<entry>"0" or "1"</entry>
<entry>
"0" to remove nicklist for buffer, "1" to add
nicklist for buffer
</entry>
</row>
<row>
<entry>nicklist_case_sensitive</entry>
<entry>"0" or "1"</entry>
<entry>
"0" to have case insensitive nicklist, "1" to have
case sensitive nicklist
</entry>
</row>
<row>
<entry>nicklist_display_groups</entry>
<entry>"0" or "1"</entry>
<entry>
"0" to hide nicklist groups, "1" to display nicklist
groups
</entry>
</row>
<row>
<entry>highlight_words</entry>
<entry>"-" or comma separated list of words</entry>
<entry>
"-" is a special value to disable any highlight on this
buffer, or comma separated list of words to higlkight
in this buffer, for example: "abc,def,ghi"
</entry>
</row>
<row>
<entry>highlight_tags</entry>
<entry>comma separated list of tags</entry>
<entry>
comma separated list of tags to highlight in this
buffer
</entry>
</row>
<row>
<entry>key_bind_xxx</entry>
<entry>any string</entry>
<entry>
bind a new key, specific to this buffer (replace "xxx"
by the key, for example "meta-I" to bind alt+i) ; the
value is text or command to execute
</entry>
</row>
<row>
<entry>key_bind_xxx</entry>
<entry>N/A</entry>
<entry>
unbind a key (which was bound with above property)
</entry>
</row>
<row>
<entry>input</entry>
<entry>any string</entry>
<entry>set new value for buffer input</entry>
</row>
<row>
<entry>input_get_unknown_commands</entry>
<entry>"0" or "1"</entry>
<entry>
"0" to disable unknown commands on this buffer
(default behaviour), "1" to get unknown commands,
for example if user type "/unknowncmd", buffer will
receive it (no error about unknown command)
</entry>
</row>
<row>
<entry>localvar_set_xxx</entry>
<entry>any string</entry>
<entry>
set new value for a local variable (replace "xxx" by
variable name) ; variable is created if it does not
exist
</entry>
</row>
<row>
<entry>localvar_del_xxx</entry>
<entry>any string</entry>
<entry>
remove a local variable (replace "xxx" by variable name)
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
/* disable hotlist (for all buffers) */
weechat_buffer_set (NULL, "hotlist", "-");
/* enable again hotlist */
weechat_buffer_set (NULL, "hotlist", "+");
/* change buffer name */
weechat_buffer_set (my_buffer, "name", "my_new_name");
/* add new local variable "toto" with value "my_value" */
weechat_buffer_set (my_buffer, "localvar_set_toto", "my_value");
/* remove local variable "toto" */
weechat_buffer_set (my_buffer, "localvar_del_toto", NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_buffer_set_pointer">
<title>weechat_buffer_set_pointer</title>
<para>
Prototype:
<programlisting>
void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property,
void *pointer);
</programlisting>
</para>
<para>
Set pointer value of a buffer property.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>property</option>: property name:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Value</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>close_callback</entry>
<entry>close callback function</entry>
<entry>close callback function</entry>
</row>
<row>
<entry>close_callback_data</entry>
<entry>close callback data pointer</entry>
<entry>close callback data pointer</entry>
</row>
<row>
<entry>input_callback</entry>
<entry>input callback function</entry>
<entry>input callback function</entry>
</row>
<row>
<entry>input_callback_data</entry>
<entry>input callback data pointer</entry>
<entry>input callback data pointer</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
/* ... */
return WEECHAT_RC_OK;
}
weechat_buffer_set_pointer (NULL, "close_callback", &amp;my_close_cb);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_buffer_string_replace_local_var">
<title>weechat_buffer_string_replace_local_var</title>
<para>
Prototype:
<programlisting>
char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer,
const char *string);
</programlisting>
</para>
<para>
Replace local variables in a string by their value, using buffer local
variables.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>string</option>: string with text and local variables
using format "$var"
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: string with value for local variables.
</para>
<note>
<para>
Result has to be free by a call to "free" after use.
</para>
</note>
<para>
Example:
<screen>
weechat_buffer_set (my_buffer, "localvar_set_toto", "my_value");
char *str = weechat_buffer_string_replace_local_var (my_buffer,
"test with $toto");
/* str contains "test with my_value" */
/* ... */
free (str);
</screen>
</para>
</section>
</section>
<!-- ============================[ windows ]============================= -->
<section id="secPluginCApi_windows">
<title>Windows</title>
<para>
Functions to query windows.
</para>
<section id="secPluginCApi_weechat_current_window">
<title>weechat_current_window</title>
<para>
Prototype:
<programlisting>
struct t_gui_window *weechat_current_window ();
</programlisting>
</para>
<para>
Return pointer to current window.
</para>
<para>
Return value: pointer to current window.
</para>
<para>
Example:
<screen>
struct t_gui_window *current_window = weechat_current_window ();
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_window_get_integer">
<title>weechat_window_get_integer</title>
<para>
Prototype:
<programlisting>
int weechat_window_get_integer (struct t_gui_window *window, const char *property);
</programlisting>
</para>
<para>
Get integer value of a window property.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>window</option>: window pointer
</para>
</listitem>
<listitem>
<para>
<option>property</option>: property name:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>win_x</entry>
<entry>
X position of window in terminal (0 is first column)
</entry>
</row>
<row>
<entry>win_y</entry>
<entry>
Y position of window in terminal (0 is first column)
</entry>
</row>
<row>
<entry>win_width</entry>
<entry>width of window, in chars</entry>
</row>
<row>
<entry>win_height</entry>
<entry>height of window, in chars</entry>
</row>
<row>
<entry>win_width_pct</entry>
<entry>
percentage size, compared to parent window (if 50,
width is half)
</entry>
</row>
<row>
<entry>win_height_pct</entry>
<entry>
percentage size, compared to parent window (if 50,
height is half)
</entry>
</row>
<row>
<entry>win_chat_x</entry>
<entry>
X position of chat window in terminal (0 is first
column)
</entry>
</row>
<row>
<entry>win_chat_y</entry>
<entry>
Y position of chat window in terminal (0 is first
column)
</entry>
</row>
<row>
<entry>win_chat_width</entry>
<entry>width of chat window, in chars</entry>
</row>
<row>
<entry>win_chat_height</entry>
<entry>height of chat window, in chars</entry>
</row>
<row>
<entry>first_line_displayed</entry>
<entry>
1 if first line of buffer is displayed on screen,
otherwise 0
</entry>
</row>
<row>
<entry>scroll</entry>
<entry>
1 if scroll is active on window (last line not
displayed)
</entry>
</row>
<row>
<entry>scroll_lines_after</entry>
<entry>
number of lines not displayed after last one displayed
(when scrolling)
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: integer value of property.
</para>
<para>
Example:
<screen>
weechat_printf (NULL, "current window is at position (x,y): (%d,%d)",
weechat_window_get_integer (weechat_current_window, "win_x"),
weechat_window_get_integer (weechat_current_window, "win_y"));
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_window_get_string">
<title>weechat_window_get_string</title>
<para>
Prototype:
<programlisting>
const char *weechat_window_get_string (struct t_gui_window *window, const char *property);
</programlisting>
</para>
<para>
Get string value of a window property. NOT USED TODAY, reserved for
future version.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>window</option>: window pointer
</para>
</listitem>
<listitem>
<para>
<option>property</option>: property name
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: string value of property.
</para>
</section>
<section id="secPluginCApi_weechat_window_get_pointer">
<title>weechat_window_get_pointer</title>
<para>
Prototype:
<programlisting>
void *weechat_window_get_pointer (struct t_gui_window *window, const char *property);
</programlisting>
</para>
<para>
Get pointer value of a window property.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>window</option>: window pointer
</para>
</listitem>
<listitem>
<para>
<option>property</option>: property name:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>current</entry>
<entry>current window pointer</entry>
</row>
<row>
<entry>buffer</entry>
<entry>pointer to buffer displayed by window</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer value of property.
</para>
<para>
Example:
<screen>
weechat_printf (NULL, "current window pointer is: %lx, buffer displayed is: %lx",
weechat_window_get_pointer (NULL, "current"),
weechat_window_get_integer (weechat_current_window, "buffer"));
</screen>
</para>
</section>
</section>
<!-- ============================[ nicklist ]============================ -->
<section id="secPluginCApi_nicklist">
<title>Nicklist</title>
<para>
Functions for buffer nicklist.
</para>
<section id="secPluginCApi_weechat_nicklist_add_group">
<title>weechat_nicklist_add_group</title>
<para>
Prototype:
<programlisting>
struct t_gui_nick_group *weechat_nicklist_add_group (
struct t_gui_buffer *buffer,
struct t_gui_nick_group *parent_group,
const char *name,
const char *color,
int visible);
</programlisting>
</para>
<para>
Add a group in a nicklist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>parent_group</option>: pointer to parent of group, NULL
if group has no parent (nicklist root)
</para>
</listitem>
<listitem>
<para>
<option>name</option>: group name
</para>
</listitem>
<listitem>
<para>
<option>visible</option>: 1 if group and sub-groups/nicks are
visible, 0 if they are hidden
</para>
</listitem>
<listitem>
<para>
<option>color</option>: color option name
("weechat.color.xxx" or "file.section.option") or color name
("blue", "red",..) or "bar_fg"/"bar_bg"/"bar_delim" (bar
foreground/background/delimiter)
</para>
</listitem>
</itemizedlist>
</para>
<note>
<para>
The group name can begin with one or more digits, followed by pipe,
and then group name. When such string is found at beginning, it's
used to sort groups in nicklist. For examples groups "1|test" and
"2|abc" will be sorted: "test" first, "abc" second, whereas "test"
and "abc" will be sorted: "abc" first, "test" second.
</para>
</note>
<para>
Return value: pointer to new group, NULL if an error occured.
</para>
<para>
Example:
<screen>
struct t_gui_nick_group *my_group =
weechat_nicklist_add_group (my_buffer, my_parent_group,
"test_group", "weechat.color.nicklist_group", 1);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_nicklist_search_group">
<title>weechat_nicklist_search_group</title>
<para>
Prototype:
<programlisting>
struct t_gui_nick_group *weechat_nicklist_search_group (
struct t_gui_buffer *buffer,
struct t_gui_nick_group *from_group,
const char *name);
</programlisting>
</para>
<para>
Search a group in a nicklist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>from_group</option>: search from this group only, if NULL,
then search in whole nicklist
</para>
</listitem>
<listitem>
<para>
<option>name</option>: group name to search
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to group found, NULL if not found.
</para>
<para>
Example:
<screen>
struct t_gui_nick_group *ptr_group =
weechat_nicklist_search_group (my_buffer, NULL, "test_group");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_nicklist_add_nick">
<title>weechat_nicklist_add_nick</title>
<para>
Prototype:
<programlisting>
struct t_gui_nick_group *weechat_nicklist_add_nick (
struct t_gui_buffer *buffer,
struct t_gui_nick_group *group,
const char *name,
const char *color,
const char *prefix,
const char *prefix_color,
int visible);
</programlisting>
</para>
<para>
Add a nick in a group.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>group</option>: group pointer
</para>
</listitem>
<listitem>
<para>
<option>name</option>: nick name
</para>
</listitem>
<listitem>
<para>
<option>color</option>: color option name
("weechat.color.xxx" or "file.section.option") or color name
("blue", "red",..) or "bar_fg"/"bar_bg"/"bar_delim" (bar
foreground/background/delimiter)
</para>
</listitem>
<listitem>
<para>
<option>prefix</option>: prefix displayed before nick
</para>
</listitem>
<listitem>
<para>
<option>prefix_color</option>: color option name
("weechat.color.xxx" or "file.section.option") or color name
("blue", "red",..) or "bar_fg"/"bar_bg"/"bar_delim" (bar
foreground/background/delimiter)
</para>
</listitem>
<listitem>
<para>
<option>visible</option>: 1 if nick is visible, 0 if it is hidden
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new nick, NULL if an error occured.
</para>
<para>
Example:
<screen>
struct t_gui_nick *my_nick =
weechat_nicklist_add_nick (my_buffer, my_group,
"test_nick",
(nick_away) ? "weechat.color.nicklist_away" : "bar_fg",
"@", "lightgreen",
1);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_nicklist_search_nick">
<title>weechat_nicklist_search_nick</title>
<para>
Prototype:
<programlisting>
struct t_gui_nick *weechat_nicklist_search_nick (
struct t_gui_buffer *buffer,
struct t_gui_nick_group *from_group,
const char *name);
</programlisting>
</para>
<para>
Search a nick in a nicklist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>from_group</option>: search from this group only, if NULL,
then search in whole nicklist
</para>
</listitem>
<listitem>
<para>
<option>name</option>: nick name to search
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to nick found, NULL if not found.
</para>
<para>
Example:
<screen>
struct t_gui_nick *ptr_nick =
weechat_nicklist_search_nick (my_buffer, NULL, "test_nick");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_nicklist_remove_group">
<title>weechat_nicklist_remove_group</title>
<para>
Prototype:
<programlisting>
void weechat_nicklist_remove_group (
struct t_gui_buffer *buffer,
struct t_gui_nick_group *group);
</programlisting>
</para>
<para>
Remove a group from a nicklist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>group</option>: group pointer to remove (all
sub-groups/nicks will be removed too)
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
weechat_nicklist_remove_group (my_buffer, my_group);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_nicklist_remove_nick">
<title>weechat_nicklist_remove_nick</title>
<para>
Prototype:
<programlisting>
void weechat_nicklist_remove_nick (
struct t_gui_buffer *buffer,
struct t_gui_nick *nick);
</programlisting>
</para>
<para>
Remove a nick from a nicklist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
<listitem>
<para>
<option>nick</option>: nick pointer to remove
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
weechat_nicklist_remove_nick (my_buffer, my_nick);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_nicklist_remove_all">
<title>weechat_nicklist_remove_all</title>
<para>
Prototype:
<programlisting>
void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);
</programlisting>
</para>
<para>
Remove all groups/nicks from a nicklist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
weechat_nicklist_remove_all (my_buffer);
</screen>
</para>
</section>
</section>
<!-- ==============================[ bars ]============================== -->
<section id="secPluginCApi_bars">
<title>Bars</title>
<para>
Functions for bars.
</para>
<section id="secPluginCApi_weechat_bar_item_search">
<title>weechat_bar_item_search</title>
<para>
Prototype:
<programlisting>
struct t_gui_bar_item *weechat_bar_item_search (const char *name);
</programlisting>
</para>
<para>
Search a bar item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>name</option>: bar item name
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to bar item found, NULL if bar item was not found.
</para>
<para>
Example:
<screen>
struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_bar_item_new">
<title>weechat_bar_item_new</title>
<para>
Prototype:
<programlisting>
struct t_gui_bar_item *weechat_bar_item_new (
const char *name,
char *(build_callback)(void *data,
struct t_gui_bar_item *item,
struct t_gui_window *window),
void *build_callback_data);
</programlisting>
</para>
<para>
Create a new bar item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>name</option>: bar item name
</para>
</listitem>
<listitem>
<para>
<option>build_callback</option>: function called when bar item
is built: it must return content of bar item
</para>
</listitem>
<listitem>
<para>
<option>build_callback_data</option>: pointer given to build
callback, when it is called by Weechat
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new bar item, NULL if an error occured.
</para>
<para>
Example:
<screen>
char *
my_build_callback (void *data,
struct t_gui_bar_item *item,
struct t_gui_window *window)
{
return strdup ("my content");
}
struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
&amp;my_build_callback,
NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_bar_item_update">
<title>weechat_bar_item_update</title>
<para>
Prototype:
<programlisting>
void weechat_bar_item_update (const char *name);
</programlisting>
</para>
<para>
Update content of a bar item, by calling its build callback.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>name</option>: bar item name
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
weechat_bar_item_update ("myitem");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_bar_item_remove">
<title>weechat_bar_item_remove</title>
<para>
Prototype:
<programlisting>
void weechat_bar_item_remove (struct t_gui_bar_item *item);
</programlisting>
</para>
<para>
Remove a bar item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>item</option>: bar item pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
weechat_bar_item_remove (&amp;my_item);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_bar_search">
<title>weechat_bar_search</title>
<para>
Prototype:
<programlisting>
struct t_gui_bar_item *weechat_bar_search (const char *name);
</programlisting>
</para>
<para>
Search a bar.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>name</option>: bar name
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to bar found, NULL if bar was not found.
</para>
<para>
Example:
<screen>
struct t_gui_bar *bar = weechat_bar_search ("mybar");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_bar_new">
<title>weechat_bar_new</title>
<para>
Prototype:
<programlisting>
struct t_gui_bar *weechat_bar_new (
const char *name,
const char *hidden,
const char *priority,
const char *type,
const char *condition,
const char *position,
const char *filling_top_bottom,
const char *filling_left_right,
const char *size,
const char *size_max,
const char *color_fg,
const char *color_delim,
const char *color_bg,
const char *separator,
const char *items);
</programlisting>
</para>
<para>
Create a new item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>name</option>: bar item name
</para>
</listitem>
<listitem>
<para>
<option>hidden</option>: "on" if bar is hidden, "off" is bar is
visible
</para>
</listitem>
<listitem>
<para>
<option>priority</option>: bar priority (integer)
</para>
</listitem>
<listitem>
<para>
<option>type</option>: "root" (bar displayed once, outside
windows), or "window" (bar displayed in each window)
</para>
</listitem>
<listitem>
<para>
<option>condition</option>: condition for displaying bar, one of
following:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Condition</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>active</entry>
<entry>
bar is displayed in active window only
</entry>
</row>
<row>
<entry>inactive</entry>
<entry>
bar is displayed in inactive window(s) only
</entry>
</row>
<row>
<entry>nicklist</entry>
<entry>bar is displayed in window(s) with nicklist</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>position</option>: "top", "bottom", "left" or "right"
</para>
</listitem>
<listitem>
<para>
<option>filling_top_bottom</option>: filling when bar is in
position "top" or "bottom", one of following:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Filling</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>horizontal</entry>
<entry>
items are filled horitontally (space after each item)
</entry>
</row>
<row>
<entry>vertical</entry>
<entry>
items are filled verticaly (new line after each item)
</entry>
</row>
<row>
<entry>columns_horizontal</entry>
<entry>
items are filled horizontally, displayed with columns
</entry>
</row>
<row>
<entry>columns_vertical</entry>
<entry>
items are filled vertically, displayed with columns
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>filling_left_right</option>: filling when bar is in
position "left" or "right", one of following:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Filling</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>horizontal</entry>
<entry>
items are filled horitontally (space after each item)
</entry>
</row>
<row>
<entry>vertical</entry>
<entry>
items are filled verticaly (new line after each item)
</entry>
</row>
<row>
<entry>columns_horizontal</entry>
<entry>
items are filled horizontally, displayed with columns
</entry>
</row>
<row>
<entry>columns_vertical</entry>
<entry>
items are filled vertically, displayed with columns
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>size</option>: bar size in chars (0 means automatic
size)
</para>
</listitem>
<listitem>
<para>
<option>size_max</option>: max size for bar (0 means no max size)
</para>
</listitem>
<listitem>
<para>
<option>color_fg</option>: color for text in bar
</para>
</listitem>
<listitem>
<para>
<option>color_delim</option>: color for delimiters in bar
</para>
</listitem>
<listitem>
<para>
<option>color_bg</option>: background color for bar
</para>
</listitem>
<listitem>
<para>
<option>separator</option>: "on" if bar has separator line with
other windows/bars, "off" otherwise
</para>
</listitem>
<listitem>
<para>
<option>items</option>: list of items in bar, separated by comma
(space between items), or "+" (glued items)
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new bar, NULL if an error occured.
</para>
<para>
Example:
<screen>
struct t_gui_bar *my_bar =
weechat_bar_new ("mybar",
"off",
100,
"window",
"",
"top",
"horizontal",
"vertical",
"0",
"5",
"default",
"cyan",
"blue",
"off",
"time,buffer_number+buffer_name");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_bar_set">
<title>weechat_bar_set</title>
<para>
Prototype:
<programlisting>
int weechat_bar_set (struct t_gui_bar *bar,
const char *property,
const char *value);
</programlisting>
</para>
<para>
Set a new value for a bar property.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>bar</option>: bar pointer
</para>
</listitem>
<listitem>
<para>
<option>property</option>: property name: name, hidden, priority,
conditions, position, filling_top_bottom, filling_left_right,
size, size_max, color_fg, color_delim, color_bg, separator, items
(see <xref linkend="secPluginCApi_weechat_bar_new" />)
</para>
</listitem>
<listitem>
<para>
<option>value</option>: new value for property
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: 1 if new value was set, 0 if an error occured.
</para>
<para>
Example: <screen>weechat_bar_set (mybar, "position", "bottom");</screen>
</para>
</section>
<section id="secPluginCApi_weechat_bar_update">
<title>weechat_bar_update</title>
<para>
Prototype:
<programlisting>
void weechat_bar_update (const char *name);
</programlisting>
</para>
<para>
Refresh content of a bar on screen.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>name</option>: bar name
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example: <screen>weechat_bar_update ("mybar");</screen>
</para>
</section>
<section id="secPluginCApi_weechat_bar_remove">
<title>weechat_bar_remove</title>
<para>
Prototype:
<programlisting>
void weechat_bar_remove (struct t_gui_bar *bar);
</programlisting>
</para>
<para>
Remove a bar.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>bar</option>: bar pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example: <screen>weechat_bar_remove (mybar);</screen>
</para>
</section>
</section>
<!-- ============================[ commands ]============================ -->
<section id="secPluginCApi_commands">
<title>Commands</title>
<para>
Functions for executing WeeChat commands.
</para>
<section id="secPluginCApi_weechat_command">
<title>weechat_command</title>
<para>
Prototype:
<programlisting>
void weechat_command (struct t_gui_buffer *buffer,
const char *command);
</programlisting>
</para>
<para>
Execute a command.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>buffer</option>: buffer pointer (command is executed
on this buffer, use NULL for WeeChat core buffer)
</para>
</listitem>
<listitem>
<para>
<option>command</option>: command to execute (if beginning with a
"/"), or text is sent to buffer (without leading "/")
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>
weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"),
"/whois FlashCode");
</screen>
</para>
</section>
</section>
<!-- ============================[ network ]============================= -->
<section id="secPluginCApi_network">
<title>Network</title>
<para>
Network functions.
</para>
<section id="secPluginCApi_weechat_network_pass_proxy">
<title>weechat_network_pass_proxy</title>
<para>
Prototype:
<programlisting>
int weechat_network_pass_proxy (const char *proxy,
int sock,
const char *address,
int port);
</programlisting>
</para>
<para>
Establish a connection/authentification to a proxy.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>proxy</option>: proxy name to use
</para>
</listitem>
<listitem>
<para>
<option>sock</option>: socket to use
</para>
</listitem>
<listitem>
<para>
<option>address</option>: address (hostname or IP)
</para>
</listitem>
<listitem>
<para>
<option>port</option>: port
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: 1 if connection is ok, 0 if an error occured.
</para>
<para>
Example:
<screen>
if (weechat_network_pass_proxy ("myproxy", sock, "irc.freenode.net", 6667))
{
/* OK */
}
else
{
/* error */
}
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_network_connect_to">
<title>weechat_network_network_connect_to</title>
<para>
Prototype:
<programlisting>
int weechat_network_connect_to (const char *proxy,
int sock,
unsigned long address,
int port);
</programlisting>
</para>
<para>
Establish a connection to a remote host.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>proxy</option>: proxy name to use
</para>
</listitem>
<listitem>
<para>
<option>sock</option>: socket to use
</para>
</listitem>
<listitem>
<para>
<option>address</option>: address
</para>
</listitem>
<listitem>
<para>
<option>port</option>: port
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: 1 if connection is ok, 0 if an error occured.
</para>
<para>
Example:
<screen>
struct sockaddr_in addr;
socklen_t length;
unsigned long address;
memset (&amp;addr, 0, sizeof (struct sockaddr_in));
length = sizeof (addr);
getsockname (sock, (struct sockaddr *) &amp;addr, &amp;length);
addr.sin_family = AF_INET;
address = ntohl (addr.sin_addr.s_addr);
if (weechat_network_connect_to (NULL, sock, address, 6667))
{
/* OK */
}
else
{
/* error */
}
</screen>
</para>
</section>
</section>
<!-- =============================[ infos ]============================== -->
<section id="secPluginCApi_infos">
<title>Infos</title>
<para>
Functions to get infos.
</para>
<section id="secPluginCApi_weechat_info_get">
<title>weechat_info_get</title>
<para>
Prototype:
<programlisting>
const char *weechat_info_get (const char *info_name,
const char *arguments);
</programlisting>
</para>
<para>
Get info from WeeChat or a plugin.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>info_name</option>: name of info to read:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<thead>
<row>
<entry>Plugin</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
&infos.xml;
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>arguments</option>: arguments for info asked (optional,
NULL if no argument is needed)
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: const string with info asked, NULL if an error occured.
</para>
<para>
Example:
<screen>
weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)",
weechat_info_get ("version", NULL),
weechat_info_get ("date", NULL));
weechat_printf (NULL, "WeeChat home is: %s",
weechat_info_get ("weechat_dir"));
</screen>
</para>
</section>
</section>
<!-- ===========================[ infolists ]============================ -->
<section id="secPluginCApi_infolists">
<title>Infolists</title>
<para>
Infolists functions.
</para>
<para>
An infolist is a list of "items". Each item contains variables.
For example, infolist "irc_server" has N items (N is number of IRC
servers defined). For each item, there is variables like "name",
"buffer", "is_connected", ...
Each variable has a type and a value. Possible types are:
<informaltable colsep="0" frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>integer</entry>
<entry>any integer value</entry>
</row>
<row>
<entry>string</entry>
<entry>any string value</entry>
</row>
<row>
<entry>pointer</entry>
<entry>any pointer</entry>
</row>
<row>
<entry>buffer</entry>
<entry>buffer with fixed length, containing any data</entry>
</row>
<row>
<entry>time</entry>
<entry>time value</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<section id="secPluginCApi_weechat_infolist_new">
<title>weechat_infolist_new</title>
<para>
Prototype:
<programlisting>
struct t_infolist *weechat_infolist_new ();
</programlisting>
</para>
<para>
Create a new infolist.
</para>
<para>
Return value: pointer to new infolist.
</para>
<para>
Example:
<screen>struct t_infolist *infolist = weechat_infolist_new ();</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_new_item">
<title>weechat_infolist_new_item</title>
<para>
Prototype:
<programlisting>
struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist);
</programlisting>
</para>
<para>
Add an item in an infolist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new item.
</para>
<para>
Example:
<screen>
struct t_infolist_item *item = weechat_infolist_new_item (infolist);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_new_var_integer">
<title>weechat_infolist_new_var_integer</title>
<para>
Prototype:
<programlisting>
struct t_infolist_var *weechat_infolist_new_var_integer (
struct t_infolist_item *item,
const char *name,
int value);
</programlisting>
</para>
<para>
Add an integer variable to an infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>item</option>: infolist item pointer
</para>
</listitem>
<listitem>
<para>
<option>name</option>: variable name
</para>
</listitem>
<listitem>
<para>
<option>value</option>: integer value
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new variable.
</para>
<para>
Example:
<screen>
struct t_infolist_var *var =
weechat_infolist_new_variable_integer (item, "my_integer", 123);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_new_var_string">
<title>weechat_infolist_new_var_string</title>
<para>
Prototype:
<programlisting>
struct t_infolist_var *weechat_infolist_new_var_string (
struct t_infolist_item *item,
const char *name,
const char *value);
</programlisting>
</para>
<para>
Add a string variable to an infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>item</option>: infolist item pointer
</para>
</listitem>
<listitem>
<para>
<option>name</option>: variable name
</para>
</listitem>
<listitem>
<para>
<option>value</option>: string value
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new variable.
</para>
<para>
Example:
<screen>
struct t_infolist_var *var =
weechat_infolist_new_variable_string (item, "my_string", "value here");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_new_var_pointer">
<title>weechat_infolist_new_var_pointer</title>
<para>
Prototype:
<programlisting>
struct t_infolist_var *weechat_infolist_new_var_pointer (
struct t_infolist_item *item,
const char *name,
void *pointer);
</programlisting>
</para>
<para>
Add a pointer variable to an infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>item</option>: infolist item pointer
</para>
</listitem>
<listitem>
<para>
<option>name</option>: variable name
</para>
</listitem>
<listitem>
<para>
<option>pointer</option>: pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new variable.
</para>
<para>
Example:
<screen>
struct t_infolist_var *var =
weechat_infolist_new_variable_pointer (item, "my_pointer", &amp;something);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_new_var_buffer">
<title>weechat_infolist_new_var_buffer</title>
<para>
Prototype:
<programlisting>
struct t_infolist_var *weechat_infolist_new_var_buffer (
struct t_infolist_item *item,
const char *name,
void *pointer,
int size);
</programlisting>
</para>
<para>
Add a buffer variable to an infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>item</option>: infolist item pointer
</para>
</listitem>
<listitem>
<para>
<option>name</option>: variable name
</para>
</listitem>
<listitem>
<para>
<option>pointer</option>: pointer to buffer
</para>
</listitem>
<listitem>
<para>
<option>size</option>: size of buffer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new variable.
</para>
<para>
Example:
<screen>
char buffer[256];
/* ... */
struct t_infolist_var *var =
weechat_infolist_new_variable_buffer (item, "my_buffer",
&amp;buffer, sizeof (buffer));
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_new_var_time">
<title>weechat_infolist_new_var_time</title>
<para>
Prototype:
<programlisting>
struct t_infolist_var *weechat_infolist_new_var_time (
struct t_infolist_item *item,
const char *name,
time_t time);
</programlisting>
</para>
<para>
Add a time variable to an infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>item</option>: infolist item pointer
</para>
</listitem>
<listitem>
<para>
<option>name</option>: variable name
</para>
</listitem>
<listitem>
<para>
<option>time</option>: time value
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new variable.
</para>
<para>
Example:
<screen>
struct t_infolist_var *var =
weechat_infolist_new_variable_time (item, "my_time", time (NULL));
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_get">
<title>weechat_infolist_get</title>
<para>
Prototype:
<programlisting>
struct t_infolist *weechat_infolist_get (const char *infolist_name,
void *pointer,
const char *arguments);
</programlisting>
</para>
<para>
Get infolist from WeeChat or a plugin.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist_name</option>: name of infolist to read:
<informaltable colsep="0" frame="none">
<tgroup cols="3">
<thead>
<row>
<entry>Plugin</entry>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
&infolists.xml;
</tbody>
</tgroup>
</informaltable>
</para>
</listitem>
<listitem>
<para>
<option>pointer</option>: pointer to an item, to get only this
item in infolist (optional, can be NULL)
</para>
</listitem>
<listitem>
<para>
<option>arguments</option>: name/type of item to retrieve
(optional, can be NULL)
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to infolist, NULL if an error occured.
</para>
<para>
Example:
<screen>
struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_next">
<title>weechat_infolist_next</title>
<para>
Prototype:
<programlisting>
int weechat_infolist_next (struct t_infolist *infolist);
</programlisting>
</para>
<para>
Move "cursor" to next item in an infolist. The first call to this
function for an infolist moves cursor to first item in infolist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: 1 if pointer is now on next item, 0 if end of list was
reached.
</para>
<para>
Example:
<screen>
if (weechat_infolist_next (infolist))
{
/* read variables in item... */
}
else
{
/* no more item available */
}
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_prev">
<title>weechat_infolist_prev</title>
<para>
Prototype:
<programlisting>
int weechat_infolist_prev (struct t_infolist *infolist);
</programlisting>
</para>
<para>
Move "cursor" to previous item in an infolist. The first call to this
function for an infolist moves cursor to last item in infolist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: 1 if pointer is now on previous item, 0 if beginning of
list was reached.
</para>
<para>
Example:
<screen>
if (weechat_infolist_prev (infolist))
{
/* read variables in item... */
}
else
{
/* no more item available */
}
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_reset_item_cursor">
<title>weechat_infolist_reset_item_cursor</title>
<para>
Prototype:
<programlisting>
void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);
</programlisting>
</para>
<para>
Reset "cursor" for infolist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example: <screen>weechat_infolist_reset_item_cursor (infolist);</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_fields">
<title>weechat_infolist_fields</title>
<para>
Prototype:
<programlisting>
const char *weechat_infolist_fields (struct t_infolist *infolist);
</programlisting>
</para>
<para>
Get list of fields for current infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: string with list of fields for current infolist item.
List is comma separated, and contains letter for type, followed by
variable name. Types are: "i" (integer), "s" (string), "p" (pointer),
"b" (buffer), "t" (time).
</para>
<para>
Example:
<screen>
const char *fields = weechat_infolist_fields (infolist);
/* fields contains something like:
"i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" */
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_integer">
<title>weechat_infolist_integer</title>
<para>
Prototype:
<programlisting>
int weechat_infolist_integer (struct t_infolist *infolist,
const char *var);
</programlisting>
</para>
<para>
Get value of integer variable in current infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
<listitem>
<para>
<option>var</option>: variable name (must be type "integer")
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: integer value of variable.
</para>
<para>
Example:
<screen>
weechat_printf (NULL, "integer value = %d",
weechat_infolist_integer (infolist, "my_integer"));
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_string">
<title>weechat_infolist_string</title>
<para>
Prototype:
<programlisting>
const char *weechat_infolist_string (struct t_infolist *infolist,
const char *var);
</programlisting>
</para>
<para>
Get value of string variable in current infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
<listitem>
<para>
<option>var</option>: variable name (must be type "string")
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: string value of variable.
</para>
<para>
Example:
<screen>
weechat_printf (NULL, "string value = %s",
weechat_infolist_string (infolist, "my_string"));
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_pointer">
<title>weechat_infolist_pointer</title>
<para>
Prototype:
<programlisting>
void *weechat_infolist_pointer (struct t_infolist *infolist,
const char *var);
</programlisting>
</para>
<para>
Get value of pointer variable in current infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
<listitem>
<para>
<option>var</option>: variable name (must be type "pointer")
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer value of variable.
</para>
<para>
Example:
<screen>
weechat_printf (NULL, "pointer value = 0x%lx",
weechat_infolist_pointer (infolist, "my_pointer"));
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_buffer">
<title>weechat_infolist_buffer</title>
<para>
Prototype:
<programlisting>
void *weechat_infolist_buffer (struct t_infolist *infolist,
const char *var,
int *size);
</programlisting>
</para>
<para>
Get value of buffer variable in current infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
<listitem>
<para>
<option>var</option>: variable name (must be type "buffer")
</para>
</listitem>
<listitem>
<para>
<option>size</option>: pointer to integer variable, will be set
with buffer size
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: buffer pointer.
</para>
<para>
Example:
<screen>
int size;
void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &amp;size);
weechat_printf (NULL, "buffer pointer = 0x%lx, size = %d",
pointer, size);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_time">
<title>weechat_infolist_time</title>
<para>
Prototype:
<programlisting>
time_t weechat_infolist_time (struct t_infolist *infolist,
const char *var);
</programlisting>
</para>
<para>
Get value of time variable in current infolist item.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
<listitem>
<para>
<option>var</option>: variable name (must be type "time")
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: time value of variable.
</para>
<para>
Example:
<screen>
weechat_printf (NULL, "time value = 0x%ld",
weechat_infolist_time (infolist, "my_time"));
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_infolist_free">
<title>weechat_infolist_free</title>
<para>
Prototype:
<programlisting>
void weechat_infolist_free (struct t_infolist *infolist);
</programlisting>
</para>
<para>
Free an infolist.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>infolist</option>: infolist pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example:
<screen>weechat_infolist_free (infolist);</screen>
</para>
</section>
</section>
<!-- ============================[ upgrade ]============================= -->
<section id="secPluginCApi_upgrade">
<title>Upgrade</title>
<para>
Functions for WeeChat upgrading.
</para>
<section id="secPluginCApi_weechat_upgrade_new">
<title>weechat_upgrade_new</title>
<para>
Prototype:
<programlisting>
struct t_upgrade_file *weechat_upgrade_new (const char *filename,
int write);
</programlisting>
</para>
<para>
Create or read a file for upgrade.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>filename</option>: name of file (extension ".upgrade"
will be added to this name by WeeChat)
</para>
<para>
<option>write</option>: 1 to create file (write mode, before
upgrade), 0 to read file (after upgrade)
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: pointer to new upgrade file.
</para>
<para>
Example:
<screen>
struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file");
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_upgrade_write_object">
<title>weechat_upgrade_write_object</title>
<para>
Prototype:
<programlisting>
struct t_upgrade_file *weechat_upgrade_write_object (
struct t_upgrade_file *upgrade_file,
int object_id,
struct t_infolist *infolist);
</programlisting>
</para>
<para>
Write an object in upgrade file.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>upgrade_file</option>: upgrade file pointer
</para>
<para>
<option>object_id</option>: id for object
</para>
<para>
<option>infolist</option>: infolist to write in file
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: 1 if ok, 0 if error.
</para>
<para>
Example:
<screen>
weechat_upgrade_write_object (upgrade_file, 1, &amp;infolist);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_upgrade_read">
<title>weechat_upgrade_read</title>
<para>
Prototype:
<programlisting>
struct t_upgrade_file *weechat_upgrade_read (
struct t_upgrade_file *upgrade_file,
int (*callback_read)(void *data,
struct t_upgrade_file *upgrade_file,
int object_id,
struct t_infolist *infolist),
void *callback_read_data);
</programlisting>
</para>
<para>
Read an upgrade file.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>upgrade_file</option>: upgrade file pointer
</para>
<para>
<option>callback_read</option>: callback called for each object
read in upgrade file
</para>
<para>
<option>callback_read_data</option>: pointer given to read
callback when it is called by WeeChat
</para>
</listitem>
</itemizedlist>
</para>
<para>
Return value: 1 if ok, 0 if error.
</para>
<para>
Example:
<screen>
int
my_upgrade_read_cb (struct t_upgrade_file *upgrade_file,
int object_id,
struct t_infolist *infolist)
{
/* read variables... */
return WEECHAT_RC_OK;
}
weechat_upgrade_read (upgrade_file, &amp;my_upgrade_read_cb, NULL);
</screen>
</para>
</section>
<section id="secPluginCApi_weechat_upgrade_close">
<title>weechat_upgrade_close</title>
<para>
Prototype:
<programlisting>
void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);
</programlisting>
</para>
<para>
Close an upgrade file.
</para>
<para>
Arguments:
<itemizedlist>
<listitem>
<para>
<option>upgrade_file</option>: upgrade file pointer
</para>
</listitem>
</itemizedlist>
</para>
<para>
Example: <screen>weechat_upgrade_close (upgrade_file);</screen>
</para>
</section>
</section>
</section>
View Git Blame Copy Permalink