Functions to get infos about plugins.

Prototype: void weechat_plugin_get_name (struct t_weechat_plugin *plugin); Get plugin name (return "core" for WeeChat - NULL pointer). Arguments: plugin: plugin pointer Example: char *name = weechat_plugin_get_name (plugin);

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.

Prototype: void weechat_charset_set (const char *charset); Set new plugin charset. Arguments: charset: new charset to use Example: weechat_charset_set (plugin, "iso-8859-1");

Prototype: void weechat_iconv_to_internal (const char *charset, const char *string); Convert string to WeeChat internal charset (UTF-8). Arguments: charset: charset to convert string: string to convert Return value: converted string. Result has to be free by a call to "free" after use. Example: char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string: é à");

Prototype: void weechat_iconv_from_internal (const char *charset, const char *string); Convert string from internal WeeChat charset (UTF-8) to another. Arguments: charset: target charset string: string to convert Return value: converted string. Result has to be free by a call to "free" after use. Example: char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");

Prototype: char *weechat_gettext (const char *string); Return translated string (depends on local language). Arguments: string: string to translate Return value: translated string. Example: char *str = weechat_gettext ("hello !");

Prototype: char *weechat_ngettext (const char *string, const char *plural, int count); Return translated string, using single or plural form, according to count. Arguments: single: string to translate (single form) plural: string to translate (plural form) count: used to choose between single and plural form Return value: translated string. Example: char *str = weechat_ngettext ("file", "files", num_files);

Prototype: char *weechat_strndup (const char *string, int length); Return duplicated string, with max "length" chars. Arguments: string: string to duplicate length: max chars to duplicate Return value: duplicated string. Result has to be free by a call to "free" after use. Example: char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */

Prototype: char *weechat_string_tolower (const char *string); Convert UTF-8 string to lower case. Arguments: string: string to convert Return value: none. Example: weechat_string_tolower ("AbCdEé"); /* result: "abcdeé" */

Prototype: char *weechat_string_toupper (const char *string); Convert UTF-8 string to upper case. Arguments: string: string to convert Return value: none. Example: weechat_string_toupper ("AbCdEé"); /* result: "ABCDEé" */

Prototype: int weechat_strcasecmp (const char *string1, const char *string2); Locale and case independent string comparison. Arguments: string1: first string for comparison string2: second string for comparison Return value: difference between two strings: negative if string1 < string2, zero if string1 == string2, positive if string1 > string2 Example: int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */

Prototype: int weechat_strncasecmp (const char *string1, const char *string2, int max); Locale and case independent string comparison, for "max" chars. Arguments: string1: first string for comparison string2: second string for comparison max: max number of chars for comparison Return value: difference between two strings: negative if string1 < string2, zero if string1 == string2, positive if string1 > string2 Example: int diff = weechat_strncasecmp ("aaa", "CCC", 2); /* == -2 */

Prototype: int weechat_strcmp_ignore_chars ( const char *string1, const char *string2, const char *chars_ignored, int case_sensitive); Locale (and optionally case independent) string comparison, ignoring some chars. Arguments: string1: first string for comparison string2: second string for comparison chars_ignored: string with chars to ignore case_sensitive: 1 for case sensitive comparison, 0 otherwise Return value: difference between two strings: negative if string1 < string2, zero if string1 == string2, positive if string1 > string2 Example: int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */

Prototype: int weechat_strcasestr (const char *string, const char *search); Locale and case independent string search. Arguments: string: string search: string to search in "string" Return value: pointer to string found, or NULL if not found Example: char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */

Prototype: int weechat_string_match ( const char *string, const char *mask, int case_sensitive); Check if a string matches a mask. Mask may begin or end with "*" (no other "*" are allowed inside mask). Arguments: string: string mask: mask case_sensitive: 1 for case sensitive search, otherwise 0 Return value: 1 if string matches mask, otherwise 0. Examples: 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 */

Prototype: char *weechat_string_replace (const char *string, const char *search, const char *replace); Replace "search" string by new one in a string. Arguments: string: string search: string to replace replace: replacement for "search" string Return value: string with "search" replaced by "replace". Result has to be free by a call to "free" after use. Example: char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */

