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