diff options
| -rw-r--r-- | doc/de/dev/plugin_c_api.de.xml | 10679 | ||||
| -rw-r--r-- | doc/fr/dev/plugin_c_api.fr.xml | 10837 |
2 files changed, 19374 insertions, 2142 deletions
diff --git a/doc/de/dev/plugin_c_api.de.xml b/doc/de/dev/plugin_c_api.de.xml index fc15d82ab..2dbf4149a 100644 --- a/doc/de/dev/plugin_c_api.de.xml +++ b/doc/de/dev/plugin_c_api.de.xml @@ -21,484 +21,9173 @@ along with this program. If not, see <http://www.gnu.org/licenses/>. --> -<section id="secAPIFunctions"> +<section id="secPluginCApi"> <!-- TRANSLATION NEEDED --> - <title>Plugin C API</title> + <title>C plugin API</title> - <section id="secAPI_set_charset"> - <title>set_charset</title> + <!-- =============================[ plugins ]============================ --> + + <section id="secPluginCApi_plugins"> + <title>Plugins</title> <para> - Prototyp: - <command> - void set_charset (t_weechat_plugin *plugin, char *charset) - </command> - </para> - <para> - Legt neuen Zeichensatz für ein Plugin fest. - </para> - <para> - Argumente: - <itemizedlist> - <listitem> - <para> - <option>plugin</option>: Zeiger auf Plugin-Struktur - </para> - </listitem> - <listitem> - <para> - <option>charset</option>: neuer Zeichensatz, der benutzt - werden soll - </para> - </listitem> - </itemizedlist> - </para> - <para> - Beispiel: - <screen>plugin->set_charset (plugin, "ISO-8859-1");</screen> + 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> - <section id="secAPI_iconv_to_internal"> - <title>iconv_to_internal</title> + <!-- =============================[ strings ]============================ --> + + <section id="secPluginCApi_strings"> + <title>Strings</title> <para> - Prototyp: - <command> - void iconv_to_internal (t_weechat_plugin *plugin, char *charset, - char *string) - </command> - </para> - <para> - Konvertiert eine Zeichenkette in das interne Format von WeeChat - (UTF-8). - </para> - <para> - Argumente: - <itemizedlist> - <listitem> - <para> - <option>plugin</option>: Zeiger auf Plugin-Struktur - </para> - </listitem> - <listitem> - <para> - <option>charset</option>: ursprünglicher Zeichensatz, von - dem konvertiert werden soll - </para> - </listitem> - <listitem> - <para> - <option>string</option>: zu konvertierende Zeichenkette - </para> - </listitem> - </itemizedlist> - </para> - <para> - Rückgabewert: konvertierte Zeichenkette - </para> - <para> - Anmerkung: der Speicher, der durch das Ergebnis belegt wird, muss - mit free() wieder freigegeben werden. - </para> - <para> - Beispiel: - <screen>char *str = plugin->iconv_to_internal (plugin, "ISO-8859-1", "iso string: é à");</screen> + 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 < string2, zero if string1 == string2, positive if + string1 > 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 < string2, zero if string1 == string2, positive if + string1 > 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 < string2, zero if string1 == string2, positive if + string1 > 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 may begin or end with "*" (no + other "*" are allowed inside mask). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>string</option>: string + </para> + </listitem> + <listitem> + <para> + <option>mask</option>: mask + </para> + </listitem> + <listitem> + <para> + <option>case_sensitive</option>: 1 for case sensitive search, + otherwise 0 + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if string matches mask, otherwise 0. + </para> + <para> + Examples: +<screen> +int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */ +int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */ +int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */ +</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_string_replace"> + <title>weechat_string_replace</title> + + <para> + Prototype: +<programlisting> +char *weechat_string_replace (const char *string, const char *search, + const char *replace); +</programlisting> + </para> + <para> + Replace "search" string by new one in a string. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>string</option>: string + </para> + </listitem> + <listitem> + <para> + <option>search</option>: string to replace + </para> + </listitem> + <listitem> + <para> + <option>replace</option>: replacement for "search" string + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: string with "search" replaced by "replace". + </para> + <note> + <para> + Result has to be free by a call to "free" after use. + </para> + </note> + <para> + Example: + <screen>char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_string_remove_quotes"> + <title>weechat_string_remove_quotes</title> + + <para> + Prototype: +<programlisting> +char *weechat_string_remove_quotes (const char *string, const char *quotes); +</programlisting> + </para> + <para> + Remove quotes at beginning/end of string (ignore spaces if there are + before first quote or after last quote). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>string</option>: string + </para> + </listitem> + <listitem> + <para> + <option>quotes</option>: string with list of quotes + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: string without quotes at beginning/end. + </para> + <note> + <para> + Result has to be free by a call to "free" after use. + </para> + </note> + <para> + Example: + <screen>char *str = weechat_string_remove_quotes (string, " 'abc' ", "'"); /* result: "abc" */</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_string_strip"> + <title>weechat_string_strip</title> + + <para> + Prototype: +<programlisting> +char *weechat_string_strip ( + const char *string, + int left, + int right, + const char *chars); +</programlisting> + </para> + <para> + Strip chars at beginning and/or end of string. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>string</option>: string + </para> + </listitem> + <listitem> + <para> + <option>left</option>: strip left chars if different from 0 + </para> + </listitem> + <listitem> + <para> + <option>right</option>: strip right chars if different from 0 + </para> + </listitem> + <listitem> + <para> + <option>chars</option>: string with chars to strip + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: stripped string. + </para> + <note> + <para> + Result has to be free by a call to "free" after use. + </para> + </note> + <para> + Example: +<screen> +char *str = weechat_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, &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, &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, &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, &argc); +char *string = weechat_string_build_with_exploded (argv, ";"); +/* string == "abc;def;ghi" */ +</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_string_split_command"> + <title>weechat_string_split_command</title> + + <para> + Prototype: +<programlisting> +char **weechat_string_split_command (const char *command, char separator); +</programlisting> + </para> + <para> + Split a list of commands separated by 'separator' (which can be escaped + by '\' in string). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>command</option>: command to split + </para> + </listitem> + <listitem> + <para> + <option>separator</option>: separator + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: array of strings, NULL if problem. + </para> + <note> + <para> + Result has to be free by a call to + "weechat_string_free_splitted_command" after use. + </para> + </note> + <para> + Example: + <screen>char **argv = weechat_string_split_command ("/command1;/command2", ';');</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_string_splitted_command"> + <title>weechat_string_free_splitted_command</title> + + <para> + Prototype: +<programlisting> +void weechat_string_free_splitted_command (char **splitted_command); +</programlisting> + </para> + <para> + Free memory used by a splitted command. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>splitted_command</option>: command splitted by + "weechat_string_split_commaand" function + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Example: +<screen> +char **argv = weechat_string_split_command ("/command1;/command2", ';'); +... +weechat_string_free_splitted_command (argv); +</screen> + </para> + </section> + + <section 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> - <section id="secAPI_iconv_from_internal"> - <title>iconv_from_internal</title> + <!-- ==============================[ UTF-8 ]============================= --> + + <section id="secPluginCApi_utf8"> + <title>UTF-8</title> <para> - Prototyp: - <command> - void iconv_from_internal (t_weechat_plugin *plugin, char *charset, - char *string) - </command> - </para> - <para> - Konvertiert eine Zeichenkette von dem internen WeeChat-Zeichensatz - (UTF-8) in einen anderen. - </para> - <para> - Argumente: - <itemizedlist> - <listitem> - <para> - <option>plugin</option>: Zeiger auf Plugin-Struktur - </para> - </listitem> - <listitem> - <para> - <option>charset</option>: Ziel-Zeichensatz - </para> - </listitem> - <listitem> - <para> - <option>string</option>: zu konvertierende Zeichenkette - </para> - </listitem> - </itemizedlist> - </para> - <para> - Rückgabewert: konvertierte Zeichenkette - </para> - <para> - Anmerkung: der Speicher, der durch das Ergebnis belegt wird, muss - mit free() wieder freigegeben werden. - </para> - <para> - Beispiel: - <screen>char *str = plugin->iconv_from_internal (plugin, "ISO-8859-1", "utf-8 string: é à");</screen> + 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, &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 ("东"); /* == 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 < char2, zero if char1 == char2, positive if char1 > 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> - <section id="secAPI_ascii_strcasecmp"> - <title>ascii_strcasecmp</title> + <!-- ===========================[ directories ]========================== --> + + <section id="secPluginCApi_directories"> + <title>Directories</title> <para> - Prototyp: - <command> - int ascii_strcasecmp (t_weechat_plugin *plugin, - char *string1, char *string2) - </command> - </para> - <para> - Vergleich von Zeichenketten unabhängig von Sprache und - Schreibweise (gross/klein). - </para> - <para> - Argumente: - <itemizedlist> - <listitem> - <para> - <option>plugin</option>: Zeiger auf Plugin-Struktur - </para> - </listitem> - <listitem> - <para> - <option>string1</option>: erste Zeichenkette des Vergleichs - </para> - </listitem> - <listitem> - <para> - <option>string2</option>: zweite Zeichenkette des Vergleichs - </para> - </listitem> - </itemizedlist> - </para> - <para> - Rückgabewert: Unterschied zwischen den zwei Zeichenketten: kleiner - Null wenn - string1 < string2, Null wenn string1 == string2, grösser Null - wenn string1 > string2 - </para> - <para> - Beispiel: - <screen>if (plugin->ascii_strcasecmp (plugin, "abc", "def") != 0) ...</screen> + 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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", &callback); +</screen> + </para> + </section> + </section> - <section id="secAPI_ascii_strncasecmp"> - <title>ascii_strncasecmp</title> + <!-- ==============================[ util ]============================== --> + + <section id="secPluginCApi_util"> + <title>Util</title> <para> - Prototyp: - <command> - int ascii_strncasecmp (t_weechat_plugin *plugin, - char *string1, char *string2, int max) - </command> - </para> - <para> - Vergleich von Zeichenketten unabhängig von Sprache und Schreibweise - (gross/klein) für höchstens "max" Zeichen. - </para> - <para> - Argumente: - <itemizedlist> - <listitem> - <para> - <option>plugin</option>: Zeiger auf Plugin-Struktur - </para> - </listitem> - <listitem> - <para> - <option>string1</option>: erste Zeichenkette des Vergleichs - </para> - </listitem> - <listitem> - <para> - <option>string2</option>: zweite Zeichenkette des Vergleichs - </para> - </listitem> - <listitem> - <para> - <option>max</option>: maximale Zahl an Zeichen für den - Vergleich - </para> - </listitem> - </itemizedlist> - </para> - <para> - Rückgabewert: Unterschied zwischen den zwei Zeichenketten: kleiner - Null wenn string1 < string2, Null wenn string1 == string2, - grösser Null wenn string1 > string2 - </para> - <para> - Beispiel: - <screen>if (plugin->ascii_strncasecmp (plugin, "abc", "def", 2) != 0) ...</screen> + 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 < char2, zero if tv1 == tv2, +1 if tv1 > + tv2 + </para> + <para> + Example: + <screen>if (weechat_timeval_cmp (&tv1, &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 (&tv1, &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 (&tv, 2000); /* add 2 seconds */</screen> + </para> + </section> + </section> - <section id="secAPI_explode_string"> - <title>explode_string</title> + <!-- ==========================[ sorted list ]=========================== --> + + <section id="secPluginCApi_sorted_list"> + <title>Sorted lists</title> <para> - Prototyp: - <command> - char **explode_string (t_weechat_plugin *plugin, char *string, - char *separators, int num_items_max, int *num_items) - </command> - </para> - <para> - Zerlege eine Zeichenkette entsprechend eines oder mehrerer - Trennzeichen(s). - </para> - <para> - Argumente: - <itemizedlist> - <listitem> - <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur - </para> - </listitem> - <listitem> - <para> - <option>string</option>: zu zerlegende Zeichenkette - </para> - </listitem> - <listitem> - <para> - <option>separators</option>: zu verwendende(s) Trennzeichen - </para> - </listitem> - <listitem> - <para> - <option>num_items_max</option>: maximale Anzahl an zu - erzeugenden Teilen (0 = keine Grenze) - </para> - </listitem> - <listitem> - <para> - <option>num_items</option>: Zeiger auf eine int-Variable, - die die Anzahl der erzeugten - Teile enthält - </para> - </listitem> - </itemizedlist> - </para> - <para> - Rückgabewert: ein Array von Zeichenketten, NULL bei Fehlern. + Sorted list functions. </para> + + <section id="secPluginCApi_weechat_list_new"> + <title>weechat_list_new</title> + + <para> + Prototype: +<programlisting> +struct t_weelist *weechat_list_new (); +</programlisting> + </para> + <para> + Create a new list. + </para> + <para> + Return value: pointer to new list. + </para> + <para> + Example: + <screen>struct t_weelist *list = weechat_list_new ();</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_add"> + <title>weechat_list_add</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_add ( + struct t_weelist *weelist, + const char *data, + const char *where); +</programlisting> + </para> + <para> + Add an item in a list. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>weelist</option>: list pointer + </para> + </listitem> + <listitem> + <para> + <option>data</option>: data to insert in list + </para> + </listitem> + <listitem> + <para> + <option>where</option>: position in list (constants are: + WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING or + WEECHAT_LIST_POS_END) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to new item. + </para> + <para> + Example: + <screen>weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT);</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_search"> + <title>weechat_list_search</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_search ( + struct t_weelist *weelist, + const char *data); +</programlisting> + </para> + <para> + Search an item in a list. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>weelist</option>: list pointer + </para> + </listitem> + <listitem> + <para> + <option>data</option>: data to search in list + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to item found, NULL if item was not found. + </para> + <para> + Example: + <screen>struct t_weelist_item *item = weechat_list_search (list, "my data");</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_casesearch"> + <title>weechat_list_casesearch</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_casesearch ( + struct t_weelist *weelist, + const char *data); +</programlisting> + </para> + <para> + Search an item in a list (case sensitive search). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>weelist</option>: list pointer + </para> + </listitem> + <listitem> + <para> + <option>data</option>: data to search in list + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to item found, NULL if item was not found. + </para> + <para> + Example: + <screen>struct t_weelist_item *item = weechat_list_casesearch (list, "my data");</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_get"> + <title>weechat_list_get</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_get ( + struct t_weelist *weelist, + int position); +</programlisting> + </para> + <para> + Get an item in a list by position. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>weelist</option>: list pointer + </para> + </listitem> + <listitem> + <para> + <option>position</option>: position in list (0 is first item) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to item found, NULL if item position was not + found. + </para> + <para> + Example: + <screen>struct t_weelist_item *item = weechat_list_get (list, 0); /* first item */</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_set"> + <title>weechat_list_set</title> + + <para> + Prototype: +<programlisting> +void weechat_list_set (struct t_weelist_item *item, const char *value); +</programlisting> + </para> + <para> + Set new value for an item. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>item</option>: item pointer + </para> + </listitem> + <listitem> + <para> + <option>value</option>: new value for item + </para> + </listitem> + </itemizedlist> + </para> + <para> + Example: + <screen>weechat_list_set (item, "new data");/</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_next"> + <title>weechat_list_next</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_next (struct t_weelist_item *item); +</programlisting> + </para> + <para> + Get next item in list. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>item</option>: item pointer + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to next item, NULL if pointer was last item in + list. + </para> + <para> + Example: + <screen>struct t_weelist_item *next_item = weechat_list_next_item (item);/</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_prev"> + <title>weechat_list_prev</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item); +</programlisting> + </para> + <para> + Get previous item in list. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>item</option>: item pointer + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to previous item, NULL if pointer was first item + in list. + </para> + <para> + Example: + <screen>struct t_weelist_item *prev_item = weechat_list_prev_item (item);/</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_string"> + <title>weechat_list_string</title> + + <para> + Prototype: +<programlisting> +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> - Hinweis: Das zurückgegebene Array muss nach der Benutzung mittels - "free_exloded_string" explizit freigegeben werden. + Functions for configuration files. </para> - <para> - Beispiel: + + <section id="secPluginCApi_weechat_config_new"> + <title>weechat_config_new</title> + + <para> + Prototype: +<programlisting> +struct t_config_file *weechat_config_new ( + const char *name, + int (*callback_reload)(void *data, + struct t_config_file *config_file), + void *callback_reload_data); +</programlisting> + </para> + <para> + Create a new configuration file. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>name</option>: name of configuration file (without path + or extension) + </para> + </listitem> + <listitem> + <para> + <option>callback_reload</option>: callback called when + configuration file is reloaded with /reload (optional, may be + NULL), arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_reload_data</option>: pointer given to reload + callback when it is called by WeeChat + NULL) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to new configuration file, NULL if an error + occured. + </para> + <note> + <para> + File is NOT created by this function. It will be created by call to + function <xref linkend="secPluginCApi_weechat_config_write" /> (you + should do that only after adding some sections (with + <xref linkend="secPluginCApi_weechat_config_new_section" />) and + options (with + <xref linkend="secPluginCApi_weechat_config_new_option" />). + </para> + </note> + <para> + Example: <screen> -char **argv; -int argc; -argv = plugin->explode_string (plugin, string, " ", 0, &argc); -... -if (argv != NULL) - plugin->free_exploded_string (plugin, argv); +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", + &my_config_reload_cb, + NULL); </screen> - </para> + </para> + </section> + + <section id="secPluginCApi_weechat_config_new_section"> + <title>weechat_config_new_section</title> + + <para> + Prototype: +<programlisting> +struct t_config_section *weechat_config_new_section ( + struct t_config_file *config_file, + const char *name, + int user_can_add_options, + int user_can_delete_options, + int (*callback_read)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, + const char *value), + void *callback_read_data, + int (*callback_write)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name), + void *callback_write_data, + int (*callback_write_default)(void *data, + struct t_config_file *config_file, + const char *section_name); + void *callback_write_default_data, + int (*callback_create_option)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, + const char *value), + void *callback_create_option_data, + int (*callback_delete_option)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + struct t_config_option *option), + void *callback_delete_option_data); +</programlisting> + </para> + <para> + Create a new section in configuration file. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>config_file</option>: configuration file pointer + </para> + </listitem> + <listitem> + <para> + <option>name</option>: name of section + </para> + </listitem> + <listitem> + <para> + <option>user_can_add_options</option>: 1 if user can add options + in section, or 0 if it is forbidden + </para> + </listitem> + <listitem> + <para> + <option>user_can_delete_options</option>: 1 if user can delete + options in section, or 0 if it is forbidden + </para> + </listitem> + <listitem> + <para> + <option>callback_read</option>: callback called when an option + in section is read from disk (should be NULL for most cases, + except if options in your section need custom function), + arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>struct t_config_section *</entry> + <entry>section</entry> + <entry>section pointer</entry> + </row> + <row> + <entry>const char *</entry> + <entry>option_name</entry> + <entry>name of option</entry> + </row> + <row> + <entry>const char *</entry> + <entry>value</entry> + <entry>value</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_read_data</option>: pointer given to read + callback when it is called by WeeChat + NULL) + </para> + </listitem> + <listitem> + <para> + <option>callback_write</option>: callback called when section + is written in file (should be NULL for most cases, except if your + section needs to be written by a custom function), arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>struct t_config_section *</entry> + <entry>section</entry> + <entry>section pointer</entry> + </row> + <row> + <entry>const char *</entry> + <entry>option_name</entry> + <entry>name of option</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_write_data</option>: pointer given to write + callback when it is called by WeeChat + NULL) + </para> + </listitem> + <listitem> + <para> + <option>callback_write_default</option>: callback called when + default values for section must be written in file, arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>struct t_config_section *</entry> + <entry>section</entry> + <entry>section pointer</entry> + </row> + <row> + <entry>const char *</entry> + <entry>option_name</entry> + <entry>name of option</entry> + </row> + <row> + <entry>const char *</entry> + <entry>value</entry> + <entry>value</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_create_option_data</option>: pointer given to + create_option callback when it is called by WeeChat + NULL) + </para> + </listitem> + <listitem> + <para> + <option>callback_delete_option</option>: callback called when an + option is deleted (NULL if section does not allow options to be + deleted), arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>struct t_config_section *</entry> + <entry>section</entry> + <entry>section pointer</entry> + </row> + <row> + <entry>struct t_config_option *option</entry> + <entry>option</entry> + <entry>option pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_delete_option_data</option>: pointer given to + delete_option callback when it is called by WeeChat + NULL) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to new section in configuration file, NULL if an + error occured. + </para> + <para> + Example: +<screen> +int +my_section_read_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, const char *option_name, + const char *value) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +my_section_write_cb (void *data, struct t_config_file *config_file, + const char *section_name) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +my_section_write_default_cb (void *data, struct t_config_file *config_file, + const char *section_name) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +my_section_create_option_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, const char *value) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +my_section_delete_option_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, + struct t_config_option *option) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +/* standard section, user can not add/delete options */ +struct t_config_section *new_section1 = + weechat_config_new ("section1", 0, 0, + NULL, NULL, /* read callback */ + NULL, NULL, /* write callback */ + NULL, NULL, /* write default callback */ + NULL, NULL, /* create option callback */ + NULL, NULL); /* delete option callback */ + +/* special section, user can add/delete options, and options need + callback to be read/written */ +struct t_config_section *new_section2 = + weechat_config_new ("section2", 1, 1, + &my_section_read_cb, NULL, + &my_section_write_cb, NULL, + &my_section_write_default_cb, NULL, + &my_section_create_option_cb, NULL, + &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_option *</entry> + <entry>option</entry> + <entry>option pointer</entry> + </row> + <row> + <entry>const char *</entry> + <entry>value</entry> + <entry>new value for option</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_check_value_data</option>: pointer given to + check_value callback when it is called by WeeChat + NULL) + </para> + </listitem> + <listitem> + <para> + <option>callback_change</option>: callback called when value of + option has changed (optional), arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_option *</entry> + <entry>option</entry> + <entry>option pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_change_data</option>: pointer given to change + callback when it is called by WeeChat + NULL) + </para> + </listitem> + <listitem> + <para> + <option>callback_delete</option>: callback called when option + will be deleted (optional), arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_option *</entry> + <entry>option</entry> + <entry>option pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_delete_data</option>: pointer given to delete + callback when it is called by WeeChat + NULL) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to new option in section, NULL if an error + occured. + </para> + <para> + Example: +<screen> +/* boolean */ +struct t_config_option *option1 = + weechat_config_new_option (config_file, section, + "option1", "My option, type boolean" + NULL, /* string values */ + 0, 0, /* min, max */ + "on", /* default */ + "on", /* value */ + 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", + &ptr_config_file, + &ptr_section, + &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="2"> + <thead> + <row> + <entry>Property</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>config_file</entry> + <entry>struct t_config_file *</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>section</entry> + <entry>struct t_config_section *</entry> + <entry>section pointer</entry> + </row> + <row> + <entry>name</entry> + <entry>char *</entry> + <entry>option name</entry> + </row> + <row> + <entry>type</entry> + <entry>int</entry> + <entry>option type</entry> + </row> + <row> + <entry>description</entry> + <entry>char *</entry> + <entry>option description</entry> + </row> + <row> + <entry>string_values</entry> + <entry>char **</entry> + <entry>string values</entry> + </row> + <row> + <entry>min</entry> + <entry>int</entry> + <entry>minimum value</entry> + </row> + <row> + <entry>max</entry> + <entry>int</entry> + <entry>maximum value</entry> + </row> + <row> + <entry>default_value</entry> + <entry>(depends on type)</entry> + <entry>default value</entry> + </row> + <row> + <entry>value</entry> + <entry>(depends on type)</entry> + <entry>current value</entry> + </row> + <row> + <entry>prev_option</entry> + <entry>struct t_config_option *</entry> + <entry>previous option pointer</entry> + </row> + <row> + <entry>next_option</entry> + <entry>struct t_config_option *</entry> + <entry>next option pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + </itemizedlist> + </para> + <para> + 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> - <section id="secAPI_free_exploded_string"> - <title>free_exploded_string</title> + <!-- ============================[ display ]============================= --> + + <section id="secPluginCApi_display"> + <title>Display</title> <para> - Prototyp: - <command> - char **free_exploded_string (t_weechat_plugin *plugin, - char **string) - </command> + 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="2"> + <thead> + <row> + <entry>Prefix</entry> + <entry>Default value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>error</entry> + <entry>=!=</entry> + <entry>error message</entry> + </row> + <row> + <entry>network</entry> + <entry>--</entry> + <entry>message from network</entry> + </row> + <row> + <entry>action</entry> + <entry>*</entry> + <entry>self action</entry> + </row> + <row> + <entry>join</entry> + <entry>--></entry> + <entry>someone joins current chat</entry> + </row> + <row> + <entry>quit</entry> + <entry><--</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: may 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> - Gib ein Array frei, dass infolge der Zerlegung eines Strings - reserviert wurde. + Functions to hook/unhook something. </para> + + <section id="secPluginCApi_weechat_hook_command"> + <title>weechat_hook_command</title> + + <para> + Prototype: +<programlisting> +struct t_hook *weechat_hook_command ( + const char *command, + const char *description, + const char *args, + const char *args_description, + const char *completion, + int (*callback)(void *data, + struct t_gui_buffer *buffer, + int argc, char **argv, + char **argv_eol), + void *callback_data); +</programlisting> + </para> + <para> + Hook a command. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>command</option>: new command name + </para> + </listitem> + <listitem> + <para> + <option>description</option>: description of command (displayed + with <command>/help command</command>) + </para> + </listitem> + <listitem> + <para> + <option>args</option>: arguments for command (displayed with + <command>/help command</command>) + </para> + </listitem> + <listitem> + <para> + <option>args_description</option>: description of arguments + (displayed with <command>/help command</command>) + </para> + </listitem> + <listitem> + <para> + <option>completion</option>: completion template for command: + list of completions for each arguments, separated by space. Many + completions are possible for one argument, separated by "|". + Default completion codes are: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Code</entry> + <entry>Completion</entry> + </row> + </thead> + <tbody> + <row> + <entry>%-</entry> + <entry>Stop completion</entry> + </row> + <row> + <entry>%*</entry> + <entry>Repeat last completion</entry> + </row> + <row> + <entry>%b</entry> + <entry>Buffers names</entry> + </row> + <row> + <entry>%B</entry> + <entry>Buffers names (with plugin name)</entry> + </row> + <row> + <entry>%c</entry> + <entry>Configuration files</entry> + </row> + <row> + <entry>%f</entry> + <entry>Filename</entry> + </row> + <row> + <entry>%F</entry> + <entry>Filters</entry> + </row> + <row> + <entry>%h</entry> + <entry>Commands hooked</entry> + </row> + <row> + <entry>%i</entry> + <entry>Infos hooked</entry> + </row> + <row> + <entry>%I</entry> + <entry>Infolists hooked</entry> + </row> + <row> + <entry>%n</entry> + <entry>Nick</entry> + </row> + <row> + <entry>%o</entry> + <entry>Configuration option</entry> + </row> + <row> + <entry>%p</entry> + <entry>Plugin name</entry> + </row> + <row> + <entry>%P</entry> + <entry>Plugin commands</entry> + </row> + <row> + <entry>%r</entry> + <entry>Bar names</entry> + </row> + <row> + <entry>%v</entry> + <entry>Value of configuration option</entry> + </row> + <row> + <entry>%w</entry> + <entry>WeeChat commands</entry> + </row> + <row> + <entry>%(xxx)</entry> + <entry>Custom completion by plugin (xxx is a completion + code added by a plugin)</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback</option>: function called when command is used, + arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_gui_buffer *</entry> + <entry>buffer</entry> + <entry>buffer where command is executed</entry> + </row> + <row> + <entry>int</entry> + <entry>argc</entry> + <entry>argument count</entry> + </row> + <row> + <entry>char **</entry> + <entry>argv</entry> + <entry>arguments</entry> + </row> + <row> + <entry>char **</entry> + <entry>argv_eol</entry> + <entry>arguments (until end of line)</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + <para> + For example, if command called is + <command>/command abc def ghi</command>, then argv and argv_eol + contain following values: + <itemizedlist> + <listitem><para>argv[0] == "abc"</para></listitem> + <listitem><para>argv[1] == "def"</para></listitem> + <listitem><para>argv[2] == "ghi"</para></listitem> + <listitem><para>argv_eol[0] == "abc def ghi"</para></listitem> + <listitem><para>argv_eol[1] == "def ghi"</para></listitem> + <listitem><para>argv_eol[2] == "ghi"</para></listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <option>callback_data</option>: pointer given to callback when it + is called by WeeeChat + </para> + </listitem> + </itemizedlist> + </para> + <para> + 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; +} + +struct t_hook *my_command_hook = + weechat_hook_command ("mycommand", + "description of my command", + "[command [buffer]]", + "command: WeeChat or plugin command\n" + " buffer: buffer name", + "%w|%p %b", &my_command_cb, 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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_gui_buffer *</entry> + <entry>buffer</entry> + <entry>buffer where command is executed</entry> + </row> + <row> + <entry>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*", + &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>int</entry> + <entry>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, &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>int</entry> + <entry>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, &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>const char *</entry> + <entry>command</entry> + <entry>command executed by child</entry> + </row> + <row> + <entry>int</entry> + <entry>return_code</entry> + <entry> + if >= 0, it's child (command) return code (it's last + call to this callback), if < 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 >= 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, &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>int</entry> + <entry>status</entry> + <entry> + constant with connection status: + <itemizedlist> + <listitem> + <para>WEECHAT_HOOK_CONNECT_OK</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_PROXY_ERROR</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_MEMORY_ERROR</para> + </listitem> + </itemizedlist> + </entry> + </row> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_data</option>: pointer given to callback when it + is called by WeeeChat + </para> + </listitem> + </itemizedlist> + </para> + <para> + 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, &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_gui_buffer *</entry> + <entry>buffer</entry> + <entry>buffer pointer</entry> + </row> + <row> + <entry>time_t</entry> + <entry>date</entry> + <entry>date</entry> + </row> + <row> + <entry>int</entry> + <entry>tags_count</entry> + <entry>number of tags for line</entry> + </row> + <row> + <entry>const char **</entry> + <entry>tags</entry> + <entry>tags for line</entry> + </row> + <row> + <entry>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, &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 + </para> + </listitem> + <listitem> + <para> + <option>callback</option>: function called when signal is + received, arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", + &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", + &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", + &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 (you should look at + core and plugins doc to find name of existing modifiers) + </para> + </listitem> + <listitem> + <para> + <option>callback</option>: function called when modifier is + received, arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", + &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", + &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", + &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> - Argumente: - <itemizedlist> - <listitem> - <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur - </para> - </listitem> - <listitem> - <para> - <option>string</option>: ein Array von Strings - </para> - </listitem> - </itemizedlist> + 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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_gui_buffer *</entry> + <entry>buffer</entry> + <entry>buffer pointer</entry> + </row> + <row> + <entry>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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_gui_buffer *</entry> + <entry>buffer</entry> + <entry>buffer pointer</entry> + </row> + </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", + &my_input_cb, NULL, &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", + &my_input_cb, NULL, &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="2"> + <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="2"> + <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", &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> - Rückgabewert: keiner (?). + Functions to query windows. </para> - <para> - Beispiel: + + <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> -char *argv; -int argc; -argv = plugin->explode_string (plugin, string, " ", 0, &argc); -... -if (argv != NULL) - plugin->free_exploded_string (plugin, argv); +struct t_gui_window *current_window = weechat_current_window (); </screen> - </para> + </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> - <section id="secAPI_mkdir_home"> - <title>mkdir_home</title> + <!-- ============================[ nicklist ]============================ --> + + <section id="secPluginCApi_nicklist"> + <title>Nicklist</title> <para> - Prototyp: - <command> - int mkdir_home (t_weechat_plugin *plugin, char *directory) - </command> + 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> - Erzeugt ein Verzeichnis im WeeChat-Verzeichnis. + 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", + &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 (&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> - Argumente: - <itemizedlist> - <listitem> - <para> - <option>plugin</option>: Zeiger auf Pluginstrukur - </para> - </listitem> - <listitem> - <para> - <option>directory</option>: Verzeichnis, das erzeugt werden - soll - </para> - </listitem> - </itemizedlist> + 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> - Rückgabewert: 1 wenn das Verzeichnis erfolgreich erstellt wurde, 0 - wenn ein Fehler aufgetreten ist. + Network functions. </para> - <para> - Beispiel: + + <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 (!plugin->mkdir_home (plugin, "temp")) - plugin->print_server(plugin, "Konnte 'temp'-Verzeichnis im WeeChat-Verzeichnis nicht erstellen."); +if (weechat_network_pass_proxy ("myproxy", sock, "irc.freenode.net", 6667)) +{ + /* OK */ +} +else +{ + /* error */ +} </screen> - </para> + </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 (&addr, 0, sizeof (struct sockaddr_in)); +length = sizeof (addr); +getsockname (sock, (struct sockaddr *) &addr, &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> - <section id="secAPI_exec_on_files"> - <title>exec_on_files</title> + <!-- =============================[ infos ]============================== --> + + <section id="secPluginCApi_infos"> + <title>Infos</title> <para> - Prototyp: - <command> - void exec_on_files (t_weechat_plugin *plugin, char *repertoire, - int (*callback)(t_weechat_plugin *, char *)) - </command> + 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 other plugin. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>info_name</option>: info name to read, from WeeChat + core or other plugin (see plugin doc for infos returned by + each plugin). WeeChat core infos are: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Info</entry> + <entry>Description</entry> + <entry>Example</entry> + </row> + </thead> + <tbody> + <row> + <entry>version</entry> + <entry>WeeChat version</entry> + <entry>0.2.7</entry> + </row> + <row> + <entry>date</entry> + <entry>WeeChat compilation date</entry> + <entry>Dec 25 2008</entry> + </row> + <row> + <entry>dir_separator</entry> + <entry> + directory separator: "/" under GNU/Linux, "\" under + MS-Windows + </entry> + <entry>/</entry> + </row> + <row> + <entry>weechat_dir</entry> + <entry>WeeChat home directory</entry> + <entry>/home/login/.weechat</entry> + </row> + <row> + <entry>weechat_libdir</entry> + <entry>WeeChat lib directory</entry> + <entry>/usr/lib/weechat</entry> + </row> + <row> + <entry>weechat_sharedir</entry> + <entry>WeeChat share directory</entry> + <entry>/usr/share/weechat</entry> + </row> + <row> + <entry>weechat_localedir</entry> + <entry>WeeChat locale directory</entry> + <entry>/usr/share/locale</entry> + </row> + <row> + <entry>charset_terminal</entry> + <entry>terminal charset</entry> + <entry>UTF-8</entry> + </row> + <row> + <entry>charset_internal</entry> + <entry>internal WeeChat charset (always "UTF-8")</entry> + <entry>UTF-8</entry> + </row> + <row> + <entry>inactivity</entry> + <entry>keyboard inactivity (in seconds)</entry> + <entry>12</entry> + </row> + <row> + <entry>filters_enabled</entry> + <entry>1 if filters are enabled, otherwise 0</entry> + <entry>1</entry> + </row> + </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> - Führe eine Funktion auf allen Dateien eines Verzeichnisses aus. + Functions for infolists. </para> + <para> - Argumente: - <itemizedlist> - <listitem> - <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur - </para> - </listitem> - <listitem> - <para> - <option>directory</option>: Verzeichnis der zu verwendenden - Dateien - </para> - </listitem> - <listitem> - <para> - <option>callback</option>: die anzuwendende Funktion - </para> - </listitem> - </itemizedlist> + Missing doc! </para> + + </section> + + <!-- ============================[ upgrade ]============================= --> + + <section id="secPluginCApi_upgrade"> + <title>Upgrade</title> + <para> - Rückgabewert: keiner. + Functions for WeeChat upgrading. </para> + <para> - Beispiel: -<screen> -int callback (t_weechat_plugin *plugin, char *file) -{ - plugin->print_server (plugin, "file: %s", file); - return 1; -} -... -plugin->exec_on_files (plugin, "/tmp", &callback); -</screen> + Missing doc! </para> + </section> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + + + <!-- + To be continued... + + + <section id="secAPI_print"> <title>print</title> <para> - Prototyp: + Prototype: <command> void print (t_weechat_plugin *plugin, char *server, char *channel, char *message, ...) </command> </para> <para> - Sende eine Nachricht an einen WeeChat-Puffer, bezeichnet durch - server und channel (beide können NULL sein, dann wird der aktuelle - Puffer verwendet). + Display a message on a WeeChat buffer, identified by server and + channel (both may be NULL for current buffer). </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>server</option>: interner Name des Servers, zu - welchem der Puffer gehört, in dem die Nachricht angezeigt - werden soll (kann NULL sein) + <option>server</option>: internal name of server to find + buffer for message display (may be NULL) </para> </listitem> <listitem> <para> - <option>channel</option>: Name des Channels, in dem die - Nachricht angezeigt werden soll (kann NULL sein) + <option>channel</option>: name of channel to find buffer + for message display (may be NULL) </para> </listitem> <listitem> <para> - <option>message</option>: Nachricht + <option>message</option>: message </para> </listitem> </itemizedlist> </para> - <!-- TRANSLATION NEEDED --> <para> To display colored text, there are following codes: <informaltable colsep="0" frame="none"> @@ -556,16 +9245,16 @@ plugin->exec_on_files (plugin, "/tmp", &callback); the attribute. </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiele: + Examples: <screen> plugin->print (plugin, NULL, NULL, "hello"); plugin->print (plugin, NULL, "#weechat", "hello"); plugin->print (plugin, "freenode", "#weechat", "hello"); plugin->print (plugin, NULL, NULL, - "Test: \x02 Fett \x0F\x03%02d Blau \x03%02d Grün", + "test: \x02 bold \x0F\x03%02d blue \x03%02d green", plugin->get_irc_color (plugin, "blue"), plugin->get_irc_color (plugin, "green")); </screen> @@ -576,39 +9265,38 @@ plugin->print (plugin, NULL, NULL, <title>print_server</title> <para> - Prototyp: + Prototype: <command> void print_server (t_weechat_plugin *plugin, char *message, ...) </command> </para> <para> - Zeige eine Nachricht im aktuellen Server-Puffer. + Display a message on current server buffer. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>message</option>: Nachricht + <option>message</option>: message </para> </listitem> </itemizedlist> </para> <para> - <!-- TRANSLATION NEEDED --> To display colored text, see <xref linkend="secAPI_print" />. </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiel: <screen>plugin->print_server (plugin, "hello");</screen> + Example: <screen>plugin->print_server (plugin, "hello");</screen> </para> </section> @@ -616,48 +9304,47 @@ plugin->print (plugin, NULL, NULL, <title>log</title> <para> - Prototyp: + Prototype: <command> void log (t_weechat_plugin *plugin, char *server, char *channel, char *message, ...) </command> </para> <para> - Schreibe eine Nachricht in die Log-Datei (für den entsprechenden - Server/Channel). + Write a message in log file for a server or a channel. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>server</option>: interner Name des Servers, zu - welchem der Log-Puffer gehört (kann NULL sein) + <option>server</option>: internal name of server to find + buffer for log (may be NULL) </para> </listitem> <listitem> <para> - <option>channel</option>: Name des Channels, zu welchem der - Log-Puffer gehört (kann NULL sein) + <option>channel</option>: name of channel to find buffer + for log (may be NULL) </para> </listitem> <listitem> <para> - <option>message</option>: Nachricht + <option>message</option>: message </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiel: + Example: <screen> plugin->log (plugin, "freenode", "#weechat", "test"); </screen> @@ -668,7 +9355,7 @@ plugin->log (plugin, "freenode", "#weechat", "test"); <title>msg_handler_add</title> <para> - Prototyp: + Prototype: <command> t_plugin_handler *msg_handler_add (t_weechat_plugin *plugin, char *message, t_plugin_handler_func *function, @@ -676,59 +9363,57 @@ plugin->log (plugin, "freenode", "#weechat", "test"); </command> </para> <para> - Erzeuge einen IRC-Message-Handler, der aufgerufen wird, wenn - eine Nachricht empfangen wird. + Add an IRC message handler, called when an IRC message is + received. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>message</option>: Name (Typ) der IRC-Nachricht ("*" - für alle Nachrichten). - Eine Liste der bekannten IRC-Nachrichten ist in den + <option>message</option>: name of IRC message ("*" for all + messages). + To know list of IRC messages, please consult <acronym>RFC</acronym>s <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink> - und - <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink> - zu finden. - Weiterhin können sie einen speziellen Namen verwenden, der - mit "weechat_" beginnt, um spezielle Ereignisse zu - bearbeiten, wie in der folgenden Tabelle aufgeführt: + and + <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink>. + Moreover you can use a special name, prefixed by "weechat_" + to catch special events, as written in table below: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> <entry>Name</entry> - <entry>Beschreibung</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>weechat_pv</literal></entry> - <entry>private Nachricht empfangen</entry> + <entry>private message received</entry> </row> <row> <entry><literal>weechat_highlight</literal></entry> <entry> - hervorgehobene Nachricht (in einem Channel oder privatem Chat) + message with highlight (on a channel or pv) </entry> </row> <row> <entry><literal>weechat_ctcp</literal></entry> <entry> - CTCP-Nachricht empfangen (VERSION, PING, ...) + CTCP message received (VERSION, PING, ..) </entry> </row> <row> <entry><literal>weechat_dcc</literal></entry> <entry> - DCC-Nachricht empfangen (Chat oder Datei) + DCC message received (chat or file) </entry> </row> </tbody> @@ -738,11 +9423,11 @@ plugin->log (plugin, "freenode", "#weechat", "test"); </listitem> <listitem> <para> - <option>function</option>: Funktion, die aufgerufen wird, - wenn eine Nachricht empfangen wurde + <option>function</option>: function called when message + is received </para> <para> - Sie verwendet den folgenden Prototyp: + It uses following prototype: <command> int my_function (t_weechat_plugin *plugin, int argc, char **argv, @@ -750,84 +9435,82 @@ plugin->log (plugin, "freenode", "#weechat", "test"); </command> </para> <para> - Argument argc ist auf 3 gesetzt, die folgenden Werte sind - im argv-Array: + Argument argc is set to 3, following values are set in + argv array: <itemizedlist> <listitem> - <para>argv[0] = Server Name</para> + <para>argv[0] = server name</para> </listitem> <listitem> - <para>argv[1] = IRC Nachricht</para> + <para>argv[1] = IRC message</para> </listitem> <listitem> - <para>argv[2] = Kommando Argumente</para> + <para>argv[2] = command arguments</para> </listitem> </itemizedlist> </para> </listitem> <listitem> <para> - <option>handler_args</option>: Argumente, die beim Aufruf - an die Funktion übergeben werden + <option>handler_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> <option>handler_pointer</option>: pointer given to function when called - <option>handler_pointer</option>: Zeiger, der an die Funktion - übergeben wird </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: Zeiger auf den neuen Handler + Return value: pointer to new message handler. </para> <para> - Hinweis: die Funktion, die aufgerufen wird wenn eine Nachricht - empfangen wurde, muss einen der folgenden Werte zurückgeben: + Note: function called when message is received has to return + one of following values: <itemizedlist> <listitem> <para> - <literal>PLUGIN_RC_KO</literal>: Funktion ist fehlgschlagen + <literal>PLUGIN_RC_KO</literal>: function failed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK</literal>: Funktion war erfolgreich + <literal>PLUGIN_RC_OK</literal>: function successfully + completed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK_IGNORE_WEECHAT</literal>: Die Nachricht - wird nicht an WeeChat übergeben + <literal>PLUGIN_RC_OK_IGNORE_WEECHAT</literal>: message + will not be sent to WeeChat </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK_IGNORE_PLUGINS</literal>: Die Nachricht - wird nicht an andere Plugins weitergegeben + <literal>PLUGIN_RC_OK_IGNORE_PLUGINS</literal>: message + will not be sent to other plugins </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK_IGNORE_ALL</literal>: Die Nachricht - wird weder an WeeChat noch an andere - Plugins weitergegeben + <literal>PLUGIN_RC_OK_IGNORE_ALL</literal>: message + will not be sent to WeeChat neither other plugins </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK_WITH_HIGHLIGHT</literal>: Funktion - erfolgreich vervollständigt und eine Hervorhebung bei den - empfangenen Nachrichten eingebaut + <literal>PLUGIN_RC_OK_WITH_HIGHLIGHT</literal>: function + successfully completed and make "highlight" on received + message </para> </listitem> </itemizedlist> </para> <para> - Beispiel: + Example: <screen> int msg_kick (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) @@ -847,7 +9530,7 @@ msg_handler = plugin->msg_handler_add (plugin, "KICK", <title>cmd_handler_add</title> <para> - Prototyp: + Prototype: <command> t_plugin_handler *cmd_handler_add (t_weechat_plugin *plugin, char *command, char *description, char *arguments, @@ -857,75 +9540,70 @@ msg_handler = plugin->msg_handler_add (plugin, "KICK", </command> </para> <para> - Erzeugt einen Handler für ein WeeChat-Kommando, der aufgerufen - wird, wenn der Anwender das Kommando ausführt (Beispiel: /command). + Add a WeeChat command handler, called when user uses command + (for example /command). </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>command</option>: Name des neuen Kommandos, der auch - Name eines bereits existierenden Kommandos sein kann (mit - Bedacht zu verwenden, das ersetzte Kommando ist nicht - verfügbar, bis das Plugin entfernt wurde) + <option>command</option>: the new command name, which + may be an existing command (be careful, replaced command + will not be available until plugin is unloaded) </para> </listitem> <listitem> <para> - <option>description</option>: kurze Beschreibung des - Kommandos (angezeigt beim Ausführen von /help command) + <option>description</option>: short command description + (displayed by /help command) </para> </listitem> <listitem> <para> - <option>arguments</option>: kurze Beschreibung der Argumente - des Kommandos (angezeigt beim Ausführen von /help command) + <option>arguments</option>: short description of command + arguments (displayed by /help command) </para> </listitem> <listitem> <para> - <option>arguments_description</option>: lange Beschreibung - der Argumente des Kommandos (angezeigt beim Ausführen von - /help command) + <option>arguments_description</option>: long description + of command arguments (displayed by /help command) </para> </listitem> <listitem> <para> - <option>completion_template</option>: Vorlage für die - Vervollständigung; zum Beispiel bedeutet - "<literal>abc|%w def|%i</literal>", dass das erste Argument - "abc" oder ein WeeChat-Kommando sein kann und das zweite - Argument "def" oder ein IRC-Kommando. Eine leere - Zeichenkette bedeutet, dass WeeChat für jedes Argument - einen Nicknamen des gegenwärtigen Channels einsetzt, ein - NULL oder "-" schaltet die Vervollständigung für alle - Argumente ab. + <option>completion_template</option>: template for + completion, like "<literal>abc|%w def|%i</literal>" + which means "abc" or a WeeChat command for first argument, + "def" or IRC command for second. + An empty string lets WeeChat complete any argument with + a nick from current channel, NULL or "-" disable completion + for all command arguments. </para> <para> - Die folgenden Ersetzungen können verwendet werden: + Following codes can be used: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> <entry>Code</entry> - <entry>Beschreibung</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>%-</literal></entry> - <entry>keine Vervollständigung für das Argument</entry> + <entry>no completion for argument</entry> </row> <row> <entry><literal>%*</literal></entry> <entry> - <!-- TRANSLATION NEEDED --> repeat last completion for all following arguments (this code has to be at the end of completion template, preceded by "|") @@ -933,103 +9611,99 @@ msg_handler = plugin->msg_handler_add (plugin, "KICK", </row> <row> <entry><literal>%a</literal></entry> - <entry>Alias</entry> + <entry>alias</entry> </row> <row> <entry><literal>%A</literal></entry> <entry> - Aliase und Kommandos (WeeChat, IRC und Plugins) + alias and commands (WeeChat, IRC and plugins) </entry> </row> <row> <entry><literal>%c</literal></entry> - <entry>gegenwärtiger Channel</entry> + <entry>current channel</entry> </row> <row> <entry><literal>%C</literal></entry> - <entry>alle channels (inklusive Queries)</entry> + <entry>all channels (including queries)</entry> </row> <row> <entry><literal>%f</literal></entry> - <entry>Dateiname</entry> + <entry>file name</entry> </row> <row> <entry><literal>%h</literal></entry> - <entry>Plugin Kommandos</entry> + <entry>plugins commands</entry> </row> <row> <entry><literal>%i</literal></entry> - <entry>IRC Kommandos (senden)</entry> + <entry>IRC commands (sent)</entry> </row> <row> <entry><literal>%I</literal></entry> - <entry>IRC Kommandos (empfangen)</entry> + <entry>IRC commands (received)</entry> </row> <row> <entry><literal>%k</literal></entry> - <entry>Grundfunktionen</entry> + <entry>key functions</entry> </row> <row> <entry><literal>%m</literal></entry> - <entry>Nicknamen des gegenwärtigen Servers</entry> + <entry>nick on current server</entry> </row> <row> <entry><literal>%M</literal></entry> <entry> - Nicks auf dem gegenwärtigen Server (in allen - offenen Channeln) + nicks on current server (on all open channels) </entry> </row> <row> <entry><literal>%n</literal></entry> - <entry>Nicknamen des gegenwärtigen Channels</entry> + <entry>nicks of current channel</entry> </row> <row> <entry><literal>%N</literal></entry> - <entry> - Nicknamen und Hostnamen des gegenwärtigen - Channels - </entry> + <entry>nicks and hostnames of current channel</entry> </row> <row> <entry><literal>%o</literal></entry> - <entry>Konfigurationseinstellungen</entry> + <entry>setup options</entry> </row> <row> <entry><literal>%O</literal></entry> - <entry>Plugin Optionen</entry> + <entry>plugin options</entry> </row> <row> <entry><literal>%p</literal></entry> - <entry>Standard "part" Nachricht</entry> + <entry>default "part" message</entry> </row> <row> <entry><literal>%q</literal></entry> - <entry>Standard "quit" Nachricht</entry> + <entry>default "quit" message</entry> </row> <row> <entry><literal>%s</literal></entry> - <entry>Name des gegenwärtigen Servers</entry> + <entry>current server name</entry> </row> <row> <entry><literal>%S</literal></entry> - <entry>Namen aller definierten Server</entry> + <entry>all servers names</entry> </row> <row> <entry><literal>%t</literal></entry> - <entry>Topic des gegenwärtigen Channels</entry> + <entry>topic of current channel</entry> </row> <row> <entry><literal>%v</literal></entry> - <entry>Wert einer Konfigurationseinstellung</entry> + <entry>setup option value</entry> </row> <row> <entry><literal>%V</literal></entry> - <entry>Wert einer Plugin-Option</entry> + <entry>plugin option value</entry> </row> <row> <entry><literal>%w</literal></entry> - <entry>WeeChat Kommandos</entry> + <entry>WeeChat commands</entry> </row> </tbody> </tgroup> @@ -1038,11 +9712,11 @@ msg_handler = plugin->msg_handler_add (plugin, "KICK", </listitem> <listitem> <para> - <option>function</option>: Funktion, die aufgerufen wird, - wenn das Kommando ausgeführt wird + <option>function</option>: function called when command + is executed </para> <para> - Sie verwendet den folgenden Prototypen: + It uses following prototype: <command> int my_function (t_weechat_plugin *plugin, int argc, char **argv, @@ -1050,56 +9724,57 @@ msg_handler = plugin->msg_handler_add (plugin, "KICK", </command> </para> <para> - Das Argument argc ist auf 3 gesetzt, das Array argv enthält - die folgenden Werte: + Argument argc is set to 3, following values are set in + argc array: <itemizedlist> <listitem> - <para>argv[0] = Server Name</para> + <para>argv[0] = server name</para> </listitem> <listitem> - <para>argv[1] = Kommando</para> + <para>argv[1] = command</para> </listitem> <listitem> - <para>argv[2] = Kommando-Argumente</para> + <para>argv[2] = command arguments</para> </listitem> </itemizedlist> - </para> + </para> </listitem> <listitem> <para> - <option>handler_args</option>: Argumente, die an die Funktion - übergeben werden + <option>handler_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>handler_pointer</option>: Zeiger, der an die Funktion - übergeben wird + <option>handler_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: Zeiger auf den neuen Kommando-Handler. + Return value: pointer to new command handler. </para> <para> - Hinweis: die Funktion, die aufgerufen wird, wenn das Kommando - ausgeführt wird, muss einen der folgende Werte zurückgeben: + Note: function called when command is executed has to return + one of following values: <itemizedlist> <listitem> <para> - <literal>PLUGIN_RC_KO</literal>: Funktion ist fehlgeschlagen + <literal>PLUGIN_RC_KO</literal>: function failed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK</literal>: Funktion war erfolgreich + <literal>PLUGIN_RC_OK</literal>: function successfully + completed </para> </listitem> </itemizedlist> </para> <para> - Beispiel: + Example: <screen> int cmd_test (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) @@ -1122,7 +9797,7 @@ cmd_handler = plugin->cmd_handler_add (plugin, "test", "Test command", <title>timer_handler_add</title> <para> - Prototyp: + Prototype: <command> t_plugin_handler *timer_handler_add (t_weechat_plugin *plugin, int interval, t_plugin_handler_func *function, @@ -1130,29 +9805,28 @@ cmd_handler = plugin->cmd_handler_add (plugin, "test", "Test command", </command> </para> <para> - Erzeuge einen zeitgesteuerten Handler, der periodisch - eine Funktion aufruft. + Add a timer handler which periodically calls a function. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>interval</option>: Intervall (in Secunden) zwischen - zwei Aufrufen der Funktion + <option>interval</option>: interval (in seconds) between + two calls of function. </para> </listitem> <listitem> <para> - <option>function</option>: Funktion, die aufgerufen wird + <option>function</option>: function called </para> <para> - Sie verwendet den folgenden Prototypen: + It uses following prototype: <command> int my_function (t_weechat_plugin *plugin, int argc, char **argv, @@ -1160,45 +9834,44 @@ cmd_handler = plugin->cmd_handler_add (plugin, "test", "Test command", </command> </para> <para> - Das Argument argc ist auf 0 gesetzt und argv ist auf NULL - gesetzt. + Argument argc is set to 0, and argv is set to NULL. </para> </listitem> <listitem> <para> - <option>handler_args</option>: Argumente der aufgerufenen - Funktion + <option>handler_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>handler_pointer</option>: Zeiger, der an die Funktion - übergeben wird + <option>handler_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: Zeiger auf den neuen timer-Handler. + Return value: pointer to new timer handler. </para> <para> - Hinweis: die Funktion, die aufgerufen wird, muss einen der folgende - Werte zurückgeben: + Note: function called has to return one of following values: <itemizedlist> <listitem> <para> - <literal>PLUGIN_RC_KO</literal>: Funktion ist fehlgeschlagen + <literal>PLUGIN_RC_KO</literal>: function failed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK</literal>: Funktion war erfolgreich + <literal>PLUGIN_RC_OK</literal>: function successfully + completed </para> </listitem> </itemizedlist> </para> <para> - Beispiel: + Example: <screen> int my_timer (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) @@ -1217,7 +9890,7 @@ timer_handler = plugin->timer_handler_add (plugin, 60, &my_timer); <title>keyboard_handler_add</title> <para> - Prototyp: + Prototype: <command> t_plugin_handler *keyboard_handler_add (t_weechat_plugin *plugin, t_plugin_handler_func *function, @@ -1225,23 +9898,22 @@ timer_handler = plugin->timer_handler_add (plugin, 60, &my_timer); </command> </para> <para> - Erzeugt einen Keyboard-Handler, der nach dem Drücken einer Taste - aufgerufen wird. + Add a keyboard handler, called for any key pressed. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>function</option>: Die Funktion, die aufgerufen wird + <option>function</option>: function called </para> <para> - Sie verwendet den folgenden Prototypen: + It uses following prototype: <command> int my_function (t_weechat_plugin *plugin, int argc, char **argv, @@ -1249,24 +9921,23 @@ timer_handler = plugin->timer_handler_add (plugin, 60, &my_timer); </command> </para> <para> - Das Argument argc ist auf 3 gesetzt, argv enthält die - folgenden Werte: + Argument argc is set to 3, following values are set in + argc array: <itemizedlist> <listitem> <para> - argv[0] = Taste, die gedrückt wurde - (Name der internen Funktion oder '*' gefolgt von einem - Tastaturcode) + argv[0] = key pressed (name of internal function or + '*' followed by a key code) </para> </listitem> <listitem> <para> - argv[1] = Kommandozeile vor dem Tastendruck + argv[1] = command line before key action </para> </listitem> <listitem> <para> - argv[2] = Kommandozeile nach dem Tastendruck + argv[2] = command line after key action </para> </listitem> </itemizedlist> @@ -1274,41 +9945,39 @@ timer_handler = plugin->timer_handler_add (plugin, 60, &my_timer); </listitem> <listitem> <para> - <option>handler_args</option>: Argumente, die bei Aufruf der - Funktion übergeben - werden + <option>handler_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>handler_pointer</option>: Zeiger auf die Funktion, - der bei Aufruf übergeben - wird + <option>handler_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: Zeiger auf den Handler. + Return value: pointer to new message handler. </para> <para> - Hinweis: Die aufgerufene Funktion muss einen der folgenden Werte - zurückgeben: + Note: function called has to return one of following values: <itemizedlist> <listitem> <para> - <literal>PLUGIN_RC_KO</literal>: Funktion ist fehlgeschlagen + <literal>PLUGIN_RC_KO</literal>: function failed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK</literal>: Funktion war erfolgreich + <literal>PLUGIN_RC_OK</literal>: function successfully + completed </para> </listitem> </itemizedlist> </para> <para> - Beispiel: + Example: <screen> int my_keyb (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) @@ -1334,7 +10003,7 @@ keyb_handler = plugin->keyboard_handler_add (plugin, &my_keyb); <title>event_handler_add</title> <para> - Prototyp: + Prototype: <command> t_plugin_handler *event_handler_add (t_weechat_plugin *plugin, char *event, t_plugin_handler_func *function, @@ -1342,28 +10011,27 @@ keyb_handler = plugin->keyboard_handler_add (plugin, &my_keyb); </command> </para> <para> - Fügt einen Ereignishandler hinzu, der aufgerufen wird, wenn ein - Ereignis eintritt. + Add an event handler, called when an event happens. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Plugin-Strukture + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>event</option> : Ereignis (siehe folgende Tabelle) + <option>event</option> : event (see table below) </para> </listitem> <listitem> <para> - <option>function</option>: aufgerufene Funktion + <option>function</option>: function called </para> <para> - Es wird folgender Prototyp verwendet: + It uses following prototype: <command> int my_function (t_weechat_plugin *plugin, int argc, char **argv, @@ -1371,47 +10039,45 @@ keyb_handler = plugin->keyboard_handler_add (plugin, &my_keyb); </command> </para> <para> - <!-- TRANSLATION NEEDED --> Arguments depend on event (see table below). </para> </listitem> <listitem> <para> - <option>handler_args</option>: Argument, die an die aufgerufene - Funktion übergeben werden + <option>handler_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>handler_pointer</option>: Pointer, der an die - aufgerufene Funktion übergeben werden + <option>handler_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> - <!-- TRANSLATION NEEDED --> <para> List of events: <informaltable colsep="0" frame="none"> <tgroup cols="3"> <thead> <row> - <entry>Ereignis</entry> - <entry>Beschreibung</entry> + <entry>Event</entry> + <entry>Description</entry> <entry>Arguments</entry> </row> </thead> <tbody> <row> <entry><literal>buffer_open</literal></entry> - <entry>ein Puffer wurde geöffnet</entry> + <entry>a buffer was open</entry> <entry> argc = 1, argv = { buffer number } </entry> </row> <row> <entry><literal>buffer_close</literal></entry> - <entry>ein Puffer wurde geschlossen</entry> + <entry>a buffer was closed</entry> <entry> argc = 1, argv = { buffer number } </entry> @@ -1428,26 +10094,26 @@ keyb_handler = plugin->keyboard_handler_add (plugin, &my_keyb); </informaltable> </para> <para> - Rückgabewert: Pointer auf den neuen Ereignishandler. + Return value: pointer to new event handler. </para> <para> - Anmerkung: die aufgerufene Function muss einen der folgenden Werte - zurückgeben: + Note: function called has to return one of following values: <itemizedlist> <listitem> <para> - <literal>PLUGIN_RC_KO</literal>: Funktion fehlgeschlagen + <literal>PLUGIN_RC_KO</literal>: function failed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK</literal>: Funktion erfolgreich beendet + <literal>PLUGIN_RC_OK</literal>: function successfully + completed </para> </listitem> </itemizedlist> </para> <para> - Beispiel: + Example: <screen> int my_event (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) @@ -1467,35 +10133,35 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", <title>handler_remove</title> <para> - Prototyp: + Prototype: <command> void handler_remove (t_weechat_plugin *plugin, t_plugin_handler *handler) </command> </para> <para> - Entfernt einen Nachrichten- oder Kommando-Handler. + Remove a command or message handler. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>handler</option>: Handler, der entfernt werden soll + <option>handler</option>: handler to remove </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner + Return value: none. </para> <para> - Beispiel: + Example: <screen>plugin->handler_remove (plugin, my_handler);</screen> </para> </section> @@ -1504,29 +10170,29 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", <title>handler_remove_all</title> <para> - Prototyp: + Prototype: <command> void handler_remove_all (t_weechat_plugin *plugin) </command> </para> <para> - Entfernt alle Handler eines Plugins. + Remove all handlers for a plugin. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner + Return value: none. </para> <para> - Beispiel: + Example: <screen>plugin->handler_remove_all (plugin);</screen> </para> </section> @@ -1535,7 +10201,7 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", <title>modifier_add</title> <para> - Prototyp: + Prototype: <command> t_plugin_modifier *modifier_add (t_weechat_plugin *plugin, char *type, char *message, t_plugin_modifier_func *function, @@ -1543,46 +10209,45 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", </command> </para> <para> - Füge einen Nachrichtenmodifikator hinzu. + Add a message modifier. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>type</option>: Modifikatorart: + <option>type</option>: modifier type: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Art</entry> - <entry>Beschreibung</entry> + <entry>Type</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>irc_in</literal></entry> - <entry>wird bei eingehenden IRC-Nachrichten aufgerufen</entry> + <entry>called for incoming IRC messages</entry> </row> <row> <entry><literal>irc_user</literal></entry> <entry> - wird bei jeder Benutzernachricht (oder Befehl) - aufgerufen (bevor WeeChat die Nachricht parst) + called for each user message (or command) (before + WeeChat parses message) </entry> </row> <row> <entry><literal>irc_out</literal></entry> <entry> - wird unmittelbar vor dem Abschicken einer ausgehenden - Nachricht an den IRC-Server aufgerufen (auch bei - Nachrichten, die WeeChat automatisch an den Server - sendet) + called for outgoing messages, immediately before + sending it to IRC server (this includes messages + sent automatically by WeeChat to server) </entry> </row> </tbody> @@ -1592,23 +10257,22 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", </listitem> <listitem> <para> - <option>message</option>: Name der IRC-Nachricht (wird nur - bei den Arten "irc_in" and "irc_out" benutzt) - Um eine Liste der IRC-Nachrichten zu erhalten, lies bitte - folgende Dokumente:<acronym>RFC</acronym>s + <option>message</option>: name of IRC message (used only for + types "irc_in" and "irc_out"). + To know list of IRC messages, please consult + <acronym>RFC</acronym>s <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink> and <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink>. - Außerdem gibt es den Wert "*", der alle Nachrichten - anspricht (ohne Filter). + Moreover, special value "*" means all messages (no filter). </para> </listitem> <listitem> <para> - <option>function</option>: aufgerufene Funktion + <option>function</option>: function called </para> <para> - Folgender Prototyp wird dafür benutzt: + It uses following prototype: <command> int my_function (t_weechat_plugin *plugin, int argc, char **argv, @@ -1616,47 +10280,46 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", </command> </para> <para> - Argument argc hat den Wert 2, folgende Werte sind in dem - argv-Array: + Argument argc is set to 2, following values are set in + argv array: <itemizedlist> <listitem> - <para>argv[0] = Servername</para> + <para>argv[0] = server name</para> </listitem> <listitem> - <para>argv[1] = Nachricht</para> + <para>argv[1] = message</para> </listitem> </itemizedlist> </para> </listitem> <listitem> <para> - <option>modifier_args</option>: an die Funktion übergebene - Werte + <option>modifier_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>modifier_pointer</option>: an die Funktion - übergebener Zeiger + <option>modifier_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: Zeiger auf den neuen Nachrichtenmodifikator + Return value: pointer to new message modifier. </para> <para> - Anmerkung: Die Funktion muss die veränderte Zeichenkette oder NULL - (wenn keine Änderungen erfolgten) zurückgeben. - Wenn die Funktion eine leere Zeichenkette zurückgibt, wird die - Nachricht komplett verworfen und nicht weiter von WeeChat - verarbeitet. (Seien Sie vorsichtig mit dem Verwerfen von - Nachrichten!) Die zurückgegebene Zeichenkette muss mit malloc() - zugewiesen worden sein und wird von WeeChat nach Gebrauch - automatisch mit free() wieder freigegeben. + Note: function has to return modified string, or NULL if no + changes are made to message. + If function returns empty string, then message is dropped and + will not be read at all by WeeChat (be careful when dropping + messages!). + Returned string must have been allocated by malloc() and will + be freed (with call to free()) automatically by WeeChat after use. </para> <para> - Beispiel: + Example: <screen> char *adder (t_weechat_plugin *plugin, int argc, char **argv, char *modifier_args, void *modifier_pointer) @@ -1679,35 +10342,35 @@ modifier = plugin->modifier_add (plugin, "irc_in", "privmsg", <title>modifier_remove</title> <para> - Prototyp: + Prototype: <command> void modifier_remove (t_weechat_plugin *plugin, t_plugin_modifier *modifier) </command> </para> <para> - Entfernt einen Nachrichtenmodifikator. + Remove a message modifier. </para> <para> Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>modifier</option>: zu entfernender Modifikator + <option>modifier</option>: modifier to remove </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner + Return value: none. </para> <para> - Beispiel: + Example: <screen>plugin->modifier_remove (plugin, my_modifier);</screen> </para> </section> @@ -1716,29 +10379,29 @@ modifier = plugin->modifier_add (plugin, "irc_in", "privmsg", <title>modifier_remove_all</title> <para> - Prototyp: + Prototype: <command> void modifier_remove_all (t_weechat_plugin *plugin) </command> </para> <para> - Entfernt alle Modifikatoren für ein Plugin. + Remove all modifiers for a plugin. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner + Return value: none. </para> <para> - Beispiel: + Example: <screen>plugin->modifier_remove_all (plugin);</screen> </para> </section> @@ -1747,48 +10410,47 @@ modifier = plugin->modifier_add (plugin, "irc_in", "privmsg", <title>exec_command</title> <para> - Prototyp: + Prototype: <command> void exec_command (t_weechat_plugin *plugin, char *server, char *channel, char *command) </command> </para> <para> - Führe ein WeeChat-Kommando aus (oder sende eine Nachricht an - einen Channel). + Execute a WeeChat command (or send a message to a channel). </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>server</option>: interner Name des Servers, auf den - das Kommando angewendet werden soll (kann NULL sein) + <option>server</option>: internal name of server for + executing command (may be NULL) </para> </listitem> <listitem> <para> - <option>channel</option>: Name des Channels, auf den das - Kommando angewendet werden soll (kann NULL sein) + <option>channel</option>: name of channel for executing + command (may be NULL) </para> </listitem> <listitem> <para> - <option>command</option>: Kommando + <option>command</option>: command </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner + Return value: none. </para> <para> - Beispiel: + Examples: <screen> plugin->exec_command (plugin, NULL, NULL, "/help nick"); plugin->exec_command (plugin, "freenode", "#weechat", "hello"); @@ -1800,102 +10462,101 @@ plugin->exec_command (plugin, "freenode", "#weechat", "hello"); <title>get_info</title> <para> - Prototyp: + Prototype: <command> char *get_info (t_weechat_plugin *plugin, char *info, char *server) </command> </para> <para> - Gib eine Information über WeeChat oder einen Channel zurück. + Return an info about WeeChat or a channel. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>info</option> : Name (Typ) der Information: + <option>info</option> : name of info to read: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> <entry>Info</entry> - <entry>Beschreibung</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>version</literal></entry> - <entry>WeeChats Version</entry> + <entry>WeeChat's version</entry> </row> <row> <entry><literal>nick</literal></entry> - <entry>Nickname</entry> + <entry>nick</entry> </row> <row> <entry><literal>channel</literal></entry> <entry> - Name des Channels (NULL bei einem Server oder - Privatchat) + name of channel (NULL for a server or private) </entry> </row> <row> <entry><literal>server</literal></entry> - <entry>Name des Servers</entry> + <entry>name of server</entry> </row> <row> <entry><literal>type</literal></entry> <entry> - Puffertyp: 0=standard, 1=DCC, 2=raw IRC data + buffer type: 0=standard, 1=DCC, 2=raw IRC data </entry> </row> <row> <entry><literal>away</literal></entry> - <entry>Status des "away"-Flags</entry> + <entry>"away" flag</entry> </row> <row> <entry><literal>inactivity</literal></entry> <entry> - Anzahl der Sekunden seit der letzten - Tastenbetätigung + number of seconds since last key was pressed </entry> </row> <row> <entry><literal>input</literal></entry> <entry> - Inhalt der Kommandozeile im gegenwärtigen Fenster + content of command line for current window </entry> </row> <row> <entry><literal>input_mask</literal></entry> <entry> - Inhalt der Farbmaske für die Kommandozeile + content of color mask for command line </entry> </row> <row> <entry><literal>input_pos</literal></entry> <entry> - Position des Cursors in der Kommandozeile + cursor position in command line </entry> </row> <row> <entry><literal>weechat_dir</literal></entry> <entry> - WeeChat-Verzeichnis (Standard: ~/.weechat/) + WeeChat home directory + (by default: ~/.weechat/) </entry> </row> <row> <entry><literal>weechat_libdir</literal></entry> - <entry>WeeChat-Systemverzeichnis (Bibliotheken)</entry> + <entry>WeeChat system lib directory</entry> </row> <row> <entry><literal>weechat_sharedir</literal></entry> - <entry>WeeChat-Systemverzeichnis (gemeinsame Dateien)</entry> + <entry>WeeChat system share directory</entry> </row> </tbody> </tgroup> @@ -1904,21 +10565,21 @@ plugin->exec_command (plugin, "freenode", "#weechat", "hello"); </listitem> <listitem> <para> - <option>server</option>: interner Name des Servers um - Informationen zu lesen (wenn benötigt) + <option>server</option>: internal name of server for + reading info (if needed) </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: angeforderte Information oder NULL + Return value: information asked, NULL if not found. </para> <para> - Hinweis: das Ergebnis muss nach Nutzung mit "free" wieder - freigegeben werden. + Note: result has to be free by a call to "free" function after + use. </para> <para> - Beispiele: + Examples: <screen> char *version = plugin->get_info (plugin, "version", NULL); char *nick = plugin->get_info (plugin, "nick", "freenode"); @@ -1930,11 +10591,11 @@ plugin->print (plugin, NULL, NULL, version, nick, inactivity); if (version) - free (version); + free (version); if (nick) - free (nick); + free (nick); if (inactivity) - free (inactivity); + free (inactivity); </screen> </para> </section> @@ -1943,144 +10604,144 @@ if (inactivity) <title>get_dcc_info</title> <para> - Prototyp: + Prototype: <command> t_plugin_info_dcc *get_dcc_info (t_weechat_plugin *plugin) </command> </para> <para> - Gib eine Liste der aktiven oder beendeten DCCs zurück. + Return list of DCC currently active or finished. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: verkettete Liste von DCCs. + Return value: linked list of DCC. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Typ</entry> - <entry>Feld</entry> - <entry>Beschreibung</entry> + <entry>Type</entry> + <entry>Field</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry>char *</entry> <entry><literal>server</literal></entry> - <entry>IRC Server</entry> + <entry>IRC server</entry> </row> <row> <entry>char *</entry> <entry><literal>channel</literal></entry> - <entry>IRC Channel</entry> + <entry>IRC channel</entry> </row> <row> <entry>int</entry> <entry><literal>type</literal></entry> <entry> - DCC Typ: - 0 = Chatanfrage empfangen, - 1 = Chatanfrage gesendet, - 2 = Datei empfangen, - 3 = Datei gesendet + DCC type: + 0 = chat received, + 1 = chat sent, + 2 = file received, + 3 = file sent </entry> </row> <row> <entry>int*</entry> <entry><literal>status</literal></entry> <entry> - DCC Status: - 0 = wartend, - 1 = verbindend, - 2 = aktiv, - 3 = beendet, - 4 = fehlgeschlagen, - 5 = unterbrochen durch Anwender + DCC status: + 0 = waiting, + 1 = connecting, + 2 = active, + 3 = finished, + 4 = failed, + 5 = interrupted by user </entry> </row> <row> <entry>time_t</entry> <entry><literal>start_time</literal></entry> - <entry>Datum/Zeit der Erzeugung der DCC</entry> + <entry>date/time of DCC creation</entry> </row> <row> <entry>time_t</entry> <entry><literal>start_transfer</literal></entry> - <entry>Datum/Zeit des Beginns der Übertragung der DCC</entry> + <entry>date/time of DCC transfer start</entry> </row> <row> <entry>unsigned long</entry> <entry><literal>addr</literal></entry> - <entry>IP-Adresse des Partners</entry> + <entry>IP address of remote user</entry> </row> <row> <entry>int</entry> <entry><literal>port</literal></entry> - <entry>Port der DCC</entry> + <entry>port used for DCC</entry> </row> <row> <entry>char *</entry> <entry><literal>nick</literal></entry> - <entry>Nickname des Partners</entry> + <entry>remote nick</entry> </row> <row> <entry>char *</entry> <entry><literal>filename</literal></entry> - <entry>Dateiname</entry> + <entry>file name</entry> </row> <row> <entry>char *</entry> <entry><literal>local_filename</literal></entry> - <entry>lokaler Dateiname</entry> + <entry>local file name</entry> </row> <row> <entry>int</entry> <entry><literal>filename_suffix</literal></entry> - <entry>Suffix wenn die Datei umbenannt wird</entry> + <entry>suffix if renaming file</entry> </row> <row> <entry>unsigned long</entry> <entry><literal>size</literal></entry> - <entry>Dateigrösse</entry> + <entry>file size</entry> </row> <row> <entry>unsigned long</entry> <entry><literal>pos</literal></entry> - <entry>Position in Datei</entry> + <entry>position in file</entry> </row> <row> <entry>unsigned long</entry> <entry><literal>start_resume</literal></entry> - <entry>Startposition nach einer Unterbrechung</entry> + <entry>start position after interruption</entry> </row> <row> <entry>unsigned long</entry> <entry><literal>bytes_per_sec</literal></entry> <entry> - Übertragungsrate (Bytes/s) seit Beginn der Übertragung + number of bytes per second since transfer start </entry> </row> <row> <entry>t_plugin_dcc_info *</entry> <entry><literal>prev_dcc</literal></entry> <entry> - Zeiger auf voheriges DCC-Info + pointer to previous DCC info </entry> </row> <row> <entry>t_plugin_dcc_info *</entry> <entry><literal>next_dcc</literal></entry> <entry> - Zeiger auf nächstes DCC-Info + pointer to next DCC info </entry> </row> @@ -2089,11 +10750,11 @@ if (inactivity) </informaltable> </para> <para> - Hinweis: Das Ergebnis muss nach der Benutzung mittels - "free_dcc_info" wieder freigegeben werden. + Note: result has to be free by a call to "free_dcc_info" function + after use. </para> <para> - Beispiele: + Examples: <screen> t_plugin_dcc_info *dcc_info = plugin->get_dcc_info (plugin); for (ptr_dcc = dcc_info; ptr_dcc; ptr_dcc = ptr_dcc->next_dcc) @@ -2111,36 +10772,36 @@ if (dcc_info) <title>free_dcc_info</title> <para> - Prototyp: + Prototype: <command> void free_dcc_info (t_weechat_plugin *plugin, t_plugin_dcc_info *dcc_info) </command> </para> <para> - Gibt den Speicher einer Liste von DCC-Infos wieder frei. + Free memory used by a DCC list. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>dcc_info</option>: Zeiger auf eine Liste mit - DCC-Infos, die mit "get_dcc_info" angelegt wurde + <option>dcc_info</option>: pointer to DCC list returned by + "get_dcc_info" function </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiel: + Example: <screen>plugin->free_dcc_info (plugin, dcc_info);</screen> </para> </section> @@ -2149,216 +10810,210 @@ if (dcc_info) <title>get_server_info</title> <para> - Prototyp: + Prototype: <command> t_plugin_server_info *get_server_info (t_weechat_plugin *plugin) </command> </para> <para> - Gibt die Liste von IRC-Servern zurück (verbunden oder nicht) + Return list of IRC servers (connected or not). </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: Liste von IRC-Servern. + Return value: linked list of IRC servers. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Typ</entry> - <entry>Feld</entry> - <entry>Beschreibung</entry> + <entry>Type</entry> + <entry>Field</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry>char *</entry> <entry><literal>name</literal></entry> - <entry>interner Servername</entry> + <entry>server internal name</entry> </row> <row> <entry>int</entry> <entry><literal>autoconnect</literal></entry> - <entry>1 wenn Autoconnect gesetzt ist, 0 sonst</entry> + <entry>1 if autoconnect at start-up, 0 otherwise</entry> </row> <row> <entry>int</entry> <entry><literal>autoreconnect</literal></entry> <entry> - 1 wenn autoreconnect gesetzt ist, - 0 sonst + 1 if autoreconnect when disconnected, + 0 otherwise </entry> </row> <row> <entry>int</entry> <entry><literal>autoreconnect_delay</literal></entry> - <entry>Wartezeit vor erneutem Verbindungsversuch</entry> + <entry>delay before trying again connection</entry> </row> <row> <entry>int</entry> <entry><literal>command_line</literal></entry> <entry> - 1 wenn der Servername auf der Kommandozeile angegeben - wurde (ist somit temporär) 0 sonst + 1 if server was on command line (so it is temporary), + 0 otherwise </entry> </row> <row> <entry>char *</entry> <entry><literal>address</literal></entry> - <entry>Serveradresse (Name oder IP)</entry> + <entry>server address (host or IP)</entry> </row> <row> <entry>int</entry> <entry><literal>port</literal></entry> - <entry>Port</entry> + <entry>port</entry> </row> <row> <entry>int</entry> <entry><literal>ipv6</literal></entry> - <entry>IPv6-Verbindung</entry> + <entry>IPv6 connection</entry> </row> <row> <entry>int</entry> <entry><literal>ssl</literal></entry> - <entry>SSL-Verbindung</entry> + <entry>SSL connection</entry> </row> <row> <entry>char *</entry> <entry><literal>password</literal></entry> - <entry>Passwort</entry> + <entry>server password</entry> </row> <row> <entry>char *</entry> <entry><literal>nick1</literal></entry> - <entry>primärer Nickname</entry> + <entry>first nickname</entry> </row> <row> <entry>char *</entry> <entry><literal>nick2</literal></entry> - <entry>alternativer Nickname</entry> + <entry>alternate nickname</entry> </row> <row> <entry>char *</entry> <entry><literal>nick3</literal></entry> - <entry>zweiter, alternativer Nickname</entry> + <entry>second alternate nickname</entry> </row> <row> <entry>char *</entry> <entry><literal>username</literal></entry> - <entry>Username</entry> + <entry>user name</entry> </row> <row> <entry>char *</entry> <entry><literal>real name</literal></entry> - <entry>tatsächlicher Name</entry> + <entry>real name</entry> </row> <row> <entry>char *</entry> <entry><literal>command</literal></entry> - <entry> - Kommando, dass bei erfolgreicher Verbindung - ausgeführt wurde - </entry> + <entry>command run once connected</entry> </row> <row> <entry>int</entry> <entry><literal>command_delay</literal></entry> - <entry>Verzögerung nach Ausführung des Kommandos</entry> + <entry>delay after execution of command</entry> </row> <row> <entry>char *</entry> <entry><literal>autojoin</literal></entry> - <entry>Channels, die automatisch betreten werden sollen</entry> + <entry>channels joined automatically</entry> </row> <row> <entry>int</entry> <entry><literal>autorejoin</literal></entry> <entry> - 1 wenn Channels wieder betreten werden sollen, nachdem - man gekickt wurde 0 sonst + 1 if channels are rejoined when kicked, + 0 otherwise </entry> </row> <row> <entry>char *</entry> <entry><literal>notify_levels</literal></entry> - <entry>Benachrichtigungs-Level von Channels</entry> + <entry>channels notify levels</entry> </row> <row> <entry>char *</entry> <entry><literal>charset_decode_iso</literal></entry> - <entry>Zeichensatz zum Dekodieren von ISO</entry> + <entry>channels charsets for decoding ISO</entry> </row> <row> <entry>char *</entry> <entry><literal>charset_decode_utf</literal></entry> - <entry>Zeichensatz zum Dekodieren von UTF</entry> + <entry>channels charsets for decoding UTF</entry> </row> <row> <entry>char *</entry> <entry><literal>charset_encode</literal></entry> - <entry> - Zeichensatz der Channels zum Kodieren von - Nachrichten - </entry> + <entry>channels charsets for encoding messages</entry> </row> <row> <entry>int</entry> <entry><literal>is_connected</literal></entry> - <entry>1 wenn verbunden mit einem Server, 0 otherwise</entry> + <entry>1 if connected to server, 0 otherwise</entry> </row> <row> <entry>int</entry> <entry><literal>ssl_connected</literal></entry> - <entry>1 wenn verbunden über SSL, 0 sonst</entry> + <entry>1 if connected with SSL, 0 otherwise</entry> </row> <row> <entry>char *</entry> <entry><literal>nick</literal></entry> - <entry>gegenwärtiger Nickname</entry> + <entry>current nickname</entry> </row> <row> <entry>int</entry> <entry><literal>is_away</literal></entry> - <entry>1 wenn away-flag gesetzt ist, 0 sonst</entry> + <entry>1 if away, 0 otherwise</entry> </row> <row> <entry>time_t</entry> <entry><literal>away_time</literal></entry> - <entry>Zeitspanne seit away-flag gesetzt ist</entry> + <entry>time when user is marking as away</entry> </row> <row> <entry>int</entry> <entry><literal>lag</literal></entry> - <entry>Lag (in Millisekunden)</entry> + <entry>lag (in milliseconds)</entry> </row> <row> <entry>t_plugin_server_info *</entry> <entry><literal>prev_server</literal></entry> - <entry>Zeiger auf vorherigen Knoten der Liste</entry> + <entry>pointer to previous server info</entry> </row> <row> <entry>t_plugin_server_info *</entry> <entry><literal>next_server</literal></entry> - <entry>Zeiger auf nächsten Knoten der Liste</entry> + <entry>pointer to next server info</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Hinweis: das Ergebnis muss nach der Benutzung mit - "free_server_info" wieder freigegeben werden. + Note: result has to be free by a call to "free_server_info" + function after use. </para> <para> - Beispiel: + Example: <screen> t_plugin_server_info *server_info, *ptr_server_info; server_info = plugin->get_server_info (plugin); @@ -2384,36 +11039,36 @@ if (server_info) <title>free_server_info</title> <para> - Prototyp: + Prototype: <command> void free_server_info (t_weechat_plugin *plugin, t_plugin_server_info *server_info) </command> </para> <para> - Gib den Speicher einer Liste "server info" frei + Free memory used by server info list. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>server_info</option>: Zeiger auf eine Server-Liste, - der von der Funktion "get_server_info" zurückgegeben wurde. + <option>server_info</option>: pointer to server list + returned by "get_server_info" function </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiel: + Example: <screen>plugin->free_server_info (plugin, server_info);</screen> </para> </section> @@ -2422,99 +11077,97 @@ if (server_info) <title>get_channel_info</title> <para> - Prototyp: + Prototype: <command> t_plugin_channel_info *get_channel_info (t_weechat_plugin *plugin, char *server) </command> </para> <para> - Gib eine Liste der Channels für einen Server zurück. + Return list of IRC channels for a server. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>server</option>: interner Name des Server + <option>server</option>: internal server name </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: verkettete Liste von Channels für einen Server. + Return value: linked list of IRC channels for server. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Typ</entry> - <entry>Feld</entry> - <entry>Beschreibung</entry> + <entry>Type</entry> + <entry>Field</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry>int</entry> <entry><literal>type</literal></entry> - <entry> - 0 für einen normalen Channel, 1 für einen Privaten - </entry> + <entry>0 for a channel, 1 for a private</entry> </row> <row> <entry>char *</entry> <entry><literal>name</literal></entry> - <entry>Name des Channels</entry> + <entry>name of channel</entry> </row> <row> <entry>char *</entry> <entry><literal>topic</literal></entry> - <entry>Topic des Channels</entry> + <entry>topic of channel</entry> </row> <row> <entry>char *</entry> <entry><literal>modes</literal></entry> - <entry>Channelmodus (Flags)</entry> + <entry>channel modes</entry> </row> <row> <entry>int</entry> <entry><literal>limit</literal></entry> - <entry>Anzahl der erlaubten User</entry> + <entry>user limit</entry> </row> <row> <entry>char *</entry> <entry><literal>key</literal></entry> - <entry>Schlüssel des Channels</entry> + <entry>channel key</entry> </row> <row> <entry>int</entry> <entry><literal>nicks_count</literal></entry> - <entry>Anzahl der Nicknamen des Channels</entry> + <entry>number of nicks on channel</entry> </row> <row> <entry>t_plugin_channel_info *</entry> <entry><literal>prev_channel</literal></entry> - <entry>Zeiger auf vorherigem Knoten der Liste</entry> + <entry>pointer to previous channel info</entry> </row> <row> <entry>t_plugin_channel_info *</entry> <entry><literal>next_channel</literal></entry> - <entry>Zeiger auf nächsten Knoten der Liste</entry> + <entry>pointer to next channel info</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Hinweis: Das Ergebnis muss nach der Benutzung mit - "free_channel_info" wieder freigegeben werden. + Note: result has to be free by a call to "free_channel_info" + function after use. </para> <para> - Beispiel: + Example: <screen> t_plugin_channel_info *channel_info, *ptr_chan_info; channel_info = plugin->get_channel_info (plugin, "freenode"); @@ -2538,37 +11191,36 @@ if (channel_info) <title>free_channel_info</title> <para> - Prototyp: + Prototype: <command> void free_channel_info (t_weechat_plugin *plugin, t_plugin_channel_info *channel_info) </command> </para> <para> - Gibt den Speicher einer Liste "channel info" wieder frei. + Free memory used by channel info list. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>channel_info</option>: Zeiger auf eine Liste - "channel info", der von "get_channel_info" zurückgegeben - wurde + <option>channel_info</option>: pointer to channel info list + returned by "get_channel_info" function </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiel: + Example: <screen>plugin->free_channel_info (plugin, channel_info);</screen> </para> </section> @@ -2577,90 +11229,86 @@ if (channel_info) <title>get_nick_info</title> <para> - Prototyp: + Prototype: <command> t_plugin_nick_info *get_nick_info (t_weechat_plugin *plugin, char *server, char *channel) </command> </para> <para> - Gib eine Liste der Nicknamen für einen Channel zurück. + Return list of nicks for a channel. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>server</option>: interner Name des Servers + <option>server</option>: internal server name </para> </listitem> <listitem> <para> - <option>channel</option>: Name des Channels + <option>channel</option>: channel name </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: verkettete Liste von Nicknamen eines Channels. + Return value: linked list of nicks on channel. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Typ</entry> - <entry>Feld</entry> - <entry>Beschreibung</entry> + <entry>Type</entry> + <entry>Field</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry>char *</entry> <entry><literal>nick</literal></entry> - <entry>Nickname</entry> + <entry>nick name</entry> </row> <row> <entry>char *</entry> <entry><literal>host</literal></entry> - <entry>Hostname</entry> + <entry>hostname</entry> </row> <row> <entry>int</entry> - <entry><literal>Flags</literal></entry> + <entry><literal>flags</literal></entry> <entry> - Flags, die für einen Nicknamen gesetzt sind: - Zweierpotenzen "oder" Zwischenwerte - (1 = channel owner, - 2 = channel admin, - 4 = op, - 8 = halfop, - 16 = voice, - 32 = away) + nick flags, binary "or" between values (1 = channel + owner, 2 = channel admin, 4 = op, 8 = halfop, + 16 = voice, 32 = away) </entry> </row> <row> <entry>t_plugin_nick_info *</entry> <entry><literal>prev_nick</literal></entry> - <entry>Zeiger auf vorherigen Knoten der Liste</entry> + <entry>pointer to previous nick info</entry> </row> <row> <entry>t_plugin_nick_info *</entry> <entry><literal>next_nick</literal></entry> - <entry>Zeiger auf nächsten Knoten der Liste</entry> + <entry>pointer to next nick info</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Hinweis: Das Ergebnis muss nach der Benutzung mit "free_nick_info" wieder freigegeben werden. + Note: result has to be free by a call to "free_nick_info" + function after use. </para> <para> - Beispiel: + Example: <screen> t_plugin_nick_info *nick_info, *ptr_nick_info; nick_info = plugin->get_nick_info (plugin, "freenode", "#weechat"); @@ -2684,36 +11332,36 @@ if (nick_info) <title>free_nick_info</title> <para> - Prototyp: + Prototype: <command> void free_nick_info (t_weechat_plugin *plugin, t_plugin_nick_info *nick_info) </command> </para> <para> - Gibt den Speicher einer Liste "nick info" frei. + Free memory used by nick info list. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>nick_info</option>: Zeiger auf eine Liste - "nick info", der von "get_nick_info" zurückgegeben wurde + <option>nick_info</option>: pointer to nick info list + returned by "get_nick_info" function </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiel: + Example: <screen>plugin->free_nick_info (plugin, nick_info);</screen> </para> </section> @@ -2722,38 +11370,38 @@ if (nick_info) <title>get_config</title> <para> - Prototyp: + Prototype: <command> char *get_config (t_weechat_plugin *plugin, char *option) </command> </para> <para> - Gibt den Wert einer Option der WeeChat-Konfiguration zurück. + Return value of a WeeChat config option. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>option</option>: Name der Option + <option>option</option>: name of option to read </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: Wert der Option, oder NULL, wenn nichts gefunden wurde. + Return value: option value, NULL if not found. </para> <para> - Hinweis: Das Ergebnis muss nach der Benutzung mit "free" wieder - freigegeben werden. + Note: result has to be free by a call to "free" function after + use. </para> <para> - Beispiel: + Examples: <screen> char *value1 = plugin->get_config (plugin, "look_set_title"); char *value2 = plugin->get_config (plugin, "freenode.server_autojoin"); @@ -2765,41 +11413,41 @@ char *value2 = plugin->get_config (plugin, "freenode.server_autojoin"); <title>set_config</title> <para> - Prototyp: + Prototype: <command> int set_config (t_weechat_plugin *plugin, char *option, char *value) </command> </para> <para> - Setze den Wert einer Option der WeeChat-Konfiguration. + Update value of a WeeChat config option. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>option</option>: Name der Option + <option>option</option>: name of option to update </para> </listitem> <listitem> <para> - <option>value</option>: der neue Wert der Option + <option>value</option>: new value for option </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: 1 wenn der Wert der Option gesetzt werden konnte, - 0 bei Auftreten eines Fehlers. + Return value: 1 if option was successfully updated, 0 if an + error occurred. </para> <para> - Beispiel: + Example: <screen> plugin->set_config (plugin, "look_nicklist", "off"); </screen> @@ -2810,42 +11458,41 @@ plugin->set_config (plugin, "look_nicklist", "off"); <title>get_plugin_config</title> <para> - Prototyp: + Prototype: <command> char *get_plugin_config (t_weechat_plugin *plugin, char *option) </command> </para> <para> - Gibt den Wert einer Option eines Plugins zurück. - Die Option wird aus "<literal>~/.weechat/plugins.rc</literal>" - gelesen und sieht so aus: "<literal>plugin.option=value</literal>" - (Hinweis: der Name des Plugins wird automatisch gesetzt). - + Return value of a plugin option. + Option is read from file "<literal>~/.weechat/plugins.rc</literal>" + and is like: "<literal>plugin.option=value</literal>" + (note: plugin name is automatically added). </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>option</option>: Name der Option + <option>option</option>: name of option to read </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: Wert der Option, NULL wenn nichts gefunden wurde. + Return value: option value, NULL if not found. </para> <para> - Hinweis: Das Ergebnis muss nach der Benutzung mit "free" wieder - freigegeben werden. + Note: result has to be free by a call to "free" function after + use. </para> <para> - Beispiel: + Example: <screen> char *value = plugin->get_plugin_config (plugin, "my_var"); </screen> @@ -2856,45 +11503,44 @@ char *value = plugin->get_plugin_config (plugin, "my_var"); <title>set_plugin_config</title> <para> - Prototyp: + Prototype: <command> int set_plugin_config (t_weechat_plugin *plugin, char *option, char *value) </command> </para> <para> - Setzt den Wert einer Option eines Plugins. - Die Option wird in die Datei - "<literal>~/.weechat/plugins.rc</literal>" geschrieben - und sieht so aus: "<literal>plugin.option=value</literal>" - (Hinweis: der Name des Plugins wird automatisch gesetzt) + Update value of a plugin option. + Option is written in file "<literal>~/.weechat/plugins.rc</literal>" + and is like: "<literal>plugin.option=value</literal>" + (note: plugin name is automatically added). </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf eine Plugin-Struktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>option</option>: Name der Option, die gesetzt werden soll + <option>option</option>: name of option to update </para> </listitem> <listitem> <para> - <option>value</option>: Wert der zu setzenden Option + <option>value</option>: new value for option </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: 1 wenn die Option gesetzt werden konnte, 0 wenn ein - Fehler aufgetreten ist. + Return value: 1 if option was successfully updated, 0 if an + error occurred. </para> <para> - Beispiel: + Example: <screen> plugin->set_plugin_config (plugin, "my_var", "value"); </screen> @@ -2912,26 +11558,26 @@ plugin->set_plugin_config (plugin, "my_var", "value"); </command> </para> <para> - Hole IRC-Farbindex mit dem Farbnamen. + Get IRC color index with name. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf die Pluginstruktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>color_name</option>: Farbname - Folgende Farben sind erlaubt: + <option>color_name</option>: color name + Allowed colors are: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Farbname</entry> - <entry>Wert</entry> + <entry>Color name</entry> + <entry>Value</entry> </row> </thead> <tbody> @@ -3007,10 +11653,10 @@ plugin->set_plugin_config (plugin, "my_var", "value"); </itemizedlist> </para> <para> - Rückgabewert: IRC-Farbindex, -1 wenn die Farbe nicht gefunden wurde. + Return value: IRC color index, -1 if color is not found. </para> <para> - Beispiel: + Example: <screen> int color_blue = plugin->get_irc_color (plugin, "blue"); /* return 2 */ </screen> @@ -3021,48 +11667,49 @@ int color_blue = plugin->get_irc_color (plugin, "blue"); /* return 2 */ <title>input_color</title> <para> - Prototyp: + Prototype: <command> void input_color (t_weechat_plugin *plugin, int color, int start, int length) </command> </para> <para> - Erzeugt einen Farbcode im Eingabepuffer. + Add color in input buffer. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf die Pluginstruktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>color</option>: Textfarbe (wenn der Wert < 0 ist, - dann wird der Eingabepuffer aufgefrischt und nicht verändert) + <option>color</option>: color for text (if < 0, then input + buffer is refresh, and there's no change in input buffer + content) </para> </listitem> <listitem> <para> - <option>start</option>: Startposition für Einfärbung (wenn - der Wert < 0 ist, wird die Maske neu initialisiert) + <option>start</option>: start position for color (if < 0, + then mask is reinitialized) </para> </listitem> <listitem> <para> - <option>length</option>: Länge der Einfärbung (wenn der Wert - <= 0 ist, wird die Maske neu initialisiert) + <option>length</option>: length for color (if <= 0, + then mask is reinitialized) </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiele: + Example: <screen> plugin->input_color (plugin, plugin->get_irc_color (plugin, "blue"), 10, 5); </screen> @@ -3079,90 +11726,82 @@ plugin->input_color (plugin, plugin->get_irc_color (plugin, "blue"), 10, 5); </command> </para> <para> - Gibt die Liste der WeeChat-Fenster zurück. + Return list of WeeChat windows. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Pluginstruktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: verkettete Liste der WeeChat-Fenster. + Return value: linked list of WeeChat windows. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Typ</entry> - <entry>Feld</entry> - <entry>Beschreibung</entry> + <entry>Type</entry> + <entry>Field</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry>int</entry> <entry><literal>win_x</literal></entry> - <entry>horizontale Fensterposition</entry> + <entry>horizontal position of window</entry> </row> <row> <entry>int</entry> <entry><literal>win_y</literal></entry> - <entry>vertikale Fensterposition</entry> + <entry>vertical position of window</entry> </row> <row> <entry>int</entry> <entry><literal>win_width</literal></entry> - <entry>Fensterbreite</entry> + <entry>width of window</entry> </row> <row> <entry>int</entry> <entry><literal>win_height</literal></entry> - <entry>Fensterhöhe</entry> + <entry>height of window</entry> </row> <row> <entry>int</entry> <entry><literal>win_width_pct</literal></entry> - <entry> - Breite in % (im Vergleich zum übergeordneten Fenster) - </entry> + <entry>width % (compared to parent window)</entry> </row> <row> <entry>int</entry> <entry><literal>win_height_pct</literal></entry> - <entry> - Höhe % (im Vergleich zum übergeordneten Fenster) - </entry> + <entry>height % (compared to parent window)</entry> </row> <row> <entry>int</entry> <entry><literal>num_buffer</literal></entry> - <entry>Anzahl der angezeigten Puffer</entry> + <entry>number of displayed buffer</entry> </row> <row> <entry>t_plugin_window_info *</entry> <entry><literal>prev_window</literal></entry> - <entry> - Zeiger auf die Informationen des vorhergehenden Fensters - </entry> + <entry>pointer to previous window info</entry> </row> <row> <entry>t_plugin_window_info *</entry> <entry><literal>next_window</literal></entry> - <entry> - Zeiger auf die Informationen des nächsten Fensters - </entry> + <entry>pointer to next window info</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Anmerkung: Das Ergebnis muss nach Benutzung durch einen Aufruf der - "free_window_info"-Funktion gelöscht werden. + Note: result has to be free by a call to "free_window_info" + function after use. </para> <para> Example: @@ -3174,7 +11813,7 @@ if (window_info) { for (ptr_window = window_info; ptr_window; ptr_window = ptr_window->next_window) { - plugin->print (plugin, NULL, NULL, "--- window info ---"); + plugin->print (plugin, NULL, NULL, "window info"); plugin->print (plugin, NULL, NULL, "(%d,%d), size: %dx%d, %%size: %d%%x%d%%", ptr_window->win_x, ptr_window->win_y, ptr_window->win_width, ptr_window->win_height, @@ -3193,38 +11832,36 @@ else <title>free_window_info</title> <para> - Prototyp: + Prototype: <command> void free_window_info (t_weechat_plugin *plugin, t_plugin_window_info *window_info) </command> </para> <para> - Gibt den Speicher wieder frei, der von der - Fenster-Informationsliste belegt wird. + Free memory used by window info list. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Pluginstruktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>window_info</option>: Zeiger auf - Fenster-Informationsliste, der von der - "get_window_info"-Funktion zurückgegeben wurde + <option>window_info</option>: pointer to window info list + returned by "get_window_info" function </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiel: + Example: <screen>plugin->free_window_info (plugin, window_info);</screen> </para> </section> @@ -3233,94 +11870,91 @@ else <title>get_buffer_info</title> <para> - Prototyp: + Prototype: <command> t_plugin_buffer_info *get_buffer_info (t_weechat_plugin *plugin) </command> </para> <para> - Gibt eine Liste der WeeChat-Puffer zurück. + Return list of WeeChat buffers. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Pluginstruktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: verkettete Liste der WeeChat-Puffer. + Return value: linked list of WeeChat buffers. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Typ</entry> - <entry>Feld</entry> - <entry>Beschreibung</entry> + <entry>Type</entry> + <entry>Field</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry>int</entry> <entry><literal>type</literal></entry> - <entry>Puffertyp: 0=standard, 1=DCC, 2=raw IRC data</entry> + <entry>buffer type: 0=standard, 1=DCC, 2=raw IRC data</entry> </row> <row> <entry>int</entry> <entry><literal>number</literal></entry> - <entry>Puffer-Nummer</entry> + <entry>buffer number</entry> </row> <row> <entry>int</entry> <entry><literal>num_displayed</literal></entry> - <entry>Anzahl der Fenster im Puffer</entry> + <entry>number of windows displaying buffer</entry> </row> <row> <entry>char *</entry> <entry><literal>server_name</literal></entry> - <entry>Servername für den Puffer (kann NULL sein)</entry> + <entry>server name for buffer (may be NULL)</entry> </row> <row> <entry>char *</entry> <entry><literal>channel_name</literal></entry> - <entry>Channelname für den Puffer (kann NULL sein)</entry> + <entry>channel name for buffer (may be NULL)</entry> </row> <row> <entry>int</entry> <entry><literal>notify_level</literal></entry> - <entry>Benachrichtigungslevel für den Puffer</entry> + <entry>notify level for buffer</entry> </row> <row> <entry>char *</entry> <entry><literal>log_filename</literal></entry> - <entry> - Name der Logdatei (NULL bedeutet, dass nichts geloggt - wird) - </entry> + <entry>log filename (NULL means not logging)</entry> </row> <row> <entry>t_plugin_buffer_info *</entry> <entry><literal>prev_buffer</literal></entry> - <entry>Zeiger auf die vorhergehenden Pufferinformationen</entry> + <entry>pointer to previous buffer info</entry> </row> <row> <entry>t_plugin_buffer_info *</entry> <entry><literal>next_buffer</literal></entry> - <entry>Zeiger auf die nächsten Pufferinformationen</entry> + <entry>pointer to next buffer info</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Bemerkung: Das Ergebnis muss nach der Auswertung mit der - "free_buffer_info"-Funktion wieder gelöscht werden. + Note: result has to be free by a call to "free_buffer_info" + function after use. </para> <para> - Beispiel: + Example: <screen> t_plugin_buffer_info *buffer_info, *ptr_buffer; @@ -3329,7 +11963,7 @@ if (buffer_info) { for (ptr_buffer = buffer_info; ptr_buffer; ptr_buffer = ptr_buffer->next_buffer) { - plugin->print (plugin, NULL, NULL, "--- buffer info ---"); + plugin->print (plugin, NULL, NULL, "buffer info"); plugin->print (plugin, NULL, NULL, "type: %d", ptr_buffer->type); plugin->print (plugin, NULL, NULL, "number: %d", ptr_buffer->number); plugin->print (plugin, NULL, NULL, "num_displayed: %d", ptr_buffer->num_displayed); @@ -3350,22 +11984,21 @@ else <title>free_buffer_info</title> <para> - Prototyp: + Prototype: <command> void free_buffer_info (t_weechat_plugin *plugin, t_plugin_buffer_info *buffer_info) </command> </para> <para> - Gibt den Speicher frei, der von der Puffer-Informationsliste - belegt wird. + Free memory used by buffer info list. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Pluginstruktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> @@ -3377,10 +12010,10 @@ else </itemizedlist> </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiel: + Example: <screen>plugin->free_buffer_info (plugin, buffer_info);</screen> </para> </section> @@ -3396,72 +12029,72 @@ else </command> </para> <para> - Gibt den Inhalt des Puffers zurück. + Return content of buffer. </para> <para> - Argumente: + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Pluginstruktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>server</option>: interner Name des Servers + <option>server</option>: internal name of server </para> </listitem> <listitem> <para> - <option>channel</option>: Channelname + <option>channel</option>: channel name </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: Pufferinhalt (verkettete Liste mit den Zeilen). + Return value: buffer content (linked list of lines). <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Typ</entry> - <entry>Feld</entry> - <entry>Beschreibung</entry> + <entry>Type</entry> + <entry>Field</entry> + <entry>Description</entry> </row> </thead> <tbody> <row> <entry>time_t</entry> <entry><literal>date</literal></entry> - <entry>Datum/Zeit</entry> + <entry>date and time</entry> </row> <row> <entry>char *</entry> <entry><literal>nick</literal></entry> - <entry>Nick</entry> + <entry>nick</entry> </row> <row> <entry>char *</entry> <entry><literal>data</literal></entry> - <entry>Zeileninhalt (Farbcodes wurden entfernt)</entry> + <entry>line content (color codes are removed)</entry> </row> <row> <entry>t_plugin_buffer_line *</entry> <entry><literal>prev_line</literal></entry> - <entry>Zeiger auf die vorherige Zeile</entry> + <entry>pointer to previous line</entry> </row> <row> <entry>t_plugin_buffer_line *</entry> <entry><literal>next_line</literal></entry> - <entry>Zeiger auf die nächste Zeile</entry> + <entry>pointer to next line</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Bemerkung: Das Ergebnis muss nach der Auswertung mit der - "free_buffer_data"-Funktion wieder gelöscht werden. + Note: result has to be free by a call to "free_buffer_data" + function after use. </para> <para> Example: @@ -3495,33 +12128,33 @@ if (buffer_line) </command> </para> <para> - Gibt den Speicher frei, der von den Pufferzeilen belegt wurde. + Free memory used by buffer line list. </para> <para> Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option>: Zeiger auf Pluginstruktur + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>buffer_line</option>: Zeiger auf Pufferzeilen, der - von der "get_buffer_data"-Funktion zurückgegeben wurde + <option>buffer_line</option>: pointer to buffer line list + returned by "get_buffer_data" function </para> </listitem> </itemizedlist> </para> <para> - Rückgabewert: keiner. + Return value: none. </para> <para> - Beispiele: + Example: <screen>plugin->free_buffer_data (plugin, buffer_line);</screen> </para> </section> + + --> </section> - ---> diff --git a/doc/fr/dev/plugin_c_api.fr.xml b/doc/fr/dev/plugin_c_api.fr.xml index 5b43e9784..fb4037abe 100644 --- a/doc/fr/dev/plugin_c_api.fr.xml +++ b/doc/fr/dev/plugin_c_api.fr.xml @@ -22,490 +22,9174 @@ along with this program. If not, see <http://www.gnu.org/licenses/>. --> <section id="secPluginCApi"> - <title>API extension en C</title> + <!-- TRANSLATION NEEDED --> + <title>C plugin API</title> - <section id="secAPI_set_charset"> - <title>set_charset</title> + <!-- =============================[ plugins ]============================ --> + + <section id="secPluginCApi_plugins"> + <title>Plugins</title> <para> - Prototype : - <command> - void set_charset (t_weechat_plugin *plugin, char *charset) - </command> - </para> - <para> - Change le jeu de caractères de l'extension. - </para> - <para> - Paramètres : - <itemizedlist> - <listitem> - <para> - <option>plugin</option> : pointeur vers la structure - de l'extension - </para> - </listitem> - <listitem> - <para> - <option>charset</option> : nouveau jeu de caractères à - utiliser - </para> - </listitem> - </itemizedlist> - </para> - <para> - Exemple : - <screen>plugin->set_charset (plugin, "ISO-8859-1");</screen> + 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> - <section id="secAPI_iconv_to_internal"> - <title>iconv_to_internal</title> + <!-- =============================[ strings ]============================ --> + + <section id="secPluginCApi_strings"> + <title>Strings</title> <para> - Prototype : - <command> - void iconv_to_internal (t_weechat_plugin *plugin, char *charset, - char *string) - </command> - </para> - <para> - Convertit une chaîne de caractères vers le jeu de caractères - interne WeeChat (UTF-8). - </para> - <para> - Paramètres : - <itemizedlist> - <listitem> - <para> - <option>plugin</option> : pointeur vers la structure - de l'extension - </para> - </listitem> - <listitem> - <para> - <option>charset</option> : le jeu de caractères de départ - </para> - </listitem> - <listitem> - <para> - <option>string</option> : la chaîne à convertir - </para> - </listitem> - </itemizedlist> - </para> - <para> - Valeur renvoyée : la chaîne convertie. - </para> - <para> - Note : le résultat doit être libéré par un appel à la fonction - "free" après utilisation. - </para> - <para> - Exemple : - <screen>char *str = plugin->iconv_to_internal (plugin, "ISO-8859-1", "chaine iso: é à");</screen> + 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 < string2, zero if string1 == string2, positive if + string1 > 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 < string2, zero if string1 == string2, positive if + string1 > 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 < string2, zero if string1 == string2, positive if + string1 > 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 may begin or end with "*" (no + other "*" are allowed inside mask). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>string</option>: string + </para> + </listitem> + <listitem> + <para> + <option>mask</option>: mask + </para> + </listitem> + <listitem> + <para> + <option>case_sensitive</option>: 1 for case sensitive search, + otherwise 0 + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: 1 if string matches mask, otherwise 0. + </para> + <para> + Examples: +<screen> +int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */ +int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */ +int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */ +</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_string_replace"> + <title>weechat_string_replace</title> + + <para> + Prototype: +<programlisting> +char *weechat_string_replace (const char *string, const char *search, + const char *replace); +</programlisting> + </para> + <para> + Replace "search" string by new one in a string. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>string</option>: string + </para> + </listitem> + <listitem> + <para> + <option>search</option>: string to replace + </para> + </listitem> + <listitem> + <para> + <option>replace</option>: replacement for "search" string + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: string with "search" replaced by "replace". + </para> + <note> + <para> + Result has to be free by a call to "free" after use. + </para> + </note> + <para> + Example: + <screen>char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_string_remove_quotes"> + <title>weechat_string_remove_quotes</title> + + <para> + Prototype: +<programlisting> +char *weechat_string_remove_quotes (const char *string, const char *quotes); +</programlisting> + </para> + <para> + Remove quotes at beginning/end of string (ignore spaces if there are + before first quote or after last quote). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>string</option>: string + </para> + </listitem> + <listitem> + <para> + <option>quotes</option>: string with list of quotes + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: string without quotes at beginning/end. + </para> + <note> + <para> + Result has to be free by a call to "free" after use. + </para> + </note> + <para> + Example: + <screen>char *str = weechat_string_remove_quotes (string, " 'abc' ", "'"); /* result: "abc" */</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_string_strip"> + <title>weechat_string_strip</title> + + <para> + Prototype: +<programlisting> +char *weechat_string_strip ( + const char *string, + int left, + int right, + const char *chars); +</programlisting> + </para> + <para> + Strip chars at beginning and/or end of string. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>string</option>: string + </para> + </listitem> + <listitem> + <para> + <option>left</option>: strip left chars if different from 0 + </para> + </listitem> + <listitem> + <para> + <option>right</option>: strip right chars if different from 0 + </para> + </listitem> + <listitem> + <para> + <option>chars</option>: string with chars to strip + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: stripped string. + </para> + <note> + <para> + Result has to be free by a call to "free" after use. + </para> + </note> + <para> + Example: +<screen> +char *str = weechat_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, &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, &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, &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, &argc); +char *string = weechat_string_build_with_exploded (argv, ";"); +/* string == "abc;def;ghi" */ +</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_string_split_command"> + <title>weechat_string_split_command</title> + + <para> + Prototype: +<programlisting> +char **weechat_string_split_command (const char *command, char separator); +</programlisting> + </para> + <para> + Split a list of commands separated by 'separator' (which can be escaped + by '\' in string). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>command</option>: command to split + </para> + </listitem> + <listitem> + <para> + <option>separator</option>: separator + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: array of strings, NULL if problem. + </para> + <note> + <para> + Result has to be free by a call to + "weechat_string_free_splitted_command" after use. + </para> + </note> + <para> + Example: + <screen>char **argv = weechat_string_split_command ("/command1;/command2", ';');</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_string_splitted_command"> + <title>weechat_string_free_splitted_command</title> + + <para> + Prototype: +<programlisting> +void weechat_string_free_splitted_command (char **splitted_command); +</programlisting> + </para> + <para> + Free memory used by a splitted command. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>splitted_command</option>: command splitted by + "weechat_string_split_commaand" function + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: none. + </para> + <para> + Example: +<screen> +char **argv = weechat_string_split_command ("/command1;/command2", ';'); +... +weechat_string_free_splitted_command (argv); +</screen> + </para> + </section> + + <section 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> - <section id="secAPI_iconv_from_internal"> - <title>iconv_from_internal</title> + <!-- ==============================[ UTF-8 ]============================= --> + + <section id="secPluginCApi_utf8"> + <title>UTF-8</title> <para> - Prototype : - <command> - void iconv_from_internal (t_weechat_plugin *plugin, char *charset, - char *string) - </command> - </para> - <para> - Convertit une chaîne de caractères depuis le jeu de caractères - interne WeeChat (UTF-8) vers un autre. - </para> - <para> - Paramètres : - <itemizedlist> - <listitem> - <para> - <option>plugin</option> : pointeur vers la structure - de l'extension - </para> - </listitem> - <listitem> - <para> - <option>charset</option> : le jeu de caractères voulu - </para> - </listitem> - <listitem> - <para> - <option>string</option> : la chaîne à convertir - </para> - </listitem> - </itemizedlist> - </para> - <para> - Valeur renvoyée : la chaîne convertie. - </para> - <para> - Note : le résultat doit être libéré par un appel à la fonction - "free" après utilisation. - </para> - <para> - Exemple : - <screen>char *str = plugin->iconv_from_internal (plugin, "ISO-8859-1", "chaine utf-8: é à");</screen> + 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, &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 ("东"); /* == 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 < char2, zero if char1 == char2, positive if char1 > 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> - <section id="secAPI_ascii_strcasecmp"> - <title>ascii_strcasecmp</title> + <!-- ===========================[ directories ]========================== --> + + <section id="secPluginCApi_directories"> + <title>Directories</title> <para> - Prototype : - <command> - int ascii_strcasecmp (t_weechat_plugin *plugin, - char *chaine1, char *chaine2) - </command> - </para> - <para> - Effectue une comparaison entre deux chaînes, sans tenir compte des - majuscules/minuscules ni de la locale. - </para> - <para> - Paramètres : - <itemizedlist> - <listitem> - <para> - <option>plugin</option> : pointeur vers la structure - de l'extension - </para> - </listitem> - <listitem> - <para> - <option>chaine1</option> : la première chaîne à comparer - </para> - </listitem> - <listitem> - <para> - <option>chaine2</option> : la deuxième chaîne à comparer - </para> - </listitem> - </itemizedlist> - </para> - <para> - Valeur renvoyée : la différence entre les deux chaînes : négatif - si chaine1 < chaine2, zéro si chaine1 == chaine2, positif si - chaine1 > chaine2 - </para> - <para> - Exemple : - <screen>if (plugin->ascii_strcasecmp (plugin, "abc", "def") != 0) ...</screen> + 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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", &callback); +</screen> + </para> + </section> + </section> - <section id="secAPI_ascii_strncasecmp"> - <title>ascii_strncasecmp</title> + <!-- ==============================[ util ]============================== --> + + <section id="secPluginCApi_util"> + <title>Util</title> <para> - Prototype : - <command> - int ascii_strncasecmp (t_weechat_plugin *plugin, - char *chaine1, char *chaine2, int max) - </command> - </para> - <para> - Effectue une comparaison entre deux chaînes, sans tenir compte des - majuscules/minuscules ni de la locale, en comparant au plus "max" - caractères. - </para> - <para> - Paramètres : - <itemizedlist> - <listitem> - <para> - <option>plugin</option> : pointeur vers la structure - de l'extension - </para> - </listitem> - <listitem> - <para> - <option>chaine1</option> : la première chaîne à comparer - </para> - </listitem> - <listitem> - <para> - <option>chaine2</option> : la deuxième chaîne à comparer - </para> - </listitem> - <listitem> - <para> - <option>max</option> : nombre de caractères max à comparer - </para> - </listitem> - </itemizedlist> - </para> - <para> - Valeur renvoyée : la différence entre les deux chaînes : négatif - si chaine1 < chaine2, zéro si chaine1 == chaine 2, positif si - chaine1 > chaine2 - </para> - <para> - Exemple : - <screen>if (plugin->ascii_strncasecmp (plugin, "abc", "def", 2) != 0) ...</screen> + 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 < char2, zero if tv1 == tv2, +1 if tv1 > + tv2 + </para> + <para> + Example: + <screen>if (weechat_timeval_cmp (&tv1, &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 (&tv1, &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 (&tv, 2000); /* add 2 seconds */</screen> + </para> + </section> + </section> - <section id="secAPI_explode_string"> - <title>explode_string</title> + <!-- ==========================[ sorted list ]=========================== --> + + <section id="secPluginCApi_sorted_list"> + <title>Sorted lists</title> <para> - Prototype : - <command> - char **explode_string (t_weechat_plugin *plugin, char *chaine, - char *separateurs, int num_items_max, int *num_items) - </command> - </para> - <para> - Explose une chaîne en plusieurs selon un/des délimiteur(s). - </para> - <para> - Paramètres : - <itemizedlist> - <listitem> - <para> - <option>plugin</option> : pointeur vers la structure - de l'extension - </para> - </listitem> - <listitem> - <para> - <option>chaine</option> : la chaîne à exploser - </para> - </listitem> - <listitem> - <para> - <option>separateurs</option> : les délimiteurs utilisés - pour exploser la chaîne - </para> - </listitem> - <listitem> - <para> - <option>num_items_max</option> : nombre maximum de - sous-chaînes créées (0 = pas de limite) - </para> - </listitem> - <listitem> - <para> - <option>num_items</option> : pointeur vers un entier qui - contiendra le nombre de sous-chaînes créées en retour - </para> - </listitem> - </itemizedlist> - </para> - <para> - Valeur renvoyée : un tableau de chaînes, ou NULL si un problème - a été rencontré. + Sorted list functions. </para> + + <section id="secPluginCApi_weechat_list_new"> + <title>weechat_list_new</title> + + <para> + Prototype: +<programlisting> +struct t_weelist *weechat_list_new (); +</programlisting> + </para> + <para> + Create a new list. + </para> + <para> + Return value: pointer to new list. + </para> + <para> + Example: + <screen>struct t_weelist *list = weechat_list_new ();</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_add"> + <title>weechat_list_add</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_add ( + struct t_weelist *weelist, + const char *data, + const char *where); +</programlisting> + </para> + <para> + Add an item in a list. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>weelist</option>: list pointer + </para> + </listitem> + <listitem> + <para> + <option>data</option>: data to insert in list + </para> + </listitem> + <listitem> + <para> + <option>where</option>: position in list (constants are: + WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING or + WEECHAT_LIST_POS_END) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to new item. + </para> + <para> + Example: + <screen>weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT);</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_search"> + <title>weechat_list_search</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_search ( + struct t_weelist *weelist, + const char *data); +</programlisting> + </para> + <para> + Search an item in a list. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>weelist</option>: list pointer + </para> + </listitem> + <listitem> + <para> + <option>data</option>: data to search in list + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to item found, NULL if item was not found. + </para> + <para> + Example: + <screen>struct t_weelist_item *item = weechat_list_search (list, "my data");</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_casesearch"> + <title>weechat_list_casesearch</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_casesearch ( + struct t_weelist *weelist, + const char *data); +</programlisting> + </para> + <para> + Search an item in a list (case sensitive search). + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>weelist</option>: list pointer + </para> + </listitem> + <listitem> + <para> + <option>data</option>: data to search in list + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to item found, NULL if item was not found. + </para> + <para> + Example: + <screen>struct t_weelist_item *item = weechat_list_casesearch (list, "my data");</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_get"> + <title>weechat_list_get</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_get ( + struct t_weelist *weelist, + int position); +</programlisting> + </para> + <para> + Get an item in a list by position. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>weelist</option>: list pointer + </para> + </listitem> + <listitem> + <para> + <option>position</option>: position in list (0 is first item) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to item found, NULL if item position was not + found. + </para> + <para> + Example: + <screen>struct t_weelist_item *item = weechat_list_get (list, 0); /* first item */</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_set"> + <title>weechat_list_set</title> + + <para> + Prototype: +<programlisting> +void weechat_list_set (struct t_weelist_item *item, const char *value); +</programlisting> + </para> + <para> + Set new value for an item. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>item</option>: item pointer + </para> + </listitem> + <listitem> + <para> + <option>value</option>: new value for item + </para> + </listitem> + </itemizedlist> + </para> + <para> + Example: + <screen>weechat_list_set (item, "new data");/</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_next"> + <title>weechat_list_next</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_next (struct t_weelist_item *item); +</programlisting> + </para> + <para> + Get next item in list. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>item</option>: item pointer + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to next item, NULL if pointer was last item in + list. + </para> + <para> + Example: + <screen>struct t_weelist_item *next_item = weechat_list_next_item (item);/</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_prev"> + <title>weechat_list_prev</title> + + <para> + Prototype: +<programlisting> +struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item); +</programlisting> + </para> + <para> + Get previous item in list. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>item</option>: item pointer + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to previous item, NULL if pointer was first item + in list. + </para> + <para> + Example: + <screen>struct t_weelist_item *prev_item = weechat_list_prev_item (item);/</screen> + </para> + </section> + + <section id="secPluginCApi_weechat_list_string"> + <title>weechat_list_string</title> + + <para> + Prototype: +<programlisting> +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> - Note : le résultat doit être libéré par un appel à la fonction - "free_exploded_string" après utilisation. + Functions for configuration files. </para> - <para> - Exemple : + + <section id="secPluginCApi_weechat_config_new"> + <title>weechat_config_new</title> + + <para> + Prototype: +<programlisting> +struct t_config_file *weechat_config_new ( + const char *name, + int (*callback_reload)(void *data, + struct t_config_file *config_file), + void *callback_reload_data); +</programlisting> + </para> + <para> + Create a new configuration file. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>name</option>: name of configuration file (without path + or extension) + </para> + </listitem> + <listitem> + <para> + <option>callback_reload</option>: callback called when + configuration file is reloaded with /reload (optional, may be + NULL), arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_reload_data</option>: pointer given to reload + callback when it is called by WeeChat + NULL) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to new configuration file, NULL if an error + occured. + </para> + <note> + <para> + File is NOT created by this function. It will be created by call to + function <xref linkend="secPluginCApi_weechat_config_write" /> (you + should do that only after adding some sections (with + <xref linkend="secPluginCApi_weechat_config_new_section" />) and + options (with + <xref linkend="secPluginCApi_weechat_config_new_option" />). + </para> + </note> + <para> + Example: <screen> -char **argv; -int argc; -argv = plugin->explode_string (plugin, chaine, " ", 0, &argc); -... -if (argv != NULL) - plugin->free_exploded_string (plugin, argv); +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", + &my_config_reload_cb, + NULL); </screen> - </para> + </para> + </section> + + <section id="secPluginCApi_weechat_config_new_section"> + <title>weechat_config_new_section</title> + + <para> + Prototype: +<programlisting> +struct t_config_section *weechat_config_new_section ( + struct t_config_file *config_file, + const char *name, + int user_can_add_options, + int user_can_delete_options, + int (*callback_read)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, + const char *value), + void *callback_read_data, + int (*callback_write)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name), + void *callback_write_data, + int (*callback_write_default)(void *data, + struct t_config_file *config_file, + const char *section_name); + void *callback_write_default_data, + int (*callback_create_option)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, + const char *value), + void *callback_create_option_data, + int (*callback_delete_option)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + struct t_config_option *option), + void *callback_delete_option_data); +</programlisting> + </para> + <para> + Create a new section in configuration file. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>config_file</option>: configuration file pointer + </para> + </listitem> + <listitem> + <para> + <option>name</option>: name of section + </para> + </listitem> + <listitem> + <para> + <option>user_can_add_options</option>: 1 if user can add options + in section, or 0 if it is forbidden + </para> + </listitem> + <listitem> + <para> + <option>user_can_delete_options</option>: 1 if user can delete + options in section, or 0 if it is forbidden + </para> + </listitem> + <listitem> + <para> + <option>callback_read</option>: callback called when an option + in section is read from disk (should be NULL for most cases, + except if options in your section need custom function), + arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>struct t_config_section *</entry> + <entry>section</entry> + <entry>section pointer</entry> + </row> + <row> + <entry>const char *</entry> + <entry>option_name</entry> + <entry>name of option</entry> + </row> + <row> + <entry>const char *</entry> + <entry>value</entry> + <entry>value</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_read_data</option>: pointer given to read + callback when it is called by WeeChat + NULL) + </para> + </listitem> + <listitem> + <para> + <option>callback_write</option>: callback called when section + is written in file (should be NULL for most cases, except if your + section needs to be written by a custom function), arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>struct t_config_section *</entry> + <entry>section</entry> + <entry>section pointer</entry> + </row> + <row> + <entry>const char *</entry> + <entry>option_name</entry> + <entry>name of option</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_write_data</option>: pointer given to write + callback when it is called by WeeChat + NULL) + </para> + </listitem> + <listitem> + <para> + <option>callback_write_default</option>: callback called when + default values for section must be written in file, arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>struct t_config_section *</entry> + <entry>section</entry> + <entry>section pointer</entry> + </row> + <row> + <entry>const char *</entry> + <entry>option_name</entry> + <entry>name of option</entry> + </row> + <row> + <entry>const char *</entry> + <entry>value</entry> + <entry>value</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_create_option_data</option>: pointer given to + create_option callback when it is called by WeeChat + NULL) + </para> + </listitem> + <listitem> + <para> + <option>callback_delete_option</option>: callback called when an + option is deleted (NULL if section does not allow options to be + deleted), arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_file *</entry> + <entry>config_file</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>struct t_config_section *</entry> + <entry>section</entry> + <entry>section pointer</entry> + </row> + <row> + <entry>struct t_config_option *option</entry> + <entry>option</entry> + <entry>option pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_delete_option_data</option>: pointer given to + delete_option callback when it is called by WeeChat + NULL) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to new section in configuration file, NULL if an + error occured. + </para> + <para> + Example: +<screen> +int +my_section_read_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, const char *option_name, + const char *value) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +my_section_write_cb (void *data, struct t_config_file *config_file, + const char *section_name) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +my_section_write_default_cb (void *data, struct t_config_file *config_file, + const char *section_name) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +my_section_create_option_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, const char *value) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +my_section_delete_option_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, + struct t_config_option *option) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +/* standard section, user can not add/delete options */ +struct t_config_section *new_section1 = + weechat_config_new ("section1", 0, 0, + NULL, NULL, /* read callback */ + NULL, NULL, /* write callback */ + NULL, NULL, /* write default callback */ + NULL, NULL, /* create option callback */ + NULL, NULL); /* delete option callback */ + +/* special section, user can add/delete options, and options need + callback to be read/written */ +struct t_config_section *new_section2 = + weechat_config_new ("section2", 1, 1, + &my_section_read_cb, NULL, + &my_section_write_cb, NULL, + &my_section_write_default_cb, NULL, + &my_section_create_option_cb, NULL, + &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_option *</entry> + <entry>option</entry> + <entry>option pointer</entry> + </row> + <row> + <entry>const char *</entry> + <entry>value</entry> + <entry>new value for option</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_check_value_data</option>: pointer given to + check_value callback when it is called by WeeChat + NULL) + </para> + </listitem> + <listitem> + <para> + <option>callback_change</option>: callback called when value of + option has changed (optional), arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_option *</entry> + <entry>option</entry> + <entry>option pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_change_data</option>: pointer given to change + callback when it is called by WeeChat + NULL) + </para> + </listitem> + <listitem> + <para> + <option>callback_delete</option>: callback called when option + will be deleted (optional), arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_config_option *</entry> + <entry>option</entry> + <entry>option pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_delete_data</option>: pointer given to delete + callback when it is called by WeeChat + NULL) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Return value: pointer to new option in section, NULL if an error + occured. + </para> + <para> + Example: +<screen> +/* boolean */ +struct t_config_option *option1 = + weechat_config_new_option (config_file, section, + "option1", "My option, type boolean" + NULL, /* string values */ + 0, 0, /* min, max */ + "on", /* default */ + "on", /* value */ + 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", + &ptr_config_file, + &ptr_section, + &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="2"> + <thead> + <row> + <entry>Property</entry> + <entry>Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>config_file</entry> + <entry>struct t_config_file *</entry> + <entry>configuration file pointer</entry> + </row> + <row> + <entry>section</entry> + <entry>struct t_config_section *</entry> + <entry>section pointer</entry> + </row> + <row> + <entry>name</entry> + <entry>char *</entry> + <entry>option name</entry> + </row> + <row> + <entry>type</entry> + <entry>int</entry> + <entry>option type</entry> + </row> + <row> + <entry>description</entry> + <entry>char *</entry> + <entry>option description</entry> + </row> + <row> + <entry>string_values</entry> + <entry>char **</entry> + <entry>string values</entry> + </row> + <row> + <entry>min</entry> + <entry>int</entry> + <entry>minimum value</entry> + </row> + <row> + <entry>max</entry> + <entry>int</entry> + <entry>maximum value</entry> + </row> + <row> + <entry>default_value</entry> + <entry>(depends on type)</entry> + <entry>default value</entry> + </row> + <row> + <entry>value</entry> + <entry>(depends on type)</entry> + <entry>current value</entry> + </row> + <row> + <entry>prev_option</entry> + <entry>struct t_config_option *</entry> + <entry>previous option pointer</entry> + </row> + <row> + <entry>next_option</entry> + <entry>struct t_config_option *</entry> + <entry>next option pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + </itemizedlist> + </para> + <para> + 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> - <section id="secAPI_free_exploded_string"> - <title>free_exploded_string</title> + <!-- ============================[ display ]============================= --> + + <section id="secPluginCApi_display"> + <title>Display</title> <para> - Prototype : - <command> - char **free_exploded_string (t_weechat_plugin *plugin, - char **chaine) - </command> + 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="2"> + <thead> + <row> + <entry>Prefix</entry> + <entry>Default value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>error</entry> + <entry>=!=</entry> + <entry>error message</entry> + </row> + <row> + <entry>network</entry> + <entry>--</entry> + <entry>message from network</entry> + </row> + <row> + <entry>action</entry> + <entry>*</entry> + <entry>self action</entry> + </row> + <row> + <entry>join</entry> + <entry>--></entry> + <entry>someone joins current chat</entry> + </row> + <row> + <entry>quit</entry> + <entry><--</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: may 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> - Libère la mémoire utilisée pour une explosion de chaîne. + Functions to hook/unhook something. </para> + + <section id="secPluginCApi_weechat_hook_command"> + <title>weechat_hook_command</title> + + <para> + Prototype: +<programlisting> +struct t_hook *weechat_hook_command ( + const char *command, + const char *description, + const char *args, + const char *args_description, + const char *completion, + int (*callback)(void *data, + struct t_gui_buffer *buffer, + int argc, char **argv, + char **argv_eol), + void *callback_data); +</programlisting> + </para> + <para> + Hook a command. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>command</option>: new command name + </para> + </listitem> + <listitem> + <para> + <option>description</option>: description of command (displayed + with <command>/help command</command>) + </para> + </listitem> + <listitem> + <para> + <option>args</option>: arguments for command (displayed with + <command>/help command</command>) + </para> + </listitem> + <listitem> + <para> + <option>args_description</option>: description of arguments + (displayed with <command>/help command</command>) + </para> + </listitem> + <listitem> + <para> + <option>completion</option>: completion template for command: + list of completions for each arguments, separated by space. Many + completions are possible for one argument, separated by "|". + Default completion codes are: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Code</entry> + <entry>Completion</entry> + </row> + </thead> + <tbody> + <row> + <entry>%-</entry> + <entry>Stop completion</entry> + </row> + <row> + <entry>%*</entry> + <entry>Repeat last completion</entry> + </row> + <row> + <entry>%b</entry> + <entry>Buffers names</entry> + </row> + <row> + <entry>%B</entry> + <entry>Buffers names (with plugin name)</entry> + </row> + <row> + <entry>%c</entry> + <entry>Configuration files</entry> + </row> + <row> + <entry>%f</entry> + <entry>Filename</entry> + </row> + <row> + <entry>%F</entry> + <entry>Filters</entry> + </row> + <row> + <entry>%h</entry> + <entry>Commands hooked</entry> + </row> + <row> + <entry>%i</entry> + <entry>Infos hooked</entry> + </row> + <row> + <entry>%I</entry> + <entry>Infolists hooked</entry> + </row> + <row> + <entry>%n</entry> + <entry>Nick</entry> + </row> + <row> + <entry>%o</entry> + <entry>Configuration option</entry> + </row> + <row> + <entry>%p</entry> + <entry>Plugin name</entry> + </row> + <row> + <entry>%P</entry> + <entry>Plugin commands</entry> + </row> + <row> + <entry>%r</entry> + <entry>Bar names</entry> + </row> + <row> + <entry>%v</entry> + <entry>Value of configuration option</entry> + </row> + <row> + <entry>%w</entry> + <entry>WeeChat commands</entry> + </row> + <row> + <entry>%(xxx)</entry> + <entry>Custom completion by plugin (xxx is a completion + code added by a plugin)</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback</option>: function called when command is used, + arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_gui_buffer *</entry> + <entry>buffer</entry> + <entry>buffer where command is executed</entry> + </row> + <row> + <entry>int</entry> + <entry>argc</entry> + <entry>argument count</entry> + </row> + <row> + <entry>char **</entry> + <entry>argv</entry> + <entry>arguments</entry> + </row> + <row> + <entry>char **</entry> + <entry>argv_eol</entry> + <entry>arguments (until end of line)</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + <para> + For example, if command called is + <command>/command abc def ghi</command>, then argv and argv_eol + contain following values: + <itemizedlist> + <listitem><para>argv[0] == "abc"</para></listitem> + <listitem><para>argv[1] == "def"</para></listitem> + <listitem><para>argv[2] == "ghi"</para></listitem> + <listitem><para>argv_eol[0] == "abc def ghi"</para></listitem> + <listitem><para>argv_eol[1] == "def ghi"</para></listitem> + <listitem><para>argv_eol[2] == "ghi"</para></listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + <option>callback_data</option>: pointer given to callback when it + is called by WeeeChat + </para> + </listitem> + </itemizedlist> + </para> + <para> + 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; +} + +struct t_hook *my_command_hook = + weechat_hook_command ("mycommand", + "description of my command", + "[command [buffer]]", + "command: WeeChat or plugin command\n" + " buffer: buffer name", + "%w|%p %b", &my_command_cb, 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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_gui_buffer *</entry> + <entry>buffer</entry> + <entry>buffer where command is executed</entry> + </row> + <row> + <entry>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*", + &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>int</entry> + <entry>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, &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>int</entry> + <entry>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, &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>const char *</entry> + <entry>command</entry> + <entry>command executed by child</entry> + </row> + <row> + <entry>int</entry> + <entry>return_code</entry> + <entry> + if >= 0, it's child (command) return code (it's last + call to this callback), if < 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 >= 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, &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>int</entry> + <entry>status</entry> + <entry> + constant with connection status: + <itemizedlist> + <listitem> + <para>WEECHAT_HOOK_CONNECT_OK</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_PROXY_ERROR</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR</para> + </listitem> + <listitem> + <para>WEECHAT_HOOK_CONNECT_MEMORY_ERROR</para> + </listitem> + </itemizedlist> + </entry> + </row> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </listitem> + <listitem> + <para> + <option>callback_data</option>: pointer given to callback when it + is called by WeeeChat + </para> + </listitem> + </itemizedlist> + </para> + <para> + 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, &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_gui_buffer *</entry> + <entry>buffer</entry> + <entry>buffer pointer</entry> + </row> + <row> + <entry>time_t</entry> + <entry>date</entry> + <entry>date</entry> + </row> + <row> + <entry>int</entry> + <entry>tags_count</entry> + <entry>number of tags for line</entry> + </row> + <row> + <entry>const char **</entry> + <entry>tags</entry> + <entry>tags for line</entry> + </row> + <row> + <entry>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, &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 + </para> + </listitem> + <listitem> + <para> + <option>callback</option>: function called when signal is + received, arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", + &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", + &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", + &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 (you should look at + core and plugins doc to find name of existing modifiers) + </para> + </listitem> + <listitem> + <para> + <option>callback</option>: function called when modifier is + received, arguments: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", + &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", + &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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>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", + &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> - Paramètres : - <itemizedlist> - <listitem> - <para> - <option>plugin</option> : pointeur vers la structure - de l'extension - </para> - </listitem> - <listitem> - <para> - <option>chaine</option> : la chaîne explosée par la fonction - "explode_string" - </para> - </listitem> - </itemizedlist> + 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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_gui_buffer *</entry> + <entry>buffer</entry> + <entry>buffer pointer</entry> + </row> + <row> + <entry>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="2"> + <thead> + <row> + <entry>Type</entry> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>void *</entry> + <entry>data</entry> + <entry>pointer</entry> + </row> + <row> + <entry>struct t_gui_buffer *</entry> + <entry>buffer</entry> + <entry>buffer pointer</entry> + </row> + </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", + &my_input_cb, NULL, &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", + &my_input_cb, NULL, &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="2"> + <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="2"> + <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", &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> - Valeur renvoyée : aucune. + Functions to query windows. </para> - <para> - Exemple : + + <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> -char *argv; -int argc; -argv = plugin->explode_string (plugin, chaine, " ", 0, &argc); -... -if (argv != NULL) - plugin->free_exploded_string (plugin, argv); +struct t_gui_window *current_window = weechat_current_window (); </screen> - </para> + </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> - <section id="secAPI_mkdir_home"> - <title>mkdir_home</title> + <!-- ============================[ nicklist ]============================ --> + + <section id="secPluginCApi_nicklist"> + <title>Nicklist</title> <para> - Prototype : - <command> - int mkdir_home (t_weechat_plugin *plugin, char *repertoire) - </command> + 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> - Créé un répertoire dans le répertoire de base de WeeChat. + 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", + &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 (&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> - Paramètres : - <itemizedlist> - <listitem> - <para> - <option>plugin</option> : pointeur vers la structure - de l'extension - </para> - </listitem> - <listitem> - <para> - <option>repertoire</option> : répertoire à créer - </para> - </listitem> - </itemizedlist> + 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> - Valeur renvoyée : 1 si le répertoire a été créé avec succès, - 0 si une erreur s'est produite. + Network functions. </para> - <para> - Example: + + <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 (!plugin->mkdir_home (plugin, "temp")) - plugin->print_server(plugin, "Impossible de créer le répertoire 'temp' dans la base WeeChat."); +if (weechat_network_pass_proxy ("myproxy", sock, "irc.freenode.net", 6667)) +{ + /* OK */ +} +else +{ + /* error */ +} </screen> - </para> + </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 (&addr, 0, sizeof (struct sockaddr_in)); +length = sizeof (addr); +getsockname (sock, (struct sockaddr *) &addr, &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> - <section id="secAPI_exec_on_files"> - <title>exec_on_files</title> + <!-- =============================[ infos ]============================== --> + + <section id="secPluginCApi_infos"> + <title>Infos</title> <para> - Prototype : - <command> - void exec_on_files (t_weechat_plugin *plugin, char *repertoire, - int (*callback)(t_weechat_plugin *, char *)) - </command> + 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 other plugin. + </para> + <para> + Arguments: + <itemizedlist> + <listitem> + <para> + <option>info_name</option>: info name to read, from WeeChat + core or other plugin (see plugin doc for infos returned by + each plugin). WeeChat core infos are: + <informaltable colsep="0" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Info</entry> + <entry>Description</entry> + <entry>Example</entry> + </row> + </thead> + <tbody> + <row> + <entry>version</entry> + <entry>WeeChat version</entry> + <entry>0.2.7</entry> + </row> + <row> + <entry>date</entry> + <entry>WeeChat compilation date</entry> + <entry>Dec 25 2008</entry> + </row> + <row> + <entry>dir_separator</entry> + <entry> + directory separator: "/" under GNU/Linux, "\" under + MS-Windows + </entry> + <entry>/</entry> + </row> + <row> + <entry>weechat_dir</entry> + <entry>WeeChat home directory</entry> + <entry>/home/login/.weechat</entry> + </row> + <row> + <entry>weechat_libdir</entry> + <entry>WeeChat lib directory</entry> + <entry>/usr/lib/weechat</entry> + </row> + <row> + <entry>weechat_sharedir</entry> + <entry>WeeChat share directory</entry> + <entry>/usr/share/weechat</entry> + </row> + <row> + <entry>weechat_localedir</entry> + <entry>WeeChat locale directory</entry> + <entry>/usr/share/locale</entry> + </row> + <row> + <entry>charset_terminal</entry> + <entry>terminal charset</entry> + <entry>UTF-8</entry> + </row> + <row> + <entry>charset_internal</entry> + <entry>internal WeeChat charset (always "UTF-8")</entry> + <entry>UTF-8</entry> + </row> + <row> + <entry>inactivity</entry> + <entry>keyboard inactivity (in seconds)</entry> + <entry>12</entry> + </row> + <row> + <entry>filters_enabled</entry> + <entry>1 if filters are enabled, otherwise 0</entry> + <entry>1</entry> + </row> + </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> - Exécute une fonction sur tous les fichiers d'un répertoire. + Functions for infolists. </para> + <para> - Paramètres : - <itemizedlist> - <listitem> - <para> - <option>plugin</option> : pointeur vers la structure - de l'extension - </para> - </listitem> - <listitem> - <para> - <option>repertoire</option> : le répertoire où les fichiers - sont recherchés - </para> - </listitem> - <listitem> - <para> - <option>callback</option> : une fonction appelée pour chaque - fichier trouvé - </para> - </listitem> - </itemizedlist> + Missing doc! </para> + + </section> + + <!-- ============================[ upgrade ]============================= --> + + <section id="secPluginCApi_upgrade"> + <title>Upgrade</title> + <para> - Valeur renvoyée : aucune. + Functions for WeeChat upgrading. </para> + <para> - Exemple : -<screen> -int callback (t_weechat_plugin *plugin, char *fichier) -{ - plugin->print_server (plugin, "fichier: %s", fichier); - return 1; -} -... -plugin->exec_on_files (plugin, "/tmp", &callback); -</screen> + Missing doc! </para> + </section> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + <!-- ==================================================================== --> + + + <!-- + To be continued... + + + <section id="secAPI_print"> <title>print</title> <para> - Prototype : + Prototype: <command> void print (t_weechat_plugin *plugin, - char *serveur, char *canal, char *message, ...) + char *server, char *channel, char *message, ...) </command> </para> <para> - Affiche un message sur un tampon WeeChat, identifié par le serveur - et le canal (tous deux pouvant être NULL pour le tampon courant). + Display a message on a WeeChat buffer, identified by server and + channel (both may be NULL for current buffer). </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>serveur</option> : nom interne du serveur pour - trouver le tampon dans lequel afficher (peut être NULL) + <option>server</option>: internal name of server to find + buffer for message display (may be NULL) </para> </listitem> <listitem> <para> - <option>canal</option> : nom du canal pour trouver le - tampon dans lequel afficher (peut être NULL) + <option>channel</option>: name of channel to find buffer + for message display (may be NULL) </para> </listitem> <listitem> <para> - <option>message</option> : message à afficher + <option>message</option>: message </para> </listitem> </itemizedlist> </para> <para> - Pour afficher du texte en couleur, il faut utiliser les codes - suivants : + To display colored text, there are following codes: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> @@ -518,63 +9202,59 @@ plugin->exec_on_files (plugin, "/tmp", &callback); <row> <entry>0x02</entry> <entry> - texte gras + bold text </entry> </row> <row> <entry>0x03 + "xx"</entry> <entry> - couleur du texte "<literal>xx</literal>" - (voir <xref linkend="secAPI_get_irc_color" /> pour les - couleurs) + text color "<literal>xx</literal>" + (see <xref linkend="secAPI_get_irc_color" /> for colors) </entry> </row> <row> <entry>0x03 + "xx,yy"</entry> <entry> - couleur du texte "<literal>xx</literal>" - et du fond "<literal>yy</literal>" - (voir <xref linkend="secAPI_get_irc_color" /> pour les - couleurs) + text color "<literal>xx</literal>" + and background "<literal>yy</literal>" + (see <xref linkend="secAPI_get_irc_color" /> for colors) </entry> </row> <row> <entry>0x0F</entry> <entry> - désactiver la couleur et tous les attributs + disable color and attributes </entry> </row> <row> <entry>0x12</entry> <entry> - vidéo inverse (inversion de la couleur d'écriture et du - fond) + reverse video (revert text color with background) </entry> </row> <row> <entry>0x1F</entry> <entry> - texte souligné + underlined text </entry> </row> </tbody> </tgroup> </informaltable> - NB: le même code (sans le numéro pour 0x03) peut être utilisé pour - stopper l'attribut défini. + Note: the same code (without number for 0x03) may be used to stop + the attribute. </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemples : + Examples: <screen> plugin->print (plugin, NULL, NULL, "hello"); plugin->print (plugin, NULL, "#weechat", "hello"); plugin->print (plugin, "freenode", "#weechat", "hello"); -plugin->print (plugin, "freenode", "#weechat", "hello"); plugin->print (plugin, NULL, NULL, - "test: \x02 gras \x0F\x03%02d bleu \x03%02d vert", + "test: \x02 bold \x0F\x03%02d blue \x03%02d green", plugin->get_irc_color (plugin, "blue"), plugin->get_irc_color (plugin, "green")); </screen> @@ -585,40 +9265,38 @@ plugin->print (plugin, NULL, NULL, <title>print_server</title> <para> - Prototype : + Prototype: <command> void print_server (t_weechat_plugin *plugin, char *message, ...) </command> </para> <para> - Affiche un message sur le tampon du serveur courant. + Display a message on current server buffer. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>message</option> : message à afficher + <option>message</option>: message </para> </listitem> </itemizedlist> </para> <para> - Pour afficher du texte en couleur, voir - <xref linkend="secAPI_print" />. + To display colored text, see <xref linkend="secAPI_print" />. </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : <screen>plugin->print_server (plugin, "hello");</screen> + Example: <screen>plugin->print_server (plugin, "hello");</screen> </para> </section> @@ -626,49 +9304,47 @@ plugin->print (plugin, NULL, NULL, <title>log</title> <para> - Prototype : + Prototype: <command> void log (t_weechat_plugin *plugin, - char *serveur, char *canal, char *message, ...) + char *server, char *channel, char *message, ...) </command> </para> <para> - Ecrit un message dans le fichier de log pour un serveur ou un - canal. + Write a message in log file for a server or a channel. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>serveur</option> : nom interne du serveur pour - trouver le log du tampon (peut être NULL) + <option>server</option>: internal name of server to find + buffer for log (may be NULL) </para> </listitem> <listitem> <para> - <option>canal</option> : nom du canal pour trouver le - tampon le log du tampon (peut être NULL) + <option>channel</option>: name of channel to find buffer + for log (may be NULL) </para> </listitem> <listitem> <para> - <option>message</option> : message + <option>message</option>: message </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen> plugin->log (plugin, "freenode", "#weechat", "test"); </screen> @@ -679,67 +9355,65 @@ plugin->log (plugin, "freenode", "#weechat", "test"); <title>msg_handler_add</title> <para> - Prototype : + Prototype: <command> t_plugin_handler *msg_handler_add (t_weechat_plugin - *plugin, char *message, t_plugin_handler_func *fonction, + *plugin, char *message, t_plugin_handler_func *function, char *handler_args, void *handler_pointer) </command> </para> <para> - Ajoute un gestionnaire de messages IRC, appelé dès qu'un message - IRC est reçu. + Add an IRC message handler, called when an IRC message is + received. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>message</option> : nom du message IRC pour lequel la - fonction est appelée ("*" pour tous les messages). - Pour connaître la liste des messages IRC disponibles, merci - de consulter les <acronym>RFC</acronym>s + <option>message</option>: name of IRC message ("*" for all + messages). + To know list of IRC messages, please consult + <acronym>RFC</acronym>s <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink> - et + and <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink>. - De plus, vous pouvez utiliser un nom spécial, préfixé par - "weechat_" pour capturer des évènements spéciaux, comme - décrit dans le tableau ci-dessous : + Moreover you can use a special name, prefixed by "weechat_" + to catch special events, as written in table below: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Nom</entry> + <entry>Name</entry> <entry>Description</entry> </row> </thead> <tbody> <row> <entry><literal>weechat_pv</literal></entry> - <entry>message privé reçu</entry> + <entry>private message received</entry> </row> <row> <entry><literal>weechat_highlight</literal></entry> <entry> - message avec highlight (sur un canal ou en privé) + message with highlight (on a channel or pv) </entry> </row> <row> <entry><literal>weechat_ctcp</literal></entry> <entry> - message CTCP reçu (VERSION, PING, etc...) + CTCP message received (VERSION, PING, ..) </entry> </row> <row> <entry><literal>weechat_dcc</literal></entry> <entry> - message DCC reçu (discussion ou fichier) + DCC message received (chat or file) </entry> </row> </tbody> @@ -749,98 +9423,99 @@ plugin->log (plugin, "freenode", "#weechat", "test"); </listitem> <listitem> <para> - <option>fonction</option> : fonction appelée lorsque le - message est reçu + <option>function</option>: function called when message + is received </para> <para> - Elle a le prototype suivant : + It uses following prototype: <command> - int ma_fonction (t_weechat_plugin *plugin, + int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) </command> </para> <para> - Le paramètre argc vaut 3 et les arguments suivants sont - passés dans le tableau argv : + Argument argc is set to 3, following values are set in + argv array: <itemizedlist> <listitem> - <para>argv[0] = nom du serveur</para> + <para>argv[0] = server name</para> </listitem> <listitem> - <para>argv[1] = message IRC</para> + <para>argv[1] = IRC message</para> </listitem> <listitem> - <para>argv[2] = arguments de la commande</para> + <para>argv[2] = command arguments</para> </listitem> </itemizedlist> </para> </listitem> <listitem> <para> - <option>handler_args</option> : paramètres passés à la - fonction appelée + <option>handler_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>handler_pointer</option> : pointeur passé à la - fonction appelée + <option>handler_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : le pointeur vers le nouveau gestionnaire de - messages. + Return value: pointer to new message handler. </para> <para> - Note : la fonction appelée lorsque le message est reçu doit - renvoyer une des valeurs suivantes : + Note: function called when message is received has to return + one of following values: <itemizedlist> <listitem> <para> - <literal>PLUGIN_RC_KO</literal> : la fonction a échoué + <literal>PLUGIN_RC_KO</literal>: function failed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK</literal> : la fonction a réussi + <literal>PLUGIN_RC_OK</literal>: function successfully + completed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK_IGNORE_WEECHAT</literal> : le message - ne sera pas transmis à WeeChat + <literal>PLUGIN_RC_OK_IGNORE_WEECHAT</literal>: message + will not be sent to WeeChat </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK_IGNORE_PLUGINS</literal> : le message - ne sera pas transmis à d'autres extensions + <literal>PLUGIN_RC_OK_IGNORE_PLUGINS</literal>: message + will not be sent to other plugins </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK_IGNORE_ALL</literal> : le message - ne sera ni transmis à WeeChat ni à d'autres extensions + <literal>PLUGIN_RC_OK_IGNORE_ALL</literal>: message + will not be sent to WeeChat neither other plugins </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK_WITH_HIGHLIGHT</literal> : la fonction - a réussi et provoque un "highlight" sur le message reçu + <literal>PLUGIN_RC_OK_WITH_HIGHLIGHT</literal>: function + successfully completed and make "highlight" on received + message </para> </listitem> </itemizedlist> </para> <para> - Exemple : + Example: <screen> int msg_kick (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) { - plugin->print (plugin, argv[0], NULL, "KICK reçu"); + plugin->print (plugin, argv[0], NULL, "KICK received"); return PLUGIN_RC_OK; } ... @@ -855,67 +9530,64 @@ msg_handler = plugin->msg_handler_add (plugin, "KICK", <title>cmd_handler_add</title> <para> - Prototype : + Prototype: <command> t_plugin_handler *cmd_handler_add (t_weechat_plugin - *plugin, char *commande, char *description, char *arguments, - char *arguments_description, char *modele_completion, + *plugin, char *command, char *description, char *arguments, + char *arguments_description, char *completion_template, t_plugin_handler_func *fonction, char *handler_args, void *handler_pointer) </command> </para> <para> - Ajoute un gestionnaire de commande WeeChat, appelé dès que - l'utilisateur utilise la commande (par exemple /commande). + Add a WeeChat command handler, called when user uses command + (for example /command). </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>commande</option> : nom de la nouvelle commande, - qui peut être une commande déjà existante (attention la - commande remplacée ne sera plus disponible jusqu'à ce que - l'extension soit déchargée) + <option>command</option>: the new command name, which + may be an existing command (be careful, replaced command + will not be available until plugin is unloaded) </para> </listitem> <listitem> <para> - <option>description</option> : brève description de la - commande (affichée par /help commande) + <option>description</option>: short command description + (displayed by /help command) </para> </listitem> <listitem> <para> - <option>arguments</option> : brève description des - paramètres de la commande (affichée par /help commande) + <option>arguments</option>: short description of command + arguments (displayed by /help command) </para> </listitem> <listitem> <para> - <option>arguments_description</option> : longue description - des paramètres de la commande (affichée par /help commande) + <option>arguments_description</option>: long description + of command arguments (displayed by /help command) </para> </listitem> <listitem> <para> - <option>modele_completion</option> : modèle pour la - complétion sous la forme "<literal>abc|%w def|%i</literal>" - qui signifie "abc" ou une commande WeeChat pour le premier - paramètre, et "def" ou une commande IRC pour le deuxième. - Une chaîne vide indique à WeeChat de compléter tout - paramètre avec un pseudo du canal courant, une valeur NULL - ou égale à "-" désactive toute complétion pour tous les - paramètres de la commande. + <option>completion_template</option>: template for + completion, like "<literal>abc|%w def|%i</literal>" + which means "abc" or a WeeChat command for first argument, + "def" or IRC command for second. + An empty string lets WeeChat complete any argument with + a nick from current channel, NULL or "-" disable completion + for all command arguments. </para> <para> - Les codes suivants peuvent être utilisés : + Following codes can be used: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> @@ -927,14 +9599,14 @@ msg_handler = plugin->msg_handler_add (plugin, "KICK", <tbody> <row> <entry><literal>%-</literal></entry> - <entry>aucune complétion pour le paramètre</entry> + <entry>no completion for argument</entry> </row> <row> <entry><literal>%*</literal></entry> <entry> - répétition de la dernière complétion pour tous - les paramètres suivants (ce code doit être à la - fin du modèle de complétion, précédé d'un "|") + repeat last completion for all following arguments + (this code has to be at the end of completion + template, preceded by "|") </entry> </row> <row> @@ -944,98 +9616,94 @@ msg_handler = plugin->msg_handler_add (plugin, "KICK", <row> <entry><literal>%A</literal></entry> <entry> - alias et commandes (WeeChat, IRC et extensions) + alias and commands (WeeChat, IRC and plugins) </entry> </row> <row> <entry><literal>%c</literal></entry> - <entry>canal courant</entry> + <entry>current channel</entry> </row> <row> <entry><literal>%C</literal></entry> - <entry>tous les canaux (y compris les privés)</entry> + <entry>all channels (including queries)</entry> </row> <row> <entry><literal>%f</literal></entry> - <entry>nom de fichier</entry> + <entry>file name</entry> </row> <row> <entry><literal>%h</literal></entry> - <entry>commandes définies par des extensions</entry> + <entry>plugins commands</entry> </row> <row> <entry><literal>%i</literal></entry> - <entry>commandes IRC (envoyées)</entry> + <entry>IRC commands (sent)</entry> </row> <row> <entry><literal>%I</literal></entry> - <entry>commandes IRC (reçues)</entry> + <entry>IRC commands (received)</entry> </row> <row> <entry><literal>%k</literal></entry> - <entry>fonctions associées aux touches</entry> + <entry>key functions</entry> </row> <row> <entry><literal>%m</literal></entry> - <entry>pseudo sur le serveur courant</entry> + <entry>nick on current server</entry> </row> <row> <entry><literal>%M</literal></entry> <entry> - pseudos sur le serveur courant - (tous les canaux ouverts) + nicks on current server (on all open channels) </entry> </row> <row> <entry><literal>%n</literal></entry> - <entry>pseudos du canal courant</entry> + <entry>nicks of current channel</entry> </row> <row> <entry><literal>%N</literal></entry> - <entry> - pseudos et noms de machines du canal - courant - </entry> + <entry>nicks and hostnames of current channel</entry> </row> <row> <entry><literal>%o</literal></entry> - <entry>options de configuration</entry> + <entry>setup options</entry> </row> <row> <entry><literal>%O</literal></entry> - <entry>options des extensions</entry> + <entry>plugin options</entry> </row> <row> <entry><literal>%p</literal></entry> - <entry>message de "part" par défaut</entry> + <entry>default "part" message</entry> </row> <row> <entry><literal>%q</literal></entry> - <entry>message de "quit" par défaut</entry> + <entry>default "quit" message</entry> </row> <row> <entry><literal>%s</literal></entry> - <entry>nom du serveur courant</entry> + <entry>current server name</entry> </row> <row> <entry><literal>%S</literal></entry> - <entry>tous les serveurs</entry> + <entry>all servers names</entry> </row> <row> <entry><literal>%t</literal></entry> - <entry>titre du canal courant</entry> + <entry>topic of current channel</entry> </row> <row> <entry><literal>%v</literal></entry> - <entry>valeur d'une option de configuration</entry> + <entry>setup option value</entry> </row> <row> <entry><literal>%V</literal></entry> - <entry>valeur d'une option d'extension</entry> + <entry>plugin option value</entry> </row> <row> <entry><literal>%w</literal></entry> - <entry>commandes WeeChat</entry> + <entry>WeeChat commands</entry> </row> </tbody> </tgroup> @@ -1044,82 +9712,82 @@ msg_handler = plugin->msg_handler_add (plugin, "KICK", </listitem> <listitem> <para> - <option>fonction</option> : fonction appelée lorsque la - commande est exécutée. + <option>function</option>: function called when command + is executed </para> <para> - Elle a le prototype suivant : + It uses following prototype: <command> - int ma_fonction (t_weechat_plugin *plugin, + int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) </command> </para> <para> - Le paramètre argc vaut 3 et les arguments suivants sont - passés dans le tableau argv : + Argument argc is set to 3, following values are set in + argc array: <itemizedlist> <listitem> - <para>argv[0] = nom du serveur</para> + <para>argv[0] = server name</para> </listitem> <listitem> - <para>argv[1] = commande</para> + <para>argv[1] = command</para> </listitem> <listitem> - <para>argv[2] = arguments de la commande</para> + <para>argv[2] = command arguments</para> </listitem> </itemizedlist> </para> </listitem> <listitem> <para> - <option>handler_args</option> : paramètres passés à la - fonction appelée + <option>handler_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>handler_pointer</option> : pointeur passé à la - fonction appelée + <option>handler_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : le pointeur vers le nouveau gestionnaire de - commande. + Return value: pointer to new command handler. </para> <para> - Note : la fonction appelée lorsque la commande est exécutée doit - renvoyer une des valeurs suivantes : + Note: function called when command is executed has to return + one of following values: <itemizedlist> <listitem> <para> - <literal>PLUGIN_RC_KO</literal> : la fonction a échoué + <literal>PLUGIN_RC_KO</literal>: function failed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK</literal> : la fonction a réussi + <literal>PLUGIN_RC_OK</literal>: function successfully + completed </para> </listitem> </itemizedlist> </para> <para> - Exemple : + Example: <screen> int cmd_test (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) { plugin->print (plugin, argv[0], NULL, - "commande test, pseudo: %s", - (argv[2]) ? argv[2] : "aucun"); + "test command, nick: %s", + (argv[2]) ? argv[2] : "none"); return PLUGIN_RC_OK; } ... t_plugin_handler *cmd_handler; -cmd_handler = plugin->cmd_handler_add (plugin, "test", "Commande test", - "[pesudo]", "pseudo: un pseudo du canal", +cmd_handler = plugin->cmd_handler_add (plugin, "test", "Test command", + "[nick]", "nick: nick of channel", "%n", &cmd_test, NULL, NULL); </screen> </para> @@ -1129,94 +9797,91 @@ cmd_handler = plugin->cmd_handler_add (plugin, "test", "Commande test", <title>timer_handler_add</title> <para> - Prototype : + Prototype: <command> t_plugin_handler *timer_handler_add (t_weechat_plugin - *plugin, int intervalle, t_plugin_handler_func *fonction, + *plugin, int interval, t_plugin_handler_func *function, char *handler_args, void *handler_pointer) </command> </para> <para> - Ajoute un gestionnaire de temps, qui appelle périodiquement une - fonction. + Add a timer handler which periodically calls a function. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>intervalle</option> : intervalle (en secondes) - entre deux appels de la fonction. + <option>interval</option>: interval (in seconds) between + two calls of function. </para> </listitem> <listitem> <para> - <option>fonction</option> : fonction appelée + <option>function</option>: function called </para> <para> - Elle a le prototype suivant : + It uses following prototype: <command> - int ma_fonction (t_weechat_plugin *plugin, + int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) </command> </para> <para> - Le paramètre argc vaut 0 et argv vaut NULL. + Argument argc is set to 0, and argv is set to NULL. </para> </listitem> <listitem> <para> - <option>handler_args</option> : paramètres passés à la - fonction appelée + <option>handler_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>handler_pointer</option> : pointeur passé à la - fonction appelée + <option>handler_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : le pointeur vers le nouveau gestionnaire de - temps. + Return value: pointer to new timer handler. </para> <para> - Note : la fonction appelée doit renvoyer une des valeurs - suivantes : + Note: function called has to return one of following values: <itemizedlist> <listitem> <para> - <literal>PLUGIN_RC_KO</literal> : la fonction a échoué + <literal>PLUGIN_RC_KO</literal>: function failed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK</literal> : la fonction a réussi + <literal>PLUGIN_RC_OK</literal>: function successfully + completed </para> </listitem> </itemizedlist> </para> <para> - Exemple : + Example: <screen> -int mon_timer (t_weechat_plugin *plugin, int argc, char **argv, - char *handler_args, void *handler_pointer) +int my_timer (t_weechat_plugin *plugin, int argc, char **argv, + char *handler_args, void *handler_pointer) { - plugin->print (plugin, NULL, NULL, "mon timer"); + plugin->print (plugin, NULL, NULL, "my timer"); return PLUGIN_RC_OK; } ... t_plugin_handler *timer_handler; -timer_handler = plugin->timer_handler_add (plugin, 60, &mon_timer); +timer_handler = plugin->timer_handler_add (plugin, 60, &my_timer); </screen> </para> </section> @@ -1225,58 +9890,54 @@ timer_handler = plugin->timer_handler_add (plugin, 60, &mon_timer); <title>keyboard_handler_add</title> <para> - Prototype : + Prototype: <command> t_plugin_handler *keyboard_handler_add (t_weechat_plugin - *plugin, t_plugin_handler_func *fonction, + *plugin, t_plugin_handler_func *function, char *handler_args, void *handler_pointer) </command> </para> <para> - Ajoute un gestionnaire de clavier, appelé dès qu'une touche est - pressée. + Add a keyboard handler, called for any key pressed. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>fonction</option> : fonction appelée + <option>function</option>: function called </para> <para> - Elle a le prototype suivant : + It uses following prototype: <command> - int ma_fonction (t_weechat_plugin *plugin, + int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) </command> </para> <para> - Le paramètre argc vaut 3 et les arguments suivants sont - passés dans le tableau argv : + Argument argc is set to 3, following values are set in + argc array: <itemizedlist> <listitem> <para> - argv[0] = touche appuyée (nom d'une fonction interne - ou bien '*' suivi du code d'une touche) + argv[0] = key pressed (name of internal function or + '*' followed by a key code) </para> </listitem> <listitem> <para> - argv[1] = la ligne de commande avant l'action de la - touche + argv[1] = command line before key action </para> </listitem> <listitem> <para> - argv[2] = la ligne de commande après l'action de la - touche + argv[2] = command line after key action </para> </listitem> </itemizedlist> @@ -1284,57 +9945,56 @@ timer_handler = plugin->timer_handler_add (plugin, 60, &mon_timer); </listitem> <listitem> <para> - <option>handler_args</option> : paramètres passés à la - fonction appelée + <option>handler_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>handler_pointer</option> : pointeur passé à la - fonction appelée + <option>handler_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : le pointeur vers le nouveau gestionnaire de - clavier. + Return value: pointer to new message handler. </para> <para> - Note : la fonction appelée doit renvoyer une des valeurs - suivantes : + Note: function called has to return one of following values: <itemizedlist> <listitem> <para> - <literal>PLUGIN_RC_KO</literal> : la fonction a échoué + <literal>PLUGIN_RC_KO</literal>: function failed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK</literal> : la fonction a réussi + <literal>PLUGIN_RC_OK</literal>: function successfully + completed </para> </listitem> </itemizedlist> </para> <para> - Exemple : + Example: <screen> -int mon_keyb (t_weechat_plugin *plugin, int argc, char **argv, - char *handler_args, void *handler_pointer) +int my_keyb (t_weechat_plugin *plugin, int argc, char **argv, + char *handler_args, void *handler_pointer) { if (argc == 2) { - plugin->print (plugin, NULL, NULL, "touche appuyée: %s", argv[0]); + plugin->print (plugin, NULL, NULL, "key pressed: %s", argv[0]); if (argv[1] && (argv[1][0] == '1')) - plugin->print (plugin, NULL, NULL, "le texte d'entrée a changé"); + plugin->print (plugin, NULL, NULL, "input text changed"); else - plugin->print (plugin, NULL, NULL, "le texte d'entrée n'a pas changé"); + plugin->print (plugin, NULL, NULL, "input text not changed"); } return PLUGIN_RC_OK; } ... t_plugin_handler *keyb_handler; -keyb_handler = plugin->keyboard_handler_add (plugin, &mon_keyb); +keyb_handler = plugin->keyboard_handler_add (plugin, &my_keyb); </screen> </para> </section> @@ -1343,95 +10003,90 @@ keyb_handler = plugin->keyboard_handler_add (plugin, &mon_keyb); <title>event_handler_add</title> <para> - Prototype : + Prototype: <command> t_plugin_handler *event_handler_add (t_weechat_plugin - *plugin, char *evenement, t_plugin_handler_func *fonction, + *plugin, char *event, t_plugin_handler_func *function, char *handler_args, void *handler_pointer) </command> </para> <para> - Ajoute un gestionnaire d'évènement, appelé dès qu'un évènement se - produit. + Add an event handler, called when an event happens. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>évènement</option> : évènement (voir le tableau - ci-dessous) + <option>event</option> : event (see table below) </para> </listitem> <listitem> <para> - <option>fonction</option> : fonction appelée + <option>function</option>: function called </para> <para> - Elle a le prototype suivant : + It uses following prototype: <command> - int ma_fonction (t_weechat_plugin *plugin, + int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer) </command> </para> <para> - Les paramètres passés à la fonction dépendent de l'évènement - (voir le tableau ci-dessous). + Arguments depend on event (see table below). </para> </listitem> <listitem> <para> - <option>handler_args</option> : paramètres passés à la - fonction appelée + <option>handler_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>handler_pointer</option> : pointeur passé à la - fonction appelée + <option>handler_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> <para> - Liste des évènements : + List of events: <informaltable colsep="0" frame="none"> <tgroup cols="3"> <thead> <row> - <entry>Evènement</entry> + <entry>Event</entry> <entry>Description</entry> - <entry>Paramètres</entry> + <entry>Arguments</entry> </row> </thead> <tbody> <row> <entry><literal>buffer_open</literal></entry> - <entry>un tampon a été ouvert</entry> + <entry>a buffer was open</entry> <entry> - argc = 1, argv = { numéro de tampon } + argc = 1, argv = { buffer number } </entry> </row> <row> <entry><literal>buffer_close</literal></entry> - <entry>un tampon a été fermé</entry> + <entry>a buffer was closed</entry> <entry> - argc = 1, argv = { numéro de tampon } + argc = 1, argv = { buffer number } </entry> </row> <row> <entry><literal>buffer_move</literal></entry> - <entry>un tampon a été déplacé</entry> + <entry>a buffer was moved</entry> <entry> - argc = 2, argv = { nouveau numéro de tampon, ancien - numéro } + argc = 2, argv = { new buffer number, old number } </entry> </row> </tbody> @@ -1439,38 +10094,37 @@ keyb_handler = plugin->keyboard_handler_add (plugin, &mon_keyb); </informaltable> </para> <para> - Valeur renvoyée : le pointeur vers le nouveau gestionnaire - d'évènement. + Return value: pointer to new event handler. </para> <para> - Note : la fonction appelée doit renvoyer une des valeurs - suivantes : + Note: function called has to return one of following values: <itemizedlist> <listitem> <para> - <literal>PLUGIN_RC_KO</literal> : la fonction a échoué + <literal>PLUGIN_RC_KO</literal>: function failed </para> </listitem> <listitem> <para> - <literal>PLUGIN_RC_OK</literal> : la fonction a réussi + <literal>PLUGIN_RC_OK</literal>: function successfully + completed </para> </listitem> </itemizedlist> </para> <para> - Exemple : + Example: <screen> -int mon_evenement (t_weechat_plugin *plugin, int argc, char **argv, - char *handler_args, void *handler_pointer) +int my_event (t_weechat_plugin *plugin, int argc, char **argv, + char *handler_args, void *handler_pointer) { - plugin->print (plugin, NULL, NULL, "mon_evenement"); + plugin->print (plugin, NULL, NULL, "my_event"); return PLUGIN_RC_OK; } ... t_plugin_handler *event_handler; event_handler = plugin->event_handler_add (plugin, "buffer_open", - &mon_evenement); + &my_event); </screen> </para> </section> @@ -1479,37 +10133,36 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", <title>handler_remove</title> <para> - Prototype : + Prototype: <command> void handler_remove (t_weechat_plugin *plugin, t_plugin_handler *handler) </command> </para> <para> - Supprime un gestionnaire de commande ou message. + Remove a command or message handler. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>handler</option> : le gestionnaire à supprimer + <option>handler</option>: handler to remove </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : - <screen>plugin->handler_remove (plugin, mon_handler);</screen> + Example: + <screen>plugin->handler_remove (plugin, my_handler);</screen> </para> </section> @@ -1517,30 +10170,29 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", <title>handler_remove_all</title> <para> - Prototype : + Prototype: <command> void handler_remove_all (t_weechat_plugin *plugin) </command> </para> <para> - Supprime tous les gestionnaires d'une extension. + Remove all handlers for a plugin. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen>plugin->handler_remove_all (plugin);</screen> </para> </section> @@ -1549,28 +10201,27 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", <title>modifier_add</title> <para> - Prototype : + Prototype: <command> t_plugin_modifier *modifier_add (t_weechat_plugin *plugin, - char *type, char *message, t_plugin_modifier_func *fonction, + char *type, char *message, t_plugin_modifier_func *function, char *modifier_args, void *modifier_pointer) </command> </para> <para> - Ajoute un modifieur de message. + Add a message modifier. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>type</option> : type de modifieur : + <option>type</option>: modifier type: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> @@ -1582,23 +10233,21 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", <tbody> <row> <entry><literal>irc_in</literal></entry> - <entry>appelé pour chaque message IRC reçu</entry> + <entry>called for incoming IRC messages</entry> </row> <row> <entry><literal>irc_user</literal></entry> <entry> - appelé pour chaque message (ou commande) envoyé par - l'utilisateur (avant traitement et affichage par - WeeChat) + called for each user message (or command) (before + WeeChat parses message) </entry> </row> <row> <entry><literal>irc_out</literal></entry> <entry> - appelé pour chaque message sortant juste avant - envoi au serveur IRC (y compris pour les messages - envoyés automatiquement et de manière transparente - par WeeChat) + called for outgoing messages, immediately before + sending it to IRC server (this includes messages + sent automatically by WeeChat to server) </entry> </row> </tbody> @@ -1608,36 +10257,34 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", </listitem> <listitem> <para> - <option>message</option> : nom du message IRC pour lequel la - fonction est appelée (utilisé uniquement pour les types - "irc_in" et "irc_out"). - Pour connaître la liste des messages IRC disponibles, merci - de consulter les <acronym>RFC</acronym>s + <option>message</option>: name of IRC message (used only for + types "irc_in" and "irc_out"). + To know list of IRC messages, please consult + <acronym>RFC</acronym>s <ulink url="http://www.ietf.org/rfc/rfc1459.txt">1459</ulink> - et + and <ulink url="http://www.ietf.org/rfc/rfc2812.txt">2812</ulink>. - La valeur spéciale "*" signifie tous les messages (pas de - filtre). + Moreover, special value "*" means all messages (no filter). </para> </listitem> <listitem> <para> - <option>fonction</option> : fonction appelée + <option>function</option>: function called </para> <para> - Elle a le prototype suivant : + It uses following prototype: <command> - char *ma_fonction (t_weechat_plugin *plugin, + int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *modifier_args, void *modifier_pointer) </command> </para> <para> - Le paramètre argc vaut 2 et les arguments suivants sont - passés dans le tableau argv : + Argument argc is set to 2, following values are set in + argv array: <itemizedlist> <listitem> - <para>argv[0] = nom du serveur</para> + <para>argv[0] = server name</para> </listitem> <listitem> <para>argv[1] = message</para> @@ -1647,33 +10294,32 @@ event_handler = plugin->event_handler_add (plugin, "buffer_open", </listitem> <listitem> <para> - <option>modifier_args</option> : paramètres passés à la - fonction appelée + <option>modifier_args</option>: arguments given to function + when called </para> </listitem> <listitem> <para> - <option>modifier_pointer</option> : pointeur passé à la - fonction appelée + <option>modifier_pointer</option>: pointer given to function + when called </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : le pointeur vers le nouveau modifieur de message. + Return value: pointer to new message modifier. </para> <para> - Note : la fonction doit retourner une chaîne modifiée, ou NULL si - elle ne souhaite pas modifier le message. - Si elle retourne une chaine vide, alors le message est supprimé et - ne sera pas traité du tout par WeeChat (soyez prudent en supprimant - des messages !). - La chaîne renvoyée doit avoir été allouée par malloc() et sera - libérée (par appel à free()) automatiquement par WeeChat après - utilisation. + Note: function has to return modified string, or NULL if no + changes are made to message. + If function returns empty string, then message is dropped and + will not be read at all by WeeChat (be careful when dropping + messages!). + Returned string must have been allocated by malloc() and will + be freed (with call to free()) automatically by WeeChat after use. </para> <para> - Exemple : + Example: <screen> char *adder (t_weechat_plugin *plugin, int argc, char **argv, char *modifier_args, void *modifier_pointer) @@ -1696,37 +10342,36 @@ modifier = plugin->modifier_add (plugin, "irc_in", "privmsg", <title>modifier_remove</title> <para> - Prototype : + Prototype: <command> void modifier_remove (t_weechat_plugin *plugin, t_plugin_modifier *modifier) </command> </para> <para> - Supprime un modifieur de message. + Remove a message modifier. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>modifier</option> : le modifieur à supprimer + <option>modifier</option>: modifier to remove </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : - <screen>plugin->modifier_remove (plugin, mon_modifier);</screen> + Example: + <screen>plugin->modifier_remove (plugin, my_modifier);</screen> </para> </section> @@ -1734,30 +10379,29 @@ modifier = plugin->modifier_add (plugin, "irc_in", "privmsg", <title>modifier_remove_all</title> <para> - Prototype : + Prototype: <command> void modifier_remove_all (t_weechat_plugin *plugin) </command> </para> <para> - Supprime tous les modifieurs d'une extension. + Remove all modifiers for a plugin. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen>plugin->modifier_remove_all (plugin);</screen> </para> </section> @@ -1766,51 +10410,50 @@ modifier = plugin->modifier_add (plugin, "irc_in", "privmsg", <title>exec_command</title> <para> - Prototype : + Prototype: <command> void exec_command (t_weechat_plugin - *plugin, char *serveur, char *canal, char *commande) + *plugin, char *server, char *channel, char *command) </command> </para> <para> - Execute une commande WeeChat ou envoie un message à un canal. + Execute a WeeChat command (or send a message to a channel). </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>serveur</option> : nom interne du serveur où - exécuter la commande (peut être NULL) + <option>server</option>: internal name of server for + executing command (may be NULL) </para> </listitem> <listitem> <para> - <option>canal</option> : nom du canal où exécuter la - commande (peut être NULL) + <option>channel</option>: name of channel for executing + command (may be NULL) </para> </listitem> <listitem> <para> - <option>commande</option> : la commande à exécuter + <option>command</option>: command </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemples : + Examples: <screen> plugin->exec_command (plugin, NULL, NULL, "/help nick"); -plugin->exec_command (plugin, "freenode", "#weechat", "bonjour"); +plugin->exec_command (plugin, "freenode", "#weechat", "hello"); </screen> </para> </section> @@ -1819,27 +10462,26 @@ plugin->exec_command (plugin, "freenode", "#weechat", "bonjour"); <title>get_info</title> <para> - Prototype : + Prototype: <command> char *get_info (t_weechat_plugin *plugin, - char *info, char *serveur) + char *info, char *server) </command> </para> <para> - Renvoie une information sur WeeChat ou un canal. + Return an info about WeeChat or a channel. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>info</option> : nom de l'info à obtenir : + <option>info</option> : name of info to read: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> @@ -1851,74 +10493,70 @@ plugin->exec_command (plugin, "freenode", "#weechat", "bonjour"); <tbody> <row> <entry><literal>version</literal></entry> - <entry>version de WeeChat</entry> + <entry>WeeChat's version</entry> </row> <row> <entry><literal>nick</literal></entry> - <entry>pesudo</entry> + <entry>nick</entry> </row> <row> <entry><literal>channel</literal></entry> <entry> - nom du canal (NULL pour un serveur ou un privé) + name of channel (NULL for a server or private) </entry> </row> <row> <entry><literal>server</literal></entry> - <entry>nom du serveur</entry> + <entry>name of server</entry> </row> <row> <entry><literal>type</literal></entry> <entry> - type de tampon: 0=standard, 1=DCC, - 2=données IRC brutes + buffer type: 0=standard, 1=DCC, 2=raw IRC data </entry> </row> <row> <entry><literal>away</literal></entry> - <entry>drapeau "away"</entry> + <entry>"away" flag</entry> </row> <row> <entry><literal>inactivity</literal></entry> <entry> - nombre de secondes écoulées depuis que la dernière - touche a été appuyée + number of seconds since last key was pressed </entry> </row> <row> <entry><literal>input</literal></entry> <entry> - contenu de la ligne de commande de la fenêtre - courante + content of command line for current window </entry> </row> <row> <entry><literal>input_mask</literal></entry> <entry> - contenu du masque de couleur de la ligne de - commande + content of color mask for command line </entry> </row> <row> <entry><literal>input_pos</literal></entry> <entry> - position du curseur dans la ligne de commande + cursor position in command line </entry> </row> <row> <entry><literal>weechat_dir</literal></entry> <entry> - répertoire de base de WeeChat - (par défaut: ~/.weechat/) + WeeChat home directory + (by default: ~/.weechat/) </entry> </row> <row> <entry><literal>weechat_libdir</literal></entry> - <entry>répertoire "lib" système de WeeChat</entry> + <entry>WeeChat system lib directory</entry> </row> <row> <entry><literal>weechat_sharedir</literal></entry> - <entry>répertoire "share" système de WeeChat</entry> + <entry>WeeChat system share directory</entry> </row> </tbody> </tgroup> @@ -1927,29 +10565,29 @@ plugin->exec_command (plugin, "freenode", "#weechat", "bonjour"); </listitem> <listitem> <para> - <option>serveur</option> : nom interne du serveur où - récupérer l'information (si nécessaire) + <option>server</option>: internal name of server for + reading info (if needed) </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : l'information recherchée, NULL si non trouvée. + Return value: information asked, NULL if not found. </para> <para> - Note : le résultat doit être libéré par un appel à la fonction - "free" après utilisation. + Note: result has to be free by a call to "free" function after + use. </para> <para> - Exemples : + Examples: <screen> char *version = plugin->get_info (plugin, "version", NULL); char *nick = plugin->get_info (plugin, "nick", "freenode"); char *inactivity = plugin->get_info (plugin, "inactivity", NULL); plugin->print (plugin, NULL, NULL, - "WeeChat version %s, vous êtes %s sur freenode " - "(inactif depuis %s secondes)", + "WeeChat version %s, you are %s on freenode " + "(inactive for %s seconds)", version, nick, inactivity); if (version) @@ -1966,33 +10604,32 @@ if (inactivity) <title>get_dcc_info</title> <para> - Prototype : + Prototype: <command> t_plugin_info_dcc *get_dcc_info (t_weechat_plugin *plugin) </command> </para> <para> - Renvoie la liste des DCC en cours ou terminés. + Return list of DCC currently active or finished. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : la liste chaînée des DCC. + Return value: linked list of DCC. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> <entry>Type</entry> - <entry>Champ</entry> + <entry>Field</entry> <entry>Description</entry> </row> </thead> @@ -2000,129 +10637,129 @@ if (inactivity) <row> <entry>char *</entry> <entry><literal>server</literal></entry> - <entry>le serveur IRC</entry> + <entry>IRC server</entry> </row> <row> <entry>char *</entry> <entry><literal>channel</literal></entry> - <entry>le canal IRC</entry> + <entry>IRC channel</entry> </row> <row> <entry>int</entry> <entry><literal>type</literal></entry> <entry> - le type de DCC : - 0 = discussion reçue, - 1 = discussion envoyée, - 2 = fichier reçu, - 3 = fichier envoyé + DCC type: + 0 = chat received, + 1 = chat sent, + 2 = file received, + 3 = file sent </entry> </row> <row> - <entry>int</entry> + <entry>int*</entry> <entry><literal>status</literal></entry> <entry> - le statut du DCC : - 0 = en attente, - 1 = en cours de connexion, - 2 = actif, - 3 = terminé, - 4 = échoué, - 5 = interrompu par l'utilisateur + DCC status: + 0 = waiting, + 1 = connecting, + 2 = active, + 3 = finished, + 4 = failed, + 5 = interrupted by user </entry> </row> <row> <entry>time_t</entry> <entry><literal>start_time</literal></entry> - <entry>la date et heure de création du DCC</entry> + <entry>date/time of DCC creation</entry> </row> <row> <entry>time_t</entry> <entry><literal>start_transfer</literal></entry> - <entry>la date et heure de démarrage du transfert</entry> + <entry>date/time of DCC transfer start</entry> </row> <row> <entry>unsigned long</entry> <entry><literal>addr</literal></entry> - <entry>adresse IP de l'utilisateur distant</entry> + <entry>IP address of remote user</entry> </row> <row> <entry>int</entry> <entry><literal>port</literal></entry> - <entry>port utilisé pour le DCC</entry> + <entry>port used for DCC</entry> </row> <row> <entry>char *</entry> <entry><literal>nick</literal></entry> - <entry>pseudo de l'utilisateur distant</entry> + <entry>remote nick</entry> </row> <row> <entry>char *</entry> <entry><literal>filename</literal></entry> - <entry>nom de fichier</entry> + <entry>file name</entry> </row> <row> <entry>char *</entry> <entry><literal>local_filename</literal></entry> - <entry>nom de fichier local</entry> + <entry>local file name</entry> </row> <row> <entry>int</entry> <entry><literal>filename_suffix</literal></entry> - <entry>suffixe si renommage de fichier</entry> + <entry>suffix if renaming file</entry> </row> <row> <entry>unsigned long</entry> <entry><literal>size</literal></entry> - <entry>taille du fichier</entry> + <entry>file size</entry> </row> <row> <entry>unsigned long</entry> <entry><literal>pos</literal></entry> - <entry>position actuelle dans le fichier</entry> + <entry>position in file</entry> </row> <row> <entry>unsigned long</entry> <entry><literal>start_resume</literal></entry> - <entry>position de démarrage après une interruption</entry> + <entry>start position after interruption</entry> </row> <row> <entry>unsigned long</entry> <entry><literal>bytes_per_sec</literal></entry> <entry> - nombre d'octets transmis par seconde depuis le début - du transfert + number of bytes per second since transfer start </entry> </row> <row> <entry>t_plugin_dcc_info *</entry> <entry><literal>prev_dcc</literal></entry> <entry> - pointeur vers l'info DCC précédente + pointer to previous DCC info </entry> </row> <row> <entry>t_plugin_dcc_info *</entry> <entry><literal>next_dcc</literal></entry> <entry> - pointeur vers l'info DCC suivante + pointer to next DCC info </entry> </row> + </tbody> </tgroup> </informaltable> </para> <para> - Note : le résultat doit être libéré par un appel à la fonction - "free_dcc_info" après utilisation. + Note: result has to be free by a call to "free_dcc_info" function + after use. </para> <para> - Exemples : + Examples: <screen> t_plugin_dcc_info *dcc_info = plugin->get_dcc_info (plugin); for (ptr_dcc = dcc_info; ptr_dcc; ptr_dcc = ptr_dcc->next_dcc) { - plugin->print_server (plugin, "DCC type=%d, avec: %s", + plugin->print_server (plugin, "DCC type=%d, with: %s", ptr_dcc->type, ptr_dcc->nick); } if (dcc_info) @@ -2135,72 +10772,70 @@ if (dcc_info) <title>free_dcc_info</title> <para> - Prototype : + Prototype: <command> void free_dcc_info (t_weechat_plugin *plugin, t_plugin_dcc_info *dcc_info) </command> </para> <para> - Libère la mémoire utilisée par une liste de DCC. + Free memory used by a DCC list. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>dcc_info</option> : pointeur vers la liste DCC - renvoyée par la fonction "get_dcc_info" + <option>dcc_info</option>: pointer to DCC list returned by + "get_dcc_info" function </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen>plugin->free_dcc_info (plugin, dcc_info);</screen> </para> </section> - + <section id="secAPI_get_server_info"> <title>get_server_info</title> <para> - Prototype : + Prototype: <command> t_plugin_server_info *get_server_info (t_weechat_plugin *plugin) </command> </para> <para> - Renvoie la liste des serveurs IRC (connectés ou non). + Return list of IRC servers (connected or not). </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Valeur retournée : la liste chaînée des serveurs IRC. + Return value: linked list of IRC servers. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> <entry>Type</entry> - <entry>Champ</entry> + <entry>Field</entry> <entry>Description</entry> </row> </thead> @@ -2208,38 +10843,38 @@ if (dcc_info) <row> <entry>char *</entry> <entry><literal>name</literal></entry> - <entry>nom interne du serveur</entry> + <entry>server internal name</entry> </row> <row> <entry>int</entry> <entry><literal>autoconnect</literal></entry> - <entry>1 si auto-connexion au démarrage, 0 sinon</entry> + <entry>1 if autoconnect at start-up, 0 otherwise</entry> </row> <row> <entry>int</entry> <entry><literal>autoreconnect</literal></entry> <entry> - 1 si auto-reconnexion quand déconnecté, - 0 sinon + 1 if autoreconnect when disconnected, + 0 otherwise </entry> </row> <row> <entry>int</entry> <entry><literal>autoreconnect_delay</literal></entry> - <entry>délai avant de tenter une reconnexion</entry> + <entry>delay before trying again connection</entry> </row> <row> <entry>int</entry> <entry><literal>command_line</literal></entry> <entry> - 1 si le serveur vient de la ligne de commande - (donc temporaire), 0 sinon + 1 if server was on command line (so it is temporary), + 0 otherwise </entry> </row> <row> <entry>char *</entry> <entry><literal>address</literal></entry> - <entry>adresse du serveur (nom ou IP)</entry> + <entry>server address (host or IP)</entry> </row> <row> <entry>int</entry> @@ -2249,144 +10884,136 @@ if (dcc_info) <row> <entry>int</entry> <entry><literal>ipv6</literal></entry> - <entry>connexion IPv6</entry> + <entry>IPv6 connection</entry> </row> <row> <entry>int</entry> <entry><literal>ssl</literal></entry> - <entry>connexion SSL</entry> + <entry>SSL connection</entry> </row> <row> <entry>char *</entry> <entry><literal>password</literal></entry> - <entry>mot de passe pour le serveur</entry> + <entry>server password</entry> </row> <row> <entry>char *</entry> <entry><literal>nick1</literal></entry> - <entry>premier pseudo</entry> + <entry>first nickname</entry> </row> <row> <entry>char *</entry> <entry><literal>nick2</literal></entry> - <entry>pseudo alternatif</entry> + <entry>alternate nickname</entry> </row> <row> <entry>char *</entry> <entry><literal>nick3</literal></entry> - <entry>second pseudo alternatif</entry> + <entry>second alternate nickname</entry> </row> <row> <entry>char *</entry> <entry><literal>username</literal></entry> - <entry>nom d'utilisateur</entry> + <entry>user name</entry> </row> <row> <entry>char *</entry> <entry><literal>real name</literal></entry> - <entry>nom réel</entry> + <entry>real name</entry> </row> <row> <entry>char *</entry> <entry><literal>command</literal></entry> - <entry>commande exécutée une fois connecté</entry> + <entry>command run once connected</entry> </row> <row> <entry>int</entry> <entry><literal>command_delay</literal></entry> - <entry>délai après exécution de la commande</entry> + <entry>delay after execution of command</entry> </row> <row> <entry>char *</entry> <entry><literal>autojoin</literal></entry> - <entry>canaux joints automatiquement</entry> + <entry>channels joined automatically</entry> </row> <row> <entry>int</entry> <entry><literal>autorejoin</literal></entry> <entry> - 1 si les canaux sont rejoints après un "kick", - 0 sinon + 1 if channels are rejoined when kicked, + 0 otherwise </entry> </row> <row> <entry>char *</entry> <entry><literal>notify_levels</literal></entry> - <entry>niveaux de notification des canaux</entry> + <entry>channels notify levels</entry> </row> <row> <entry>char *</entry> <entry><literal>charset_decode_iso</literal></entry> - <entry> - jeux de caractères de décodage ISO pour les canaux - </entry> + <entry>channels charsets for decoding ISO</entry> </row> <row> <entry>char *</entry> <entry><literal>charset_decode_utf</literal></entry> - <entry> - jeux de caractères de décodage UTF pour les canaux - </entry> + <entry>channels charsets for decoding UTF</entry> </row> <row> <entry>char *</entry> <entry><literal>charset_encode</literal></entry> - <entry> - jeux de caractères d'encodage pour les canaux - </entry> + <entry>channels charsets for encoding messages</entry> </row> <row> <entry>int</entry> <entry><literal>is_connected</literal></entry> - <entry>1 si connecté au serveur, 0 sinon</entry> + <entry>1 if connected to server, 0 otherwise</entry> </row> <row> <entry>int</entry> <entry><literal>ssl_connected</literal></entry> - <entry>1 si connecté via SSL, 0 sinon</entry> + <entry>1 if connected with SSL, 0 otherwise</entry> </row> <row> <entry>char *</entry> <entry><literal>nick</literal></entry> - <entry>pseudo courant</entry> + <entry>current nickname</entry> </row> <row> <entry>int</entry> <entry><literal>is_away</literal></entry> - <entry>1 si absent, 0 sinon</entry> + <entry>1 if away, 0 otherwise</entry> </row> <row> <entry>time_t</entry> <entry><literal>away_time</literal></entry> - <entry> - date/heure à laquelle l'utilisateur a été marqué absent - </entry> + <entry>time when user is marking as away</entry> </row> <row> <entry>int</entry> <entry><literal>lag</literal></entry> - <entry>lag (en millisecondes)</entry> + <entry>lag (in milliseconds)</entry> </row> <row> <entry>t_plugin_server_info *</entry> <entry><literal>prev_server</literal></entry> - <entry>pointeur vers les infos du serveur précédent</entry> + <entry>pointer to previous server info</entry> </row> <row> <entry>t_plugin_server_info *</entry> <entry><literal>next_server</literal></entry> - <entry>pointeur vers les infos du serveur suivant</entry> + <entry>pointer to next server info</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Note : le résultat doit être libéré par un appel à la fonction - "free_server_info" après utilisation. + Note: result has to be free by a call to "free_server_info" + function after use. </para> <para> - Exemple : + Example: <screen> t_plugin_server_info *server_info, *ptr_server_info; server_info = plugin->get_server_info (plugin); @@ -2396,11 +11023,11 @@ if (server_info) ptr_server_info = ptr_server_info->next_server) { plugin->print (plugin, NULL, NULL, - "serveur: %s, addresse: %s, port: %d %s", + "server: %s, address: %s, port: %d %s", ptr_server_info->name, ptr_server_info->address, ptr_server_info->port, - (ptr_server_info->is_connected) ? "(connecté)" : ""); + (ptr_server_info->is_connected) ? "(connected)" : ""); } plugin->free_server_info (plugin, server_info); } @@ -2412,37 +11039,36 @@ if (server_info) <title>free_server_info</title> <para> - Prototype : + Prototype: <command> void free_server_info (t_weechat_plugin *plugin, t_plugin_server_info *server_info) </command> </para> <para> - Libère la mémoire utilisée par une liste de serveurs. + Free memory used by server info list. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>server_info</option> : pointeur vers la liste de - serveurs retournée par la fonction "get_server_info" + <option>server_info</option>: pointer to server list + returned by "get_server_info" function </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen>plugin->free_server_info (plugin, server_info);</screen> </para> </section> @@ -2451,33 +11077,32 @@ if (server_info) <title>get_channel_info</title> <para> - Prototype : + Prototype: <command> t_plugin_channel_info *get_channel_info (t_weechat_plugin *plugin, - char *serveur) + char *server) </command> </para> <para> - Renvoie la liste des canaux IRC pour un serveur. + Return list of IRC channels for a server. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>serveur</option> : nom interne du serveur + <option>server</option>: internal server name </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : la liste chaînée des canaux IRC du serveur. + Return value: linked list of IRC channels for server. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> @@ -2491,58 +11116,58 @@ if (server_info) <row> <entry>int</entry> <entry><literal>type</literal></entry> - <entry>0 pour un canal, 1 pour un privé</entry> + <entry>0 for a channel, 1 for a private</entry> </row> <row> <entry>char *</entry> <entry><literal>name</literal></entry> - <entry>nom du canal</entry> + <entry>name of channel</entry> </row> <row> <entry>char *</entry> <entry><literal>topic</literal></entry> - <entry>titre du canal</entry> + <entry>topic of channel</entry> </row> <row> <entry>char *</entry> <entry><literal>modes</literal></entry> - <entry>modes du canal</entry> + <entry>channel modes</entry> </row> <row> <entry>int</entry> <entry><literal>limit</literal></entry> - <entry>limite d'utilisateurs</entry> + <entry>user limit</entry> </row> <row> <entry>char *</entry> <entry><literal>key</literal></entry> - <entry>clé du canal</entry> + <entry>channel key</entry> </row> <row> <entry>int</entry> <entry><literal>nicks_count</literal></entry> - <entry>nombre de pseudos présents sur le canal</entry> + <entry>number of nicks on channel</entry> </row> <row> <entry>t_plugin_channel_info *</entry> <entry><literal>prev_channel</literal></entry> - <entry>pointeur vers les infos du canal précédent</entry> + <entry>pointer to previous channel info</entry> </row> <row> <entry>t_plugin_channel_info *</entry> <entry><literal>next_channel</literal></entry> - <entry>pointeur vers les infos du canal suivant</entry> + <entry>pointer to next channel info</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Note : le résultat doit être libéré par un appel à la fonction - "free_channel_info" après utilisation. + Note: result has to be free by a call to "free_channel_info" + function after use. </para> <para> - Exemple : + Example: <screen> t_plugin_channel_info *channel_info, *ptr_chan_info; channel_info = plugin->get_channel_info (plugin, "freenode"); @@ -2566,37 +11191,36 @@ if (channel_info) <title>free_channel_info</title> <para> - Prototype : + Prototype: <command> void free_channel_info (t_weechat_plugin *plugin, t_plugin_channel_info *channel_info) </command> </para> <para> - Libère la mémoire utilisée par une liste de canaux. + Free memory used by channel info list. </para> <para> Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>channel_info</option> : pointeur vers la liste de - canaux retournée par la fonction "get_channel_info" + <option>channel_info</option>: pointer to channel info list + returned by "get_channel_info" function </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen>plugin->free_channel_info (plugin, channel_info);</screen> </para> </section> @@ -2605,45 +11229,43 @@ if (channel_info) <title>get_nick_info</title> <para> - Prototype : + Prototype: <command> t_plugin_nick_info *get_nick_info (t_weechat_plugin *plugin, - char *serveur, char *canal) + char *server, char *channel) </command> </para> <para> - Renvoie la liste des pseudos pour un canal. + Return list of nicks for a channel. </para> <para> Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>serveur</option> : nom interne du serveur + <option>server</option>: internal server name </para> </listitem> <listitem> <para> - <option>canal</option> : nom du canal + <option>channel</option>: channel name </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : la liste chaînée des pseudos présents - sur le canal. + Return value: linked list of nicks on channel. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> <entry>Type</entry> - <entry>Champ</entry> + <entry>Field</entry> <entry>Description</entry> </row> </thead> @@ -2651,42 +11273,42 @@ if (channel_info) <row> <entry>char *</entry> <entry><literal>nick</literal></entry> - <entry>pseudo</entry> + <entry>nick name</entry> </row> <row> <entry>char *</entry> <entry><literal>host</literal></entry> - <entry>nom de machine</entry> + <entry>hostname</entry> </row> <row> <entry>int</entry> <entry><literal>flags</literal></entry> <entry> - propriétés du pseudo, "ou" binaire entre plusieurs - valeurs (1 =propriétaire du canal, 2 = administrateur - du canal, 4 = op, 8 = demi-op, 16 = voix, 32 = absent) + nick flags, binary "or" between values (1 = channel + owner, 2 = channel admin, 4 = op, 8 = halfop, + 16 = voice, 32 = away) </entry> </row> <row> <entry>t_plugin_nick_info *</entry> <entry><literal>prev_nick</literal></entry> - <entry>pointeur vers les infos du pseudo précédent</entry> + <entry>pointer to previous nick info</entry> </row> <row> <entry>t_plugin_nick_info *</entry> <entry><literal>next_nick</literal></entry> - <entry>pointeur vers les infos du pseudo précédent</entry> + <entry>pointer to next nick info</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Note : le résultat doit être libéré par un appel à la fonction - "free_nick_info" après utilisation. + Note: result has to be free by a call to "free_nick_info" + function after use. </para> <para> - Exemple : + Example: <screen> t_plugin_nick_info *nick_info, *ptr_nick_info; nick_info = plugin->get_nick_info (plugin, "freenode", "#weechat"); @@ -2710,37 +11332,36 @@ if (nick_info) <title>free_nick_info</title> <para> - Prototype : + Prototype: <command> void free_nick_info (t_weechat_plugin *plugin, t_plugin_nick_info *nick_info) </command> </para> <para> - Libère la mémoire utilisée par une liste de pseudos. + Free memory used by nick info list. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>nick_info</option> : pointeur vers la liste de - pseudos retournée par la fonction "get_nick_info" + <option>nick_info</option>: pointer to nick info list + returned by "get_nick_info" function </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen>plugin->free_nick_info (plugin, nick_info);</screen> </para> </section> @@ -2749,39 +11370,38 @@ if (nick_info) <title>get_config</title> <para> - Prototype : + Prototype: <command> char *get_config (t_weechat_plugin *plugin, char *option) </command> </para> <para> - Renvoie la valeur d'une option de configuration WeeChat. + Return value of a WeeChat config option. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>option</option> : nom de l'option à lire + <option>option</option>: name of option to read </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : la valeur de l'option, NULL si non trouvée. + Return value: option value, NULL if not found. </para> <para> - Note : le résultat doit être libéré par un appel à la fonction - "free" après utilisation. + Note: result has to be free by a call to "free" function after + use. </para> <para> - Exemples : + Examples: <screen> char *value1 = plugin->get_config (plugin, "look_set_title"); char *value2 = plugin->get_config (plugin, "freenode.server_autojoin"); @@ -2793,42 +11413,41 @@ char *value2 = plugin->get_config (plugin, "freenode.server_autojoin"); <title>set_config</title> <para> - Prototype : + Prototype: <command> int set_config (t_weechat_plugin *plugin, - char *option, char *valeur) + char *option, char *value) </command> </para> <para> - Modifie la valeur d'une option de configuration WeeChat. + Update value of a WeeChat config option. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>option</option> : nom de l'option à mettre à jour + <option>option</option>: name of option to update </para> </listitem> <listitem> <para> - <option>valeur</option> : nouvelle valeur pour l'option + <option>value</option>: new value for option </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : 1 si l'option a été modifiée avec succès, 0 si - une erreur s'est produite. + Return value: 1 if option was successfully updated, 0 if an + error occurred. </para> <para> - Exemple : + Example: <screen> plugin->set_config (plugin, "look_nicklist", "off"); </screen> @@ -2839,45 +11458,43 @@ plugin->set_config (plugin, "look_nicklist", "off"); <title>get_plugin_config</title> <para> - Prototype : + Prototype: <command> char *get_plugin_config (t_weechat_plugin *plugin, char *option) </command> </para> <para> - Renvoie la valeur d'une option de l'extension. - L'option est lue depuis le fichier - "<literal>~/.weechat/plugins.rc</literal>" et est - sous cette forme : "<literal>extension.option=valeur</literal>" - (NB : le nom de l'extension est ajouté automatiquement). + Return value of a plugin option. + Option is read from file "<literal>~/.weechat/plugins.rc</literal>" + and is like: "<literal>plugin.option=value</literal>" + (note: plugin name is automatically added). </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>option</option> : nom de l'option à lire + <option>option</option>: name of option to read </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : la valeur de l'option, NULL si non trouvée. + Return value: option value, NULL if not found. </para> <para> - Note : le résultat doit être libéré par un appel à la fonction - "free" après utilisation. + Note: result has to be free by a call to "free" function after + use. </para> <para> - Exemple : + Example: <screen> -char *value = plugin->get_plugin_config (plugin, "ma_variable"); +char *value = plugin->get_plugin_config (plugin, "my_var"); </screen> </para> </section> @@ -2886,48 +11503,46 @@ char *value = plugin->get_plugin_config (plugin, "ma_variable"); <title>set_plugin_config</title> <para> - Prototype : + Prototype: <command> int set_plugin_config (t_weechat_plugin *plugin, - char *option, char *valeur) + char *option, char *value) </command> </para> <para> - Modifie la valeur d'une option de l'extension. - L'option est écrite dans le fichier - "<literal>~/.weechat/plugins.rc</literal>" et est - sous cette forme : "<literal>extension.option=valeur</literal>" - (NB : le nom de l'extension est ajouté automatiquement). + Update value of a plugin option. + Option is written in file "<literal>~/.weechat/plugins.rc</literal>" + and is like: "<literal>plugin.option=value</literal>" + (note: plugin name is automatically added). </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>option</option> : nom de l'option à mettre à jour + <option>option</option>: name of option to update </para> </listitem> <listitem> <para> - <option>valeur</option> : nouvelle valeur pour l'option + <option>value</option>: new value for option </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : 1 si l'option a été modifiée avec succès, 0 si - une erreur s'est produite. + Return value: 1 if option was successfully updated, 0 if an + error occurred. </para> <para> - Exemple : + Example: <screen> -plugin->set_plugin_config (plugin, "ma_variable", "valeur"); +plugin->set_plugin_config (plugin, "my_var", "value"); </screen> </para> </section> @@ -2936,34 +11551,33 @@ plugin->set_plugin_config (plugin, "ma_variable", "valeur"); <title>get_irc_color</title> <para> - Prototype : + Prototype: <command> int get_irc_color (t_weechat_plugin *plugin, - char *nom_couleur) + char *color_name) </command> </para> <para> - Renvoie le numéro d'une couleur IRC avec son nom. + Get IRC color index with name. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>nom_couleur</option> : nom de la couleur - Les couleure autorisées sont : + <option>color_name</option>: color name + Allowed colors are: <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> - <entry>Nom couleur</entry> - <entry>Valeur</entry> + <entry>Color name</entry> + <entry>Value</entry> </row> </thead> <tbody> @@ -3039,13 +11653,12 @@ plugin->set_plugin_config (plugin, "ma_variable", "valeur"); </itemizedlist> </para> <para> - Valeur renvoyée : numéro de la couleur IRC, -1 si la couleur - n'est pas trouvée. + Return value: IRC color index, -1 if color is not found. </para> <para> - Exemple : + Example: <screen> -int color_blue = plugin->get_irc_color (plugin, "blue"); /* retourne 2 */ +int color_blue = plugin->get_irc_color (plugin, "blue"); /* return 2 */ </screen> </para> </section> @@ -3054,50 +11667,49 @@ int color_blue = plugin->get_irc_color (plugin, "blue"); /* retourne 2 */ <title>input_color</title> <para> - Prototype : + Prototype: <command> void input_color (t_weechat_plugin *plugin, - int couleur, int debut, int longueur) + int color, int start, int length) </command> </para> <para> - Ajoute de la couleur dans la zone de saisie. + Add color in input buffer. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>couleur</option> : couleur pour le texte (si < 0, - alors la zone de saisie est rafraichie, et il n'y a aucun - changement dans son contenu) + <option>color</option>: color for text (if < 0, then input + buffer is refresh, and there's no change in input buffer + content) </para> </listitem> <listitem> <para> - <option>debut</option> : position de début pour la coloration - (si < 0, alors le masque est réinitialisé) + <option>start</option>: start position for color (if < 0, + then mask is reinitialized) </para> </listitem> <listitem> <para> - <option>longueur</option> : longueur pour la coloration - (si <= 0, alors le masque est réinitialisé) + <option>length</option>: length for color (if <= 0, + then mask is reinitialized) </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen> plugin->input_color (plugin, plugin->get_irc_color (plugin, "blue"), 10, 5); </screen> @@ -3108,33 +11720,32 @@ plugin->input_color (plugin, plugin->get_irc_color (plugin, "blue"), 10, 5); <title>get_window_info</title> <para> - Prototype : + Prototype: <command> t_plugin_window_info *get_window_info (t_weechat_plugin *plugin) </command> </para> <para> - Retourne la liste des fenêtres WeeChat. + Return list of WeeChat windows. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : liste chaînée des fenêtres WeeChat. + Return value: linked list of WeeChat windows. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> <entry>Type</entry> - <entry>Champ</entry> + <entry>Field</entry> <entry>Description</entry> </row> </thead> @@ -3142,58 +11753,58 @@ plugin->input_color (plugin, plugin->get_irc_color (plugin, "blue"), 10, 5); <row> <entry>int</entry> <entry><literal>win_x</literal></entry> - <entry>position horizontale de la fenêtre</entry> + <entry>horizontal position of window</entry> </row> <row> <entry>int</entry> <entry><literal>win_y</literal></entry> - <entry>position verticale de la fenêtre</entry> + <entry>vertical position of window</entry> </row> <row> <entry>int</entry> <entry><literal>win_width</literal></entry> - <entry>largeur de la fenêtre</entry> + <entry>width of window</entry> </row> <row> <entry>int</entry> <entry><literal>win_height</literal></entry> - <entry>hauteur de la fenêtre</entry> + <entry>height of window</entry> </row> <row> <entry>int</entry> <entry><literal>win_width_pct</literal></entry> - <entry>largeur en % (comparé à la fenêtre parent)</entry> + <entry>width % (compared to parent window)</entry> </row> <row> <entry>int</entry> <entry><literal>win_height_pct</literal></entry> - <entry>hauteur en % (comparé à la fenêtre parent)</entry> + <entry>height % (compared to parent window)</entry> </row> <row> <entry>int</entry> <entry><literal>num_buffer</literal></entry> - <entry>numéro du tampon affiché</entry> + <entry>number of displayed buffer</entry> </row> <row> <entry>t_plugin_window_info *</entry> <entry><literal>prev_window</literal></entry> - <entry>pointeur vers les infos de la fenêtre précédente</entry> + <entry>pointer to previous window info</entry> </row> <row> <entry>t_plugin_window_info *</entry> <entry><literal>next_window</literal></entry> - <entry>pointeur vers les infos de la fenêtre suivante</entry> + <entry>pointer to next window info</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Note : le résultat doit être libéré par un appel à la fonction - "free_window_info" après utilisation. + Note: result has to be free by a call to "free_window_info" + function after use. </para> <para> - Exemple : + Example: <screen> t_plugin_window_info *window_info, *ptr_window; @@ -3202,7 +11813,7 @@ if (window_info) { for (ptr_window = window_info; ptr_window; ptr_window = ptr_window->next_window) { - plugin->print (plugin, NULL, NULL, "--- info fenêtre ---"); + plugin->print (plugin, NULL, NULL, "window info"); plugin->print (plugin, NULL, NULL, "(%d,%d), size: %dx%d, %%size: %d%%x%d%%", ptr_window->win_x, ptr_window->win_y, ptr_window->win_width, ptr_window->win_height, @@ -3212,7 +11823,7 @@ if (window_info) plugin->free_window_info (plugin, window_info); } else - plugin->print (plugin, NULL, NULL, "pas d'info fenêtre !"); + plugin->print (plugin, NULL, NULL, "no window info!"); </screen> </para> </section> @@ -3221,37 +11832,36 @@ else <title>free_window_info</title> <para> - Prototype : + Prototype: <command> void free_window_info (t_weechat_plugin *plugin, t_plugin_window_info *window_info) </command> </para> <para> - Libère la mémoire utilisée par une liste de fenêtres. + Free memory used by window info list. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>window_info</option> : pointeur vers la liste des - infos fenêtres retournée par la fonction "get_window_info" + <option>window_info</option>: pointer to window info list + returned by "get_window_info" function </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen>plugin->free_window_info (plugin, window_info);</screen> </para> </section> @@ -3260,33 +11870,32 @@ else <title>get_buffer_info</title> <para> - Prototype : + Prototype: <command> t_plugin_buffer_info *get_buffer_info (t_weechat_plugin *plugin) </command> </para> <para> - Retourne la liste des tampons WeeChat. + Return list of WeeChat buffers. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : liste chaînée des tampons WeeChat. + Return value: linked list of WeeChat buffers. <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> <entry>Type</entry> - <entry>Champ</entry> + <entry>Field</entry> <entry>Description</entry> </row> </thead> @@ -3294,64 +11903,58 @@ else <row> <entry>int</entry> <entry><literal>type</literal></entry> - <entry> - type de tampon: 0=standard, 1=DCC, - 2=données IRC brutes - </entry> + <entry>buffer type: 0=standard, 1=DCC, 2=raw IRC data</entry> </row> <row> <entry>int</entry> <entry><literal>number</literal></entry> - <entry>numéro de tampon</entry> + <entry>buffer number</entry> </row> <row> <entry>int</entry> <entry><literal>num_displayed</literal></entry> - <entry>nombre de fenêtres affichant ce tampon</entry> + <entry>number of windows displaying buffer</entry> </row> <row> <entry>char *</entry> <entry><literal>server_name</literal></entry> - <entry>nom du serveur pour le tampon (peut être NULL)</entry> + <entry>server name for buffer (may be NULL)</entry> </row> <row> <entry>char *</entry> <entry><literal>channel_name</literal></entry> - <entry>nom du canal pout le tampon (peut être NULL)</entry> + <entry>channel name for buffer (may be NULL)</entry> </row> <row> <entry>int</entry> <entry><literal>notify_level</literal></entry> - <entry>niveau de notification du tampon</entry> + <entry>notify level for buffer</entry> </row> <row> <entry>char *</entry> <entry><literal>log_filename</literal></entry> - <entry> - nom du fichier de log (NULL signifie qu'il n'y a - pas de log) - </entry> + <entry>log filename (NULL means not logging)</entry> </row> <row> <entry>t_plugin_buffer_info *</entry> <entry><literal>prev_buffer</literal></entry> - <entry>pointeur vers les infos du tampon précédent</entry> + <entry>pointer to previous buffer info</entry> </row> <row> <entry>t_plugin_buffer_info *</entry> <entry><literal>next_buffer</literal></entry> - <entry>pointeur vers les infos du tampon suivant</entry> + <entry>pointer to next buffer info</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Note : le résultat doit être libéré par un appel à la fonction - "free_buffer_info" après utilisation. + Note: result has to be free by a call to "free_buffer_info" + function after use. </para> <para> - Exemple : + Example: <screen> t_plugin_buffer_info *buffer_info, *ptr_buffer; @@ -3360,7 +11963,7 @@ if (buffer_info) { for (ptr_buffer = buffer_info; ptr_buffer; ptr_buffer = ptr_buffer->next_buffer) { - plugin->print (plugin, NULL, NULL, "--- info tampon ---"); + plugin->print (plugin, NULL, NULL, "buffer info"); plugin->print (plugin, NULL, NULL, "type: %d", ptr_buffer->type); plugin->print (plugin, NULL, NULL, "number: %d", ptr_buffer->number); plugin->print (plugin, NULL, NULL, "num_displayed: %d", ptr_buffer->num_displayed); @@ -3372,7 +11975,7 @@ if (buffer_info) plugin->free_buffer_info (plugin, buffer_info); } else - plugin->print (plugin, NULL, NULL, "pas d'info tampon !"); + plugin->print (plugin, NULL, NULL, "no buffer info!"); </screen> </para> </section> @@ -3388,30 +11991,29 @@ else </command> </para> <para> - Libère la mémoire utilisée par une liste de tampons. + Free memory used by buffer info list. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>buffer_info</option> : pointeur vers la liste des - infos tampons retournée par la fonction "get_buffer_info" + <option>buffer_info</option>: pointer to buffer info list + returned by "get_buffer_info" function </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen>plugin->free_buffer_info (plugin, buffer_info);</screen> </para> </section> @@ -3423,41 +12025,40 @@ else Prototype: <command> t_plugin_buffer_data *get_buffer_info (t_weechat_plugin *plugin, - char *serveur, char *canal) + char *server, char *channel) </command> </para> <para> - Renvoie le contenu du tampon. + Return content of buffer. </para> <para> - Paramètres : + Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>serveur</option> : nom interne du serveur + <option>server</option>: internal name of server </para> </listitem> <listitem> <para> - <option>canal</option> : nom du canal + <option>channel</option>: channel name </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : contenu du tampon (liste chaînée de lignes). + Return value: buffer content (linked list of lines). <informaltable colsep="0" frame="none"> <tgroup cols="2"> <thead> <row> <entry>Type</entry> - <entry>Champ</entry> + <entry>Field</entry> <entry>Description</entry> </row> </thead> @@ -3465,41 +12066,38 @@ else <row> <entry>time_t</entry> <entry><literal>date</literal></entry> - <entry>date et heure</entry> + <entry>date and time</entry> </row> <row> <entry>char *</entry> <entry><literal>nick</literal></entry> - <entry>pseudo</entry> + <entry>nick</entry> </row> <row> <entry>char *</entry> <entry><literal>data</literal></entry> - <entry> - contenu de la ligne (les codes couleur sont - retirés) - </entry> + <entry>line content (color codes are removed)</entry> </row> <row> <entry>t_plugin_buffer_line *</entry> <entry><literal>prev_line</literal></entry> - <entry>pointeur vers la ligne précédente</entry> + <entry>pointer to previous line</entry> </row> <row> <entry>t_plugin_buffer_line *</entry> <entry><literal>next_line</literal></entry> - <entry>pointeur vers la ligne suivante</entry> + <entry>pointer to next line</entry> </row> </tbody> </tgroup> </informaltable> </para> <para> - Note : le résultat doit être libéré par un appel à la fonction - "free_buffer_data" après utilisation. + Note: result has to be free by a call to "free_buffer_data" + function after use. </para> <para> - Exemple : + Example: <screen> t_plugin_buffer_line *buffer_line, *ptr_line; char text_time[256]; @@ -3510,7 +12108,7 @@ if (buffer_line) for (ptr_line = buffer_line; ptr_line; ptr_line = ptr_line->next_line) { strftime (text_time, sizeof (text_time), "%x %X", localtime (&(ptr_line->date))); - plugin->print (plugin, NULL, NULL, "date: %s, pseudo: %s, données: %s", + plugin->print (plugin, NULL, NULL, "date: %s, nick: %s, data: %s", text_time, ptr_line->nick, ptr_line->data); } plugin->free_buffer_data (plugin, buffer_line); @@ -3530,32 +12128,33 @@ if (buffer_line) </command> </para> <para> - Libère la mémoire utilisée par les lignes d'un tampon. + Free memory used by buffer line list. </para> <para> Arguments: <itemizedlist> <listitem> <para> - <option>plugin</option> : pointeur vers la structure - de l'extension + <option>plugin</option>: pointer to plugin structure </para> </listitem> <listitem> <para> - <option>buffer_line</option> : pointeur vers la liste des - lignes du tampon retournée par la fonction "get_buffer_data" + <option>buffer_line</option>: pointer to buffer line list + returned by "get_buffer_data" function </para> </listitem> </itemizedlist> </para> <para> - Valeur renvoyée : aucune. + Return value: none. </para> <para> - Exemple : + Example: <screen>plugin->free_buffer_data (plugin, buffer_line);</screen> </para> </section> + + --> </section> |