Prototype: char *weechat_string_remove_quotes (const char *string, const char *quotes); Remove quotes at beginning/end of string (ignore spaces if there are before first quote or after last quote). Arguments: string: string quotes: string with list of quotes Return value: string without quotes at beginning/end. Result has to be free by a call to "free" after use. Example: char *str = weechat_string_remove_quotes (string, " 'abc' ", "'"); /* result: "abc" */

Prototype: char *weechat_string_strip ( const char *string, int left, int right, const char *chars); Strip chars at beginning and/or end of string. Arguments: string: string left: strip left chars if different from 0 right: strip right chars if different from 0 chars: string with chars to strip Return value: stripped string. Result has to be free by a call to "free" after use. Example: char *str = weechat_strip (string, " ", 0, 1); /* remove spaces at end of string */

Prototype: char *weechat_string_has_highlight ( const char *string, const char highlight_words); Check if a string has highlights, using list of highlight words. Arguments: string: string highlight_words: list of highlight words, separated by comma Return value: 1 if string has one or more highlights, 0 otherwise. Example: if (weechat_string_has_highlight (string, "word1,word2")) ...

Prototype: char *weechat_string_mask_to_regex (const char *mask); Return a regex, built with a mask, where only special char is "*". All special chars for regex are escaped. Arguments: mask: mask Return value: regex. Example: char *regex = weechat_string_mask_to_regex ("test*mask");

Prototype: char **weechat_string_explode ( const char *string, const char *separators, int keep_eol, int num_items_max, int *num_items); Explode a string according to one or more delimiter(s). Arguments: string: string to explode separators: delimiters used for explosion keep_eol: if different from 0, then each argument will contain all string until end of line (see example below) num_items_max: maximum number of items created (0 = no limit) num_items: pointer to int which will contain number of items created Return value: array of strings, NULL if problem. Result has to be free by a call to "weechat_string_free_exploded" after use. Examples: 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);

Prototype: void weechat_string_free_exploded (char **exploded_string); Free memory used by a string explosion. Arguments: exploded_string: string exploded by "weechat_string_explode" function Return value: none. Example: char *argv; int argc; argv = weechat_string_explode (string, " ", 0, 0, &argc); ... weechat_string_free_exploded (, argv);

Prototype: char **weechat_string_build_with_exploded ( char **exploded_string, const char *separator); Build a string with exploded string. Arguments: exploded_string: string exploded by "weechat_string_explode" function separator: string used to separate strings Return value: string built with exploded string. Result has to be free by a call to "free" after use. Example: 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" */

Prototype: char **weechat_string_split_command (const char *command, char separator); Split a list of commands separated by 'separator' (which can be escaped by '\' in string). Arguments: command: command to split separator: separator Return value: array of strings, NULL if problem. Result has to be free by a call to "weechat_string_free_splitted_command" after use. Example: char **argv = weechat_string_split_command ("/command1;/command2", ';');

Prototype: void weechat_string_free_splitted_command (char **splitted_command); Free memory used by a splitted command. Arguments: splitted_command: command splitted by "weechat_string_split_commaand" function Return value: none. Example: char **argv = weechat_string_split_command ("/command1;/command2", ';'); ... weechat_string_free_splitted_command (argv);

Some UTF-8 string functions.

Prototype: int weechat_utf8_has_8bits (const char *string); Check if a string has 8-bits chars. Arguments: string: string Return value: 1 if string has 8-buts chars, 0 if only 7-bits chars. Example: if (weechat_utf8_has_8bits (string)) ...

Prototype: int weechat_utf8_is_valid (const char *string, char **error); Check if a string is UTF-8 valid. Arguments: string: string error: if not NULL, it is set with first non valid UTF-8 char in string, if any Return value: 1 if UTF-8 string is valid, 0 otherwise. Example: char *error; if (weechat_utf8_is_valid (string, &error)) ...

Prototype: void weechat_utf8_normalize (const char *string, char replacement); Normalize UTF-8 string: remove non UTF-8 chars and replace them by a char Arguments: string: string replacement: replacement char for non UTF-8 chars Return value: none. Example: weechat_utf8_normalize (string, '?');

Prototype: char *weechat_utf8_prev_char (const char *string_start, const char *string); Return previous UTF-8 char in a string. Arguments: string_start: start of string (function will not return a char before this pointer) string: pointer to string (must be >= string_start) Return value: pointer to previous UTF-8 char, NULL if not found (start of string reached) Example: char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);

Prototype: char *weechat_utf8_next_char (const char *string); Return next UTF-8 char in a string. Arguments: string: string Return value: pointer to next UTF-8 char, NULL if not found (end of string reached) Example: char *next_char = weechat_utf8_next_char (string);

Prototype: int weechat_utf8_char_size (const char *string); Return UTF-8 char size (in bytes). Arguments: string: string Return value: UTF-8 char size (in bytes). Example: int char_size = weechat_utf8_char_size ("être"); /* == 2 */

Prototype: int weechat_utf8_strlen (const char *string); Return UTF-8 string length (multi-byte char is considered as 1 char). Arguments: string: string Return value: UTF-8 string length (number of real chars). Example: int length = weechat_utf8_strlen ("chêne"); /* == 5 */

Prototype: int weechat_utf8_strnlen (const char *string, int bytes); Return UTF-8 string length (multi-byte char is considered as 1 char), for max bytes in string Arguments: string: string bytes: max bytes in string Return value: UTF-8 string length (number of real chars). Example: int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */

Prototype: int weechat_utf8_strlen_screen (const char *string); Return number of chars needed on screen to display UTF-8 string. Arguments: string: string Return value: number of chars needed on screen to display UTF-8 string. Example: int length_on_screen = weechat_utf8_strlen_screen ("东"); /* == 2 */

Prototype: int weechat_utf8_charcasecmp (const char *string1, const char *string2); Compare two UTF-8 chars (case is ignored). Arguments: string1: first string for comparison string2: second string for comparison Return value: difference between first char of each string: negative if char1 < char2, zero if char1 == char2, positive if char1 > char2 Example: if (weechat_utf8_charcasecmp (string1, string2) != 0) ...

Prototype: int weechat_utf8_char_size_screen (const char *string); Return number of chars needed on screen to display UTF-8 char. Arguments: string: string Return value: number of chars needed on screen to display UTF-8 char. Example: int length_on_screen = weechat_utf8_char_size_screen (string)

Prototype: char *weechat_utf8_add_offset (const char *string, int offset); Move forward N chars in an UTF-8 string. Arguments: string: string offset: number of chars Return value: pointer to string, N chars after (NULL if it's not reachable). Example: char *ptr = weechat_utf8_add_offset ("chêne", 3); /* points to "ne" */

Prototype: char *weechat_utf8_real_pos (const char *string, int pos); Get real position in UTF-8 string. Arguments: string: string pos: position in chars Return value: real position (in bytes) for "pos" chars in string. Example: int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */

Prototype: char *weechat_utf8_pos (const char *string, int real_pos); Get position in UTF-8 string. Arguments: string: string real_pos: position in bytes Return value: position (in chars) for "real_pos" bytes in string. Example: int pos = weechat_utf8_real_pos ("chêne", 4); /* == 3 */

Some functions related to directories.

Prototype: int weechat_mkdir_home (char *directory, int mode); Create a directory in WeeChat home. Arguments: directory: directory to create mode: mode for new directory Return value: 1 if directory was successfully created, 0 if an error occurred. Example: if (!weechat_mkdir_home ("temp")) ...

Prototype: int weechat_mkdir (char *directory, int mode); Create a directory. Arguments: directory: directory to create mode: mode for new directory Return value: 1 if directory was successfully created, 0 if an error occurred. Example: if (!weechat_mkdir ("/tmp/mydir")) ...

Prototype: int weechat_mkdir_parents (char *directory, int mode); Create a directory and make parent directories as needed. Arguments: directory: directory to create mode: mode for new directory (and parents) Return value: 1 if directory was successfully created, 0 if an error occurred. Example: if (!weechat_mkdir_parents ("/tmp/my/dir")) ...

Prototype: void weechat_exec_on_files ( const char *directory, void *data, int (*callback)(void *data, const char *filename)); Find files in a directory and execute a callback on each file. Arguments: directory: directory for searching files data: pointer given to callback when calling it found callback: function called for each file found, arguments: Type Name Description void * data pointer char * filename filename found Return value: none. Example: int callback (void *data, const char *filename) { /* ... */ return 1; } ... plugin->exec_on_files (plugin, "/tmp", &callback);

Some useful functions.

Prototype: int weechat_timeval_cmp (struct timeval *tv1, struct timeval *tv2); Compare 2 timeval structures. Arguments: tv1: first timeval structure tv2: second timeval structure Return value: -1 if tv1 < char2, zero if tv1 == tv2, +1 if tv1 > tv2 Example: if (weechat_timeval_cmp (&tv1, &tv2) > 0) ...

Prototype: long weechat_timeval_diff (struct timeval *tv1, struct timeval *tv2); Return difference (in milliseconds) between 2 timeval structures. Arguments: tv1: first timeval structure tv2: second timeval structure Return value: difference in milliseconds. Example: long diff = weechat_timeval_diff (&tv1, &tv2);

Prototype: void weechat_timeval_add (struct timeval *tv, long interval); Add interval (in milliseconds) to a timeval structure. Arguments: tv: timeval structure interval: interval (in milliseconds) Return value: none. Example: weechat_timeval_add (&tv, 2000); /* add 2 seconds */

Sorted list functions.

Prototype: struct t_weelist *weechat_list_new (); Create a new list. Return value: pointer to new list. Example: struct t_weelist *list = weechat_list_new ();

Prototype: struct t_weelist_item *weechat_list_add ( struct t_weelist *weelist, const char *data, const char *where); Add an item in a list. Arguments: weelist: list pointer data: data to insert in list where: position in list (constants are: WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING or WEECHAT_LIST_POS_END) Return value: pointer to new item. Example: weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT);

Prototype: struct t_weelist_item *weechat_list_search ( struct t_weelist *weelist, const char *data); Search an item in a list. Arguments: weelist: list pointer data: data to search in list Return value: pointer to item found, NULL if item was not found. Example: struct t_weelist_item *item = weechat_list_search (list, "my data");

Prototype: struct t_weelist_item *weechat_list_casesearch ( struct t_weelist *weelist, const char *data); Search an item in a list (case sensitive search). Arguments: weelist: list pointer data: data to search in list Return value: pointer to item found, NULL if item was not found. Example: struct t_weelist_item *item = weechat_list_casesearch (list, "my data");

Prototype: struct t_weelist_item *weechat_list_get ( struct t_weelist *weelist, int position); Get an item in a list by position. Arguments: weelist: list pointer position: position in list (0 is first item) Return value: pointer to item found, NULL if item position was not found. Example: struct t_weelist_item *item = weechat_list_get (list, 0); /* first item */

Prototype: void weechat_list_set (struct t_weelist_item *item, const char *value); Set new value for an item. Arguments: item: item pointer value: new value for item Example: weechat_list_set (item, "new data");/

Prototype: struct t_weelist_item *weechat_list_next (struct t_weelist_item *item); Get next item in list. Arguments: item: item pointer Return value: pointer to next item, NULL if pointer was last item in list. Example: struct t_weelist_item *next_item = weechat_list_next_item (item);/

Prototype: struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item); Get previous item in list. Arguments: item: item pointer Return value: pointer to previous item, NULL if pointer was first item in list. Example: struct t_weelist_item *prev_item = weechat_list_prev_item (item);/

Prototype: char *weechat_list_string (struct t_weelist_item *item); Get string value of an item. Arguments: item: item pointer Return value: string value of item. Example: char *value = weechat_list_string (item);/

Prototype: char *weechat_list_size (struct t_weelist *weelist); Get size of list (number of items). Arguments: weelist: list pointer Return value: size of list (number of items), 0 if list is empty. Example: int size = weechat_list_size (list);/

Prototype: void weechat_list_remove ( struct t_weelist *weelist, struct t_weelist_item *item); Remove an item in a list. Arguments: list: list pointer item: item pointer Example: weechat_list_remove (list, item);/

Prototype: void weechat_list_remove_all (struct t_weelist *weelist); Remove all items in a list. Arguments: list: list pointer Example: weechat_list_remove_all (list);/

Prototype: void weechat_list_free (struct t_weelist *weelist); Free a list. Arguments: list: list pointer Example: weechat_list_free (list);/

Functions for configuration files.

Prototype: 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); Create a new configuration file. Arguments: name: name of configuration file (without path or extension) callback_reload: callback called when configuration file is reloaded with /reload (optional, may be NULL), arguments: Type Name Description void * data pointer struct t_config_file * config_file configuration file pointer callback_reload_data: pointer given to reload callback when it is called by WeeChat NULL) Return value: pointer to new configuration file, NULL if an error occured. File is NOT created by this function. It will be created by call to function (you should do that only after adding some sections (with ) and options (with ). Example: 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);

Prototype: 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); Create a new section in configuration file. Arguments: config_file: configuration file pointer name: name of section user_can_add_options: 1 if user can add options in section, or 0 if it is forbidden user_can_delete_options: 1 if user can delete options in section, or 0 if it is forbidden callback_read: callback called when an option in section is read from disk (should be NULL for most cases, except if options in your section need custom function), arguments: Type Name Description void * data pointer struct t_config_file * config_file configuration file pointer struct t_config_section * section section pointer const char * option_name name of option const char * value value callback_read_data: pointer given to read callback when it is called by WeeChat NULL) callback_write: callback called when section is written in file (should be NULL for most cases, except if your section needs to be written by a custom function), arguments: Type Name Description void * data pointer struct t_config_file * config_file configuration file pointer struct t_config_section * section section pointer const char * option_name name of option callback_write_data: pointer given to write callback when it is called by WeeChat NULL) callback_write_default: callback called when default values for section must be written in file, arguments: Type Name Description void * data pointer struct t_config_file * config_file configuration file pointer char * section_name name of section callback_write_default_data: pointer given to write_default callback when it is called by WeeChat NULL) callback_create_option: callback called when a new option is created in section (NULL if section does not allow new options to be created), arguments: Type Name Description void * data pointer struct t_config_file * config_file configuration file pointer struct t_config_section * section section pointer const char * option_name name of option const char * value value callback_create_option_data: pointer given to create_option callback when it is called by WeeChat NULL) callback_delete_option: callback called when an option is deleted (NULL if section does not allow options to be deleted), arguments: Type Name Description void * data pointer struct t_config_file * config_file configuration file pointer struct t_config_section * section section pointer struct t_config_option *option option option pointer callback_delete_option_data: pointer given to delete_option callback when it is called by WeeChat NULL) Return value: pointer to new section in configuration file, NULL if an error occured. Example: 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);

Prototype: struct t_config_section *weechat_config_search_section ( struct t_config_file *config_file, const char *section_name); Search a section in a configuration file. Arguments: config_file: configuration file pointer section_name: name of section to search Return value: pointer to section found, NULL if section was not found. Example: struct t_config_section *section = weechat_config_search_section (config_file, "section");

Prototype: 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); Create a new option in a section of a configuration file. Arguments: config_file: configuration file pointer section: section pointer name: name of option type: type of option, one of: boolean integer string color description: description of option string_values: values as string (separated by "|"), used for type integer (optional) min: minimum value (for integer) NULL) max: maximum value (for integer) default_value: default value for option (used when option is reset) value: value for option callback_check_value: callback called to check new value for an option (optional), arguments: Type Name Description void * data pointer struct t_config_option * option option pointer const char * value new value for option callback_check_value_data: pointer given to check_value callback when it is called by WeeChat NULL) callback_change: callback called when value of option has changed (optional), arguments: Type Name Description void * data pointer struct t_config_option * option option pointer callback_change_data: pointer given to change callback when it is called by WeeChat NULL) callback_delete: callback called when option will be deleted (optional), arguments: Type Name Description void * data pointer struct t_config_option * option option pointer callback_delete_data: pointer given to delete callback when it is called by WeeChat NULL) Return value: pointer to new option in section, NULL if an error occured. Example: /* 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 */

Prototype: struct t_config_option *weechat_config_search_option ( struct t_config_file *config_file, struct t_config_section *section, const char *option_name); Search an option in a section of a configuration file. Arguments: config_file: configuration file pointer section: section pointer option_name: name of option to search Return value: pointer to option found, NULL if option was not found. Example: struct t_config_option *option = weechat_config_search_option (config_file, section, "option");

Prototype: 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); Search an option in in a configuration file with string. Arguments: option_name: full option name (format: "file.section.option") config_file: pointer to a configuration file pointer, will be set to configuration file of option, if found section: pointer to a section pointer, will be set to section of option, if found option: pointer to an option pointer, will be set to option pointer, if found Example: 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 */ /* ... */ }

Prototype: int weechat_config_string_to_boolean (const char *text); Check if a text is "true" or "false". Arguments: text: text to analyze 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"). Example: if (weechat_config_string_to_boolean ("on")) { /* true */ /* ... */ } else { /* false */ /* never executed! */ }

Prototype: int weechat_config_option_reset ( struct t_config_option *option, int run_callback); Reset an option to its default value. Arguments: option: option pointer run_callback: 1 for calling change callback if option is changed, 0 otherwise 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. Example: 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; }

Prototype: int weechat_config_option_set ( struct t_config_option *option, const char *value, int run_callback); Set new value for an option. Arguments: option: option pointer value: new value for option run_callback: 1 for calling change callback if option is changed, 0 otherwise 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. Example: 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; }

Prototype: int weechat_config_option_unset (struct t_config_option *option); Unset/reset option. Arguments: option: option pointer 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. Example: 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; }

Prototype: void weechat_config_option_rename ( struct t_config_option *option, const char *new_name); Rename an option. Arguments: option: option pointer new_name: new name for option Example: weechat_config_option_rename (option, "new_name");

Prototype: void *weechat_config_option_get_pointer ( struct t_config_option *option, const char *property); Get a pointer on an option property. Arguments: option: option pointer property: property name: Property Type Description config_file struct t_config_file * configuration file pointer section struct t_config_section * section pointer name char * option name type int option type description char * option description string_values char ** string values min int minimum value max int maximum value default_value (depends on type) default value value (depends on type) current value prev_option struct t_config_option * previous option pointer next_option struct t_config_option * next option pointer Example: char *description = weechat_config_option_get_pointer (option, "description");

Prototype: int weechat_config_boolean (struct t_config_option *option); Get boolean value of option. Arguments: option: option pointer Return value: boolean value of option (0 or 1). Example: if (weechat_config_boolean (option)) { /* true */ } else { /* false */ }

Prototype: int weechat_config_integer (struct t_config_option *option); Get integer value of option. Arguments: option: option pointer Return value: integer value of option. Example: int value = weechat_config_boolean (option);

Prototype: char *weechat_config_string (struct t_config_option *option); Get string value of option. Arguments: option: option pointer Return value: string value of option. Example: char *value = weechat_config_string (option);

Prototype: char *weechat_config_color (struct t_config_option *option); Get color value of option. Arguments: option: option pointer Return value: color value of option (string with name of color). Example: char *color = weechat_config_color (option);

Prototype: void weechat_config_write_line ( struct t_config_file *config_file, const char *option_name, const char *value, ...); Write a line in a configuration file (this function should be called only in "write" or "write_default" callbacks for a section). Arguments: config_file: configuration file pointer option_name: option name value: value Example: 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; }

Prototype: int weechat_config_write (struct t_config_file *config_file); Write configuration file to disk. Arguments: config_file: configuration file pointer 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. Example: 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; }

Prototype: int weechat_config_read (struct t_config_file *config_file); Read configuration file from disk. Arguments: config_file: configuration file pointer 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. Example: 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; }

Prototype: int weechat_config_reload (struct t_config_file *config_file); Reload configuration file from disk. Arguments: config_file: configuration file pointer 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. Example: 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; }

Prototype: void weechat_config_option_free (struct t_config_option *option); Free an option. Arguments: option: option pointer Example: weechat_config_option_free (option);

Prototype: void weechat_config_section_free_options (struct t_config_section *section); Free all options in a section. Arguments: section: section pointer Example: weechat_config_section_free_options (section);

Prototype: void weechat_config_section_free (struct t_config_section *section); Free a section. Arguments: section: section pointer Example: weechat_config_section_free (section);

Prototype: void weechat_config_free (struct t_config_file *config_file); Free a configuration file. Arguments: config_file: configuration file pointer Example: weechat_config_free (config_file);

Prototype: struct t_config_option *weechat_config_get (const char *option_name); Search an option in in a configuration file with string. Arguments: option_name: full option name (format: "file.section.option") Return value: pointer to option found, NULL if option was not found. Example: struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");

Prototype: char *weechat_config_get_plugin (const char *option_name); Search an option in plugins configuration file (plugins.conf), by adding prefix with current plugin name. Arguments: option_name: option name, WeeChat will add prefix "plugins.var.xxxx." (where xxxx is current plugin name). Return value: pointer to option found, NULL if option was not found. Example: /* 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");

Prototype: int weechat_config_set_plugin (const char *option_name, const char *value); Set value for option in in plugins configuration file (plugins.conf). Arguments: option_name: option name, WeeChat will add prefix "plugins.var.xxxx." (where xxxx is current plugin name). Return value: 1 if ok, 0 if an error occured. Example: weechat_config_set_plugin ("option", "test_value");

Functions to display text in buffers.

Prototype: char *weechat_prefix (const char *prefix); Get a prefix. Arguments: prefix: name of prefix: Prefix Default value Description error =!= error message network -- message from network action * self action join --> someone joins current chat quit <-- someone leaves current chat Return value: prefix value, empty string if prefix is not found (not NULL). Example: weechat_printf (NULL, "%sThis is an error...", weechat_prefix ("error"));

Prototype: char *weechat_color (const char *color_name); Get a string color code for display. Arguments: color_name: name of color: may be a WeeChat color name (from weechat.color.xxx), or a color with optional background (separated by comma). Return value: string with color code, or a "reset color" code if color is not found. Example: weechat_printf (NULL, "Color: %sblue %schat default %sred on green", weechat_color ("blue"), weechat_color ("chat"), weechat_color ("red,green"));

Prototype: void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...); Display a message on a buffer. Arguments: buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer. message: message to display Example: weechat_printf (NULL, "Hello on WeeChat buffer"); weechat_printf (buffer, "Hello on this buffer");

Prototype: void weechat_printf_date ( struct t_gui_buffer *buffer, time_t date, const char *message, ...); Display a message on a buffer, using a custom date. Arguments: buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer. date: date for message message: message to display Example: weechat_printf (NULL, time (NULL) - 120, "Hello, 2 minutes ago");

Prototype: void weechat_printf_tags ( struct t_gui_buffer *buffer, const char *tags, const char *message, ...); Display a message on a buffer, using a custom tags. Arguments: buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer. tags: tags for message, separated by a comma message: message to display Example: weechat_printf_tags (NULL, "notify_message", "Hello with a message notify tag");

Prototype: void weechat_printf_date_tags ( struct t_gui_buffer *buffer, time_t date, const char *tags, const char *message, ...); Display a message on a buffer, using a custom date and tags. Arguments: buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer. date: date for message tags: tags for message, separated by a comma message: message to display Example: weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message", "Hello, 2 minutes ago, with a message notify tag");

Prototype: void weechat_printf_y ( struct t_gui_buffer *buffer, int y, const char *message, ...); Display a message on a line of a buffer with free content (see ). Arguments: buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer. y: line number (0 for first line) message: message to display Example: weechat_printf_y (buffer, 2, "My message on third line");

Functions to hook/unhook something.

Prototype: struct t_hook *weechat_hook_command ( const char *command, const char *description, const char *args, const char *args_description, const char *completion, int (*callback)(void *data, struct t_gui_buffer *buffer, int argc, char **argv, char **argv_eol), void *callback_data); Hook a command. Arguments: command: new command name description: description of command (displayed with /help command) args: arguments for command (displayed with /help command) args_description: description of arguments (displayed with /help command) completion: completion template for command: list of completions for each arguments, separated by space. Many completions are possible for one argument, separated by "|". Default completion codes are: Code Completion %- Stop completion %* Repeat last completion %b Buffers names %c Configuration files %f Filename %F Filters %h Commands hooked %i Infos hooked %I Infolists hooked %n Nick %o Configuration option %p Plugin name %P Plygin commands %r Bar names %v Value of configuration opeion %w WeeChat commands %(xxx) Custom completion by plugin (xxx is a completion code added by a plugin) callback: function called when command is used, arguments: Type Name Description void * data pointer struct t_gui_buffer * buffer buffer where command is executed int argc argument count char ** argv arguments char ** argv_eol arguments (until end of line) For example, if command called is /command abc def ghi, then argv and argv_eol contain following values: argv[0] == "abc" argv[1] == "def" argv[2] == "ghi" argv_eol[0] == "abc def ghi" argv_eol[1] == "def ghi" argv_eol[2] == "ghi" callback_data: pointer given to callback when it is called by WeeeChat Example: int my_command_cb (void *data, struct t_gui_buffer *buffer, int argc, char **argv, char **argv_eol) { /* ... */ return WEECHAT_RC_OK; } struct t_hook *my_command = weechat_hook_command ("mycommand", "description of my command", "[command [buffer]]", "command: WeeChat or plugin command\n" " buffer: buffer name", "%w|%p %b", &my_command_cb, NULL);

Prototype: struct t_hook *weechat_hook_timer ( long interval, const char *align_second, const char *max_calls, int (*callback)(void *data), void *callback_data); Hook a timer. Arguments: interval: interval between two calls (milliseconds, so 1000 = 1 second) align_second: alignment on a second: align timer on a second. For example, if current time is 09:00, if interval = 60000 (60 seconds), and align_second = 60, then timer is called each minute when second is 00. max_calls: number of calls to timer (if 0, then timer has no end) callback: function called when time is reached, arguments: Type Name Description void * data pointer callback_data: pointer given to callback when it is called by WeeeChat Example: int my_timer_cb (void *data) { /* ... */ return WEECHAT_RC_OK; } /* timer called each 20 seconds */ struct t_hook *my_timer = weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL);

Prototype: struct t_hook *weechat_hook_fd ( int fd, int flag_read, int flag_write, int flag_exception, int (*callback)(void *data), void *callback_data); Hook a file descriptor (file or socket). Arguments: fd: file descriptor flag_read: 1 for catching read event, 0 for ignoring it flag_write: 1 for catching write event, 0 for ignoring it flag_exception: 1 for catching exception event, 0 for ignoring it callback: function called when a selected event occurs, arguments: Type Name Description void * data pointer callback_data: pointer given to callback when it is called by WeeeChat Example: int my_fd_cb (void *data) { /* ... */ return WEECHAT_RC_OK; } int sock = socket (AF_INET, SOCK_STREAM, 0); /* set socket options */ /* ... */ /* hook socket */ struct t_hook *my_fd = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL);

Prototype: struct t_hook *weechat_hook_connect ( const char *address, int port, int sock, int ipv6, void *gnutls_sess, const char *local_hostname, int (*callback)(void *data, int status, const char *ip_address), void *callback_data); Hook a connection (background connection to a remote host). Arguments: address: name or IP address to connect to port: port number sock: socket used to connect ipv6: 1 to use IPv6, 0 to use IPv4 gnutls_sess: GnuTLS session (optional) callback: function called when connection is ok or failed, arguments: Type Name Description void * data pointer int status constant with connection status: WEECHAT_HOOK_CONNECT_OK WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED WEECHAT_HOOK_CONNECT_PROXY_ERROR WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR WEECHAT_HOOK_CONNECT_MEMORY_ERROR void * data pointer callback_data: pointer given to callback when it is called by WeeeChat Example: int my_connect_cb (void *data, int status, const char *ip_address) { switch (status) { case WEECHAT_HOOK_CONNECT_OK: /* ... */ break; case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: /* ... */ break; case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: /* ... */ break; case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: /* ... */ break; case WEECHAT_HOOK_CONNECT_PROXY_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: /* ... */ break; case WEECHAT_HOOK_CONNECT_MEMORY_ERROR: /* ... */ break; } return WEECHAT_RC_OK; } struct t_hook *my_connect = weechat_hook_fd (sock, 1, 0, 0, &my_connect_cb, NULL);

Prototype: struct t_hook *weechat_hook_print ( struct t_gui_buffer *buffer, const char *tags, const char *message, int strip_colors, int (*callback)(void *data, struct t_gui_buffer *buffer, time_t date, int tags_count, const char **tags, const char *prefix, const char *message), void *callback_data); Hook a message printed. Arguments: buffer: buffer pointer, if NULL, messages from any buffer are catched tags: only messages with these tags (comma separated list) will be catched (optional) message: only messages with this string will be catched (optional) strip_colors: colors will be stripped from message displayed, before calling callback callback: function called when message is printed, arguments: Type Name Description void * data pointer struct t_gui_buffer * buffer buffer pointer time_t date date int tags_count number of tags for line const char ** tags tags for line const char * prefix prefix char * message message callback_data: pointer given to callback when it is called by WeeeChat Example: int my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date, int tags_count, const char **tags, const char *prefix, const char *message) { /* ... */ return WEECHAT_RC_OK; } /* catch all messages, on all buffers, without color */ struct t_hook *my_print = weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL);

Functions to create/query/close buffers. Missing doc!

Functions for buffer nicklist. Missing doc!

Functions for bars. Missing doc!

Functions for executing WeeChat commands. Missing doc!

Network functions. Missing doc!

Functions to get infos. Missing doc!

Functions for infolists. Missing doc!

Functions for WeeChat upgrading. Missing doc!