WeeChat Plugin API Reference

This manual documents WeeChat chat client, it is part of WeeChat.

Latest version of this document can be found on this page: http://weechat.org/doc

1. Introduction

WeeChat (Wee Enhanced Environment for Chat) is a free chat client, fast and light, designed for many operating systems.

This manual documents WeeChat plugins API, used by C plugins to interact with WeeChat core.

2. Plugins in WeeChat

A plugin is a C program which can call WeeChat functions defined in an interface.

This C program does not need WeeChat sources to compile and can be dynamically loaded into WeeChat with command /plugin.

The plugin has to be a dynamic library, for dynamic loading by operating system. Under GNU/Linux, the file has ".so" extension, ".dll" under Windows.

The plugin has to include "weechat-plugin.h" file (available in WeeChat source code). This file defines structures and types used to communicate with WeeChat.

2.1. Macros

The plugin must use some macros (to define some variables):

WEECHAT_PLUGIN_NAME("name"): plugin name
WEECHAT_PLUGIN_DESCRIPTION("description"): short description of plugin
WEECHAT_PLUGIN_VERSION("1.0"): plugin version
WEECHAT_PLUGIN_LICENSE("GPL3"): plugin license

2.2. Main functions

The plugin must use two functions:

weechat_plugin_init
weechat_plugin_end

2.2.1. weechat_plugin_init

This function is called when plugin is loaded by WeeChat.

Prototype:

int weechat_plugin_init (struct t_weechat_plugin *plugin,
                         int argc, char *argv[]);

Arguments:

plugin: pointer to WeeChat plugin structure
argc: number of arguments for plugin (given on command line by user)
argv: arguments for plugin

Return value:

WEECHAT_RC_OK if successful (plugin will be loaded)
WEECHAT_RC_ERROR if error (plugin will NOT be loaded)

2.2.2. weechat_plugin_end

This function is called when plugin is unloaded by WeeChat.

Prototype:

int weechat_plugin_end (struct t_weechat_plugin *plugin);

Arguments:

plugin: pointer to WeeChat plugin structure

Return value:

WEECHAT_RC_OK if successful
WEECHAT_RC_ERROR if error

2.3. Compile plugin

Compile does not need WeeChat sources, only file weechat-plugin.h is required.

To compile a plugin which has one file "toto.c" (under GNU/Linux):

$ gcc -fPIC -Wall -c toto.c
$ gcc -shared -fPIC -o libtoto.so toto.o

2.4. Load plugin

Copy file libtoto.so into system plugins directory (for example /usr/local/lib/weechat/plugins) or into user’s plugins directory (for example /home/xxx/.weechat/plugins).

Under WeeChat:

/plugin load toto

2.5. Plugin example

Full example of plugin, which adds a command /double: displays two times arguments on current buffer, or execute two times a command (ok that’s not very useful, but that’s just an example!):

#include <stdlib.h>

#include "weechat-plugin.h"

WEECHAT_PLUGIN_NAME("double");
WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat");
WEECHAT_PLUGIN_AUTHOR("Sebastien Helleu <flashcode@flashtux.org>");
WEECHAT_PLUGIN_VERSION("0.1");
WEECHAT_PLUGIN_LICENSE("GPL3");

struct t_weechat_plugin *weechat_plugin = NULL;


/* callback for command "/double" */

int
command_double_cb (void *data, struct t_gui_buffer *buffer, int argc,
                   char **argv, char **argv_eol)
{
    /* make C compiler happy */
    (void) data;
    (void) buffer;
    (void) argv;

    if (argc > 1)
    {
        weechat_command (NULL, argv_eol[1]);
        weechat_command (NULL, argv_eol[1]);
    }

    return WEECHAT_RC_OK;
}

int
weechat_plugin_init (struct t_weechat_plugin *plugin,
                     int argc, char *argv[])
{
    weechat_plugin = plugin;

    weechat_hook_command ("double",
                          "Display two times a message "
                          "or execute two times a command",
                          "message | command",
                          "message: message to display two times\n"
                          "command: command to execute two times",
                          NULL,
                          &command_double_cb, NULL);

    return WEECHAT_RC_OK;
}

int
weechat_plugin_end (struct t_weechat_plugin *plugin)
{
    /* make C compiler happy */
    (void) plugin;

    return WEECHAT_RC_OK;
}

3. Plugin API

Following chapters describe functions in API, sorted by category.

For each function, we give:

description of function,
C prototype,
detail of arguments,
return value,
C example,
example in Python script (syntax for other scripting languages is similar).

3.1. Plugins

Functions to get infos about plugins.

3.1.1. weechat_plugin_get_name

Get plugin name.

Prototype:

const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin);

Arguments:

plugin: pointer to WeeChat plugin structure (can be NULL)

Return value:

name of plugin, "core" for WeeChat core (if plugin pointer is NULL)

C example:

const char *name = weechat_plugin_get_name (plugin);

Script (Python):

# prototype
name = weechat.plugin_get_name(plugin)

# example
plugin = weechat.buffer_get_pointer(weechat.current_buffer(), "plugin")
name = weechat.plugin_get_name(plugin)

3.2. Strings

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.

3.2.1. weechat_charset_set

Set new plugin charset (default charset is UTF-8, so if your plugin uses UTF-8, you don’t need to call this function).

Prototype:

void weechat_charset_set (const char *charset);

Arguments:

charset: new charset to use

C example:

weechat_charset_set ("iso-8859-1");

Script (Python):

# prototype
weechat.charset_set(charset)

# example
weechat.charset_set("iso-8859-1")

3.2.2. weechat_iconv_to_internal

Convert string to WeeChat internal charset (UTF-8).

Prototype:

char *weechat_iconv_to_internal (const char *charset, const char *string);

Arguments:

charset: charset to convert
string: string to convert

Return value:

converted string (must be freed by calling "free" after use)

C example:

char *str = weechat_iconv_to_internal ("iso-8859-1", "iso string: é à");
/* ... */
free (str);

Script (Python):

# prototype
str = weechat.iconv_to_internal(charset, string)

# example
str = weechat.iconv_to_internal("iso-8859-1", "iso string: é à")

3.2.3. weechat_iconv_from_internal

Convert string from internal WeeChat charset (UTF-8) to another.

Prototype:

char *weechat_iconv_from_internal (const char *charset, const char *string);

Arguments:

charset: target charset
string: string to convert

Return value:

converted string (must be freed by calling "free" after use)

C example:

char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");
/* ... */
free (str);

Script (Python):

# prototype
str = weechat.iconv_from_internal(charset, string)

# example
str = weechat.iconv_from_internal("iso-8859-1", "utf-8 string: é à")

3.2.4. weechat_gettext

Return translated string (depends on local language).

Prototype:

const char *weechat_gettext (const char *string);

Arguments:

string: string to translate

Return value:

translated string

C example:

char *str = weechat_gettext ("hello");

Script (Python):

# prototype
str = weechat.gettext(string)

# example
str = weechat.gettext("hello")

3.2.5. weechat_ngettext

Return translated string, using single or plural form, according to count argument.

Prototype:

const char *weechat_ngettext (const char *string, const char *plural,
                              int count);

Arguments:

string: string to translate, single form
plural: string to translate, plural form
count: used to choose between single and plural form (choice is made according to local language)

Return value:

translated string

C example:

char *str = weechat_ngettext ("file", "files", num_files);

Script (Python):

# prototype
str = weechat.ngettext(string, plural, count)

# example
num_files = 2
str = weechat.ngettext("file", "files", num_files)

3.2.6. weechat_strndup

Return duplicated string, with length chars max.

Prototype:

char *weechat_strndup (const char *string, int length);

Arguments:

string: string to duplicate
length: max chars to duplicate

Return value:

duplicated string (must be freed by calling "free" after use)

C example:

char *str = weechat_strndup ("abcdef", 3); /* result: "abc" */
/* ... */
free (str);

Note	This function is not available in scripting API.

3.2.7. weechat_string_tolower

Convert UTF-8 string to lower case.

Prototype:

void weechat_string_tolower (const char *string);

Arguments:

string: string to convert

C example:

char *str = "AbCdé";
weechat_string_tolower (str); /* str is now: "abcdé" */

Note	This function is not available in scripting API.

3.2.8. weechat_string_toupper

Convert UTF-8 string to upper case.

Prototype:

void weechat_string_toupper (const char *string);

Arguments:

string: string to convert

C example:

char *str = "AbCdé";
weechat_string_toupper (str); /* str is now: "ABCDé" */

Note	This function is not available in scripting API.

3.2.9. weechat_strcasecmp

Locale and case independent string comparison.

Prototype:

int weechat_strcasecmp (const char *string1, const char *string2);

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

C example:

int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */

Note	This function is not available in scripting API.

3.2.10. weechat_strcasecmp_range

New in version 0.3.7.

Locale and case independent string comparison, using a range for case comparison.

Prototype:

int weechat_strcasecmp_range (const char *string1, const char *string2, int range);

Arguments:

string1: first string for comparison
string2: second string for comparison
range: number of chars in case comparison, for example:
- 26: "A-Z" are lowered to "a-z"
- 29: "A-Z [ \ ]" are lowered to "a-z { | }"
- 30: "A-Z [ \ ] ^" are lowered to "a-z { | } ~"

Note	Values 29 and 30 are used by some protocols like IRC.

Return value:

difference between two strings:
- negative if string1 < string2
- zero if string1 == string2
- positive if string1 > string2

C example:

int diff = weechat_strcasecmp_range ("nick{away}", "NICK[away]", 29); /* == 0 */

Note	This function is not available in scripting API.

3.2.11. weechat_strncasecmp

Locale and case independent string comparison, for max chars.

Prototype:

int weechat_strncasecmp (const char *string1, const char *string2, int max);

Arguments:

string1: first string for comparison
string2: second string for comparison
max: max chars to compare

Return value:

difference between two strings:
- negative if string1 < string2
- zero if string1 == string2
- positive if string1 > string2

C example:

int diff = weechat_strncasecmp ("aabb", "aacc", 2); /* == 0 */

Note	This function is not available in scripting API.

3.2.12. weechat_strncasecmp_range

New in version 0.3.7.

Locale and case independent string comparison, for max chars, using a range for case comparison.

Prototype:

int weechat_strncasecmp_range (const char *string1, const char *string2, int max, int range);

Arguments:

string1: first string for comparison
string2: second string for comparison
max: max chars to compare
range: number of chars in case comparison, for example:
- 26: "A-Z" are lowered to "a-z"
- 29: "A-Z [ \ ]" are lowered to "a-z { | }"
- 30: "A-Z [ \ ] ^" are lowered to "a-z { | } ~"

Note	Values 29 and 30 are used by some protocols like IRC.

Return value:

difference between two strings:
- negative if string1 < string2
- zero if string1 == string2
- positive if string1 > string2

C example:

int diff = weechat_strncasecmp_range ("nick{away}", "NICK[away]", 6, 29); /* == 0 */

Note	This function is not available in scripting API.

3.2.13. weechat_strcmp_ignore_chars

Locale (and optionally case independent) string comparison, ignoring some chars.

Prototype:

int weechat_strcmp_ignore_chars (const char *string1, const char *string2,
                                 const char *chars_ignored,
                                 int case_sensitive);

Arguments:

string1: first string for comparison
string2: second string for comparison
chars_ignored: string with chars to ignored
case_sensitive: 1 for case sensitive comparison, otherwise 0

Return value:

difference between two strings:
- negative if string1 < string2
- zero if string1 == string2
- positive if string1 > string2

C example:

int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */

Note	This function is not available in scripting API.

3.2.14. weechat_strcasestr

Locale and case independent string search.

Prototype:

char *weechat_strcasestr (const char *string, const char *search);

Arguments:

string: string
search: string to search in string

Return value:

pointer to string found, or NULL if not found

C example:

char *pos = weechat_strcasestr ("aBcDeF", "de"); /* result: pointer to "DeF" */

Note	This function is not available in scripting API.

3.2.15. weechat_strlen_screen

New in version 0.4.2.

Return number of chars needed on screen to display UTF-8 string. Non-printable chars have a width of 1 (this is the difference with the function weechat_utf8_strlen_screen).

Prototype:

int weechat_strlen_screen (const char *string);

Arguments:

string: string

Return value:

number of chars needed on screen to display UTF-8 string

C example:

int length_on_screen = weechat_strlen_screen ("é"); /* == 1 */

Script (Python):

# prototype
length = weechat.strlen_screen(string)

# example
length = weechat.strlen_screen("é") # 1

3.2.16. weechat_string_match

Check if a string matches a mask.

Prototype:

int weechat_string_match (const char *string, const char *mask,
                          int case_sensitive);

Arguments:

string: string
mask: mask, can begin or end with "*" (no other "*" are allowed inside mask)
case_sensitive: 1 for case sensitive comparison, otherwise 0

Return value:

1 if string matches mask, otherwise 0

C example:

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 */
int match4 = weechat_string_match ("abcdef", "*de*", 0); /* == 1 */

Script (Python):

# prototype
match = weechat.string_match(string, mask, case_sensitive)

# examples
match1 = weechat.string_match("abcdef", "abc*", 0) # 1
match2 = weechat.string_match("abcdef", "*dd*", 0) # 0
match3 = weechat.string_match("abcdef", "*def", 0) # 1
match4 = weechat.string_match("abcdef", "*de*", 0) # 1

3.2.17. weechat_string_replace

Replace all occurrences of a string by another string.

Prototype:

char *weechat_string_replace (const char *string, const char *search,
                              const char *replace);

Arguments:

string: string
search: string to replace
replace: replacement for string search

Return value:

string with search replaced by replace (must be freed by calling "free" after use)

C example:

char *str = weechat_string_replace ("test", "s", "x"); /* result: "text" */
/* ... */
free (str);

Note	This function is not available in scripting API.

3.2.18. weechat_string_expand_home

New in version 0.3.3.

Replace leading ~ by string with home directory. If string does not start with ~, then same string is returned.

Prototype:

char *weechat_string_expand_home (const char *path);

Arguments:

path: path

Return value:

path with leading ~ replaced by home directory (must be freed by calling "free" after use)

C example:

char *str = weechat_string_expand_home ("~/file.txt");
/* result: "/home/xxx/file.txt" */
/* ... */
free (str);

Note	This function is not available in scripting API.

3.2.19. weechat_string_remove_quotes

Remove quotes at beginning and end of string (ignore spaces if there are before first quote or after last quote).

Prototype:

char *weechat_string_remove_quotes (const char *string, const char *quotes);

Arguments:

string: string
quotes: string with list of quotes

Return value:

string without quotes at beginning/end (must be freed by calling "free" after use)

C example:

char *str = weechat_string_remove_quotes (string, " 'I can't' ", "'");
/* result: "I can't" */
/* ... */
free (str);

Note	This function is not available in scripting API.

3.2.20. weechat_string_strip

Strip chars at beginning and/or end of string.

Prototype:

char *weechat_string_strip (const char *string, int left, int right,
                            const char *chars);

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 (must be freed by calling "free" after use)

C example:

char *str = weechat_string_strip (".abc -", 0, 1, "- ."); /* result: ".abc" */
/* ... */
free (str);

Note	This function is not available in scripting API.

3.2.21. weechat_string_mask_to_regex

Return a regex, built with a mask, where only special char is "*". All other special chars for regex are escaped.

Prototype:

char *weechat_string_mask_to_regex (const char *mask);

Arguments:

mask: mask

Return value:

regular expression, as string (must be freed by calling "free" after use)

C example:

char *str_regex = weechat_string_mask_to_regex ("test*mask");
/* result: "test.*mask" */
/* ... */
free (str_regex);

Script (Python):

# prototype
regex = weechat.string_mask_to_regex(mask)

# example
regex = weechat.string_mask_to_regex("test*mask") # "test.*mask"

3.2.22. weechat_string_regex_flags

New in version 0.3.7.

Get pointer on string after flags and return mask with flags to compile regular expression.

Prototype:

const char *weechat_string_regex_flags (const char *regex, int default_flags, int *flags)

Arguments:

regex: regular expression
default_flags: combination of following values (see man regcomp):
- REG_EXTENDED
- REG_ICASE
- REG_NEWLINE
- REG_NOSUB
flags: pointer value is set with flags used in regular expression (default flags + flags set in regular expression)

Flags must be at beginning of regular expression. Format is: "(?eins-eins)string".

Allowed flags are:

e: POSIX extended regular expression (REG_EXTENDED)
i: case insensitive (REG_ICASE)
n: match-any-character operators don’t match a newline (REG_NEWLINE)
s: support for substring addressing of matches is not required (REG_NOSUB)

Return value:

pointer in regex, after flags

C example:

const char *regex = "(?i)test";
int flags;
const char *ptr_regex = weechat_string_regex_flags (regex, REG_EXTENDED, &flags);
/* ptr_regex == "test", flags == REG_EXTENDED | REG_ICASE */

Note	This function is not available in scripting API.

3.2.23. weechat_string_regcomp

New in version 0.3.7.

Compile a regular expression using optional flags at beginning of string (for format of flags, see weechat_string_regex_flags).

Prototype:

int weechat_string_regcomp (void *preg, const char *regex, int default_flags)

Arguments:

preg: pointer to regex_t structure
regex: regular expression
default_flags: combination of following values (see man regcomp):
- REG_EXTENDED
- REG_ICASE
- REG_NEWLINE
- REG_NOSUB

Return value:

same return code as function regcomp (0 if ok, other value for error, see man regcomp)

C example:

regex_t my_regex;
if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) != 0)
{
    /* error */
}

Note	This function is not available in scripting API.

3.2.24. weechat_string_has_highlight

Check if a string has one or more highlights, using list of highlight words.

Prototype:

int weechat_string_has_highlight (const char *string,
                                  const char highlight_words);

Arguments:

string: string
highlight_words: list of highlight words, separated by comma

Return value:

1 if string has one or more highlights, otherwise 0

C example:

int hl = weechat_string_has_highlight ("my test string", "test,word2"); /* == 1 */

Script (Python):

# prototype
highlight = weechat.string_has_highlight(string, highlight_words)

# example
highlight = weechat.string_has_highlight("my test string", "test,word2") # 1

3.2.25. weechat_string_has_highlight_regex

New in version 0.3.4.

Check if a string has one or more highlights, using a regular expression. For at least one match of regular expression on string, it must be surrounded by word chars (alphanumeric character, "-", "_" or "|").

Prototype:

int weechat_string_has_highlight_regex (const char *string, const char *regex);

Arguments:

string: string
regex: regular expression

Return value:

1 if string has one or more highlights, otherwise 0

C example:

int hl = weechat_string_has_highlight_regex ("my test string", "test|word2"); /* == 1 */

Script (Python):

# prototype
highlight = weechat.string_has_highlight_regex(string, regex)

# example
highlight = weechat.string_has_highlight_regex("my test string", "test|word2") # 1

3.2.26. weechat_string_split

Split a string according to one or more delimiter(s).

Prototype:

char **weechat_string_split (const char *string, const char *separators,
                             int keep_eol, int num_items_max,
                             int *num_items);

Arguments:

string: string to split
separators: delimiters used for split
keep_eol:
- 0: each string will contain one word
- 1: each string will contain all string until end of line (see example below)
- 2: same as 1, but do not remove separators at end of string before split (new in version 0.3.6)
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 (must be freed by calling weechat_string_free_split after use)

C examples:

char **argv;
int argc;
argv = weechat_string_split ("abc de  fghi", " ", 0, 0, &argc);
/* result: argv[0] == "abc"
           argv[1] == "de"
           argv[2] == "fghi"
           argv[3] == NULL
           argc == 3
*/
weechat_string_free_split (argv);

argv = weechat_string_split ("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_split (argv);

Note	This function is not available in scripting API.

3.2.27. weechat_string_free_split

Free memory used by a split string.

Prototype:

void weechat_string_free_split (char **split_string);

Arguments:

split_string: string split by function weechat_string_split

C example:

char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);

Note	This function is not available in scripting API.

3.2.28. weechat_string_build_with_split_string

Build a string with a split string.

Prototype:

char *weechat_string_build_with_split_string (char **split_string,
                                              const char *separator);

Arguments:

split_string: string split by function weechat_string_split
separator: string used to separate strings

Return value:

string built with split string (must be freed by calling "free" after use)

C example:

char **argv;
int argc;
argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc);
char *str = weechat_string_build_with_split_string (argv, ";");
/* str == "abc;def;ghi" */
/* ... */
free (str);

Note	This function is not available in scripting API.

3.2.29. weechat_string_split_command

Split a list of commands separated by separator (which can be escaped by "\" in string).

Prototype:

char **weechat_string_split_command (const char *command, char separator);

Arguments:

command: command to split
separator: separator

Return value:

array of strings, NULL if problem (must be freed by calling weechat_free_split_command after use)

C example:

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* result: argv[0] == "/command1 arg"
           argv[1] == "/command2"
*/
weechat_free_split_command (argv);

Note	This function is not available in scripting API.

3.2.30. weechat_string_free_split_command

Free memory used by a split command.

Prototype:

void weechat_string_free_split_command (char **split_command);

Arguments:

split_command: command split by weechat_string_split_command

C example:

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* ... */
weechat_free_split_command (argv);

Note	This function is not available in scripting API.

3.2.31. weechat_string_format_size

Build a string with formatted file size and a unit translated to local language.

Prototype:

char *weechat_string_format_size (unsigned long long size);

Arguments:

size: size (in bytes)

Return value:

formatted string (must be freed by calling "free" after use)

C examples:

/* examples with english locale */

char *str = weechat_string_format_size (0); /* str == "0 byte" */
/* ... */
free (str);

char *str = weechat_string_format_size (200); /* str == "200 bytes" */
/* ... */
free (str);

char *str = weechat_string_format_size (1536); /* str == "1.5 KB" */
/* ... */
free (str);

char *str = weechat_string_format_size (2097152); /* str == "2 MB" */
/* ... */
free (str);

Note	This function is not available in scripting API.

3.2.32. weechat_string_remove_color

Remove WeeChat colors from a string.

Prototype:

char *weechat_string_remove_color (const char *string,
                                   const char *replacement);

Arguments:

string: string
replacement: if not NULL and not empty, WeeChat color codes are replaced by first char of this string, otherwise WeeChat color codes and following chars (if related to color) are removed from string

Return value:

string without color (must be freed by calling "free" after use)

C examples:

/* remove color codes */
char *str = weechat_string_remove_color (my_string1, NULL);
/* ... */
free (str);

/* replace color codes by "?" */
char *str = weechat_string_remove_color (my_string2, "?");
/* ... */
free (str);

Script (Python):

# prototype
str = weechat.string_remove_color(string, replacement)

# example
str = weechat.string_remove_color(my_string, "?")

3.2.33. weechat_string_encode_base64

New in version 0.3.2.

Encode a string in base64.

Prototype:

void weechat_string_encode_base64 (const char *from, int length, char *to);

Arguments:

from: string to encode
length: length of string to encode (for example strlen(from))
to: pointer to string to store result (must be long enough, result is longer than initial string)

C example:

char *string = "abcdefgh", result[128];
weechat_string_encode_base64 (string, strlen (string), result);
/* result == "YWJjZGVmZ2g=" */

Note	This function is not available in scripting API.

3.2.34. weechat_string_decode_base64

New in version 0.3.2.

Decode a base64 string.

Prototype:

int weechat_string_decode_base64 (const char *from, char *to);

Arguments:

from: string to decode
to: pointer to string to store result (must be long enough, result is shorter than initial string)

Return value:

length of string stored in *to (does not count final \0)

C example:

char *string = "YWJjZGVmZ2g=", result[128];
int length;
length = weechat_string_decode_base64 (string, result);
/* length == 8, result == "abcdefgh" */

Note	This function is not available in scripting API.

3.2.35. weechat_string_is_command_char

New in version 0.3.2.

Check if first char of string is a command char (default command char is /).

Prototype:

int weechat_string_is_command_char (const char *string);

Arguments:

string: string

Return value:

1 if first char of string is a command char, otherwise 0

C examples:

int command_char1 = weechat_string_is_command_char ("/test"); /* == 1 */
int command_char2 = weechat_string_is_command_char ("test");  /* == 0 */

Script (Python):

# prototype
is_cmdchar = weechat.string_is_command_char(string)

# examples
command_char1 = weechat.string_is_command_char("/test") # == 1
command_char2 = weechat.string_is_command_char("test")  # == 0

3.2.36. weechat_string_input_for_buffer

New in version 0.3.2.

Return pointer to input text for buffer (pointer inside "string" argument), or NULL if it’s a command.

Prototype:

const char *weechat_string_input_for_buffer (const char *string);

Arguments:

string: string

Return value:

pointer into "string", or NULL

C examples:

const char *str1 = weechat_string_input_for_buffer ("test");   /* "test"  */
const char *str2 = weechat_string_input_for_buffer ("/test");  /* NULL    */
const char *str3 = weechat_string_input_for_buffer ("//test"); /* "/test" */

Script (Python):

# prototype
str = weechat.string_input_for_buffer(string)

# examples
str1 = weechat.string_input_for_buffer("test")   # "test"
str2 = weechat.string_input_for_buffer("/test")  # ""
str3 = weechat.string_input_for_buffer("//test") # "/test"

3.2.37. weechat_string_eval_expression

New in version 0.4.0, updated in 0.4.2.

Evaluate an expression and return result as a string. Special variables with format ${variable} are expanded (see command /eval in WeeChat User’s guide).

Prototype:

char *weechat_string_eval_expression (const char *expr,
                                      struct t_hashtable *pointers,
                                      struct t_hashtable *extra_vars,
                                      struct t_hashtable *options);

Arguments:

expr: the expression to evaluate
pointers: hashtable with pointers (keys must be string, values must be pointer); pointers "window" and "buffer" are automatically added if they are not in hashtable (with pointer to current window/buffer) (can be NULL)
extra_vars: extra variables that will be expanded (can be NULL)
options: a hashtable with some options (keys and values must be string) (can be NULL):
- type: default behavior is just to replace values in expression, other types can be selected:
  - condition: the expression is evaluated as a condition: operators and parentheses are used, result is a boolean ("0" or "1")
- prefix: prefix before variables to replace (default: "${")
- suffix: suffix after variables to replace (default: "}")

Return value:

evaluated expression (must be freed by calling "free" after use), or NULL if problem (invalid expression or not enough memory)

C examples:

struct t_hashtable *options = weechat_hashtable_new (8,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     NULL,
                                                     NULL);
if (options)
    weechat_hashtable_set (options, "type", "condition");
char *str1 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);          /* "core.weechat" */
char *str2 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options); /* "1" */
char *str3 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options);                /* "0" */

Script (Python):

# prototype
str = weechat.string_eval_expression(expr, pointers, extra_vars, options)

# examples
str1 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {})                          # "core.weechat"
str2 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"}) # "1"
str3 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                # "0"

3.3. UTF-8

Some UTF-8 string functions.

3.3.1. weechat_utf8_has_8bits

Check if a string has 8-bits chars.

Prototype:

int weechat_utf8_has_8bits (const char *string);

Arguments:

string: string

Return value:

1 if string has 8-bits chars, 0 if only 7-bits chars

C example:

if (weechat_utf8_has_8bits (string))
{
    /* ... */
}

Note	This function is not available in scripting API.

3.3.2. weechat_utf8_is_valid

Check if a string is UTF-8 valid.

Prototype:

int weechat_utf8_is_valid (const char *string, char **error);

Arguments:

string: string
error: if not NULL, error is set with pointer to first non valid UTF-8 char in string, if any

Return value:

1 if UTF-8 string is valid, otherwise 0

C example:

char *error;
if (weechat_utf8_is_valid (string, &error))
{
    /* ... */
}
else
{
    /* "error" points to first invalid char */
}

Note	This function is not available in scripting API.

3.3.3. weechat_utf8_normalize

Normalize UTF-8 string: remove non UTF-8 chars and replace them by a char.

Prototype:

void weechat_utf8_normalize (char *string, char replacement);

Arguments:

string: string
replacement: replacement char for invalid chars

C example:

weechat_utf8_normalize (string, '?');

Note	This function is not available in scripting API.

3.3.4. weechat_utf8_prev_char

Return pointer to previous UTF-8 char in a string.

Prototype:

char *weechat_utf8_prev_char (const char *string_start, const char *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)

C example:

char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);

Note	This function is not available in scripting API.

3.3.5. weechat_utf8_next_char

Return pointer to next UTF-8 char in a string.

Prototype:

char *weechat_utf8_next_char (const char *string);

Arguments:

string: string

Return value:

pointer to next UTF-8 char, NULL if not found (end of string reached)

C example:

char *next_char = weechat_utf8_next_char (string);

Note	This function is not available in scripting API.

3.3.6. weechat_utf8_char_int

Return UTF-8 char as integer.

Prototype:

int weechat_utf8_char_int (const char *string);

Arguments:

string: string

Return value:

UTF-8 char as integer

C example:

int char_int = weechat_utf8_char_int ("être"); /* "ê" as integer */

Note	This function is not available in scripting API.

3.3.7. weechat_utf8_char_size

Return UTF-8 char size (in bytes).

Prototype:

int weechat_utf8_char_size (const char *string);

Arguments:

string: string

Return value:

UTF-8 char size (in bytes)

C example:

int char_size = weechat_utf8_char_size ("être"); /* == 2 */

Note	This function is not available in scripting API.

3.3.8. weechat_utf8_strlen

Return UTF-8 string length (in UTF-8 chars).

Prototype:

int weechat_utf8_strlen (const char *string);

Arguments:

string: string

Return value:

UTF-8 string length (number of UTF-8 chars)

C example:

int length = weechat_utf8_strlen ("chêne"); /* == 5 */

Note	This function is not available in scripting API.

3.3.9. weechat_utf8_strnlen

Return UTF-8 string length (in UTF-8 chars), for max bytes in string.

Prototype:

int weechat_utf8_strnlen (const char *string, int bytes);

Arguments:

string: string
bytes: max bytes

Return value:

UTF-8 string length (number of UTF-8 chars)

C example:

int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */

Note	This function is not available in scripting API.

3.3.10. weechat_utf8_strlen_screen

Return number of chars needed on screen to display UTF-8 string.

Prototype:

int weechat_utf8_strlen_screen (const char *string);

Arguments:

string: string

Return value:

number of chars needed on screen to display UTF-8 string

C example:

int length_on_screen = weechat_utf8_strlen_screen ("é"); /* == 1 */

Note	This function is not available in scripting API.

3.3.11. weechat_utf8_charcmp

Compare two UTF-8 chars.

Prototype:

int weechat_utf8_charcmp (const char *string1, const char *string2);

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

C example:

int diff = weechat_utf8_charcmp ("aaa", "ccc"); /* == -2 */

Note	This function is not available in scripting API.

3.3.12. weechat_utf8_charcasecmp

Compare two UTF-8 chars, ignoring case.

Prototype:

int weechat_utf8_charcasecmp (const char *string1, const char *string2);

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

C example:

int diff = weechat_utf8_charcasecmp ("aaa", "CCC"); /* == -2 */

Note	This function is not available in scripting API.

3.3.13. weechat_utf8_char_size_screen

Return number of chars needed on screen to display UTF-8 char.

Prototype:

int weechat_utf8_char_size_screen (const char *string);

Arguments:

string: string

Return value:

number of chars needed on screen to display UTF-8 char

C example:

int length_on_screen = weechat_utf8_char_size_screen ("é"); /* == 1 */

Note	This function is not available in scripting API.

3.3.14. weechat_utf8_add_offset

Move forward N chars in an UTF-8 string.

Prototype:

char *weechat_utf8_add_offset (const char *string, int offset);

Arguments:

string: string
offset: number of chars

Return value:

pointer to string, N chars after (NULL if it’s not reachable)

C example:

char *str = "chêne";
char *str2 = weechat_utf8_add_offset (str, 3); /* points to "ne" */

Note	This function is not available in scripting API.

3.3.15. weechat_utf8_real_pos

Return real position in UTF-8 string.

Prototype:

int weechat_utf8_real_pos (const char *string, int pos);

Arguments:

string: string
pos: position (number of chars)

Return value:

real potision (in bytes)

C example:

int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */

Note	This function is not available in scripting API.

3.3.16. weechat_utf8_pos

Return position in UTF-8 string.

Prototype:

int weechat_utf8_pos (const char *string, int real_pos);

Arguments:

string: string
real_pos: position (bytes)

Return value:

position (number of chars)

C example:

int pos = weechat_utf8_pos ("chêne", 4); /* == 3 */

Note	This function is not available in scripting API.

3.3.17. weechat_utf8_strndup

Return duplicate string, with length chars max.

Prototype:

char *weechat_utf8_strndup (const char *string, int length);

Arguments:

string: string
length: max chars to duplicate

Return value:

duplicated string (must be freed by calling "free" after use)

C example:

char *string = weechat_utf8_strndup ("chêne", 3); /* returns "chê" */
/* ... */
free (string);

Note	This function is not available in scripting API.

3.4. Directories

Some functions related to directories.

3.4.1. weechat_mkdir_home

Create a directory in WeeChat home.

Prototype:

int weechat_mkdir_home (char *directory, int mode);

Arguments:

directory: name of directory to create
mode: mode for directory

Return value:

1 if directory was successfully created, 0 if an error occurred

C example:

if (!weechat_mkdir_home ("temp", 0755))
{
    /* error */
}

Script (Python):

# prototype
weechat.mkdir_home(directory, mode)

# example
weechat.mkdir_home("temp", 0755)

3.4.2. weechat_mkdir

Create a directory.

Prototype:

int weechat_mkdir (char *directory, int mode);

Arguments:

directory: name of directory to create
mode: mode for directory

Return value:

1 if directory was successfully created, 0 if an error occurred

C example:

if (!weechat_mkdir ("/tmp/mydir", 0755))
{
    /* error */
}

Script (Python):

# prototype
weechat.mkdir(directory, mode)

# example
weechat.mkdir("/tmp/mydir", 0755)

3.4.3. weechat_mkdir_parents

Create a directory and make parent directories as needed.

Prototype:

int weechat_mkdir_parents (char *directory, int mode);

Arguments:

directory: name of directory to create
mode: mode for directory

Return value:

1 if directory was successfully created, 0 if an error occurred

C example:

if (!weechat_mkdir_parents ("/tmp/my/dir", 0755))
{
    /* error */
}

Script (Python):

# prototype
weechat.mkdir_parents(directory, mode)

# example
weechat.mkdir_parents("/tmp/my/dir", 0755)

3.4.4. weechat_exec_on_files

Find files in a directory and execute a callback on each file.

Prototype:

void weechat_exec_on_files (const char *directory,
                            int hidden_files,
                            void *data,
                            void (*callback)(void *data,
                                             const char *filename));

Arguments:

directory: directory for searching files
hidden_files: 1 to include hidden files, otherwise 0
data: pointer given to callback when it is called by WeeChat
callback: function called for each file found, arguments:
- void *data: pointer
- const char *filename: filename found

C example:

void callback (void *data, const char *filename)
{
    /* ... */
}
...
weechat_exec_on_files ("/tmp", 0, NULL, &callback);

Note	This function is not available in scripting API.

3.4.5. weechat_file_get_content

New in version 0.3.1.

Get content of text file in a string.

Prototype:

char *weechat_file_get_content (const char *filename);

Arguments:

filename: path and file name

Return value:

content of file as string (must be freed by calling "free" after use)

C example:

char *content;

content = weechat_file_get_content ("/tmp/test.txt");
/* ... */
free (content);

Note	This function is not available in scripting API.

3.5. Util

Some useful functions.

3.5.1. weechat_util_timeval_cmp

Compare two "timeval" structures.

Prototype:

int weechat_util_timeval_cmp (struct timeval *tv1, struct timeval *tv2);

Arguments:

tv1: first "timeval" structure
tv2: second "timeval" structure

Return value:

-1 if tv1 < tv2
zero if tv1 == tv2
+1 if tv1 > tv2

C example:

if (weechat_util_timeval_cmp (&tv1, &tv2) > 0)
{
    /* tv1 > tv2 */
}

Note	This function is not available in scripting API.

3.5.2. weechat_util_timeval_diff

Return difference (in milliseconds) between two "timeval" structures.

Prototype:

long weechat_util_timeval_diff (struct timeval *tv1, struct timeval *tv2);

Arguments:

tv1: first "timeval" structure
tv2: second "timeval" structure

Return value:

difference in milliseconds

C example:

long diff = weechat_util_timeval_diff (&tv1, &tv2);

Note	This function is not available in scripting API.

3.5.3. weechat_util_timeval_add

Add interval (in milliseconds) to a timeval structure.

Prototype:

void weechat_util_timeval_add (struct timeval *tv, long interval);

Arguments:

tv: timeval structure
interval: interval (in milliseconds)

C example:

weechat_util_timeval_add (&tv, 2000); /* add 2 seconds */

Note	This function is not available in scripting API.

3.5.4. weechat_util_get_time_string

New in version 0.3.2.

Get date/time as a string built with "strftime".

Prototype:

char *weechat_util_get_time_string (const time_t *date);

Arguments:

date: pointer to date

C example:

time_t date = time (NULL);
weechat_printf (NULL, "date: %s",
                weechat_util_get_time_string (&date));

Note	This function is not available in scripting API.

3.5.5. weechat_util_version_number

New in version 0.3.9.

Convert a string with WeeChat version to a number.

Prototype:

int weechat_util_version_number (const char *version);

Arguments:

version: WeeChat version as string (example: "0.3.9" or "0.3.9-dev")

C example:

version_number = weechat_util_version_number ("0.3.8");     /* == 0x00030800 */
version_number = weechat_util_version_number ("0.3.9-dev"); /* == 0x00030900 */
version_number = weechat_util_version_number ("0.3.9-rc1"); /* == 0x00030900 */
version_number = weechat_util_version_number ("0.3.9");     /* == 0x00030900 */

Note	This function is not available in scripting API.

3.6. Sorted lists

Sorted list functions.

3.6.1. weechat_list_new

Create a new list.

Prototype:

struct t_weelist *weechat_list_new ();

Return value:

pointer to new list

C example:

struct t_weelist *list = weechat_list_new ();

Script (Python):

# prototype
list = weechat.list_new()

# example
list = weechat.list_new()

3.6.2. weechat_list_add

Add an item in a list.

Prototype:

struct t_weelist_item *weechat_list_add (struct t_weelist *weelist,
                                         const char *data,
                                         const char *where,
                                         void *user_data);

Arguments:

weelist: list pointer
data: data to insert in list
where: position in list:
- WEECHAT_LIST_POS_SORT: add in list, keeping list sorted
- WEECHAT_LIST_POS_BEGINNING: add to beginning of list
- WEECHAT_LIST_POS_END: add to end of list
user_data: any pointer

Return value:

pointer to new item

C example:

struct t_weelist_item *my_item =
    weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL);

Script (Python):

# prototype
item = weechat.list_add(list, data, where, user_data)

# example
item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "")

3.6.3. weechat_list_search

Search an item in a list.

Prototype:

struct t_weelist_item *weechat_list_search (struct t_weelist *weelist,
                                            const char *data);

Arguments:

weelist: list pointer
data: data to search in list

Return value:

pointer to item found, NULL if item was not found

C example:

struct t_weelist_item *item = weechat_list_search (list, "my data");

Script (Python):

# prototype
item = weechat.list_search(list, data)

# example
item = weechat.list_search(list, "my data")

3.6.4. weechat_list_search_pos

New in version 0.3.4.

Search an item position in a list.

Prototype:

int weechat_list_search_pos (struct t_weelist *weelist,
                             const char *data);

Arguments:

weelist: list pointer
data: data to search in list

Return value:

position of item found, -1 if item was not found

C example:

int pos_item = weechat_list_search_pos (list, "my data");

Script (Python):

# prototype
pos_item = weechat.list_search_pos(list, data)

# example
pos_item = weechat.list_search_pos(list, "my data")

3.6.5. weechat_list_casesearch

Search an item in a list, ignoring case.

Prototype:

struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist,
                                                const char *data);

Arguments:

weelist: list pointer
data: data to search in list

Return value:

pointer to item found, NULL if item was not found

C example:

struct t_weelist_item *item = weechat_list_casesearch (list, "my data");

Script (Python):

# prototype
item = weechat.list_casesearch(list, data)

# example
item = weechat.list_casesearch(list, "my data")

3.6.6. weechat_list_casesearch_pos

New in version 0.3.4.

Search an item position in a list, ignoring case.

Prototype:

int weechat_list_casesearch_pos (struct t_weelist *weelist,
                                 const char *data);

Arguments:

weelist: list pointer
data: data to search in list

Return value:

position of item found, -1 if item was not found

C example:

int pos_item = weechat_list_casesearch_pos (list, "my data");

Script (Python):

# prototype
pos_item = weechat.list_casesearch_pos(list, data)

# example
pos_item = weechat.list_casesearch_pos(list, "my data")

3.6.7. weechat_list_get

Return an item in a list by position.

Prototype:

struct t_weelist_item *weechat_list_get (struct t_weelist *weelist,
                                         int position);

Arguments:

weelist: list pointer
position: position in list (first item is 0)

Return value:

pointer to item found, NULL if item was not found

C example:

struct t_weelist_item *item = weechat_list_get (list, 0); /* first item */

Script (Python):

# prototype
item = weechat.list_get(list, position)

# example
item = weechat.list_get(list, 0)

3.6.8. weechat_list_set

Set new value for an item.

Prototype:

void weechat_list_set (struct t_weelist_item *item, const char *value);

Arguments:

item: item pointer
value: new value for item

C example:

weechat_list_set (item, "new data");

Script (Python):

# prototype
weechat.list_set(item, value)

# example
weechat.list_set(item, "new data")

3.6.9. weechat_list_next

Return next item in list.

Prototype:

struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);

Arguments:

item: item pointer

Return value:

pointer to next item, NULL if pointer was last item in list

C example:

struct t_weelist_item *next_item = weechat_list_next (item);

Script (Python):

# prototype
item = weechat.list_next(item)

# example
item = weechat.list_next(item)

3.6.10. weechat_list_prev

Return previous item in list.

Prototype:

struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);

Arguments:

item: item pointer

Return value:

pointer to previous item, NULL if pointer was last item in list

C example:

struct t_weelist_item *prev_item = weechat_list_prev (item);

Script (Python):

# prototype
item = weechat.list_prev(item)

# example
item = weechat.list_prev(item)

3.6.11. weechat_list_string

Return string value of an item.

Prototype:

const char *weechat_list_string (struct t_weelist_item *item);

Arguments:

item: item pointer

Return value:

string value of item

C example:

weechat_printf (NULL, "value of item: %s", weechat_list_string (item));

Script (Python):

# prototype
value = weechat.list_string(item)

# example
weechat.prnt("", "value of item: %s" % weechat.list_string(item))

3.6.12. weechat_list_size

Return size of list (number of items).

Prototype:

char *weechat_list_size (struct t_weelist *weelist);

Arguments:

weelist: list pointer

Return value:

size of list (number of items), 0 if list is empty

C example:

weechat_printf (NULL, "size of list: %d", weechat_list_size (list));

Script (Python):

# prototype
size = weechat.list_size(list)

# example
weechat.prnt("", "size of list: %d" % weechat.list_size(list))

3.6.13. weechat_list_remove

Remove an item in a list.

Prototype:

void weechat_list_remove (struct t_weelist *weelist,
                          struct t_weelist_item *item);

Arguments:

weelist: list pointer
item: item pointer

C example:

weechat_list_remove (list, item);

Script (Python):

# prototype
weechat.list_remove(list, item)

# example
weechat.list_remove(list, item)

3.6.14. weechat_list_remove_all

Remove all items in a list.

Prototype:

void weechat_list_remove_all (struct t_weelist *weelist);

Arguments:

weelist: list pointer

C example:

weechat_list_remove_all (list);

Script (Python):

# prototype
weechat.list_remove_all(list)

# example
weechat.list_remove_all(list)

3.6.15. weechat_list_free

Free a list.

Prototype:

void weechat_list_free (struct t_weelist *weelist);

Arguments:

weelist: list pointer

C example:

weechat_list_free (list);

Script (Python):

# prototype
weechat.list_free(list)

# example
weechat.list_free(list)

3.7. Hashtables

Hashtable functions.

3.7.1. weechat_hashtable_new

New in version 0.3.3.

Create a new hashtable.

Prototype:

struct t_hashtable *weechat_hashtable_new (int size,
                                           const char *type_keys,
                                           const char *type_values,
                                           unsigned long (*callback_hash_key)(struct t_hashtable *hashtable,
                                                                              const void *key),
                                           int (*callback_keycmp)(struct t_hashtable *hashtable,
                                                                  const void *key1,
                                                                  const void *key2));

Arguments:

size: size of internal array to store hashed keys, a high value uses more memory, but has better performance (this is not a limit for number of items in hashtable)
type_keys: type for keys in hashtable:
- WEECHAT_HASHTABLE_INTEGER
- WEECHAT_HASHTABLE_STRING
- WEECHAT_HASHTABLE_POINTER
- WEECHAT_HASHTABLE_BUFFER
- WEECHAT_HASHTABLE_TIME
type_values: type for values in hashtable:
- WEECHAT_HASHTABLE_INTEGER
- WEECHAT_HASHTABLE_STRING
- WEECHAT_HASHTABLE_POINTER
- WEECHAT_HASHTABLE_BUFFER
- WEECHAT_HASHTABLE_TIME
callback_hash_key: callback used to "hash" a key (key as integer value), can be NULL if key type is not "buffer" (a default hash function is used), arguments and return value:
- struct t_hashtable *hashtable: hashtable pointer
- const void *key: key
- return value: hash of the key
callback_keycmp: callback used to compare two keys, can be NULL if key type is not "buffer" (a default comparison function is used), arguments and return value:
- struct t_hashtable *hashtable: hashtable pointer
- const void *key1: first key
- const void *key2: second key
- return value:
  - negative number if key1 is less than key2
  - 0 if key1 equals key2
  - positive number if key1 is greater than key2

Return value:

pointer to new hashtable, NULL if an error occurred

C example:

struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);

Note	This function is not available in scripting API.

3.7.2. weechat_hashtable_set_with_size

New in version 0.3.3, updated in 0.4.2.

Add or update item in a hashtable with size for key and value.

Prototype:

struct t_hashtable_item *weechat_hashtable_set_with_size (struct t_hashtable *hashtable,
                                                          const void *key, int key_size,
                                                          const void *value, int value_size);

Arguments:

hashtable: hashtable pointer
key: key pointer
key_size: size of key (in bytes), used only if type of keys in hashtable is "buffer"
value: value pointer
value_size: size of value (in bytes), used only if type of values in hashtable is "buffer"

Return value:

pointer to item created/updated, NULL if error

C example:

weechat_hashtable_set_with_size (hashtable, "my_key", 0,
                                 my_buffer, sizeof (my_buffer_struct));

Note	This function is not available in scripting API.

3.7.3. weechat_hashtable_set

New in version 0.3.3, updated in 0.4.2.

Add or update item in a hashtable.

Prototype:

struct t_hashtable_item *weechat_hashtable_set (struct t_hashtable *hashtable,
                                                const void *key, const void *value);

Arguments:

hashtable: hashtable pointer
key: key pointer
value: value pointer

Return value:

pointer to item created/updated, NULL if error

C example:

weechat_hashtable_set (hashtable, "my_key", "my_value");

Note	This function is not available in scripting API.

3.7.4. weechat_hashtable_get

New in version 0.3.3.

Get value associated with a key in a hashtable.

Prototype:

void *weechat_hashtable_get (struct t_hashtable *hashtable, void *key);

Arguments:

hashtable: hashtable pointer
key: key pointer

Return value:

value for key, NULL if key is not found

C example:

void *value = weechat_hashtable_get (hashtable, "my_key");

Note	This function is not available in scripting API.

3.7.5. weechat_hashtable_has_key

New in version 0.3.4.

Return 1 if hashtable has key, otherwise 0.

Prototype:

int weechat_hashtable_has_key (struct t_hashtable *hashtable, void *key);

Arguments:

hashtable: hashtable pointer
key: key pointer

Return value:

1 if key is in hashtable, 0 if key is not in hashtable

C example:

if (weechat_hashtable_has_key (hashtable, "my_key"))
{
    /* key is in hashtable */
    /* ... */
}

Note	This function is not available in scripting API.

3.7.6. weechat_hashtable_map

New in version 0.3.3.

Call a function on all hashtable entries.

Prototype:

void hashtable_map (struct t_hashtable *hashtable,
                    void (*callback_map)(void *data,
                                         struct t_hashtable *hashtable,
                                         const void *key,
                                         const void *value),
                    void *callback_map_data);

Arguments:

hashtable: hashtable pointer
callback_map: function called for each entry in hashtable
callback_map_data: pointer given to map callback when it is called

C example:

void
map_cb (void *data, struct t_hashtable *hashtable,
        const void *key, const void *value)
{
    /* display key and value (they are both strings here) */
    weechat_printf (NULL, "key: '%s', value: '%s'",
                    (const char *)key,
                    (const char *)value);
}
/* ... */
weechat_hashtable_map (hashtable, &map_cb, NULL);

Note	This function is not available in scripting API.

3.7.7. weechat_hashtable_map_string

New in version 0.3.7.

Call a function on all hashtable entries, sending keys and values as strings.

Prototype:

void hashtable_map_string (struct t_hashtable *hashtable,
                           void (*callback_map)(void *data,
                                                struct t_hashtable *hashtable,
                                                const char *key,
                                                const char *value),
                           void *callback_map_data);

Arguments:

hashtable: hashtable pointer
callback_map: function called for each entry in hashtable
callback_map_data: pointer given to map callback when it is called

Note	The strings key and value sent to callback are temporary strings, they are deleted after call to callback.

C example:

void
map_cb (void *data, struct t_hashtable *hashtable,
        const char *key, const char *value)
{
    /* display key and value */
    weechat_printf (NULL, "key: '%s', value: '%s'",
                    key, value);
}
/* ... */
weechat_hashtable_map_string (hashtable, &map_cb, NULL);

Note	This function is not available in scripting API.

3.7.8. weechat_hashtable_get_integer

New in version 0.3.3.

Return integer value of a hashtable property.

Prototype:

int weechat_hashtable_get_integer (struct t_hashtable *hashtable,
                                   void *property);

Arguments:

hashtable: hashtable pointer
property: property name:
- size: size of internal array "htable" in hashtable
- items_count: number of items in hashtable

Return value:

integer value of property

C example:

int items_count = weechat_hashtable_get_integer (hashtable, "items_count");

Note	This function is not available in scripting API.

3.7.9. weechat_hashtable_get_string

New in version 0.3.4.

Return string value of a hashtable property.

Prototype:

const char *weechat_hashtable_get_string (struct t_hashtable *hashtable,
                                          const char *property);

Arguments:

hashtable: hashtable pointer
property: property name:
- type_keys: type for keys:
  - integer: integer
  - string: string
  - pointer: pointer
  - buffer: buffer
  - time: time
- type_values: type for values:
  - integer: integer
  - string: string
  - pointer: pointer
  - buffer: buffer
  - time: time
- keys: string with list of keys (format: "key1,key2,key3")
- keys_sorted: string with list of sorted keys (format: "key1,key2,key3")
- values: string with list of values (format: "value1,value2,value3")
- keys_values: string with list of keys and values (format: "key1:value1,key2:value2,key3:value3")
- keys_values_sorted: string with list of keys and values (sorted by keys) (format: "key1:value1,key2:value2,key3:value3")

Return value:

string value of property

C examples:

weechat_printf (NULL, "keys are type: %s",
                weechat_hashtable_get_string (hashtable, "type_keys"));
weechat_printf (NULL, "list of keys: %s",
                weechat_hashtable_get_string (hashtable, "keys"));

Note	This function is not available in scripting API.

3.7.10. weechat_hashtable_set_pointer

New in version 0.3.4.

Set pointer value of a hashtable property.

Prototype:

void weechat_hashtable_set_pointer (struct t_hashtable *hashtable,
                                    const char *property, void *pointer);

Arguments:

hashtable: hashtable pointer
property and value: property name, with its value:
- callback_free_key: set callback function used to free keys in hashtable (new in version 0.4.2)
- callback_free_value: set callback function used to free values in hashtable

C example:

void
my_free_value_cb (struct t_hashtable *hashtable, const void *key, void *value)
{
    /* ... */
}

weechat_hashtable_set_pointer (hashtable, "callback_free_value", &my_free_value_cb);

Note	This function is not available in scripting API.

3.7.11. weechat_hashtable_add_to_infolist

New in version 0.3.3.

Add hashtable items to an infolist item.

Prototype:

int weechat_hashtable_add_to_infolist (struct t_hashtable *hashtable,
                                       struct t_infolist_item *infolist_item,
                                       const char *prefix);

Arguments:

hashtable: hashtable pointer
infolist_item: infolist item pointer
prefix: string used as prefix for names in infolist

Return value:

1 if ok, 0 if error

C example:

weechat_hashtable_add_to_infolist (hashtable, infolist_item, "testhash");

/* if hashtable contains:
     "key1" => "value 1"
     "key2" => "value 2"
   then following variables will be added to infolist item:
     "testhash_name_00000"  = "key1"
     "testhash_value_00000" = "value 1"
     "testhash_name_00001"  = "key2"
     "testhash_value_00001" = "value 2"
*/

Note	This function is not available in scripting API.

3.7.12. weechat_hashtable_remove

New in version 0.3.3.

Remove an item in a hashtable.

Prototype:

void weechat_hashtable_remove (struct t_hashtable *hashtable, const void *key);

Arguments:

hashtable: hashtable pointer
key: key pointer

C example:

weechat_hashtable_remove (hashtable, "my_key");

Note	This function is not available in scripting API.

3.7.13. weechat_hashtable_remove_all

New in version 0.3.3.

Remove all items in a hashtable.

Prototype:

void weechat_hashtable_remove_all (struct t_hashtable *hashtable);

Arguments:

hashtable: hashtable pointer

C example:

weechat_hashtable_remove_all (hashtable);

Note	This function is not available in scripting API.

3.7.14. weechat_hashtable_free

New in version 0.3.3.

Free a hashtable.

Prototype:

void weechat_hashtable_free (struct t_hashtable *hashtable);

Arguments:

hashtable: hashtable pointer

C example:

weechat_hashtable_free (hashtable);

Note	This function is not available in scripting API.

3.8. Configuration files

Functions for configuration files.

3.8.1. weechat_config_new

Create a new configuration file.

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);

Arguments:

name: name of configuration file (without path or extension)
callback_reload: function called when configuration file is reloaded with /reload (optional, can be NULL), arguments and return value:
- void *data: pointer
- struct t_config_file *config_file: configuration file pointer
- return value:
  - WEECHAT_CONFIG_READ_OK
  - WEECHAT_CONFIG_READ_MEMORY_ERROR
  - WEECHAT_CONFIG_READ_FILE_NOT_FOUND
callback_reload_data: pointer given to reload callback when it is called by WeeChat

Return value:

pointer to new configuration file, NULL if an error occurred

Note	File is NOT created on disk by this function. It will be created by call to function weechat_config_write. You should call this function only after adding some sections (with weechat_config_new_section) and options (with weechat_config_new_option).

C 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);

Script (Python):

# prototype
config_file = weechat.config_new(name, calback_reload, callback_reload_data)

# example
def my_config_reload_cb(data, config_file):
    # ...
    return weechat.WEECHAT_RC_OK

config_file = weechat.config_new("test", "my_config_reload_cb", "")

3.8.2. weechat_config_new_section

Create a new section in configuration file.

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,
                          const char *section_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);

Arguments:

config_file: configuration file pointer
name: name of section
user_can_add_options: 1 if user can create new 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: function called when an option in section is read from disk (should be NULL in most cases, except if options in section need custom function), arguments and return value:
- 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
- return value:
  - WEECHAT_CONFIG_READ_OK
  - WEECHAT_CONFIG_READ_MEMORY_ERROR
  - WEECHAT_CONFIG_READ_FILE_NOT_FOUND
callback_read_data: pointer given to callback when it is called by WeeChat
callback_write: function called when section is written in file (should be NULL for most cases, except if section needs to be written by a custom function), arguments and return value:
- 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
- return value:
  - WEECHAT_CONFIG_WRITE_OK
  - WEECHAT_CONFIG_WRITE_ERROR
  - WEECHAT_CONFIG_WRITE_MEMORY_ERROR
callback_write_data: pointer given to callback when it is called by WeeChat
callback_write_default: function called when default values for section must be written in file, arguments:
- void *data: pointer
- struct t_config_file *config_file: configuration file pointer
- const char *section_name: name of section
- return value:
  - WEECHAT_CONFIG_WRITE_OK
  - WEECHAT_CONFIG_WRITE_ERROR
  - WEECHAT_CONFIG_WRITE_MEMORY_ERROR
callback_write_default_data: pointer given to callback when it is called by WeeChat
callback_create_option: function called when a new option is created in section (NULL if section does not allow new options to be created), arguments and return value:
- 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
- return value:
  - WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
  - WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
  - WEECHAT_CONFIG_OPTION_SET_ERROR
  - WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND
callback_create_option_data: pointer given to callback when it is called by WeeChat
callback_delete_option: function called when an option is deleted in section (NULL if section does not allow options to be deleted), arguments and return value:
- 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 pointer
- return value:
  - WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET
  - WEECHAT_CONFIG_OPTION_UNSET_OK_RESET
  - WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED
  - WEECHAT_CONFIG_OPTION_UNSET_ERROR
callback_delete_option_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new section in configuration file, NULL if an error occurred

C 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_CONFIG_OPTION_SET_OK_CHANGED;
    /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
}

int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    /* ... */

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
}

int
my_section_write_default_cb (void *data, struct t_config_file *config_file,
                             const char *section_name)
{
    /* ... */

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
}

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_CONFIG_OPTION_SET_OK_SAME_VALUE;
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
}

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_CONFIG_OPTION_UNSET_OK_REMOVED;
    /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */
}

/* standard section, user can not add/delete options */
struct t_config_section *new_section1 =
    weechat_config_new_section (config_file, "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_section (config_file, "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);

Script (Python):

# prototype
section = weechat.config_new_section(config_file, name,
    user_can_add_options, user_can_delete_options,
    callback_read, callback_read_data,
    callback_write, callback_write_data,
    callback_create_option, callback_create_option_data,
    callback_delete_option, callback_delete_option_data)

# example
def my_section_read_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR

def my_section_write_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK

def my_section_write_default_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK

def my_section_create_option_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

def my_section_delete_option_cb(data, config_file, section, option):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED

section = weechat.config_new_section(config_file, "section1", 1, 1,
    "my_section_read_cb", "",
    "my_section_write_cb", "",
    "my_section_write_default_cb", "",
    "my_section_create_option_cb", "",
    "my_section_delete_option_cb", "")

3.8.3. weechat_config_search_section

Search a section in a configuration file.

Prototype:

struct t_config_section *weechat_config_search_section (
    struct t_config_file *config_file,
    const char *section_name);

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

C example:

struct t_config_section *section = weechat_config_search_section (config_file,
                                                                  "section");

Script (Python):

# prototype
section = weechat.config_search_section(config_file, section_name)

# example
section = weechat.config_search_section(config_file, "section")

3.8.4. weechat_config_new_option

Create a new option in a section of a configuration file.

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 char *default_value,
    const char *value,
    int null_value_allowed,
    int (*callback_check_value)(void *data,
                                struct t_config_option *option,
                                const char *value),
    void *callback_check_value_data,
    void (*callback_change)(void *data,
                            struct t_config_option *option),
    void *callback_change_data,
    void (*callback_delete)(void *data,
                            struct t_config_option *option),
    void *callback_delete_data);

Arguments:

config_file: configuration file pointer
section: section pointer
name: name of option
type: type of option:
- boolean: boolean value (on/off)
- integer: integer value (with optional strings for values)
- string: string value
- color: color
description: description of option
string_values: values as string (separated by "|"), used for type integer (optional)
min: minimum value (for type integer)
max: maximum value (for type integer)
default_value: default value for option (used when option is reset)
value: value for option
null_value_allowed: 1 if null (undefined value) is allowed for option, otherwise 0
callback_check_value: function called to check new value for option (optional), arguments and return value:
- void *data: pointer
- struct t_config_option *option: option pointer
- const char *value: new value for option
- return value:
  - 1 if value is ok
  - 0 if value is invalid
callback_check_value_data: pointer given to check_value callback when it is called by WeeChat
callback_change: function called when value of option has changed (optional), arguments:
- void *data: pointer
- struct t_config_option *option: option pointer
callback_change_data: pointer given to change callback when it is called by WeeChat
callback_delete: function called when option will be deleted (optional), arguments:
- void *data: pointer
- struct t_config_option *option: option pointer
callback_delete_data: pointer given to delete callback when it is called by WeeChat

Return value:

pointer to new option in section, NULL if an error

C example:

/* boolean */
struct t_config_option *option1 =
    weechat_config_new_option (config_file, section, "option1", "boolean",
                               "My option, type boolean"
                               NULL, /* string values */
                               0, 0, /* min, max */
                               "on", /* default */
                               "on", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* integer */
struct t_config_option *option2 =
    weechat_config_new_option (config_file, section, "option2", "integer",
                               "My option, type integer"
                               NULL, /* string values */
                               0, 100, /* min, max */
                               "15", /* default */
                               "15", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* integer (with string values) */
struct t_config_option *option3 =
    weechat_config_new_option (config_file, section, "option3", "integer",
                               "My option, type integer (with string values)"
                               "top|bottom|left|right", /* string values */
                               0, 0, /* min, max */
                               "bottom", /* default */
                               "bottom", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* string */
struct t_config_option *option4 =
    weechat_config_new_option (config_file, section, "option4", "string",
                               "My option, type string"
                               NULL, /* string values */
                               0, 0, /* min, max */
                               "test", /* default */
                               "test", /* value */
                               1, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

/* color */
struct t_config_option *option5 =
    weechat_config_new_option (config_file, section, "option5", "color",
                               "My option, type color"
                               NULL, /* string values */
                               0, 0, /* min, max */
                               "lightblue", /* default */
                               "lightblue", /* value */
                               0, /* null value allowed */
                               NULL, NULL, /* check callback */
                               NULL, NULL, /* change callback */
                               NULL, NULL); /* delete callback */

Script (Python):

# prototype
option = weechat.config_new_option(config_file, section, name, type, description,
    string_values, min, max, default_value, value, null_value_allowed,
    callback_check_value, callback_check_value_data,
    callback_change, callback_change_data,
    callback_delete, callback_delete_data)

# example
def option4_check_value_cb(data, option, value):
    # ...
    return 1
    # return 0

def option4_change_cb(data, option):
    # ...

def option4_delete_cb(data, option):
    # ...

option1 = weechat.config_new_option(config_file, section, "option1", "boolean",
    "My option, type boolean",
    "", 0, 0, "on", "on", 0,
    "", "",
    "", "",
    "", "")

option2 = weechat.config_new_option(config_file, section, "option2", "integer",
    "My option, type integer",
    "", 0, 100, "15", "15", 0,
    "", "",
    "", "",
    "", "")

option3 = weechat.config_new_option(config_file, section, "option3", "integer",
    "My option, type integer (with string values)",
    "top|bottom|left|right",
    0, 0, "bottom", "bottom", 0,
    "", "",
    "", "",
    "", "")

option4 = weechat.config_new_option(config_file, section, "option4", "string",
    "My option, type string",
    "", 0, 0, "test", "test", 1,
    "option4_check_value_cb", ""
    "option4_change_cb", "",
    "option4_delete_cb", "")

option5 = weechat.config_new_option(config_file, section, "option5", "color",
    "My option, type color",
    "", 0, 0, "lightblue", "lightblue", 0,
    "", "",
    "", "",
    "", "")

Note	In Ruby, the 3 callbacks + data (6 strings) must be given in an array of 6 strings (due to a Ruby limitation of 15 arguments by function), see the WeeChat Scripting Guide for more info (fixed in version 0.4.1).

3.8.5. weechat_config_search_option

Search an option in a section of a configuration file.

Prototype:

struct t_config_option *weechat_config_search_option (
    struct t_config_file *config_file,
    struct t_config_section *section,
    const char *option_name);

Arguments:

config_file: configuration file pointer
section: section pointer
name: name of option to search

Return value:

pointer to option found, NULL if option was not found

C example:

struct t_config_option *option =
    weechat_config_search_option (config_file, section, "option");

Script (Python):

# prototype
option = weechat.config_search_option(config_file, section, option_name)

# example
option = weechat.config_search_option(config_file, section, "option")

3.8.6. weechat_config_search_section_option

Search a section and an option in a configuration file or section.

Prototype:

void weechat_config_search_section_option (struct t_config_file *config_file,
                                           struct t_config_section *section,
                                           const char *option_name,
                                           struct t_config_section **section_found,
                                           struct t_config_option **option_found);

Arguments:

config_file: configuration file pointer
section: section pointer
option_name: option name
section_found: pointer to section pointer, will be set to section of option, if found
option_found: pointer to an option pointer, will be set to option pointer, if found

C example:

struct t_config_section *ptr_section;
struct t_config_option *ptr_option;

weechat_config_search_section_option(config_file,
                                     section,
                                     "option",
                                     &ptr_section,
                                     &ptr_option);
if (ptr_option)
{
    /* option found */
}
else
{
    /* option not found */
}

Note	This function is not available in scripting API.

3.8.7. weechat_config_search_with_string

Search an option with full name.

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,
                                        char **pos_option_name);

Arguments:

option_name: full option name (format: "file.section.option")
config_file: pointer to configuration file pointer, will be set with pointer to configuration file of option found
section: pointer to 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
pos_option_name: pointer to a string pointer, will be set to pointer to name of option, if found

C example:

struct t_config_file *ptr_config_file;
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;
char *option_name;

weechat_config_search_with_string ("file.section.option",
                                   &ptr_config_file,
                                   &ptr_section,
                                   &ptr_option,
                                   &option_name);
if (ptr_option)
{
    /* option found */
}
else
{
    /* option not found */
}

Note	This function is not available in scripting API.

3.8.8. weechat_config_string_to_boolean

Check if a text is "true" or "false", as boolean value.

Prototype:

int weechat_config_string_to_boolean (const char *text);

Arguments:

text: text to analyze

Return value:

1 if text is "true" ("on", "yes", "y", "true", "t", "1")
0 if text is "false" ("off", "no", "n", "false", "f", "0")

C example:

if (weechat_config_string_to_boolean (option_value))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}

Script (Python):

# prototype
value = weechat.config_string_to_boolean(text)

# example
if weechat.config_string_to_boolean(text):
    # ...

3.8.9. weechat_config_option_reset

Reset an option to its default value.

Prototype:

int weechat_config_option_reset (struct t_config_option *option,
                                 int run_callback);

Arguments:

option: option pointer
run_callback: 1 for calling callback if value of option is changed, otherwise 0

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 occurred

C 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;
}

Script (Python):

# prototype
rc = weechat.config_option_reset(option, run_callback)

# example
rc = weechat.config_option_reset(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

3.8.10. weechat_config_option_set

Set new value for an option.

Prototype:

int weechat_config_option_set (struct t_config_option *option,
                               const char *value, int run_callback);

Arguments:

option: option pointer
value: new value for option
run_callback: 1 for calling change callback if value of option is changed, otherwise 0

Return value:

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been changed
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_ERROR if an error occurred

C 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;
}

Script (Python):

# prototype
rc = weechat.config_option_set(option, value, run_callback)

# example
rc = weechat.config_option_set(option, "new_value", 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

3.8.11. weechat_config_option_set_null

Set null (undefined value) for an option.

Prototype:

int weechat_config_option_set_null (struct t_config_option *option,
                                    int run_callback);

Arguments:

option: option pointer
run_callback: 1 for calling change callback if value of option is changed (if it was not null), otherwise 0

Note	You can set value to null only if it is allowed for option (see weechat_config_new_option).

Return value:

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been changed
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_ERROR if an error occurred

C example:

switch (weechat_config_option_set_null (option, 1))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* .... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* .... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_option_set_null(option, run_callback)

# example
rc = weechat.config_option_set_null(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

3.8.12. weechat_config_option_unset

Unset/reset option.

Prototype:

int weechat_config_option_unset (struct t_config_option *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 occurred

C 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;
}

Script (Python):

# prototype
rc = weechat.config_option_unset(option)

# example
rc = weechat.config_option_unset(option)
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...

3.8.13. weechat_config_option_rename

Rename an option.

Prototype:

void weechat_config_option_rename (struct t_config_option *option,
                                   const char *new_name);

Arguments:

option: option pointer
new_name: new name for option

C example:

weechat_config_option_rename (option, "new_name");

Script (Python):

# prototype
weechat.config_option_rename(option, new_name)

# example
weechat.config_option_rename(option, "new_name")

3.8.14. weechat_config_option_get_pointer

Return a pointer on an option property.

Prototype:

void *weechat_config_option_get_pointer (struct t_config_option *option,
                                         const char *property);

Arguments:

option: option pointer
property: property name:
- config_file: configuration file pointer (struct t_config_file *)
- section: section pointer (struct t_config_section *)
- name: option name (char *)
- type: option type (int *)
- description: option description (char *)
- string_values: string values (char *)
- min: minimum value (int *)
- max: maximum value (int *)
- default_value: default value (depends on type)
- value: current value (depends on type)
- prev_option: previous option pointer (struct t_config_option *)
- next_option: next option pointer (struct t_config_option *)

Return value:

pointer to property asked

C example:

char *description = weechat_config_option_get_pointer (option, "description");

Note	This function is not available in scripting API.

3.8.15. weechat_config_option_is_null

Check if an option is "null" (undefined value).

Prototype:

int weechat_config_option_is_null (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

1 if value of option is "null"
0 if value of option is not "null"

C example:

if (weechat_config_option_is_null (option))
{
    /* value is "null" */
}
else
{
    /* value is not "null" */
}

Script (Python):

# prototype
is_null = weechat.config_option_is_null(option)

# example
if weechat.config_option_is_null(option):
    # ...

3.8.16. weechat_config_option_default_is_null

Check if default value for an option is "null" (undefined value).

Prototype:

int weechat_config_option_default_is_null (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

1 if default value of option is "null"
0 if default value of option is not "null"

C example:

if (weechat_config_option_default_is_null (option))
{
    /* default value is "null" */
}
else
{
    /* default value is not "null" */
}

Script (Python):

# prototype
is_null = weechat.config_option_default_is_null(option)

# example
if weechat.config_option_default_is_null(option):
    # ...

3.8.17. weechat_config_boolean

Return boolean value of option.

Prototype:

int weechat_config_boolean (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

boolean value of option (0 or 1)

C example:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean (option))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}

Script (Python):

# prototype
value = weechat.config_boolean(option)

# example
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean(option):
    # ...

3.8.18. weechat_config_boolean_default

Return default boolean value of option.

Prototype:

int weechat_config_boolean_default (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

default boolean value of option (0 or 1)

C example:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean_default (option))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}

Script (Python):

# prototype
value = weechat.config_boolean_default(option)

# example
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean_default(option):
    # ...

3.8.19. weechat_config_integer

Return integer value of option.

Prototype:

int weechat_config_integer (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

integer value of option

C example:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer (option);

Script (Python):

# prototype
value = weechat.config_integer(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer(option)

3.8.20. weechat_config_integer_default

Return default integer value of option.

Prototype:

int weechat_config_integer_default (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

default integer value of option

C example:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer_default (option);

Script (Python):

# prototype
value = weechat.config_integer_default(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer_default(option)

3.8.21. weechat_config_string

Return string value of option.

Prototype:

const char *weechat_config_string (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

string value of option

C example:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string (option);

Script (Python):

# prototype
value = weechat.config_string(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_string(option)

3.8.22. weechat_config_string_default

Return default string value of option.

Prototype:

const char *weechat_config_string_default (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

default string value of option

C example:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string_default (option);

Script (Python):

# prototype
value = weechat.config_string_default(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_string_default(option)

3.8.23. weechat_config_color

Return color value of option.

Prototype:

const char *weechat_config_color (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

color value of option (string with name of color)

C example:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color (option);

Script (Python):

# prototype
value = weechat.config_color(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_color(option)

3.8.24. weechat_config_color_default

Return default color value of option.

Prototype:

const char *weechat_config_color_default (struct t_config_option *option);

Arguments:

option: option pointer

Return value:

default color value of option (string with name of color)

C example:

struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color_default (option);

Script (Python):

# prototype
value = weechat.config_color_default(option)

# example
option = weechat.config_get("plugin.section.option")
value = weechat.config_color_default(option)

3.8.25. weechat_config_write_option

Write a line in a configuration file with option and its value (this function should be called only in "write" or "write_default" callbacks for a section).

Prototype:

void weechat_config_write_option (struct t_config_file *config_file,
                                  struct t_config_option *option);

Arguments:

config_file: configuration file pointer
option: option pointer

C example:

int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);

    weechat_config_write_option (config_file, option);

    return WEECHAT_RC_OK;
}

Script (Python):

# prototype
weechat.config_write_option(config_file, option)

# example
def my_section_write_cb(data, config_file, section_name):
    weechat.config_write_line(config_file, "my_section", "")
    weechat.config_write_option(config_file, option)
    return weechat.WEECHAT_RC_OK

3.8.26. weechat_config_write_line

Write a line in a configuration file (this function should be called only in "write" or "write_default" callbacks for a section).

Prototype:

void weechat_config_write_line (struct t_config_file *config_file,
                                const char *option_name,
                                const char *value, ...);

Arguments:

config_file: configuration file pointer
option_name: option name
value: value (if NULL, then line with section name is written, for example: "[section]")

C example:

int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    weechat_config_write_line (config_file, "my_section", NULL);

    weechat_config_write_line (config_file, "option", "%s;%d",
                               "value", 123);

    return WEECHAT_RC_OK;
}

Script (Python):

# prototype
weechat.config_write_line(config_file, option_name, value)

# example
def my_section_write_cb(data, config_file, section_name):
    weechat.config_write_line(config_file, "my_section", "")
    weechat.config_write_line(config_file, "option", "value")
    return weechat.WEECHAT_RC_OK

3.8.27. weechat_config_write

Write configuration file to disk.

Prototype:

int weechat_config_write (struct t_config_file *config_file);

Arguments:

config_file: configuration file pointer

Return value:

WEECHAT_CONFIG_WRITE_OK if configuration was written
WEECHAT_CONFIG_WRITE_MEMORY_ERROR if there was not enough memory
WEECHAT_CONFIG_WRITE_ERROR if another error occurred

C example:

switch (weechat_config_write (config_file))
{
    case WEECHAT_CONFIG_WRITE_OK:
        /* ... */
        break;
    case WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
        /* ... */
        break;
    case WEECHAT_CONFIG_WRITE_ERROR:
        /* ... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_write(config_file)

# example
rc = weechat.config_write(config_file)
if rc == weechat.WEECHAT_CONFIG_WRITE_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_ERROR:
    # ...

3.8.28. weechat_config_read

Read configuration file from disk.

Prototype:

int weechat_config_read (struct t_config_file *config_file);

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

C 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;
}

Script (Python):

# prototype
rc = weechat.config_read(config_file)

# example
rc = weechat.config_read(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...

3.8.29. weechat_config_reload

Reload configuration file from disk.

Prototype:

int weechat_config_reload (struct t_config_file *config_file);

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

C 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;
}

Script (Python):

# prototype
rc = weechat.config_reload(config_file)

# example
rc = weechat.config_reload(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...

3.8.30. weechat_config_option_free

Free an option.

Prototype:

void weechat_config_option_free (struct t_config_option *option);

Arguments:

option: option pointer

C example:

weechat_config_option_free (option);

Script (Python):

# prototype
weechat.config_option_free(option)

# example
weechat.config_option_free(option)

3.8.31. weechat_config_section_free_options

Free all options in a section.

Prototype:

void weechat_config_section_free_options (struct t_config_section *section);

Arguments:

section: section pointer

C example:

weechat_config_section_free_options (section);

Script (Python):

# prototype
weechat.config_section_free_options(section)

# example
weechat.config_section_free_options(section)

3.8.32. weechat_config_section_free

Free a section.

Prototype:

void weechat_config_section_free (struct t_config_section *section);

Arguments:

section: section pointer

C example:

weechat_config_section_free (section);

Script (Python):

# prototype
weechat.config_section_free(section)

# example
weechat.config_section_free(section)

3.8.33. weechat_config_free

Free a configuration file.

Prototype:

void weechat_config_free (struct t_config_file *config_file);

Arguments:

config_file: configuration file pointer

C example:

weechat_config_free (config_file);

Script (Python):

# prototype
weechat.config_free(config_file)

# example
weechat.config_free(config_file)

3.8.34. weechat_config_get

Search an option with full name.

Prototype:

struct t_config_option *weechat_config_get (const char *option_name);

Arguments:

option_name: full option name (format: "file.section.option")

Return value:

pointer to option found, NULL if option was not found

C example:

struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");

Script (Python):

# prototype
option = weechat.config_get(option_name)

# example
option = weechat.config_get("weechat.look.item_time_format")

3.8.35. weechat_config_get_plugin

Search an option in plugins configuration file (plugins.conf).

Prototype:

const char *weechat_config_get_plugin (const char *option_name);

Arguments:

option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where "xxx" is current plugin name)

Return value:

value of option found, NULL if option was not found

C example:

/* if current plugin is "test", then look for value of option
   "plugins.var.test.option" in file plugins.conf */
char *value = weechat_config_get_plugin ("option");

Script (Python):

# prototype
value = weechat.config_get_plugin(option_name)

# example
value = weechat.config_get_plugin("option")

3.8.36. weechat_config_is_set_plugin

Check if option is set in plugins configuration file (plugins.conf).

Prototype:

int weechat_config_is_set_plugin (const char *option_name);

Arguments:

option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where "xxx" is current plugin name)

Return value:

1 if option is set, 0 if option does not exist

C example:

if (weechat_config_is_set_plugin ("option"))
{
    /* option is set */
}
else
{
    /* option does not exist */
}

Script (Python):

# prototype
value = weechat.config_is_set_plugin(option_name)

# example
if weechat.config_is_set_plugin("option"):
    # option is set
    # ...
else:
    # option does not exist
    # ...

3.8.37. weechat_config_set_plugin

Set new value for option in plugins configuration file (plugins.conf).

Prototype:

int weechat_config_set_plugin (const char *option_name, const char *value);

Arguments:

option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where "xxx" is current plugin name)
value: new value for option

Return value:

WEECHAT_CONFIG_OPTION_SET_OK_CHANGED if option value has been changed
WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE if value was not changed
WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND if option was not found
WEECHAT_CONFIG_OPTION_SET_ERROR if other error occurred

C example:

switch (weechat_config_set_plugin ("option", "test_value"))
{
    case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
        /* ... */
        break;
    case WEECHAT_CONFIG_OPTION_SET_ERROR:
        /* ... */
        break;
}

Script (Python):

# prototype
rc = weechat.config_set_plugin(option_name, value)

# example
rc = weechat.config_set_plugin("option", "test_value")
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...

3.8.38. weechat_config_set_desc_plugin

New in version 0.3.5.

Set description for option in plugins configuration file (plugins.conf).

Prototype:

void weechat_config_set_desc_plugin (const char *option_name,
                                     const char *description);

Arguments:

option_name: option name, WeeChat will add prefix "plugins.desc.xxx." (where "xxx" is current plugin name)
description: description for option

Note	It is not a problem if option (plugins.var.xxx.option_name) does not exist. A future creation of option with this name will use this description.

C example:

weechat_config_set_desc_plugin ("option", "description of option");

Script (Python):

# prototype
weechat.config_set_desc_plugin(option_name, description)

# example
version = weechat.info_get("version_number", "") or 0
if int(version) >= 0x00030500:
    weechat.config_set_desc_plugin("option", "description of option")

3.8.39. weechat_config_unset_plugin

Unset option in plugins configuration file (plugins.conf).

Prototype:

int weechat_config_unset_plugin (const char *option_name);

Arguments:

option_name: option name, WeeChat will add prefix "plugins.var.xxx." (where xxx is current plugin name)

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 occurred

C example:

switch (weechat_config_unset_plugin ("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;
}

Script (Python):

# prototype
rc = weechat.config_unset_plugin(option_name)

# example
rc = weechat.config_unset_plugin("option")
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...

3.9. Key bindings

Functions for key bindings.

3.9.1. weechat_key_bind

New in version 0.3.6.

Add new key bindings.

Note	Unlike command `/key bind`, this function will never change an existing key binding, only new keys are created. To remove a key binding, use weechat_key_unbind.

Prototype:

int weechat_key_bind (const char *context, struct t_hashtable *keys);

Arguments:

context: context for keys:
- default: default context (common actions)
- search: search context (when searching text in buffer)
- cursor: free movement of cursor on screen
- mouse: keys for mouse events
keys: hashtable with key bindings

Return value:

number of key bindings added

C example:

struct t_hashtable *keys = weechat_hashtable_new (8,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  NULL,
                                                  NULL);
if (keys)
{
    weechat_hashtable_set (keys, "@chat(plugin.buffer):button1", "hsignal:test_mouse");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheelup", "/mycommand up");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheeldown", "/mycommand down");
    weechat_key_bind ("mouse", keys);
    weechat_hashtable_free (keys);
}

Script (Python):

# prototype
num_keys = weechat.key_bind(context, keys)

# example
keys = { "@chat(python.test):button1": "hsignal:test_mouse",
         "@chat(python.test):wheelup": "/mycommand up",
         "@chat(python.test):wheeldown": "/mycommand down" }
weechat.key_bind("mouse", keys)

3.9.2. weechat_key_unbind

New in version 0.3.6.

Remove key binding(s).

Warning

When calling this function, ensure that you will not remove a user key binding.

Prototype:

int weechat_key_unbind (const char *context, const char *key);

Arguments:

context: context for keys (see weechat_key_bind)
key: key to remove or a special value "area:XXX" to remove all keys having XXX as first or second area

Return value:

number of key bindings removed

C examples:

/* remove a single key */
weechat_key_unbind ("mouse", "@chat(plugin.buffer):button1");

/* remove all keys with area "chat(plugin.buffer)" */
weechat_key_unbind ("mouse", "area:chat(plugin.buffer)");

Script (Python):

# prototype
num_keys = weechat.key_unbind(context, key)

# examples

# remove a single key
weechat.key_unbind("mouse", "@chat(plugin.buffer):button1")

# remove all keys with area "chat(python.test)"
weechat.key_unbind("mouse", "area:chat(python.test)")

3.10. Display

Functions to display text in buffers.

3.10.1. weechat_prefix

Return a prefix.

Prototype:

const char *weechat_prefix (const char *prefix);

Arguments:

prefix: name of prefix:

Prefix	Value	Color	Description
error	`=!=`	yellow	Error message
network	`--`	magenta	Message from network
action	`*`	white	Self action
join	`-->`	lightgreen	Someone joins current chat
quit	`<--`	lightred	Someone leaves current chat

Note	Values and colors can be customized with command `/set`.

Return value:

prefix value (string with prefix and color codes), empty string if prefix is not found

C example:

weechat_printf (NULL, "%sThis is an error...", weechat_prefix ("error"));

Script (Python):

# prototype
value = weechat.prefix(prefix)

# example
weechat.prnt("", "%sThis is an error..." % weechat.prefix("error"))

3.10.2. weechat_color

Return a string color code for display.

Prototype:

const char *weechat_color (const char *color_name);

Arguments:

color_name: name of color, one of:
- WeeChat option name (from weechat.color.xxx), for example chat_delimiters
- color with optional attributes/background (see below)
- attribute:
  - bold: set bold
  - -bold: remove bold
  - reverse: set reverse
  - -reverse: remove reverse
  - italic: set italic
  - -italic: remove italic
  - underline: set underline
  - -underline: remove underline
  - emphasis: toggle the emphasis for text (note: this should be used only in bars, because WeeChat uses text emphasis when searching text in buffer) (new in version 0.4.2)
- bar color name:
  - bar_fg: foreground color for bar
  - bar_delim: delimiters color for bar
  - bar_bg: background color for bar
- reset:
  - reset: reset color and attributes
  - resetcolor: reset color (keep attributes) (new in version 0.3.6)

Format of color is: attributes (optional) + color name + ",background" (optional). Possible attributes are:

* : bold text
! : reverse video
_ : underlined text
| : keep attributes: do not reset bold/reverse/underlined when changing color (new in version 0.3.6)

Examples:

yellow : yellow
_green : underlined green
*214 : bold orange
yellow,red : yellow on red
|cyan : cyan (and keep any attribute which was set previously)

Return value:

string with color code, or an empty string if color is not found

C example:

weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red",
                weechat_color ("blue"),
                weechat_color ("chat"),
                weechat_color ("yellow,red"));

Script (Python):

# prototype
value = weechat.color(color_name)

# example
weechat.prnt("", "%sColor: %sblue %sdefault color %syellow on red"
    % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))

3.10.3. weechat_printf

Display a message on a buffer.

Prototype:

void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);

Arguments:

buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
message: message to display

Note	The first tabulation in message ("\t") is used to separate prefix from message. If your message has some tabs and if you don’t want prefix, then use a space, a tab, then message (see example below): this will disable prefix (the space before tab will not be displayed).

Note	With two tabs ("\t") at beginning of message, time will not be displayed and message will have no alignment at all. Moreover, the date in message will be set to 0.

C example:

weechat_printf (NULL, "Hello on WeeChat buffer");
weechat_printf (buffer, "Hello on this buffer");
weechat_printf (buffer, "%sThis is an error!", weechat_prefix ("error"));
weechat_printf (buffer, " \tMessage without prefix but with \t some \t tabs");
weechat_printf (buffer, "\t\tMessage without time/alignment");
weechat_printf (buffer, "\t\t"); /* empty line (without time) */

Script (Python):

# prototype
weechat.prnt(buffer, message)

# example
weechat.prnt("", "Hello on WeeChat buffer")
weechat.prnt(buffer, "Hello on this buffer")
weechat.prnt(buffer, "%sThis is an error!" % weechat.prefix("error"))
weechat.prnt(buffer, " \tMessage without prefix but with \t some \t tabs")
weechat.prnt(buffer, "\t\tMessage without time/alignment")
weechat.prnt(buffer, "\t\t") # empty line (without time)

Note	Function is called "print" in scripts ("prnt" in Python).

3.10.4. weechat_printf_date

Display a message on a buffer, using a custom date.

Prototype:

void weechat_printf_date (struct t_gui_buffer *buffer, time_t date,
                          const char *message, ...);

Arguments:

buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
date: date for message (0 means current date/time)
message: message to display

C example:

weechat_printf_date (NULL, time (NULL) - 120, "Hello, 2 minutes ago");

Note	This function is not available in scripting API.

3.10.5. weechat_printf_tags

Display a message on a buffer, using a custom tags.

Prototype:

void weechat_printf_tags (struct t_gui_buffer *buffer, const char *tags,
                          const char *message, ...);

Arguments:

buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
tags: comma separated list of tags
message: message to display

C example:

weechat_printf_tags (NULL, "notify_message",
                     "Message with a tag 'notify_message'");

Note	This function is not available in scripting API.

3.10.6. weechat_printf_date_tags

Display a message on a buffer, using a custom date and tags.

Prototype:

void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date,
                               const char *tags, const char *message, ...);

Arguments:

buffer: buffer pointer, if NULL, message is displayed on WeeChat buffer
date: date for message (0 means current date/time)
tags: comma separated list of tags
message: message to display

Tags commonly used (non-exhaustive list):

Tag	Description
`no_filter`	Line can not be filtered
`no_highlight`	No highlight is possible on line
`no_log`	Line is not written in log file
`log0 … log9`	Level of log for line (see `/help logger`)
`notify_none`	Buffer with line is not added to hotlist
`notify_message`	Buffer with line is added to hotlist with level "message"
`notify_private`	Buffer with line is added to hotlist with level "private"
`notify_highlight`	Buffer with line is added to hotlist with level "highlight"
`nick_xxx`	Message is from nick "xxx"
`prefix_nick_ccc`	Prefix is a nick with color "ccc"
`irc_xxx`	IRC message "xxx" (can be a command or a 3-digits number)
`irc_numeric`	IRC numeric message
`irc_error`	Error from IRC server
`irc_action`	Action from a nick (command `/me`)
`irc_ctcp`	CTCP message
`irc_ctcp_reply`	Reply to CTCP message
`irc_smart_filter`	IRC message that can be filtered with the "smart filter"
`away_info`	Message with away info

C example:

weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
                          "Message 2 minutes ago, with a tag 'notify_message'");

Script (Python):

# prototype
weechat.prnt_date_tags(buffer, date, tags, message)

# example
time = int(time.time())
weechat.prnt_date_tags("", time - 120, "notify_message",
    "Message 2 minutes ago, with a tag 'notify_message'")

Note	Function is called "print_date_tags" in scripts ("prnt_date_tags" in Python).

3.10.7. weechat_printf_y

Display a message on a line of a buffer with free content.

Prototype:

void weechat_printf_y (struct t_gui_buffer *buffer, int y,
                       const char *message, ...);

Arguments:

buffer: buffer pointer
y: line number (first line is 0)
message: message to display

C example:

weechat_printf_y (buffer, 2, "My message on third line");

Script (Python):

# prototype
weechat.prnt_y(buffer, y, message)

# example
weechat.prnt_y("", 2, "My message on third line")

Note	Function is called "print_y" in scripts ("prnt_y" in Python).

3.10.8. weechat_log_printf

Write a message in WeeChat log file (weechat.log).

Prototype:

void weechat_log_printf (const char *message, ...);

Arguments:

message: message to write

C example:

weechat_log_printf ("My message in log file");

Script (Python):

# prototype
weechat.log_print(message)

# example
weechat.log_print("My message in log file")

Note	Function is called "log_print" in scripts.

3.11. Hooks

Hook priority

New in version 0.3.4.

In some hooks, you can set a priority. A hook with higher priority is at the beginning of hooks list, so it will be found and executed before other hooks. It’s useful for modifiers, because execution order is important.

To set a priority, you must use this syntax, for argument where priority is allowed: "nnn|name" where "nnn" is nonnegative integer with priority and "name" the name for argument (priority does not appear in name, it is automatically removed from string).

Default priority is 1000.

C example:

/* hook modifier with priority = 2000 */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL);

Following hook types allow priority: command, command_run, signal, hsignal, config, completion, modifier, info, info_hashtable, infolist, hdata, focus.

3.11.1. weechat_hook_command

Hook a command.

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);

Arguments:

command: command name (priority allowed, see note about priority)
description: description for 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 argument, separated by space. Many completions are possible for one argument, separated by "|". Many templates are possible for same command, separated by "||".
callback: function called when command is used, arguments and return value:
- void *data: pointer
- struct t_gui_buffer *buffer: buffer where command is executed
- int argc: number of arguments given for command
- char **argv: arguments given for command
- char **argv_eol: arguments given for command (until end of line for each argument)
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Default completion codes are:

Plugin	Name	Description
alias	alias	list of aliases
alias	alias_value	value of alias
aspell	aspell_dicts	list of aspell installed dictionaries
aspell	aspell_langs	list of all languages supported by aspell
guile	guile_script	list of scripts
irc	irc_channel	current IRC channel
irc	irc_channel_nicks_hosts	nicks and hostnames of current IRC channel
irc	irc_channel_topic	topic of current IRC channel
irc	irc_channels	channels on all IRC servers
irc	irc_ignores_numbers	numbers for defined ignores
irc	irc_msg_part	default part message for IRC channel
irc	irc_notify_nicks	nicks in notify list
irc	irc_privates	privates on all IRC servers
irc	irc_server	current IRC server
irc	irc_server_channels	channels on current IRC server
irc	irc_server_nick	nick on current IRC server
irc	irc_server_nicks	nicks on all channels of current IRC server
irc	irc_server_privates	privates on current IRC server
irc	irc_servers	IRC servers (internal names)
irc	nick	nicks of current IRC channel
lua	lua_script	list of scripts
perl	perl_script	list of scripts
python	python_script	list of scripts
relay	relay_free_port	first free port for relay plugin
relay	relay_protocol_name	all possible protocol.name for relay plugin
relay	relay_relays	protocol.name of current relays for relay plugin
rmodifier	rmodifier	list of rmodifiers
ruby	ruby_script	list of scripts
script	script_files	files in script directories
script	script_scripts	list of scripts in repository
script	script_scripts_installed	list of scripts installed (from repository)
script	script_tags	tags of scripts in repository
tcl	tcl_script	list of scripts
weechat	bars_names	names of bars
weechat	bars_options	options for bars
weechat	buffer_properties_get	properties that can be read on a buffer
weechat	buffer_properties_set	properties that can be set on a buffer
weechat	buffers_names	names of buffers
weechat	buffers_numbers	numbers of buffers
weechat	buffers_plugins_names	names of buffers (including plugins names)
weechat	commands	commands (weechat and plugins)
weechat	config_files	configuration files
weechat	config_option_values	values for a configuration option
weechat	config_options	configuration options
weechat	cursor_areas	areas ("chat" or bar name) for free cursor movement
weechat	filename	filename
weechat	filters_names	names of filters
weechat	infolists	names of infolists hooked
weechat	infos	names of infos hooked
weechat	keys_codes	key codes
weechat	keys_codes_for_reset	key codes that can be reset (keys added, redefined or removed)
weechat	keys_contexts	key contexts
weechat	layouts_names	names of layouts
weechat	nicks	nicks in nicklist of current buffer
weechat	palette_colors	palette colors
weechat	plugins_commands	commands defined by plugins
weechat	plugins_names	names of plugins
weechat	proxies_names	names of proxies
weechat	proxies_options	options for proxies
weechat	secured_data	names of secured data (file sec.conf, section data)
weechat	weechat_commands	weechat commands
weechat	windows_numbers	numbers of windows
xfer	nick	nicks of DCC chat

Special codes:

%%command: reuse completion template from command command
%-: stop completion
%*: repeat last completion

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_command_cb (void *data, struct t_gui_buffer *buffer, int argc,
               char **argv, char **argv_eol)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* this example is inspired by command /filter */
struct t_hook *my_command_hook =
    weechat_hook_command (/* command name */
                          "myfilter",
                          /* description */
                          "description of myfilter",
                          /* args */
                          "[list] | [enable|disable|toggle [name]] | "
                          "[add name plugin.buffer tags regex] | "
                          "[del name|-all]",
                          /* args description */
                          "description of arguments...",
                          /* completion */
                          "list"
                          " || enable %(filters_names)"
                          " || disable %(filters_names)"
                          " || toggle %(filters_names)"
                          " || add %(filters_names) %(buffers_plugins_names)|*"
                          " || del %(filters_names)|-all",
                          /* callback */
                          &my_command_cb,
                          /* callback_data */
                          NULL);

For example, if command called is /command abc def ghi, then argv and argv_eol have following values:

argv:
- argv[0] == "/command"
- argv[1] == "abc"
- argv[2] == "def"
- argv[3] == "ghi"
argv_eol:
- argv_eol[0] == "/command abc def ghi"
- argv_eol[1] == "abc def ghi"
- argv_eol[2] == "def ghi"
- argv_eol[3] == "ghi"

For scripts, args has value "abc def ghi".

Script (Python):

# prototype
hook = weechat.hook_command(command, description, args, args_description,
    completion, callback, callback_data)

# example
def my_command_cb(data, buffer, args):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_command("myfilter", "description of myfilter",
    "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]",
    "description of arguments...",
    "list"
    " || enable %(filters_names)"
    " || disable %(filters_names)"
    " || toggle %(filters_names)"
    " || add %(filters_names) %(buffers_plugins_names)|*"
    " || del %(filters_names)|-all",
    "my_command_cb", "")

3.11.2. weechat_hook_command_run

Hook a command when WeeChat runs it.

Prototype:

struct t_hook *weechat_hook_command_run (const char *command,
                                         int (*callback)(void *data,
                                                         struct t_gui_buffer *buffer,
                                                         const char *command),
                                         void *callback_data);

Arguments:

command: command to hook, can start or end with "*" as wildcard (priority allowed, see note about priority)
callback: function called when command is run, arguments and return value:
- void *data: pointer
- struct t_gui_buffer *buffer: buffer where command is executed
- const char *command: the command executed, with its arguments
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_OK_EAT
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Note	Callback can return WEECHAT_RC_OK or WEECHAT_RC_OK_EAT (command will not be executed by WeeChat after callback).

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_command_run_cb (void *data, struct t_gui_buffer *buffer,
                   const char *command)
{
    weechat_printf (NULL,
                    "You want to complete? I'm eating the completion ahah!");
    return WEECHAT_RC_OK_EAT;
}

struct t_hook *my_command_run_hook =
    weechat_hook_command_run ("/input complete*",
                              &my_command_run_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_command_run(command, callback, callback_data)

# example
def my_command_run_cb(data, buffer, command):
    weechat.prnt("", "You want to complete? I'm eating the completion, ahah!")
    return weechat.WEECHAT_RC_OK_EAT

hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")

3.11.3. weechat_hook_timer

Hook a timer.

Prototype:

struct t_hook *weechat_hook_timer (long interval,
                                   int align_second,
                                   int max_calls,
                                   int (*callback)(void *data,
                                                   int remaining_calls),
                                   void *callback_data);

Arguments:

interval: interval between two calls (milliseconds, so 1000 = 1 second)
align_second: alignment 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 0
max_calls: number of calls to timer (if 0, then timer has no end)
callback: function called when time is reached, arguments and return value:
- void *data: pointer
- int remaining_calls: remaining calls (-1 if timer has no end)
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_timer_cb (void *data, int remaining_calls)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* timer called each 20 seconds */
struct t_hook *my_timer_hook =
    weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_timer(interval, align_second, max_calls, callback, callback_data)

# example
def my_timer_cb(data, remaining_calls):
    # ...
    return weechat.WEECHAT_RC_OK

# timer called each 20 seconds
hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")

3.11.4. weechat_hook_fd

Hook a file descriptor (file or socket).

Prototype:

struct t_hook *weechat_hook_fd (int fd,
                                int flag_read,
                                int flag_write,
                                int flag_exception,
                                int (*callback)(void *data,
                                                int fd),
                                void *callback_data);

Arguments:

fd: file descriptor
flag_read: 1 = catch read event, 0 = ignore
flag_write: 1 = catch write event, 0 = ignore
flag_exception: 1 = catch exception event, 0 = ignore
callback: function called a selected event occurs for file (or socket), arguments and return value:
- void *data: pointer
- int fd: file descriptor
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_fd_cb (void *data, int fd)
{
    /* ... */
    return WEECHAT_RC_OK;
}

int sock = socket (AF_INET, SOCK_STREAM, 0);
/* set socket options */
/* ... */
struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_fd(fd, flag_read, flag_write, flag_exception, callback, callback_data)

# example
def my_fd_cb(data, fd):
    # ...
    return weechat.WEECHAT_RC_OK

sock = ...
hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")

3.11.5. weechat_hook_process

Hook a process (launched with fork), and catch output.

Note

Since version 0.3.9.2, the shell is not used any more to execute the command. WeeChat makes an automatic split of the command and its arguments (like the shell does).
If the split is not correct (according to quotes in your command), or if you want to use shell, you can use function weechat_hook_process_hashtable with arguments in the hashtable options (new in version 0.4.0).

Prototype:

struct t_hook *weechat_hook_process (const char *command,
                                     int timeout,
                                     int (*callback)(void *data,
                                                     const char *command,
                                                     int return_code,
                                                     const char *out,
                                                     const char *err),
                                     void *callback_data);

Arguments:

command: command to launch in child process or URL (new in version 0.3.7), see below
timeout: timeout for command (in milliseconds): after this timeout, child process is killed (0 means no timeout)
callback: function called when data from child is available, or when child has ended, arguments and return value:
- void *data: pointer
- const char *command: command executed by child
- int return_code: return code:
  - >= 0: child return code for a command, and for URL possible values are:
    
    0: transfer ok
    
    1: invalid URL
    
    2: transfer error
    
    3: not enough memory
    
    4: error with a file
  - < 0: WEECHAT_HOOK_PROCESS_RUNNING (data available, but child still running) or WEECHAT_HOOK_PROCESS_ERROR (error when launching command)
- out: standard output of command (stdout)
- err: error output of command (stderr)
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

When command has ended, or if timeout is reached, WeeChat will automatically unhook (and kill process if it is still running).

The command can be an URL with format: "url:http://www.example.com", to download content of URL (new in version 0.3.7). Options are possible for URL with function weechat_hook_process_hashtable.

Tip	If you want to retrieve infos about WeeChat (like current stable version, latest git commit, …), you can use URLs on page http://weechat.org/dev/info

Note	Buffer size for sending data to callback is 64KB (there are 2 buffers: one for stdout and one for stderr). If output from child process (stdout or stderr) is longer than 64KB, callback will be called more than one time.

Important

Even if most of times your callback is called only once, you must ensure that many calls to callback are ok in your code: you must concatenate data issued by many calls and use data only when return code is nonnegative.

C example:

int
my_process_cb (void *data, const char *command, int return_code,
               const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Error with command '%s'", command);
        return WEECHAT_RC_OK;
    }

    if (return_code >= 0)
    {
        weechat_printf (NULL, "return_code = %d", return_code);
    }

    if (out)
    {
        weechat_printf (NULL, "stdout: %s", out);
    }

    if (err)
    {
        weechat_printf (NULL, "stderr: %s", err);
    }

    return WEECHAT_RC_OK;
}

struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
                                                       &my_process_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_process(command, timeout, callback, callback_data)

# example
def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Error with command '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out != "":
        weechat.prnt("", "stdout: %s" % out)
    if err != "":
        weechat.prnt("", "stderr: %s" % err)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process("ls", 5000, "my_process_cb", "")

3.11.6. weechat_hook_process_hashtable

New in version 0.3.7.

Hook a process (launched with fork) using options in a hashtable, and catch output.

Prototype:

struct t_hook *weechat_hook_process_hashtable (const char *command,
                                               struct t_hashtable *options,
                                               int timeout,
                                               int (*callback)(void *data,
                                                               const char *command,
                                                               int return_code,
                                                               const char *out,
                                                               const char *err),
                                               void *callback_data);

Arguments are the same as function weechat_hook_process, with an extra argument:

options: options for command executed; the hashtable is duplicated in function, so it’s safe to free it after this call

For a standard command (not beginning with "url:"), the hashtable options can contain arguments for command (and then command must be only the command without arguments) (new in version 0.4.0).
The keys in hashtable must be: arg1, arg2, …

For command "url:…", following options are available (see man curl_easy_setopt for a description of each option):

Option	Type	Constants ⁽¹⁾
verbose	long
header	long
noprogress	long
nosignal	long
wildcardmatch	long
failonerror	long
protocols	mask	http, https, ftp, ftps, scp, sftp, telnet, ldap, ldaps, dict, file, tftp, imap, imaps, pop3, pop3s, smtp, smtps, rtsp, rtmp, rtmpt, rtmpe, rtmpte, rtmps, rtmpts, gopher, all
redir_protocols	mask	http, https, ftp, ftps, scp, sftp, telnet, ldap, ldaps, dict, file, tftp, imap, imaps, pop3, pop3s, smtp, smtps, rtsp, rtmp, rtmpt, rtmpe, rtmpte, rtmps, rtmpts, gopher, all
proxy	string
proxyport	long
proxytype	long	http, http_1_0, socks4, socks5, socks4a, socks5_hostname
noproxy	string
httpproxytunnel	long
socks5_gssapi_service	string
socks5_gssapi_nec	long
interface	string
localport	long
localportrange	long
dns_cache_timeout	long
buffersize	long
port	long
tcp_nodelay	long
address_scope	long
tcp_keepalive	long
tcp_keepidle	long
tcp_keepintvl	long
netrc	long	ignored, optional, required
netrc_file	string
userpwd	string
proxyuserpwd	string
username	string
password	string
proxyusername	string
proxypassword	string
httpauth	mask	none, basic, digest, gssnegotiate, ntlm, digest_ie, ntlm_wb, only, any, anysafe
tlsauth_type	mask	none, srp
tlsauth_username	string
tlsauth_password	string
proxyauth	mask	none, basic, digest, gssnegotiate, ntlm, digest_ie, ntlm_wb, only, any, anysafe
autoreferer	long
accept_encoding	string
transfer_encoding	long
followlocation	long
unrestricted_auth	long
maxredirs	long
postredir	mask	post_301, post_302
put	long
post	long
postfields	string
postfieldsize	long
postfieldsize_large	long long
copypostfields	string
referer	string
useragent	string
cookie	string
cookiefile	string
cookiejar	string
cookiesession	long
cookielist	string
httpget	long
http_version	long	none, 1_0, 1_1
ignore_content_length	long
http_content_decoding	long
http_transfer_decoding	long
mail_from	string
mail_auth	string
tftp_blksize	long
ftpport	string
dirlistonly	long
append	long
ftp_use_eprt	long
ftp_use_epsv	long
ftp_use_pret	long
ftp_create_missing_dirs	long
ftp_response_timeout	long
ftp_alternative_to_user	string
ftp_skip_pasv_ip	long
ftpsslauth	long	default, ssl, tls
ftp_ssl_ccc	long	ccc_none, ccc_passive, ccc_active
ftp_account	string
ftp_filemethod	long	multicwd, nocwd, singlecwd
rtsp_request	long	options, describe, announce, setup, play, pause, teardown, get_parameter, set_parameter, record, receive
rtsp_session_id	string
rtsp_stream_uri	string
rtsp_transport	string
rtsp_client_cseq	long
rtsp_server_cseq	long
transfertext	long
proxy_transfer_mode	long
crlf	long
range	string
resume_from	long
resume_from_large	long long
customrequest	string
filetime	long
nobody	long
infilesize	long
infilesize_large	long long
upload	long
maxfilesize	long
maxfilesize_large	long long
timecondition	long	none, ifmodsince, ifunmodsince, lastmod
timevalue	long
timeout	long
timeout_ms	long
low_speed_limit	long
low_speed_time	long
max_send_speed_large	long long
max_recv_speed_large	long long
maxconnects	long
fresh_connect	long
forbid_reuse	long
connecttimeout	long
connecttimeout_ms	long
ipresolve	long	whatever, v4, v6
connect_only	long
use_ssl	long	none, try, control, all
dns_servers	string
accepttimeout_ms	long
sslcert	string
sslcerttype	string
sslkey	string
sslkeytype	string
keypasswd	string
sslengine	string
sslengine_default	long
sslversion	long	default, tlsv1, sslv2, sslv3
ssl_verifypeer	long
cainfo	string
issuercert	string
capath	string
crlfile	string
ssl_verifyhost	long
certinfo	long
random_file	string
egdsocket	string
ssl_cipher_list	string
ssl_sessionid_cache	long
ssl_options	long	allow_beast
krblevel	string
gssapi_delegation	long	none, policy_flag, flag
ssh_auth_types	mask	none, policy_flag, flag
ssh_host_public_key_md5	string
ssh_public_keyfile	string
ssh_private_keyfile	string
ssh_knownhosts	string
new_file_perms	long
new_directory_perms	long

Note	⁽¹⁾ When constants are available they must be used as value for option. For options with type "mask", format is: "value1+value2+value3".

For URL, two extra options (strings) are allowed for input/output file:

file_in: file to read and send with URLs (post file)
file_out: write downloaded URL/file in this file (instead of standard output)

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_process_cb (void *data, const char *command, int return_code,
               const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Error with command '%s'", command);
        return WEECHAT_RC_OK;
    }

    if (return_code >= 0)
    {
        weechat_printf (NULL, "return_code = %d", return_code);
    }

    if (out)
    {
        weechat_printf (NULL, "stdout: %s", out);
    }

    if (err)
    {
        weechat_printf (NULL, "stderr: %s", err);
    }

    return WEECHAT_RC_OK;
}

/* example 1: download URL */
struct t_hashtable *options = weechat_hashtable_new (8,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     NULL,
                                                     NULL);
if (options)
{
    weechat_hashtable_set (options, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:http://www.weechat.org/",
                                                                     options,
                                                                     20000,
                                                                     &my_process_cb, NULL);
    weechat_hashtable_free (options);
}

/* example 2: execute a notify program with a message from someone */
struct t_hashtable *options_cmd1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd1)
{
    weechat_hashtable_set (options_cmd1, "arg1", "-from");
    weechat_hashtable_set (options_cmd1, "arg2", nick);
    weechat_hashtable_set (options_cmd1, "arg3", "-msg");
    weechat_hashtable_set (options_cmd1, "arg4", message); /* untrusted argument */
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("my-notify-command",
                                                                     options_cmd1,
                                                                     20000,
                                                                     &my_process_cb, NULL);
    weechat_hashtable_free (options_cmd1);
}

/* example 3: call shell to execute a command (command must be SAFE) */
struct t_hashtable *options_cmd2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd2)
{
    weechat_hashtable_set (options_cmd2, "arg1", "-c");
    weechat_hashtable_set (options_cmd2, "arg2", "ls -l /tmp | grep something");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("sh",
                                                                     options_cmd2,
                                                                     20000,
                                                                     &my_process_cb, NULL);
    weechat_hashtable_free (options_cmd2);
}

Script (Python):

# prototype
hook = weechat.hook_process_hashtable(command, options, timeout, callback, callback_data)

# example
def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Error with command '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out != "":
        weechat.prnt("", "stdout: %s" % out)
    if err != "":
        weechat.prnt("", "stderr: %s" % err)
    return weechat.WEECHAT_RC_OK

# example 1: download URL
hook1 = weechat.hook_process_hashtable("url:http://www.weechat.org/",
                                       { "file_out": "/tmp/weechat.org.html" },
                                       20000, "my_process_cb", "")

# example 2: execute a notify program with a message from someone
hook2 = weechat.hook_process_hashtable("my-notify-command",
                                       { "arg1": "-from",
                                         "arg2": nick,
                                         "arg3": "-msg",
                                         "arg4": message }, # untrusted argument
                                       20000, "my_process_cb", "")

# example 3: call shell to execute a command (command must be SAFE)
hook3 = weechat.hook_process_hashtable("sh",
                                       { "arg1": "-c",
                                         "arg2": "ls -l /tmp | grep something" },
                                       20000, "my_process_cb", "")

3.11.7. weechat_hook_connect

Hook a connection (background connection to a remote host).

Prototype:

struct t_hook *weechat_hook_connect (const char *proxy,
                                     const char *address,
                                     int port,
                                     int ipv6,
                                     int retry,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *gnutls_priorities,
                                     const char *local_hostname,
                                     int (*callback)(void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     int sock,
                                                     const char *error,
                                                     const char *ip_address),
                                     void *callback_data);

Arguments:

proxy: name of proxy to use for connection (optional, NULL means connection without proxy)
address: name or IP address to connect to
port: port number
ipv6: 1 to use IPv6 (with fallback to IPv4), 0 to use only IPv4
retry: retry count, used to fallback to IPv4 hosts if IPv6 hosts connect but then fail to accept the client
gnutls_sess: GnuTLS session (optional)
gnutls_cb: GnuTLS callback (optional)
gnutls_dhkey_size: size of the key used during the Diffie-Hellman Key Exchange (GnuTLS)
gnutls_priorities: priorities for gnutls (for syntax, see documentation of function gnutls_priority_init in gnutls manual), basic values are:
- PERFORMANCE
- NORMAL (default)
- SECURE128
- SECURE256
- EXPORT
- NONE
local_hostname: local hostname to use for connection (optional)
callback: function called when connection is ok or failed, arguments and return value:
- void *data: pointer
- int status: connection status:
  - WEECHAT_HOOK_CONNECT_OK: connection ok
  - WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: address not found
  - WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: IP address not found
  - WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: connection refused
  - WEECHAT_HOOK_CONNECT_PROXY_ERROR: error with proxy
  - WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: error with local hostname
  - WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: GnuTLS init error
  - WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: GnuTLS handshake error
  - WEECHAT_HOOK_CONNECT_MEMORY_ERROR: insufficient memory
  - WEECHAT_HOOK_CONNECT_TIMEOUT: timeout
  - WEECHAT_HOOK_CONNECT_SOCKET_ERROR: unable to create socket
- gnutls_rc: result value of gnutls_handshake()
- sock: socket used to connect
- const char *error: result value of gnutls_strerror(gnutls_rc)
- const char *ip_address: IP address found
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_connect_cb (void *data, int status, int gnutls_rc, int sock,
               const char *error, 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;
        case WEECHAT_HOOK_CONNECT_TIMEOUT:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
            /* ... */
            break;
    }
    return WEECHAT_RC_OK;
}

struct t_hook *my_connect_hook = weechat_hook_connect (NULL,
                                                       "my.server.org", 1234,
                                                       1, 0,
                                                       NULL, NULL, 0, /* GnuTLS */
                                                       NULL,
                                                       &my_connect_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_connect(proxy, address, port, ipv6, retry, local_hostname,
    callback, callback_data)

# example
def my_connect_cb(data, status, gnutls_rc, sock, error, ip_address):
    if status == WEECHAT_HOOK_CONNECT_OK:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_TIMEOUT:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
        # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_connect("", "my.server.org", 1234, 1, 0, "",
                            "my_connect_cb", "")

3.11.8. weechat_hook_print

Hook a message printed.

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,
                                                   int displayed,
                                                   int highlight,
                                                   const char *prefix,
                                                   const char *message),
                                   void *callback_data);

Arguments:

buffer: buffer pointer, if NULL, messages from any buffer are caught
tags: only messages with these tags (comma separated list) will be caught (optional)
message: only messages with this string will be caught (optional, case insensitive)
strip_colors: if 1, colors will be stripped from message displayed, before calling callback
callback: function called when a message is printed, arguments and return value:
- 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: array with tags for line
- int displayed: 1 if line is displayed, 0 if it is filtered (hidden)
- int highlight: 1 if line has highlight, otherwise 0
- const char *prefix: prefix
- const char *message: message
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date,
             int tags_count, const char **tags,
             int displayed, int highlight,
             const char *prefix, const char *message)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch all messages, on all buffers, without color */
struct t_hook *my_print_hook =
    weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_print(buffer, tags, message, strip_colors, callback, callback_data)

# example
def my_print_cb(data, buffer, date, tags, displayed, highlight, prefix, message):
    # ...
    return weechat.WEECHAT_RC_OK

# catch all messages, on all buffers, without color
hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")

3.11.9. weechat_hook_signal

Hook a signal.

Prototype:

struct t_hook *weechat_hook_signal (const char *signal,
                                    int (*callback)(void *data,
                                                    const char *signal,
                                                    const char *type_data,
                                                    void *signal_data),
                                    void *callback_data);

Arguments:

signal: signal to catch, can begin or end with "*" (priority allowed, see note about priority):

Plugin	Signal	Arguments	Description
aspell	aspell_suggest (new in version 0.4.0)	Pointer: buffer	New suggestions for a misspelled word
guile	guile_script_loaded (new in version 0.3.9)	String: path to script	Scheme script loaded
guile	guile_script_unloaded (new in version 0.3.9)	String: path to script	Scheme script unloaded
guile	guile_script_installed (new in version 0.3.9)	String: comma-separated list of paths to scripts installed (example: "/path/to/script1.scm,/path/to/script2.scm")	Scheme script(s) installed
guile	guile_script_removed (new in version 0.3.9)	String: comma-separated list of scripts removed (example: "script1.scm,script2.scm")	Scheme script(s) removed
irc	xxx,irc_in_yyy ⁽¹⁾	String: message	IRC message from server (before irc plugin uses it, signal sent only if message is not ignored)
irc	xxx,irc_in2_yyy ⁽¹⁾	String: message	IRC message from server (after irc plugin uses it, signal sent only if message is not ignored)
irc	xxx,irc_raw_in_yyy ⁽¹⁾ (new in version 0.3.2)	String: message	IRC message from server (before irc plugin uses it, signal sent even if message is ignored)
irc	xxx,irc_raw_in2_yyy ⁽¹⁾ (new in version 0.3.2)	String: message	IRC message from server (after irc plugin uses it, signal sent even if message is ignored)
irc	xxx,irc_out1_yyy ⁽¹⁾ (new in version 0.3.7)	String: message	IRC message sent to server (before automatic split to fit in 512 bytes)
irc	xxx,irc_out_yyy ⁽¹⁾	String: message	IRC message sent to server (after automatic split to fit in 512 bytes)
irc	xxx,irc_outtags_yyy ⁽¹⁾ (new in version 0.3.4)	String: tags + ";" + message	Tags + IRC message sent to server
irc	irc_ctcp	String: message	CTCP received
irc	irc_dcc	String: message	New DCC
irc	irc_pv	String: message	Private message received
irc	irc_channel_opened	Pointer: buffer	Channel opened
irc	irc_pv_opened	Pointer: buffer	Private opened
irc	irc_server_opened (new in version 0.3.7)	Pointer: buffer	Server buffer opened
irc	irc_server_connecting	String: server name	Connecting to server
irc	irc_server_connected	String: server name	Connected to server
irc	irc_server_disconnected	String: server name	Disconnected from server
irc	irc_ignore_removing	Pointer: ignore	Removing ignore
irc	irc_ignore_removed	-	Ignore removed
irc	irc_notify_join (new in version 0.3.8)	String: server name + "," + nick	A nick in notify list has joined server
irc	irc_notify_quit (new in version 0.3.8)	String: server name + "," + nick	A nick in notify list has quit server
irc	irc_notify_away (new in version 0.3.8)	String: server name + "," + nick + "," + away message	A nick in notify list is now away on server
irc	irc_notify_still_away (new in version 0.3.8)	String: server name + "," + nick + "," + away message	A nick in notify list is still away on server (away message has changed)
irc	irc_notify_back (new in version 0.3.8)	String: server name + "," + nick	A nick in notify list is back (away status removed)
logger	logger_start	Pointer: buffer	Start logging for buffer
logger	logger_stop	Pointer: buffer	Stop logging for buffer
logger	logger_backlog	Pointer: buffer	Display backlog for buffer
lua	lua_script_loaded (new in version 0.3.9)	String: path to script	Lua script loaded
lua	lua_script_unloaded (new in version 0.3.9)	String: path to script	Lua script unloaded
lua	lua_script_installed (new in version 0.3.9)	String: comma-separated list of paths to scripts installed (example: "/path/to/script1.lua,/path/to/script2.lua")	Lua script(s) installed
lua	lua_script_removed (new in version 0.3.9)	String: comma-separated list of scripts removed (example: "script1.lua,script2.lua")	Lua script(s) removed
perl	perl_script_loaded (new in version 0.3.9)	String: path to script	Perl script loaded
perl	perl_script_unloaded (new in version 0.3.9)	String: path to script	Perl script unloaded
perl	perl_script_installed (new in version 0.3.9)	String: comma-separated list of paths to scripts installed (example: "/path/to/script1.pl,/path/to/script2.pl")	Perl script(s) installed
perl	perl_script_removed (new in version 0.3.9)	String: comma-separated list of scripts removed (example: "script1.pl,script2.pl")	Perl script(s) removed
python	python_script_loaded (new in version 0.3.9)	String: path to script	Python script loaded
python	python_script_unloaded (new in version 0.3.9)	String: path to script	Python script unloaded
python	python_script_installed (new in version 0.3.9)	String: comma-separated list of paths to scripts installed (example: "/path/to/script1.py,/path/to/script2.py")	Python script(s) installed
python	python_script_removed (new in version 0.3.9)	String: comma-separated list of scripts removed (example: "script1.py,script2.py")	Python script(s) removed
ruby	ruby_script_loaded (new in version 0.3.9)	String: path to script	Ruby script loaded
ruby	ruby_script_unloaded (new in version 0.3.9)	String: path to script	Ruby script unloaded
ruby	ruby_script_installed (new in version 0.3.9)	String: comma-separated list of paths to scripts installed (example: "/path/to/script1.rb,/path/to/script2.rb")	Ruby script(s) installed
ruby	ruby_script_removed (new in version 0.3.9)	String: comma-separated list of scripts removed (example: "script1.rb,script2.rb")	Ruby script(s) removed
tcl	tcl_script_loaded (new in version 0.3.9)	String: path to script	Tcl script loaded
tcl	tcl_script_unloaded (new in version 0.3.9)	String: path to script	Tcl script unloaded
tcl	tcl_script_installed (new in version 0.3.9)	String: comma-separated list of paths to scripts installed (example: "/path/to/script1.tcl,/path/to/script2.tcl")	Tcl script(s) installed
tcl	tcl_script_removed (new in version 0.3.9)	String: comma-separated list of scripts removed (example: "script1.tcl,script2.tcl")	Tcl script(s) removed
weechat	buffer_closing	Pointer: buffer	Closing buffer
weechat	buffer_closed	Pointer: buffer	Buffer closed
weechat	buffer_line_added (new in version 0.3.7)	Pointer: line	Line added in a buffer
weechat	buffer_lines_hidden	Pointer: buffer	Lines hidden in buffer
weechat	buffer_localvar_added	Pointer: buffer	Local variable has been added
weechat	buffer_localvar_changed	Pointer: buffer	Local variable has changed
weechat	buffer_localvar_removed	Pointer: buffer	Local variable has been removed
weechat	buffer_merged	Pointer: buffer	Buffer merged
weechat	buffer_unmerged	Pointer: buffer	Buffer unmerged
weechat	buffer_moved	Pointer: buffer	Buffer moved
weechat	buffer_opened	Pointer: buffer	Buffer opened
weechat	buffer_renamed	Pointer: buffer	Buffer renamed
weechat	buffer_switch	Pointer: buffer	Switching buffer
weechat	buffer_title_changed	Pointer: buffer	Title of buffer changed
weechat	buffer_type_changed	Pointer: buffer	Type of buffer changed
weechat	day_changed (new in version 0.3.2)	String: new date, format: "2010-01-31"	Day of system date has changed
weechat	debug_dump	String: plugin name	Dump request
weechat	filter_added	Pointer: filter	Filter added
weechat	filter_removing	Pointer: filter	Removing filter
weechat	filter_removed	-	Filter removed
weechat	filters_enabled	-	Filters enabled
weechat	filters_disabled	-	Filters disabled
weechat	hotlist_changed	-	Hotlist changed
weechat	input_paste_pending	-	Paste pending
weechat	input_search	Pointer: buffer	Text search in buffer
weechat	input_text_changed	Pointer: buffer	Input text changed
weechat	input_text_cursor_moved	Pointer: buffer	Input text cursor moved
weechat	key_bind	String: key	Key added
weechat	key_unbind	String: key	Key removed
weechat	key_pressed	String: key pressed	Key pressed
weechat	nicklist_group_added (new in version 0.3.2)	String: buffer pointer + "," + group name	Group added in nicklist
weechat	nicklist_group_changed (new in version 0.3.4)	String: buffer pointer + "," + group name	Group changed in nicklist
weechat	nicklist_group_removing (new in version 0.4.1)	String: buffer pointer + "," + group name	Removing group from nicklist
weechat	nicklist_group_removed (new in version 0.3.2)	String: buffer pointer + "," + group name	Group removed from nicklist
weechat	nicklist_nick_added (new in version 0.3.2)	String: buffer pointer + "," + nick name	Nick added in nicklist
weechat	nicklist_nick_changed (new in version 0.3.4)	String: buffer pointer + "," + nick name	Nick changed in nicklist
weechat	nicklist_nick_removing (new in version 0.4.1)	String: buffer pointer + "," + nick name	Removing nick from nicklist
weechat	nicklist_nick_removed (new in version 0.3.2)	String: buffer pointer + "," + nick name	Nick removed from nicklist
weechat	partial_completion	-	Partial completion happened
weechat	plugin_loaded (new in version 0.3.9)	String: path to plugin loaded (example: "/usr/lib/weechat/plugins/irc.so")	Plugin loaded
weechat	plugin_unloaded (new in version 0.3.9)	String: name of plugin unloaded (example: "irc")	Plugin unloaded
weechat	quit	String: arguments for /quit	Command `/quit` issued by user
weechat	upgrade	String: "quit" if "-quit" argument was given for /upgrade, otherwise NULL	Command `/upgrade` issued by user
weechat	upgrade_ended (new in version 0.3.4)	-	End of upgrade process (command `/upgrade`)
weechat	weechat_highlight	String: message with prefix	Highlight happened
weechat	weechat_pv	String: message with prefix	Private message displayed
weechat	window_closing (new in version 0.3.6)	Pointer: window	Closing window
weechat	window_closed (new in version 0.3.6)	Pointer: window	Window closed
weechat	window_opened (new in version 0.4.1)	Pointer: window	Window opened
weechat	window_scrolled	Pointer: window	Scroll in window
weechat	window_switch (new in version 0.3.7)	Pointer: window	Switching window
weechat	window_unzoom	Pointer: current window	Unzooming window
weechat	window_unzoomed	Pointer: current window	Window unzoomed
weechat	window_zoom	Pointer: current window	Zomming window
weechat	window_zoomed	Pointer: current window	Window zoomed
xfer	xfer_add	Pointer: infolist with xfer info	New xfer
xfer	xfer_send_ready	Pointer: infolist with xfer info	Xfer ready
xfer	xfer_accept_resume	Pointer: infolist with xfer info	Xfer accepts resume (send)
xfer	xfer_send_accept_resume	Pointer: infolist with xfer info	Xfer accepts resume (send)
xfer	xfer_start_resume	Pointer: infolist with xfer info	Start resume
xfer	xfer_resume_ready	Pointer: infolist with xfer info	Xfer resume ready
xfer	xfer_ended (new in version 0.3.2)	Pointer: infolist with xfer info	Xfer has ended

Note	⁽¹⁾ xxx is IRC server name, yyy is IRC command name.

callback: function called when signal is received, arguments and return value:
- void *data: pointer
- const char *signal: signal received
- const char *type_data: type of data sent with signal:
  - WEECHAT_HOOK_SIGNAL_STRING: string
  - WEECHAT_HOOK_SIGNAL_INT: integer number
  - WEECHAT_HOOK_SIGNAL_POINTER: pointer
- void *signal_data: data sent with signal
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_OK_EAT (stop sending the signal immediately) (new in version 0.4.0)
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_signal_cb (void *data, const char *signal, const char *type_data,
              void *signal_data)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch signal "quit" */
struct t_hook *my_signal_hook = weechat_hook_signal ("quit",
                                                     &my_signal_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_signal(signal, callback, callback_data)

# example
def my_signal_cb(data, signal, signal_data):
    # ...
    return weechat.WEECHAT_RC_OK

# catch signal "quit"
hook = weechat.hook_signal("quit", "my_signal_cb", "")

3.11.10. weechat_hook_signal_send

Send a signal.

Prototype:

void weechat_hook_signal_send (const char *signal, const char *type_data,
                               void *signal_data);

Arguments:

signal: signal to send
type_data: type of data sent with signal (see weechat_hook_signal)
signal_data: data sent with signal

C example:

weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);

Script (Python):

# prototype
weechat.hook_signal_send(signal, type_data, signal_data)

# example
weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)

Signal logger_backlog

The signal "logger_backlog" can be sent to display backlog (chat history) in buffer (for example if you open your own buffer in your plugin/script).

Argument is a pointer to buffer.

C example:

weechat_hook_signal_send ("logger_backlog", WEECHAT_HOOK_SIGNAL_POINTER, buffer);

Script (Python):

weechat.hook_signal_send("logger_backlog", weechat.WEECHAT_HOOK_SIGNAL_POINTER, buffer)

Signals xxx_script_install

Five signals can be sent to install a script, according to language:

perl_script_install
python_script_install
ruby_script_install
lua_script_install
tcl_script_install

The callback will do following actions when receiving signal:

unload and remove installed script
move new script to directory ~/.weechat/xxx/ (where xxx is language)
create link to new script in directory ~/.weechat/xxx/autoload/
load new script

These signals are used by script weeget.py to install scripts.

Argument is a string with path to script to install.

C example:

weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                          "/home/xxx/.weechat/test.py");

Script (Python):

weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                         "/home/xxx/.weechat/test.py")

Signals xxx_script_remove

Five signals can be sent to remove list of scripts, according to language:

perl_script_remove
python_script_remove
ruby_script_remove
lua_script_remove
tcl_script_remove

For each script in list, the callback will unload then remove script.

These signals are used by script weeget.py to remove scripts.

Argument is a string with comma-separated list of script to remove (script is name without path, for example script.py).

C example:

/* unload and remove scripts test.py and script.py */
weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                          "test.py,script.py");

Script (Python):

# unload and remove scripts test.py and script.py
weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                         "test.py,script.py")

Signal irc_input_send

New in version 0.3.4.

The signal "irc_input_send" can be sent to simulate input in an irc buffer (server, channel or private).

Argument is a string with following format:

internal server name (required)
semicolon
channel name (optional)
semicolon
flags used when sending message (optional, default is 1):
- 1: queue with high priority (like user messages)
- 2: queue with low priority (like messages automatically sent by WeeChat)
semicolon
comma-separated list of tags used when sending message (optional)
semicolon
text or command (required)

C examples:

/* say "Hello!" on freenode server, #weechat channel */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;#weechat;1;;Hello!");

/* send command "/whois FlashCode" on freenode server, with low priority */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;;2;;/whois FlashCode");

Script (Python):

# say "Hello!" on freenode server, #weechat channel
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;#weechat;1;;Hello!")

# send command "/whois FlashCode" on freenode server, with low priority
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")

3.11.11. weechat_hook_hsignal

New in version 0.3.4.

Hook a hsignal (signal with hashtable).

Prototype:

struct t_hook *weechat_hook_hsignal (const char *signal,
                                     int (*callback)(void *data,
                                                     const char *signal,
                                                     struct t_hashtable *hashtable),
                                     void *callback_data);

Arguments:

signal: signal to catch, can begin or end with "*" (priority allowed, see note about priority):

Plugin	Signal	Arguments	Description
irc	irc_redirection_xxx_yyy ⁽¹⁾ (new in version 0.3.4)	See hsignal_irc_redirect_command	Redirection output
weechat	nicklist_group_added (new in version 0.4.1)	buffer (struct t_gui_buffer ): buffer parent_group* (struct t_gui_nick_group ): parent group group* (struct t_gui_nick_group *): group	Group added in nicklist
weechat	nicklist_nick_added (new in version 0.4.1)	buffer (struct t_gui_buffer ): buffer parent_group* (struct t_gui_nick_group ): parent group nick* (struct t_gui_nick *): nick	Nick added in nicklist
weechat	nicklist_group_removing (new in version 0.4.1)	buffer (struct t_gui_buffer ): buffer parent_group* (struct t_gui_nick_group ): parent group group* (struct t_gui_nick_group *): group	Removing group from nicklist
weechat	nicklist_nick_removing (new in version 0.4.1)	buffer (struct t_gui_buffer ): buffer parent_group* (struct t_gui_nick_group ): parent group nick* (struct t_gui_nick *): nick	Removing nick from nicklist
weechat	nicklist_group_changed (new in version 0.4.1)	buffer (struct t_gui_buffer ): buffer parent_group* (struct t_gui_nick_group ): parent group group* (struct t_gui_nick_group *): group	Group changed in nicklist
weechat	nicklist_nick_changed (new in version 0.4.1)	buffer (struct t_gui_buffer ): buffer parent_group* (struct t_gui_nick_group ): parent group nick* (struct t_gui_nick *): nick	Nick changed in nicklist

Note	⁽¹⁾ xxx is signal argument used in redirection, yyy is redirection pattern.

callback: function called when signal is received, arguments and return value:
- void *data: pointer
- const char *signal: signal received
- struct t_hashtable *hashtable: hashtable
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_OK_EAT (stop sending the signal immediately) (new in version 0.4.0)
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_hsignal_cb (void *data, const char *signal, struct t_hashtable *hashtable)
{
    /* ... */
    return WEECHAT_RC_OK;
}

struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test",
                                                       &my_hsignal_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_hsignal(signal, callback, callback_data)

# example
def my_hsignal_cb(data, signal, hashtable):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_hsignal("test", "my_hsignal_cb", "")

3.11.12. weechat_hook_hsignal_send

New in version 0.3.4.

Send a hsignal (signal with hashtable).

Prototype:

void weechat_hook_hsignal_send (const char *signal, struct t_hashtable *hashtable);

Arguments:

signal: signal to send
hashtable: hashtable

C example:

struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "key", "value");
    weechat_hook_hsignal_send ("my_hsignal", hashtable);
    weechat_hashtable_free (hashtable);
}

Script (Python):

# prototype
weechat.hook_hsignal_send(signal, hashtable)

# example
weechat.hook_hsignal_send("my_hsignal", { "key": "value" })

Hsignal irc_redirect_command

New in version 0.3.4.

The hsignal "irc_redirect_command" can be sent to redirect output of irc command to a callback.

Argument is a hashtable with following entries (keys and values are string):

server: internal server name (required)
pattern: redirect pattern to use (required), either a default one (defined by irc plugin), or a user pattern (see [hsignal_irc_redirect_pattern]), default patterns are:
- ison
- list
- mode_channel
- mode_channel_ban ("mode #channel b")
- mode_channel_ban_exception ("mode #channel e")
- mode_channel_invite ("mode #channel I")
- mode_user
- names
- ping
- time
- topic
- userhost
- who
- whois
- whowas
signal: signal name (required)
count: number of times redirection will work (optional, 1 by default)
string: string that must be in irc messages received (optional, but recommended, if a string can be used to identify messages)
timeout: timeout for redirect, in seconds (optional, 60 by default)
cmd_filter: comma-separated list of irc commands to filter (only these commands will be sent to callbacks, other will be ignored) (optional)

Immediately after sending this hsignal, you must send command to irc server, and redirection will be used for this command.

When complete answer to your command has been be received, a hsignal will be send. This hsignal has name irc_redirection_xxx_yyy where xxx is the signal and yyy the pattern used.

Hashtable sent in hsignal has following content (key and values are strings):

output: output of command (messages are separated by "\n")
output_size: number of bytes in output (as string)
error: error string (if an error occurred):
- timeout: redirection stopped after timeout
server: internal server name
pattern: redirect pattern
signal: signal name
command: redirected command

C example:

int
test_whois_cb (void *data, const char *signal, struct t_hashtable *hashtable)
{
    weechat_printf (NULL, "error = %s", weechat_hashtable_get (hashtable, "error"));
    weechat_printf (NULL, "output = %s", weechat_hashtable_get (hashtable, "output"));
    return WEECHAT_RC_OK;
}

weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL);
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "server", "freenode");
    weechat_hashtable_set (hashtable, "pattern", "whois");
    weechat_hashtable_set (hashtable, "signal", "test");
    weechat_hashtable_set (hashtable, "string", "FlashCode");
    weechat_hook_hsignal_send ("irc_redirect_command", hashtable);
    weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                              "freenode;;2;;/whois FlashCode");
    weechat_hashtable_free (hashtable);
}

Script (Python):

def test_whois_cb(data, signal, hashtable):
    weechat.prnt("", "error = %s" % hashtable["error"])
    weechat.prnt("", "output = %s" % hashtable["output"])
    return weechat.WEECHAT_RC_OK

weechat.hook_hsignal ("irc_redirection_test_whois", "test_whois_cb", "")
weechat.hook_hsignal_send("irc_redirect_command",
                          { "server": "freenode", "pattern": "whois", "signal": "test",
                            "string": "FlashCode" })
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")

Hsignal irc_redirect_pattern

New in version 0.3.4.

The hsignal "irc_redirect_pattern" can be sent to create a pattern for irc redirect (see [hsignal_irc_redirect_command]).

Argument is a hashtable with following entries (keys and values are string):

pattern: name of pattern (required)
timeout: default timeout for pattern, in seconds (optional, 60 by default)
cmd_start: comma-separated list of commands starting redirect (optional)
cmd_stop: comma-separated list of commands stopping redirect (required)
cmd_extra: comma-separated list of commands that may be received after stop commands (optional)

For each command in cmd_start, cmd_stop and cmd_extra, it is possible to give integer with position of "string" that must be found in received message, for example:

352:1,354,401:1

For commands 352 and 401, "string" must be found in received message, as first argument.

Important

The pattern is destroyed when it is used by a redirection. If you need pattern for many redirections, you must create pattern before each redirect.

C example:

struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "pattern", "my_whois");
    weechat_hashtable_set (hashtable, "timeout", "30");
    weechat_hashtable_set (hashtable, "cmd_start", "311:1");
    weechat_hashtable_set (hashtable, "cmd_stop", "318:1,401:1,402:1,431:1,461");
    weechat_hashtable_set (hashtable, "cmd_extra", "318:1");
    weechat_hook_hsignal_send ("irc_redirect_pattern", hashtable);
    /*
     * now redirect irc whois command with hsignal irc_redirect_command,
     * using pattern "my_whois"
     */
    /* ... */
    weechat_hashtable_free (hashtable);
}

Script (Python):

weechat.hook_hsignal_send("irc_redirect_pattern",
                          { "pattern": "my_whois", "timeout": "30",
                            "cmd_start": "311:1",
                            "cmd_stop": "318:1,401:1,402:1,431:1,461",
                            "cmd_extra": "318:1" })
# now redirect irc whois command with hsignal irc_redirect_command
# using pattern "my_whois"
# ...

3.11.13. weechat_hook_config

Hook a configuration option.

Prototype:

struct t_hook *weechat_hook_config (const char *option,
                                    int (*callback)(void *data,
                                                    const char *option,
                                                    const char *value),
                                    void *callback_data);

Arguments:

option: option, format is full name, as used with command /set (for example: weechat.look.item_time_format) (priority allowed, see note about priority)
callback: function called when configuration option is changed, arguments and return value:
- void *data: pointer
- const char *option: name of option
- const char *value: new value for option
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_config_cb (void *data, const char *option, const char *value)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch changes to option "weechat.look.item_time_format" */
struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format",
                                                     &my_config_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_config(option, callback, callback_data)

# example
def my_config_cb(data, option, value):
    # ...
    return weechat.WEECHAT_RC_OK

# catch changes to option "weechat.look.item_time_format"
hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")

3.11.14. weechat_hook_completion

Hook a completion.

Prototype:

struct t_hook *weechat_hook_completion (const char *completion_item,
                                        const char *description,
                                        int (*callback)(void *data,
                                                        const char *completion_item,
                                                        struct t_gui_buffer *buffer,
                                                        struct t_gui_completion *completion),
                                        void *callback_data);

Arguments:

completion_item: name of completion item, after you can use %(name) in a command hooked (argument completion) (priority allowed, see note about priority)
description: description of completion
callback: function called when completion item is used (user is completing something using this item), arguments and return value:
- void *data: pointer
- const char *completion_item: name of completion item
- struct t_gui_buffer *buffer: buffer where completion is made
- struct t_gui_completion *completion: structure used to add words for completion (see weechat_hook_completion_list_add)
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Note	Completion names are global (shared across WeeChat and plugins). So it is recommended to choose a name with a unique prefix, like "plugin_xxx" (where "xxx" is your item name).

Return value:

pointer to new hook, NULL if error occurred

C example:

int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    weechat_hook_completion_list_add (completion, "word1",
                                      0, WEECHAT_LIST_POS_SORT);
    weechat_hook_completion_list_add (completion, "test_word2",
                                      0, WEECHAT_LIST_POS_SORT);
    return WEECHAT_RC_OK;
}

struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item",
                                                             "my custom completion!",
                                                             &my_completion_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_completion(completion_item, description, callback, callback_data)

# example
def my_completion_cb(data, completion_item, buffer, completion):
    weechat.hook_completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.hook_completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_completion("plugin_item", "my custom completion!",
                               "my_completion_cb", "")

3.11.15. weechat_hook_completion_get_string

New in version 0.3.4.

Get a completion property as string.

Prototype:

const char *weechat_hook_completion_get_string (struct t_gui_completion *completion,
                                                const char *property);

Arguments:

completion: completion pointer
property: property name:
- base_command: command used for completion
- base_word: word being completed
- args: command arguments (including base word)

C example:

int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    /* get arguments of command */
    const char *args = weechat_hook_completion_get_string (completion, "args");

    /* completion depending on args */
    /* ... */

    return WEECHAT_RC_OK;
}

Script (Python):

# prototype
value = weechat.hook_completion_get_string(completion, property)

# example
def my_completion_cb(data, completion_item, buffer, completion):
    # get arguments of command
    args = weechat.hook_completion_get_string(completion, "args")
    # completion depending on args
    # ...
    return weechat.WEECHAT_RC_OK

3.11.16. weechat_hook_completion_list_add

Add a word for a completion.

Prototype:

void weechat_hook_completion_list_add (struct t_gui_completion *completion,
                                       const char *word,
                                       int nick_completion,
                                       const char *where);

Arguments:

completion: completion pointer
word: word to add
nick_completion: 1 if word is a nick, otherwise 0
where: position where word will be inserted in list:
- WEECHAT_LIST_POS_SORT: any position, to keep list sorted
- WEECHAT_LIST_POS_BEGINNING: beginning of list
- WEECHAT_LIST_POS_END: end of list

C example: see weechat_hook_completion.

Script (Python):

# prototype
weechat.hook_completion_list_add(completion, word, nick_completion, where)

# example: see function hook_completion above

3.11.17. weechat_hook_modifier

Hook a modifier.

Prototype:

struct t_hook *weechat_hook_modifier (const char *modifier,
                                      char *(*callback)(void *data,
                                                        const char *modifier,
                                                        const char *modifier_data,
                                                        const char *string),
                                      void *callback_data);

Arguments:

modifier: modifier name, list of modifiers used by Weechat or plugins (priority allowed, see note about priority):

Plugin	Modifier	Modifier data	String	Output
charset	charset_decode	plugin.buffer_name	Any string	String decoded from charset found for plugin/buffer to UTF-8
charset	charset_encode	plugin.buffer_name	Any string	String encoded from UTF-8 to charset found for plugin/buffer
irc	irc_color_decode	"1" to keep colors, "0" to remove colors	Any string	String with WeeChat color codes, or without color
irc	irc_color_encode	"1" to keep colors, "0" to remove colors	Any string	String with IRC color codes, or without color
irc	irc_command_auth (new in version 0.4.1)	Server name	Authentication command (for example: `/msg nickserv identify password`)	command with hidden password (for example: `/msg nickserv identify ********`)
irc	irc_message_auth (new in version 0.4.1)	Server name	Message displayed after `/msg` sent to nickserv	Message with hidden password
irc	irc_in_xxx ⁽¹⁾	Server name	Content of message received from IRC server (before charset decoding)	New content of message
irc	irc_in2_xxx ⁽¹⁾ (new in version 0.3.5)	Server name	Content of message received from IRC server (after charset decoding)	New content of message
irc	irc_out1_xxx ⁽¹⁾ (new in version 0.3.7)	Server name	Content of message about to be sent to IRC server (before automatic split to fit in 512 bytes)	New content of message
irc	irc_out_xxx ⁽¹⁾	Server name	Content of message about to be sent to IRC server (after automatic split to fit in 512 bytes)	New content of message
weechat	bar_condition_yyy ⁽²⁾	String with window pointer ("0x123..")	Empty string	"1" to display bar, "0" to hide it
weechat	history_add (new in version 0.3.2)	String with buffer pointer ("0x123..")	Content of command line to add in command history (buffer and global)	String added to command history
weechat	input_text_content	String with buffer pointer ("0x123..")	Content of command line	New content of command line
weechat	input_text_display	String with buffer pointer ("0x123..")	Content of command line, without cursor tag	New string, for display only (command line is not changed)
weechat	input_text_display_with_cursor	String with buffer pointer ("0x123..")	Content of command line, with cursor tag	New string, for display only (command line is not changed)
weechat	input_text_for_buffer (new in version 0.3.7)	String with buffer pointer ("0x123..")	Content of command line sent to buffer (text or command)	New content of command line sent to buffer
weechat	weechat_print	plugin;buffer_name;tags	Message printed	New message printed

Note	⁽¹⁾ xxx is IRC command name. ⁽²⁾ yyy is bar name.

callback: function called when modifier is used, arguments and return value:
- void *data: pointer
- const char *modifier: name of modifier
- const char *modifier_data: data for modifier
- const char *string: string to modify
- return value: new string
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

char *
my_modifier_cb (void *data, const char *modifier,
                const char *modifier_data,
                const char *string)
{
    char *result;
    int length;

    if (!string)
        return NULL;

    length = strlen (string) + 5;
    result = malloc (length);
    if (result)
    {
        /* add "xxx" to any message printed */
        snprintf (result, length, "%s xxx", string);
    }

    return result;
}

struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print",
                                                         &my_modifier_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_modifier(modifier, callback, callback_data)

# example
def my_modifier_cb(data, modifier, modifier_data, string):
    return "%s xxx" % string

hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")

3.11.18. weechat_hook_modifier_exec

Execute modifier(s).

Prototype:

char *weechat_hook_modifier_exec (const char *modifier,
                                  const char *modifier_data,
                                  const char *string);

Arguments:

modifier: modifier name
modifier_data: modifier data
string: string to modify

Return value:

string modified, NULL if error occurred

C example:

char *new_string = weechat_hook_modifier_exec ("my_modifier",
                                               my_data, my_string);

Script (Python):

# prototype
weechat.hook_modifier_exec(modifier, modifier_data, string)

# example
weechat.hook_modifier_exec("my_modifier", my_data, my_string)

3.11.19. weechat_hook_info

Hook an information (callback takes and returns a string).

Prototype:

struct t_hook *weechat_hook_info (const char *info_name,
                                  const char *description,
                                  const char *args_description,
                                  const char *(*callback)(void *data,
                                                          const char *info_name,
                                                          const char *arguments),
                                  void *callback_data);

Arguments:

info_name: name of info (priority allowed, see note about priority)
description: description
args_description: description of arguments (optional, can be NULL)
callback: function called when info is asked, arguments and return value:
- void *data: pointer
- const char *info_name: name of info
- const char *arguments: additional arguments, depending on info
- return value: value of info asked
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

const char *
my_info_cb (void *data, const char *info_name, const char *arguments)
{
    /* ... */
    return pointer_to_string;
}

/* add info "my_info" */
struct t_hook *my_info_hook = weechat_hook_info ("my_info",
                                                 "Some info",
                                                 "Info about arguments",
                                                 &my_info_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_info(info_name, description, args_description, callback, callback_data)

# example
def my_info_cb(data, info_name, arguments):
    return "some_info"

hook = weechat.hook_info("my_info", "Some info", "Info about arguments",
                         "my_info_cb", "")

3.11.20. weechat_hook_info_hashtable

New in version 0.3.4.

Hook an information (callback takes and returns a hashtable).

Prototype:

struct t_hook *weechat_hook_info_hashtable (const char *info_name,
                                            const char *description,
                                            const char *args_description,
                                            const char *output_description,
                                            struct t_hashtable *(*callback)(void *data,
                                                                            const char *info_name,
                                                                            struct t_hashtable *hashtable),
                                            void *callback_data);

Arguments:

info_name: name of info (priority allowed, see note about priority)
description: description
args_description: description of expected hashtable (optional, can be NULL)
output_description: description of hashtable returned by callback (optional, can be NULL)
callback: function called when info is asked, arguments and return value:
- void *data: pointer
- const char *info_name: name of info
- struct t_hashtable *hashtable: hashtable, depending on info
- return value: hashtable asked
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

struct t_hashtable *
my_info_hashtable_cb (void *data, const char *info_name, struct t_hashtable *hashtable)
{
    /* ... */
    return pointer_to_new_hashtable;
}

/* add info "my_info_hashtable" */
struct t_hook *my_info_hook = weechat_hook_info_hashtable ("my_info_hashtable",
                                                           "Some info",
                                                           "Info about input hashtable",
                                                           "Info about output hashtable",
                                                           &my_info_hashtable_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_info_hashtable(info_name, description, args_description,
                                   output_description, callback, callback_data)

# example
def my_info_hashtable_cb(data, info_name, hashtable):
    return { "test_key": "test_value" }

hook = weechat.hook_info_hashtable("my_info_hashtable", "Some info",
                                   "Info about input hashtable",
                                   "Info about output hashtable",
                                   "my_info_hashtable_cb", "")

3.11.21. weechat_hook_infolist

Hook an infolist: callback will return pointer to infolist asked.

Prototype:

struct t_hook *weechat_hook_infolist (const char *infolist_name,
                                      const char *description,
                                      const char *pointer_description,
                                      const char *args_description,
                                      struct t_infolist *(*callback)(void *data,
                                                                     const char *infolist_name,
                                                                     void *pointer,
                                                                     const char *arguments),
                                      void *callback_data);

Arguments:

infolist_name: name of infolist (priority allowed, see note about priority)
description: description
pointer_description: description of pointer (optional, can be NULL)
args_description: description of arguments (optional, can be NULL)
callback: function called when infolist is asked, arguments and return value:
- void *data: pointer
- const char *infolist_name: name of infolist
- void *pointer: pointer to an object that infolist must return (to get only one item in infolist)
- const char *arguments: additional arguments, depending on infolist
- return value: infolist asked
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

struct t_infolist *
my_infolist_cb (void *data, const char *infolist_name, void *pointer,
                const char *arguments)
{
    struct t_infolist *my_infolist;

    /* build infolist */
    /* ... */

    return my_infolist;
}

/* add infolist "my_infolist" */
struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist",
                                                    "Infolist with some data",
                                                    "Info about pointer",
                                                    "Info about arguments",
                                                    &my_infolist_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_infolist(infolist_name, description, pointer_description,
                             args_description, callback, callback_data)

# example
def my_infolist_cb(data, infolist_name, pointer, arguments):
    # build infolist
    # ...
    return my_infolist

hook = weechat.hook_infolist("my_infolist", "Infolist with some data",
                             "Info about pointer", "Info about arguments",
                             "my_infolist_cb", "")

3.11.22. weechat_hook_hdata

Hook a hdata: callback will return pointer to hdata asked.

Prototype:

struct t_hook *weechat_hook_hdata (const char *hdata_name,
                                   const char *description,
                                   struct t_hdata *(*callback)(void *data,
                                                               const char *hdata_name),
                                   void *callback_data);

Arguments:

hdata_name: name of hdata (priority allowed, see note about priority)
description: description
callback: function called when hdata is asked, arguments and return value:
- void *data: pointer
- const char *hdata_name: name of hdata
- return value: hdata asked
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new hook, NULL if error occurred

C example:

struct t_hdata *
my_hdata_cb (void *data, const char *hdata_name)
{
    struct t_hdata *my_hdata;

    /* build hdata */
    /* ... */

    return my_hdata;
}

/* add hdata "my_hdata" */
struct t_hook *my_hdata = weechat_hook_hdata ("my_hdata",
                                              "Hdata for my structure",
                                              &my_hdata_cb, NULL);

Note	This function is not available in scripting API.

3.11.23. weechat_hook_focus

Hook a focus: mouse event or key pressed in cursor mode (free movement of cursor).

Prototype:

struct t_hook *weechat_hook_focus (const char *area,
                                   struct t_hashtable *(*callback)(void *data,
                                                                   struct t_hashtable *info),
                                   void *callback_data);

Arguments:

area: "chat" for chat area, or name of bar item (priority allowed, see note about priority)
callback: function called when focus is made, arguments and return value:
- void *data: pointer
- struct t_hashtable *info: hashtable with info on focus and strings returned by other calls to focus callbacks (with higher priority) (see table below)
- return value: either "info" pointer (hashtable completed), or pointer to a new hashtable (created by callback, with keys and values of type "string"), this new hashtable content will be added to info for other calls to focus callbacks
callback_data: pointer given to callback when it is called by WeeChat

Important

For a mouse gesture, your callback will be called two times: first time when button is pressed (here the area always matches your area), second time when button is released, and then the area may not match your area: so you must always test in your callback if area is matching before using info in hashtable.

Content of hashtable sent to callback (keys and values are of type "string"):

Key ⁽¹⁾	Description	Value examples	Value if N/A
`_x`	Column on screen	"0" … "n"
`_y`	Line on screen	"0" … "n"
`_key`	Key or mouse event	"button1", "button2-gesture-left", …
`_window`	Pointer to window	"0x12345678"	""
`_window_number`	Number of window	"1" … "n"	"*"
`_buffer`	Pointer to buffer	"0x12345678"	""
`_buffer_number`	Number of buffer	"1" … "n"	"-1"
`_buffer_plugin`	Plugin name of buffer	"core", "irc", …	""
`_buffer_name`	Name of buffer	"weechat", "freenode.#weechat", …	""
`_buffer_full_name`	Full name of buffer	"core.weechat", "irc.freenode.#weechat", …	""
`_buffer_localvar_XXX ⁽²⁾`	Local variables of buffer	any value	not set
`_chat`	Chat area indicator	"0" or "1"	"0"
`_chat_line_x`	Column in line ⁽³⁾	"0" … "n"	"-1"
`_chat_line_y`	Line number ⁽³⁾	"0" … "n"	"-1"
`_chat_line_date`	Line date/time	"1313237175"	"0"
`_chat_line_date_printed`	Line date/time ⁽⁴⁾	"1313237175"	"0"
`_chat_line_time`	Time displayed	"14:06:15"	""
`_chat_line_tags`	Tags of line	"irc_privmsg,notify_message,nick_FlashCode,log1"	""
`_chat_line_nick`	Nick of line	"FlashCode"	""
`_chat_line_prefix`	Prefix of line	"@FlashCode"	""
`_chat_line_message`	Message of line	"Hello world!"	""
`_chat_word`	Word at (x,y)	"Hello"	""
`_chat_bol`	Beginning of line ⇒ (x-1,y)	"He"	""
`_chat_eol`	(x,y) ⇒ end of line	"llo world!"	""
`_bar_name`	Name of bar	"title", "nicklist", …	""
`_bar_filling`	Filling of bar	"horizontal", "vertical", …	""
`_bar_item_name`	Name of bar item	"buffer_nicklist", "hotlist", …	""
`_bar_item_line`	Line in bar item	"0" … "n"	"-1"
`_bar_item_col`	Column in bar item	"0" … "n"	"-1"

Note

⁽¹⁾ There are same keys suffixed with "2" (ie: "_x2", "_y2", "_window2", …) with info on second point (useful only for mouse gestures, to know where mouse button has been released).
⁽²⁾ XXX is name of local variable in buffer.
⁽³⁾ It is set only for buffers with free content.
⁽⁴⁾ It is date when WeeChat adds line in buffer (greater or equal to "_chat_line_date").

Extra info for bar item "buffer_nicklist":

Key	Plugin ⁽¹⁾	Description
`nick`	core	Nick name
`prefix`	core	Prefix for nick
`group`	core	Group name
`irc_host`	irc	Host for nick (if known)

Note	⁽¹⁾ The name of plugin which defines a hook_focus to return info for this bar item (so for example if plugin is "irc", such info will be available only on irc buffers).

Return value:

pointer to new hook, NULL if error occurred

C example:

struct t_hashtable *
my_focus_nicklist_cb (void *data, struct t_hashtable *info)
{
    /* add strings in hashtable */
    /* ... */

    return info;
}

/* add focus on nicklist */
struct t_hook *my_focus = weechat_hook_focus ("buffer_nicklist",
                                              &my_focus_nicklist_cb, NULL);

Script (Python):

# prototype
hook = weechat.hook_focus(area, callback, callback_data)

# example
def my_focus_nicklist_cb(data, info):
    # build dict
    # ...
    return my_dict

hook = weechat.hook_focus("buffer_nicklist", "my_focus_nicklist_cb", "")

3.11.24. weechat_hook_set

New in version 0.3.9.

Set string value of a hook property.

Prototype:

void weechat_hook_set (struct t_hook *hook, const char *property,
                       const char *value);

Arguments:

hook: something hooked with "weechat_hook_xxx()"
property and value: property name, with its value:

Name	Value	Description
subplugin	any string	Name of sub plugin (commonly script name, which is displayed in `/help command` for a hook of type command)

C example:

struct t_hook *my_command_hook =
    weechat_hook_command ("abcd", "description",
                          "args", "description args",
                          "", &my_command_cb, NULL);
weechat_hook_set (my_command_hook, "subplugin", "test");

Note	This function is not available in scripting API.

3.11.25. weechat_unhook

Unhook something hooked.

Prototype:

void weechat_unhook (struct t_hook *hook);

Arguments:

hook: something hooked with "weechat_hook_xxx()"

C example:

struct t_hook *my_hook = weechat_hook_command ( /* ... */ );
/* ... */
weechat_unhook (my_hook);

Script (Python):

# prototype
weechat.unhook(hook)

# example
weechat.unhook(my_hook)

3.11.26. weechat_unhook_all

Unhook everything that has been hooked by current plugin.

Prototype:

void weechat_unhook_all ();

C example:

weechat_unhook_all ();

Script (Python):

# prototype
weechat.unhook_all()

# example
weechat.unhook_all()

3.12. Buffers

Functions to create/query/close buffers.

3.12.1. weechat_buffer_new

Open a new buffer.

Prototype:

struct t_gui_buffer *weechat_buffer_new (const char *name,
                                         int (*input_callback)(void *data,
                                                               struct t_gui_buffer *buffer,
                                                               const char *input_data),
                                         void *input_callback_data,
                                         int (*close_callback)(void *data,
                                                               struct t_gui_buffer *buffer),
                                         void *close_callback_data);

Arguments:

name: name of buffer (must be unique for plugin)
input_callback: function called when input text is entered on buffer, arguments and return value:
- void *data: pointer
- struct t_gui_buffer *buffer: buffer pointer
- const char *input_data: input data
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat
close_callback: function called when buffer is closed, arguments and return value:
- void *data: pointer
- struct t_gui_buffer *buffer: buffer pointer
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_data: pointer given to callback when it is called by WeeChat

Return value:

pointer to new buffer, NULL if error occurred

C example:

int
my_input_cb (void *data, struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Text: %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    weechat_printf (NULL, "Buffer '%s' will be closed!",
                    weechat_buffer_get_string (buffer, "name"));
    return WEECHAT_RC_OK;
}

struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);

Script (Python):

# prototype
buffer = weechat.buffer_new(name, input_callback, input_callback_data,
    close_callback, close_callback_data)

# example
def my_input_cb(data, buffer, input_data):
    weechat.prnt(buffer, "Text: %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data, buffer):
    weechat.prnt("", "Buffer '%s' will be closed!" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")

3.12.2. weechat_current_buffer

Return pointer to current buffer (buffer displayed by current window).

Prototype:

struct t_gui_buffer *weechat_current_buffer ();

Return value:

pointer to current buffer

C example:

weechat_printf (weechat_current_buffer (), "Text on current buffer");

Script (Python):

# prototype
buffer = weechat.current_buffer()

# example
weechat.prnt(weechat.current_buffer(), "Text on current buffer")

3.12.3. weechat_buffer_search

Search a buffer by plugin and/or name.

Prototype:

struct t_gui_buffer *weechat_buffer_search (const char *plugin,
                                            const char *name);

Arguments:

plugin: name of plugin
name: name of buffer, if it is NULL or empty string, the current buffer is returned (buffer displayed by current window)

Return value:

pointer to buffer found, NULL if not found

C example:

struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                        "my_buffer");

Script (Python):

# prototype
buffer = weechat.buffer_search(plugin, name)

# example
buffer = weechat.buffer_search("my_plugin", "my_buffer")

3.12.4. weechat_buffer_search_main

Search WeeChat main buffer (core buffer, first buffer displayed when WeeChat is starting).

Prototype:

struct t_gui_buffer *weechat_buffer_search_main ();

Return value:

pointer to WeeChat main buffer (core buffer)

C example:

struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();

Script (Python):

# prototype
buffer = weechat.buffer_search_main()

# example
buffer = weechat.buffer_search_main()

3.12.5. weechat_buffer_clear

Clear content of a buffer.

Prototype:

void weechat_buffer_clear (struct t_gui_buffer *buffer);

Arguments:

buffer: buffer pointer

C example:

struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                        "my_buffer");
if (my_buffer)
{
    weechat_buffer_clear (my_buffer);
}

Script (Python):

# prototype
weechat.buffer_clear(buffer)

# example
buffer = weechat.buffer_search("my_plugin", "my_buffer")
if buffer != "":
    weechat.buffer_clear(buffer)

3.12.6. weechat_buffer_close

Close a buffer.

Prototype:

void weechat_buffer_close (struct t_gui_buffer *buffer);

Arguments:

buffer: buffer pointer

C example:

struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
/* ... */
weechat_buffer_close (my_buffer);

Script (Python):

# prototype
weechat.buffer_close(buffer)

# example
buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
# ...
weechat.buffer_close(buffer)

3.12.7. weechat_buffer_merge

Merge buffer into another buffer: both buffers will still exist separately, but with same number, and WeeChat will display lines from both buffers (mixed lines).

Prototype:

void weechat_buffer_merge (struct t_gui_buffer *buffer,
                           struct t_gui_buffer *target_buffer);

Arguments:

buffer: buffer pointer
target_buffer: target buffer, where buffer will be merged

C example:

/* merge current buffer with weechat "core" buffer */
weechat_buffer_merge (weechat_current_buffer (),
                      weechat_buffer_search_main ());

Script (Python):

# prototype
weechat.buffer_merge(buffer, target_buffer)

# example
# merge current buffer with WeeChat "core" buffer
weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())

3.12.8. weechat_buffer_unmerge

Unmerge buffer from a group of merged buffers.

Prototype:

void weechat_buffer_unmerge (struct t_gui_buffer *buffer,
                             int number);

Arguments:

buffer: buffer pointer
number: target number for detached buffer, if it is < 1, then buffer will be moved to number of buffer + 1

C example:

weechat_buffer_unmerge (weechat_current_buffer (), 1);

Script (Python):

# prototype
weechat.buffer_unmerge(buffer, number)

# example
weechat.buffer_unmerge(weechat.current_buffer(), 1)

3.12.9. weechat_buffer_get_integer

Return integer value of a buffer property.

Prototype:

int weechat_buffer_get_integer (struct t_gui_buffer *buffer,
                                const char *property);

Arguments:

buffer: buffer pointer
property: property name:
- number: number of buffer (starts to 1)
- layout_number: number of buffer saved in layout
- layout_number_merge_order: order in merge for layout
- short_name_is_set: 1 if short name is set, 0 if not set
- type: buffer type (0: formatted, 1: free content)
- notify: notify level for buffer
- num_displayed: number of windows displaying buffer
- active: 1 if buffer is active, 0 if buffer is merged and not selected
- print_hooks_enabled: 1 if print hooks are enabled, otherwise 0
- lines_hidden: 1 if at least one line is hidden on buffer (filtered), or 0 if all lines are displayed
- prefix_max_length: max length for prefix in this buffer
- time_for_each_line: 1 if time is displayed for each line in buffer (default), otherwise 0
- nicklist: 1 if nicklist is enabled, otherwise 0
- nicklist_case_sensitive: 1 if nicks are case sensitive, otherwise 0
- nicklist_max_length: max length for a nick
- nicklist_display_groups: 1 if groups are displayed, otherwise 0
- nicklist_count: number of nicks and groups in nicklist
- nicklist_groups_count: number of groups in nicklist
- nicklist_nicks_count: number of nicks in nicklist
- nicklist_visible_count: number of nicks/groups displayed
- input: 1 if input is enabled, otherwise 0
- input_get_unknown_commands: 1 if unknown commands are sent to input callback, otherwise 0
- input_size: input size (in bytes)
- input_length: input length (number of chars)
- input_pos: cursor position in buffer input
- input_1st_display: first char displayed on screen
- num_history: number of commands in history
- text_search: text search type:
  - 0: no search at this moment
  - 1: backward search (direction: oldest messages)
  - 2: forward search (direction: newest messages)
- text_search_exact: 1 if text search is case sensitive
- text_search_found: 1 if text found, otherwise 0

Return value:

integer value of property

C example:

weechat_printf (NULL, "my buffer number is: %d",
                weechat_buffer_get_integer (my_buffer, "number"));

Script (Python):

# prototype
value = weechat.buffer_get_integer(buffer, property)

# example
weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number"))

3.12.10. weechat_buffer_get_string

Return string value of a buffer property.

Prototype:

const char *weechat_buffer_get_string (struct t_gui_buffer *buffer,
                                       const char *property);

Arguments:

buffer: buffer pointer
property: property name:
- plugin: name of plugin which created this buffer ("core" for WeeChat main buffer)
- name: name of buffer
- full_name: full name of buffer ("plugin.name") (new in version 0.3.7)
- short_name: short name of buffer (note: used for display only and can be changed by user, this must not be used to find name of buffer, use instead name, full_name or local variable channel)
- title: title of buffer
- input: input text
- text_search_input: input saved before text search
- highlight_words: list of words to highlight
- highlight_regex: regular expression for highlight
- highlight_tags: list of tags to highlight
- hotlist_max_level_nicks: max hotlist level for some nicks
- localvar_xxx: get content of local variable "xxx" (replace "xxx" by the name of variable to read)

Return value:

string value of property

C example:

weechat_printf (NULL, "name / short name of buffer are: %s / %s",
                weechat_buffer_get_string (my_buffer, "name"),
                weechat_buffer_get_string (my_buffer, "short_name"));

Script (Python):

# prototype
value = weechat.buffer_get_string(buffer, property)

# example
weechat.prnt("", "name / short name of buffer are: %s / %s"
    % (weechat.buffer_get_string(my_buffer, "name"),
    weechat.buffer_get_string(my_buffer, "short_name")))

3.12.11. weechat_buffer_get_pointer

Return pointer value of a buffer property.

Prototype:

void *weechat_buffer_pointer (struct t_gui_buffer *buffer,
                              const char *property);

Arguments:

buffer: buffer pointer
property: property name:
- plugin: pointer to plugin which created this buffer (NULL for WeeChat main buffer)
- highlight_regex_compiled: regular expression highlight_regex compiled

Return value:

pointer value of property

C example:

weechat_printf (NULL, "plugin pointer of my buffer: %lx",
                weechat_buffer_get_pointer (my_buffer, "plugin"));

Script (Python):

# prototype
value = weechat.buffer_get_pointer(buffer, property)

# example
weechat.prnt("", "plugin pointer of my buffer: %s" % weechat.buffer_get_pointer(my_buffer, "plugin"))

3.12.12. weechat_buffer_set

Set string value of a buffer property.

Prototype:

void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property,
                         const char *value);

Arguments:

buffer: buffer pointer
property and value: property name, with its value:

Name	Value	Description
hotlist	"+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT	"+": enable hotlist (global setting, buffer pointer is not used) "-": disable hotlist (global setting, buffer pointer is not used) priority: add buffer to hotlist with this priority
completion_freeze	"0", "1"	"0": no freeze of completion (default value) (global setting, buffer pointer is not used) "1": do not stop completion when command line is updated (global setting, buffer pointer is not used)
unread	-	Set unread marker after last line of buffer
display	"1", "auto"	"1": switch to this buffer in current window "auto": switch to this buffer in current window, read marker is not reset
number	number	Move buffer to this number
name	any string	Set new name for buffer
short_name	any string	Set new short name for buffer
type	"formatted" or "free"	Set type for buffer: "formatted" (for printing chat messages), or "free" (for free content)
notify	"0", "1", "2", "3"	Set notify level for buffer: "0" = never add to hotlist, "1" = add for highlights only, "2" = add for highlights and messages, "3" = add for all messages
title	any string	Set new title for buffer
time_for_each_line	"0" or "1"	"0" to hide time for all lines in buffer, "1" to see time for all lines (default for a new buffer)
nicklist	"0" or "1"	"0" to remove nicklist for buffer, "1" to add nicklist for buffer
nicklist_case_sensitive	"0" or "1"	"0" to have case insensitive nicklist, "1" to have case sensitive nicklist
nicklist_display_groups	"0" or "1"	"0" to hide nicklist groups, "1" to display nicklist groups
highlight_words	"-" or comma separated list of words	"-" is a special value to disable any highlight on this buffer, or comma separated list of words to highlight in this buffer, for example: "abc,def,ghi"
highlight_words_add	comma separated list of words	Comma separated list of words to highlight in this buffer, these words are added to existing highlighted words in buffer
highlight_words_del	comma separated list of words	Comma separated list of words to remove from highlighted words on buffer
highlight_regex	any string	Regular expression for highlight
highlight_tags	comma separated list of tags	Comma separated list of tags to highlight in this buffer
hotlist_max_level_nicks	comma separated list of "nick:level"	Comma separated list of nicks with max level for hotlist on this buffer (level can be: -1: never in hotlist, 0: low, 1: message, 2: private, 3: highlight), for example: "joe:2,mike:-1,robert:-1" (joe will never produce highlight on buffer, mike and robert will never change hotlist)
hotlist_max_level_nicks_add	comma separated list of "nick:level"	Comma separated list of nicks with level for hotlist, these nicks are added to existing nicks in buffer
hotlist_max_level_nicks_del	comma separated list of nicks	Comma separated list of nicks to remove from hotlist max levels
key_bind_xxx	any string	Bind a new key xxx, specific to this buffer, value is command to execute for this key
key_unbind_xxx	-	Unbind key xxx for this buffer
input	any string	Set new value for buffer input
input_pos	position	Set cursor position in buffer input
input_get_unknown_commands	"0" or "1"	"0" to disable unknown commands on this buffer (default behavior), "1" to get unknown commands, for example if user type "/unknowncmd", buffer will receive it (no error about unknown command)
localvar_set_xxx	any string	Set new value for local variable xxx (variable is created if it does not exist)
localvar_del_xxx	-	Remove local variable xxx

C example:

/* disable hotlist (for all buffers) */
weechat_buffer_set (NULL, "hotlist", "-");

/* enable again hotlist */
weechat_buffer_set (NULL, "hotlist", "+");

/* change buffer name */
weechat_buffer_set (my_buffer, "name", "my_new_name");

/* add new local variable "toto" with value "abc" */
weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

/* remove local variable "toto" */
weechat_buffer_set (my_buffer, "localvar_del_toto", NULL);

Script (Python):

# prototype
weechat.buffer_set(buffer, property, value)

# examples

# disable hotlist (for all buffers)
weechat.buffer_set("", "hotlist", "-")

# enable again hotlist
weechat.buffer_set("", "hotlist", "+")

# change buffer name
weechat.buffer_set(my_buffer, "name", "my_new_name")

# add new local variable "toto" with value "abc"
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")

# remove local variable "toto"
weechat.buffer_set(my_buffer, "localvar_del_toto", "")

3.12.13. weechat_buffer_set_pointer

Set pointer value of a buffer property.

Prototype:

void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property,
                                 void *pointer);

Arguments:

buffer: buffer pointer
property and value: property name, with its value:
- close_callback: set close callback function
- close_callback_data: set close callback data
- input_callback: set input callback function
- input_callback_data: set input callback data
- nickcmp_callback: set nick comparison callback function (this callback is called when searching nick in nicklist) (new in version 0.3.9)
- nickcmp_callback_data: set nick comparison callback data (new in version 0.3.9)

Prototypes for callbacks:

int close_callback (void *data, struct t_gui_buffer *buffer);

int input_callback (void *data, struct t_gui_buffer *buffer, const char *input_data);

int nickcmp_callback (void *data, struct t_gui_buffer *buffer, const char *nick1, const char *nick2);

C example:

int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    /* ... */
    return WEECHAT_RC_OK;
}

weechat_buffer_set_pointer (my_buffer, "close_callback", &my_close_cb);

Note	This function is not available in scripting API.

3.12.14. weechat_buffer_string_replace_local_var

Replace local variables in a string by their values, using buffer local variables.

Prototype:

char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer,
                                               const char *string);

Arguments:

buffer: buffer pointer
string: string with text and local variables using format "$var"

Return value:

string with values of local variables

C example:

weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

char *str = weechat_buffer_string_replace_local_var (my_buffer,
                                                     "test with $toto");
/* str contains "test with abc" */

Script (Python):

# prototype
value = weechat.buffer_string_replace_local_var(buffer, string)

# example
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")
str = weechat.buffer_string_replace_local_var(my_buffer, "test with $toto")
# str contains "test with abc"

3.12.15. weechat_buffer_match_list

New in version 0.3.5.

Check if buffer matches a list of buffers.

Prototype:

int weechat_buffer_match_list (struct t_gui_buffer *buffer, const char *string);

Arguments:

buffer: buffer pointer
string: comma-separated list of buffers:
- "*" means all buffers
- name beginning with "!" is excluded
- name can start or end with "*" to match many buffers

Return value:

1 if buffer matches list of buffers, 0 otherwise

C example:

struct t_gui_buffer *buffer = weechat_buffer_search ("irc", "freenode.#weechat");
if (buffer)
{
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*"));                   /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*,!*#weechat*"));       /* 0 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.freenode.*"));      /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.oftc.*,python.*")); /* 0 */
}

Script (Python):

# prototype
match = weechat.buffer_match_list(buffer, string)

# example
buffer = weechat.buffer_search("irc", "freenode.#weechat")
if buffer:
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*"))                   # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*,!*#weechat*"))       # 0
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.freenode.*"))      # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.oftc.*,python.*")) # 0

3.13. Windows

Functions to query windows.

3.13.1. weechat_current_window

Return pointer to current window.

Prototype:

struct t_gui_window *weechat_current_window ();

Return value:

pointer to current window

C example:

struct t_gui_window *current_window = weechat_current_window ();

Script (Python):

# prototype
window = weechat.current_window()

# example
current_window = weechat.current_window()

3.13.2. weechat_window_search_with_buffer

New in version 0.3.5.

Return pointer to window displaying buffer.

Prototype:

struct t_gui_window *weechat_window_search_with_buffer (struct t_gui_buffer *buffer);

Arguments:

buffer: buffer pointer

Return value:

pointer to window displaying buffer (NULL if no window is displaying buffer)

C example:

weechat_printf (NULL,
                "window displaying core buffer: %lx",
                weechat_window_search_with_buffer (weechat_buffer_search_main ()));

Script (Python):

# prototype
window = weechat.window_search_with_buffer(buffer)

# example
weechat.prnt("", "window displaying core buffer: %s"
    % weechat.window_search_with_buffer(weechat.buffer_search_main()))

3.13.3. weechat_window_get_integer

Return integer value of a window property.

Prototype:

int weechat_window_get_integer (struct t_gui_window *window,
                                const char *property);

Arguments:

window: window pointer
property: property name:
- number: number of window (starts to 1)
- win_x: X position of window in terminal (first column is 0)
- win_y: Y position of window in terminal (first line is 0)
- win_width: width of window, in chars
- win_height: height of window, in chars
- win_width_pct: percentage size, compared to parent window (for example 50 means half size)
- win_height_pct: percentage size, compared to parent window (for example 50 means half size)
- win_chat_x: X position of chat window in terminal (first column is 0)
- win_chat_y: Y position of chat window in terminal (first line is 0)
- win_chat_width: width of chat window, in chars
- win_chat_height: height of chat window, in chars
- first_line_displayed: 1 if first line of buffer is displayed on screen, otherwise 0
- scrolling: 1 if scroll is active on window (last line not displayed)
- lines_after: number of lines not displayed after last one displayed (when scrolling)

Return value:

integer value of property

C example:

weechat_printf (NULL, "current window is at position (x,y): (%d,%d)",
                weechat_window_get_integer (weechat_current_window (), "win_x"),
                weechat_window_get_integer (weechat_current_window (), "win_y"));

Script (Python):

# prototype
value = weechat.window_get_integer(window, property)

# example
weechat.prnt("", "current window is at position (x,y): (%d,%d)"
    % (weechat.window_get_integer(weechat.current_window(), "win_x"),
    weechat.window_get_integer(weechat.current_window(), "win_y")))

3.13.4. weechat_window_get_string

Return string value of a window property.

Note	This function is not used today, it is reserved for a future version.

Prototype:

int weechat_window_get_string (struct t_gui_window *window,
                               const char *property);

Arguments:

window: window pointer
property: property name

Return value:

string value of property

3.13.5. weechat_window_get_pointer

Return pointer value of a window property.

Prototype:

void *weechat_window_get_pointer (struct t_gui_window *window,
                                  const char *property);

Arguments:

window: window pointer
property: property name:
- current: current window pointer
- buffer: pointer to buffer displayed by window

Return value:

pointer value of property

C example:

weechat_printf (NULL,
                "buffer displayed in current window: %lx",
                weechat_window_get_pointer (weechat_current_window (), "buffer"));

Script (Python):

# prototype
value = weechat.window_get_pointer(window, property)

# example
weechat.prnt("", "buffer displayed in current window: %s"
    % weechat.window_get_pointer(weechat.current_window(), "buffer"))

3.13.6. weechat_window_set_title

Set title for terminal.

Prototype:

void weechat_window_set_title (const char *title);

Arguments:

title: new title for terminal (NULL to reset title)

C example:

weechat_window_set_title ("new title here");

Script (Python):

# prototype
weechat.window_set_title(window, title)

# example
weechat.window_set_title("new title here")

3.14. Nicklist

Functions for buffer nicklist.

3.14.1. weechat_nicklist_add_group

Add a group in a nicklist.

Prototype:

struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer,
                                                     struct t_gui_nick_group *parent_group,
                                                     const char *name,
                                                     const char *color,
                                                     int visible);

Arguments:

buffer: buffer pointer
parent_group: pointer to parent of group, NULL if group has no parent (nicklist root)
name: group name
color: color option name:
- WeeChat option name, for example weechat.color.nicklist_group
- color with optional background, for example yellow or yellow,red
- bar color name:
  - bar_fg: foreground color for bar
  - bar_delim: delimiters color for bar
  - bar_bg: background color for bar
visible:
- 1: group and sub-groups/nicks are visible
- 0: group and sub-groups/nicks are hidden

Note	The group name can begin with one or more digits, followed by pipe, and then group name. When such string is found at beginning, it’s used to sort groups in nicklist. For example groups "1\|test" and "2\|abc" will be displayed in that order: first "test" then "abc".

Return value:

pointer to new group, NULL if an error occurred

C example:

struct t_gui_nick_group *my_group =
    weechat_nicklist_add_group (my_buffer,
                                my_parent_group,
                                "test_group",
                                "weechat.color.nicklist_group",
                                1);

Script (Python):

# prototype
group = weechat.nicklist_add_group(buffer, parent_group, name, color, visible)

# example
group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group",
    "weechat.color.nicklist_group", 1)

3.14.2. weechat_nicklist_search_group

Search a group in a nicklist.

Prototype:

struct t_gui_nick_group *weechat_nicklist_search_group (struct t_gui_buffer *buffer,
                                                        struct t_gui_nick_group *from_group,
                                                        const char *name);

Arguments:

buffer: buffer pointer
from_group: search from this group only, if NULL, then search in whole nicklist
name: group name to search

Return value:

pointer to group found, NULL if not found

C example:

struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer,
                                                                    NULL, "test_group");

Script (Python):

# prototype
group = weechat.nicklist_search_group(buffer, from_group, name)

# example
group = weechat.nicklist_search_group(my_buffer, "", "test_group")

3.14.3. weechat_nicklist_add_nick

Add a nick in a group.

Prototype:

struct t_gui_nick_group *weechat_nicklist_add_nick (struct t_gui_buffer *buffer,
                                                    struct t_gui_nick_group *group,
                                                    const char *name,
                                                    const char *color,
                                                    const char *prefix,
                                                    const char *prefix_color,
                                                    int visible);

Arguments:

buffer: buffer pointer
group: group pointer
name: nick name
color: color option name:
- WeeChat option name (from weechat.color.xxx), for example chat_delimiters
- color with optional background, for example yellow or yellow,red
- bar color name:
  - bar_fg: foreground color for bar
  - bar_delim: delimiters color for bar
  - bar_bg: background color for bar
prefix: prefix displayed before nick
prefix_color: color option name:
- WeeChat option name (from weechat.color.xxx), for example chat_delimiters
- color with optional background, for example yellow or yellow,red
- bar color name:
  - bar_fg: foreground color for bar
  - bar_delim: delimiters color for bar
  - bar_bg: background color for bar
visible:
- 1: nick is visible
- 0: nick is hidden

Return value:

pointer to new nick, NULL if an error occurred

C example:

struct t_gui_nick *my_nick =
    weechat_nicklist_add_nick (my_buffer, my_group,
                               "test_nick",
                               (nick_away) ? "weechat.color.nicklist_away" : "bar_fg",
                               "@", "lightgreen",
                               1);

Script (Python):

# prototype
nick = weechat.nicklist_add_nick(buffer, group, name, color, prefix, prefix_color, visible)

# example
if nick_away:
    color = "weechat.color.nicklist_away"
else:
    color = "bar_fg"
nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)

3.14.4. weechat_nicklist_search_nick

Search a nick in a nicklist.

Prototype:

struct t_gui_nick *weechat_nicklist_search_nick (struct t_gui_buffer *buffer,
                                                 struct t_gui_nick_group *from_group,
                                                 const char *name);

Arguments:

buffer: buffer pointer
from_group: search from this group only, if NULL, then search in whole nicklist
name: nick name to search

Return value:

pointer to nick found, NULL if not found

C example:

struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer,
                                                            NULL, "test_nick");

Script (Python):

# prototype
nick = weechat.nicklist_search_nick(buffer, from_group, name)

# example
nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick")

3.14.5. weechat_nicklist_remove_group

Remove a group from a nicklist.

Prototype:

void weechat_nicklist_remove_group (struct t_gui_buffer *buffer,
                                    struct t_gui_nick_group *group);

Arguments:

buffer: buffer pointer
group: group pointer to remove (all sub-groups/nicks will be removed too)

C example:

weechat_nicklist_remove_group (my_buffer, my_group);

Script (Python):

# prototype
weechat.nicklist_remove_group(buffer, group)

# example
weechat.nicklist_remove_group(my_buffer, my_group)

3.14.6. weechat_nicklist_remove_nick

Remove a nick from a nicklist.

Prototype:

void weechat_nicklist_remove_nick (struct t_gui_buffer *buffer,
                                   struct t_gui_nick *nick);

Arguments:

buffer: buffer pointer
nick: nick pointer to remove

C example:

weechat_nicklist_remove_nick (my_buffer, my_nick);

Script (Python):

# prototype
weechat.nicklist_remove_nick(buffer, nick)

# example
weechat.nicklist_remove_nick(my_buffer, my_nick)

3.14.7. weechat_nicklist_remove_all

Remove all groups/nicks from a nicklist.

Prototype:

void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);

Arguments:

buffer: buffer pointer

C example:

weechat_nicklist_remove_all (my_buffer);

Script (Python):

# prototype
weechat.nicklist_remove_all(buffer)

# example
weechat.nicklist_remove_all(my_buffer)

3.14.8. weechat_nicklist_get_next_item

New in version 0.3.7.

Get next group or nick from nicklist (mainly used to display nicklist).

Prototype:

void weechat_nicklist_get_next_item (struct t_gui_buffer *buffer,
                                     struct t_gui_nick_group **group,
                                     struct t_gui_nick **nick);

Arguments:

buffer: buffer pointer
group: pointer on pointer to group
nick: pointer on pointer to nick

C example:

struct t_gui_nick_group *ptr_group;
struct t_gui_nick *ptr_nick;

ptr_group = NULL;
ptr_nick = NULL;
weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
while (ptr_group || ptr_nick)
{
    if (ptr_nick)
    {
        /* nick */
        /* ... */
    }
    else
    {
        /* group */
        /* ... */
    }
    weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
}

Note	This function is not available in scripting API.

3.14.9. weechat_nicklist_group_get_integer

New in version 0.3.4.

Return integer value of a group property.

Prototype:

int weechat_nicklist_group_get_integer (struct t_gui_buffer *buffer,
                                        struct t_gui_nick_group *group,
                                        const char *property);

Arguments:

buffer: buffer pointer
group: group pointer
property: property name:
- visible: 1 if group is visible, otherwise 0
- level: group level (root is 0)

Return value:

integer value of property

C example:

int visible = weechat_nicklist_group_get_integer (buffer, group, "visible");

Script (Python):

# prototype
value = weechat.nicklist_group_get_integer(buffer, group, property)

# example
visible = weechat.nicklist_group_get_integer(buffer, group, "visible")

3.14.10. weechat_nicklist_group_get_string

New in version 0.3.4.

Return string value of a group property.

Prototype:

const char *weechat_nicklist_group_get_string (struct t_gui_buffer *buffer,
                                               struct t_gui_nick_group *group,
                                               const char *property);

Arguments:

buffer: buffer pointer
group: group pointer
property: property name:
- name: name of group
- color: group color in nicklist

Return value:

string value of property

C example:

const char *color = weechat_nicklist_group_get_string (buffer, group, "color");

Script (Python):

# prototype
value = weechat.nicklist_group_get_string(buffer, group, property)

# example
color = weechat.nicklist_group_get_string(buffer, group, "color")

3.14.11. weechat_nicklist_group_get_pointer

New in version 0.3.4.

Return pointer value of a group property.

Prototype:

void *weechat_nicklist_group_get_pointer (struct t_gui_buffer *buffer,
                                          struct t_gui_nick_group *group,
                                          const char *property);

Arguments:

buffer: buffer pointer
group: group pointer
property: property name:
- parent: pointer to parent group

Return value:

pointer value of property

C example:

struct t_gui_nick_group *parent = weechat_nicklist_group_get_pointer (buffer, group, "parent");

Script (Python):

# prototype
value = weechat.nicklist_group_get_pointer(buffer, group, property)

# example
parent = weechat.nicklist_group_get_pointer(buffer, group, "parent")

3.14.12. weechat_nicklist_group_set

New in version 0.3.4.

Set string value of a group property.

Prototype:

void weechat_nicklist_group_set (struct t_gui_buffer *buffer,
                                 struct t_gui_nick_group *group,
                                 const char *property,
                                 const char *value);

Arguments:

buffer: buffer pointer
group: group pointer
property and value: property name, with its value:

Name	Value	Description
color	WeeChat color option name	See argument "color" of function weechat_nicklist_add_group
visible	"0", "1"	"0" = hidden group, "1" = visible group

C examples:

/* change group color to "bar_fg" */
weechat_nicklist_group_set (buffer, group, "color", "bar_fg");

/* change group color to yellow */
weechat_nicklist_group_set (buffer, group, "color", "yellow");

/* hide group in nicklist */
weechat_nicklist_group_set (buffer, group, "visible", "0");

Script (Python):

# prototype
weechat.nicklist_group_set(buffer, group, property, value)

# examples

# change group color to "bar_fg"
weechat.nicklist_group_set(buffer, group, "color", "bar_fg")

# change group color to yellow
weechat.nicklist_group_set(buffer, group, "color", "yellow")

# hide group in nicklist
weechat.nicklist_group_set(buffer, group, "visible", "0")

3.14.13. weechat_nicklist_nick_get_integer

New in version 0.3.4.

Return integer value of a nick property.

Prototype:

int weechat_nicklist_nick_get_integer (struct t_gui_buffer *buffer,
                                       struct t_gui_nick *nick,
                                       const char *property);

Arguments:

buffer: buffer pointer
nick: nick pointer
property: property name:
- visible: 1 if nick is visible, otherwise 0

Return value:

integer value of property

C example:

int visible = weechat_nicklist_nick_get_integer (buffer, nick, "visible");

Script (Python):

# prototype
value = weechat.nicklist_nick_get_integer(buffer, nick, property)

# example
visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible")

3.14.14. weechat_nicklist_nick_get_string

New in version 0.3.4.

Return string value of a nick property.

Prototype:

const char *weechat_nicklist_nick_get_string (struct t_gui_buffer *buffer,
                                              struct t_gui_nick *nick,
                                              const char *property);

Arguments:

buffer: buffer pointer
nick: nick pointer
property: property name:
- name: name of nick
- color: nick color in nicklist
- prefix: prefix of nick
- prefix_color: prefix color in nicklist

Return value:

string value of property

C example:

const char *color = weechat_nicklist_nick_get_string (buffer, nick, "color");

Script (Python):

# prototype
value = weechat.nicklist_nick_get_string(buffer, nick, property)

# example
color = weechat.nicklist_nick_get_string(buffer, nick, "color")

3.14.15. weechat_nicklist_nick_get_pointer

New in version 0.3.4.

Return pointer value of a nick property.

Prototype:

void *weechat_nicklist_nick_get_pointer (struct t_gui_buffer *buffer,
                                         struct t_gui_nick *nick,
                                         const char *property);

Arguments:

buffer: buffer pointer
nick: nick pointer
property: property name:
- group: pointer to group containing this nick

Return value:

pointer value of property

C example:

struct t_gui_nick_group *group = weechat_nicklist_nick_get_pointer (buffer, nick, "group");

Script (Python):

# prototype
value = weechat.nicklist_nick_get_pointer(buffer, nick, property)

# example
group = weechat.nicklist_nick_get_pointer(buffer, nick, "group")

3.14.16. weechat_nicklist_nick_set

New in version 0.3.4.

Set string value of a nick property.

Prototype:

void weechat_nicklist_nick_set (struct t_gui_buffer *buffer,
                                struct t_gui_nick *nick,
                                const char *property,
                                const char *value);

Arguments:

buffer: buffer pointer
nick: nick pointer
property and value: property name, with its value:

Name	Value	Description
color	WeeChat color option name	See argument "color" of function weechat_nicklist_add_nick
prefix	any string	Prefix of nick
prefix_color	WeeChat color option name	See argument "prefix_color" of function weechat_nicklist_add_nick
visible	"0", "1"	"0" = hidden nick, "1" = visible nick

C examples:

/* change nick color to cyan */
weechat_nicklist_nick_set (buffer, nick, "color", "cyan");

/* change prefix to "+" */
weechat_nicklist_nick_set (buffer, nick, "prefix", "+");

/* change prefix color to yellow */
weechat_nicklist_nick_set (buffer, nick, "prefix_color", "yellow");

/* hide nick in nicklist */
weechat_nicklist_nick_set (buffer, nick, "visible", "0");

Script (Python):

# prototype
weechat.nicklist_nick_set(buffer, nick, property, value)

# examples

# change nick color to cyan
weechat.nicklist_nick_set(buffer, nick, "color", "cyan")

# change prefix to "+"
weechat.nicklist_nick_set(buffer, nick, "prefix", "+")

# change prefix color to yellow
weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow")

# hide nick in nicklist
weechat.nicklist_nick_set(buffer, nick, "visible", "0")

3.15. Bars

Functions for bars.

3.15.1. weechat_bar_item_search

Search a bar item.

Prototype:

struct t_gui_bar_item *weechat_bar_item_search (const char *name);

Arguments:

name: bar item name

Return value:

pointer to bar item found, NULL if bar item was not found

C example:

struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");

Script (Python):

# prototype
bar_item = weechat.bar_item_search(name)

# example
bar_item = weechat.bar_item_search("myitem")

3.15.2. weechat_bar_item_new

Updated in version 0.4.2.

Create a new bar item.

Prototype:

struct t_gui_bar_item *weechat_bar_item_new (const char *name,
                                             char *(*build_callback)(void *data,
                                                                     struct t_gui_bar_item *item,
                                                                     struct t_gui_window *window,
                                                                     struct t_gui_buffer *buffer,
                                                                     struct t_hashtable *extra_info),
                                             void *build_callback_data);

Arguments:

name: bar item name
build_callback: function called when bar item is built, arguments and return value:
- void *data: pointer
- struct t_gui_bar_item *item: item pointer
- struct t_gui_window *window: window pointer (NULL when called for a root bar)
- struct t_gui_buffer *buffer: buffer displayed in window (if window is NULL, then it is current buffer) or buffer given in bar item with syntax: "@buffer:item" (new in version 0.4.2)
- struct t_hashtable *extra_info: always NULL (argument is reserved for a future version) (new in version 0.4.2)
- return value: content of bar item
build_callback_data: pointer given to build callback, when it is called by WeeChat

Return value:

pointer to new bar item, NULL if an error occurred

C example:

char *
my_build_callback (void *data,
                   struct t_gui_bar_item *item,
                   struct t_gui_window *window,
                   struct t_gui_buffer *buffer,
                   struct t_hashtable *extra_info)
{
    return strdup ("my content");
}

struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                       &my_build_callback,
                                                       NULL);

Script (Python):

Note	For compatibility with versions ≤ 0.4.1, the default callback has only 3 arguments: data, item and window (no buffer and extra_info). To use a callback with all arguments, you must add "(extra)" before the name, see example below.

# prototype
bar_item = weechat.bar_item_new(name, build_callback, build_callback_data)

# example (callback without "buffer" and "extra_info")
def my_build_callback(data, item, window):
    return "my content"

bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")

# example (callback with all arguments)
def my_build_callback2(data, item, window, buffer, extra_info):
    return "my content"

bar_item2 = weechat.bar_item_new("(extra)myitem2", "my_build_callback2", "")

3.15.3. weechat_bar_item_update

Update content of a bar item, by calling its build callback.

Prototype:

void weechat_bar_item_update (const char *name);

Arguments:

name: bar item name

C example:

weechat_bar_item_update ("myitem");

Script (Python):

# prototype
weechat.bar_item_update(name)

# example
weechat.bar_item_update("myitem")

3.15.4. weechat_bar_item_remove

Remove a bar item.

Prototype:

void weechat_bar_item_remove (struct t_gui_bar_item *item);

Arguments:

item: bar item pointer

C example:

weechat_bar_item_remove (&my_item);

Script (Python):

# prototype
weechat.bar_item_remove(item)

# example
weechat.bar_item_remove(myitem)

3.15.5. weechat_bar_search

Search a bar.

Prototype:

struct t_gui_bar *weechat_bar_search (const char *name);

Arguments:

name: bar name

Return value:

pointer to bar found, NULL if bar was not found

C example:

struct t_gui_bar *bar = weechat_bar_search ("mybar");

Script (Python):

# prototype
bar = weechat.bar_search(name)

# example
bar = weechat.bar_search("mybar")

3.15.6. weechat_bar_new

Create a new bar.

Prototype:

struct t_gui_bar *weechat_bar_new (const char *name,
                                   const char *hidden,
                                   const char *priority,
                                   const char *type,
                                   const char *condition,
                                   const char *position,
                                   const char *filling_top_bottom,
                                   const char *filling_left_right,
                                   const char *size,
                                   const char *size_max,
                                   const char *color_fg,
                                   const char *color_delim,
                                   const char *color_bg,
                                   const char *separator,
                                   const char *items);

Arguments:

name: bar name
hidden:
- on: bar is hidden
- off: bar is visible
priority: bar priority (integer)
type:
- root: bar displayed once, outside windows
- window: bar displayed in each window
condition: condition for displaying bar:
- active: bar is displayed in active window only
- inactive: bar is displayed in inactive windows only
- nicklist: bar is displayed in windows with nicklist
position: top, bottom, left or right
filling_top_bottom:
- horizontal: items are filled horizontally (space after each item)
- vertical: items are filled vertically (new line after each item)
- columns_horizontal: items are filled horizontally, displayed with columns
- columns_vertical: items are filled vertically, displayed with columns
filling_left_right:
- horizontal: items are filled horitontally (space after each item)
- vertical: items are filled verticaly (new line after each item)
- columns_horizontal: items are filled horizontally, displayed with columns
- columns_vertical: items are filled vertically, displayed with columns
size: bar size in chars (0 means automatic size)
size_max: max size for bar (0 means no max size)
color_fg: color for text in bar
color_delim: color for delimiters in bar
color_bg: background color for bar
separator:
- on: bar has separator line with other windows/bars
- off: no separator
items: list of items in bar, separated by comma (space between items), or "+" (glued items)

Return value:

pointer to new bar, NULL if an error occurred

C example:

struct t_gui_bar *my_bar = weechat_bar_new ("mybar",
                                            "off",
                                            "100",
                                            "window",
                                            "",
                                            "top",
                                            "horizontal",
                                            "vertical",
                                            "0",
                                            "5",
                                            "default",
                                            "cyan",
                                            "blue",
                                            "off",
                                            "time,buffer_number+buffer_name");

Script (Python):

# prototype
bar = weechat.bar_new(name, hidden, priority, type, condition, position,
    filling_top_bottom, filling_left_right, size, size_max,
    color_fg, color_delim, color_bg, separator, items)

# example
bar = weechat.bar_new("mybar", "off", "100", "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "off", "time,buffer_number+buffer_name")

3.15.7. weechat_bar_set

Set a new value for a bar property.

Prototype:

int weechat_bar_set (struct t_gui_bar *bar, const char *property,
                     const char *value);

Arguments:

bar: bar pointer
property: name, hidden, priority, conditions, position, filling_top_bottom, filling_left_right, size, size_max, color_fg, color_delim, color_bg, separator, items (see weechat_bar_new)
value: new value for property

Return value:

1 if new value was set, 0 if an error occurred

C example:

weechat_bar_set (mybar, "position", "bottom");

Script (Python):

# prototype
weechat.bar_set(bar, property, value)

# example
weechat.bar_set(my_bar, "position", "bottom")

3.15.8. weechat_bar_update

Refresh content of a bar on screen.

Prototype:

void weechat_bar_update (const char *name);

Arguments:

name: bar name

C example:

weechat_bar_update ("mybar");

Script (Python):

# prototype
weechat.bar_update(name)

# example
weechat.bar_update("mybar")

3.15.9. weechat_bar_remove

Remove a bar.

Prototype:

void weechat_bar_remove (struct t_gui_bar *bar);

Arguments:

bar: bar pointer

C example:

weechat_bar_remove (mybar);

Script (Python):

# prototype
weechat.bar_remove(bar)

# example
weechat.bar_remove(my_bar)

3.16. Commands

Functions for executing WeeChat commands.

3.16.1. weechat_command

Execute a command.

Prototype:

void weechat_command (struct t_gui_buffer *buffer, const char *command);

Arguments:

buffer: buffer pointer (command is executed on this buffer, use NULL for current buffer)
command: command to execute (if beginning with a "/"), or text to send to buffer

C example:

weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"),
                 "/whois FlashCode");

Script (Python):

# prototype
weechat.command(buffer, command)

# example
weechat.command(weechat.buffer_search("irc", "freenode.#weechat"), "/whois FlashCode")

3.17. Network

Network functions.

3.17.1. weechat_network_pass_proxy

Establish a connection/authentification to a proxy.

Important

This function is blocking on call to connect(), so it must be called in a forked process only, to not block WeeChat.

Prototype:

int weechat_network_pass_proxy (const char *proxy,
                                int sock,
                                const char *address,
                                int port);

Arguments:

proxy: proxy name to use
sock: socket to use
address: address (hostname or IP address)
port: port

Return value:

1 if connection is ok, 0 if an error occurred

C example:

if (weechat_network_pass_proxy ("my_proxy", sock, "irc.freenode.net", 6667))
{
    /* OK */
}
else
{
    /* error */
}

Note	This function is not available in scripting API.

3.17.2. weechat_network_connect_to

Establish a connection to a remote host.

Important

This function is blocking on call to connect(), so it must be called in a forked process only, to not block WeeChat.

Prototype:

int weechat_network_connect_to (const char *proxy,
                                int sock,
                                unsigned long address,
                                int port);

Arguments:

proxy: proxy name to use
sock: socket to use
address: address
port: port

Return value:

1 if connection is ok, 0 if an error occurred

C example:

struct sockaddr_in addr;
socklen_t length;
unsigned long address;

memset (&addr, 0, sizeof (struct sockaddr_in));
length = sizeof (addr);
getsockname (sock, (struct sockaddr *) &addr, &length);
addr.sin_family = AF_INET;
address = ntohl (addr.sin_addr.s_addr);

if (weechat_network_connect_to (NULL, sock, address, 6667))
{
    /* OK */
}
else
{
    /* error */
}

Note	This function is not available in scripting API.

3.18. Infos

Functions to get infos.

3.18.1. weechat_info_get

Return info, as string, from WeeChat or a plugin.

Prototype:

const char *weechat_info_get (const char *info_name, const char *arguments);

Arguments:

info_name: name of info to read:

Plugin	Name	Description	Arguments
aspell	aspell_dict	comma-separated list of dictionaries used in buffer	buffer pointer ("0x12345678") or buffer full name ("irc.freenode.#weechat")
fifo	fifo_filename	name of FIFO pipe	-
irc	irc_buffer	get buffer pointer for an IRC server/channel/nick	server,channel,nick (channel and nicks are optional)
irc	irc_is_channel	1 if string is a valid IRC channel name for server	server,channel (server is optional)
irc	irc_is_nick	1 if string is a valid IRC nick name	nickname
irc	irc_nick	get current nick on a server	server name
irc	irc_nick_color	get nick color code	nickname
irc	irc_nick_color_name	get nick color name	nickname
irc	irc_nick_from_host	get nick from IRC host	IRC host (like `:nick!name@server.com`)
irc	irc_server_isupport	1 if server supports this feature (from IRC message 005)	server,feature
irc	irc_server_isupport_value	value of feature, if supported by server (from IRC message 005)	server,feature
python	python2_bin	path to python 2.x interpreter	-
weechat	charset_internal	WeeChat internal charset	-
weechat	charset_terminal	terminal charset	-
weechat	cursor_mode	1 if cursor mode is enabled	-
weechat	date	WeeChat compilation date	-
weechat	dir_separator	directory separator	-
weechat	filters_enabled	1 if filters are enabled	-
weechat	inactivity	keyboard inactivity (seconds)	-
weechat	locale	locale used for translating messages	-
weechat	version	WeeChat version	-
weechat	version_git	WeeChat git version (output of command "git describe" for a development version only, empty for a stable release)	-
weechat	version_number	WeeChat version (as number)	-
weechat	weechat_dir	WeeChat directory	-
weechat	weechat_libdir	WeeChat "lib" directory	-
weechat	weechat_localedir	WeeChat "locale" directory	-
weechat	weechat_sharedir	WeeChat "share" directory	-
weechat	weechat_site	WeeChat site	-
weechat	weechat_site_download	WeeChat site, download page	-
weechat	weechat_upgrading	1 if WeeChat is upgrading (command `/upgrade`)	-

arguments: arguments for info asked (optional, NULL if no argument is needed)

Return value:

string with info asked, NULL if an error occurred

C example:

weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)",
                weechat_info_get ("version", NULL),
                weechat_info_get ("date", NULL));
weechat_printf (NULL, "WeeChat home is: %s",
                weechat_info_get ("weechat_dir", NULL));

Script (Python):

# prototype
value = weechat.info_get(info_name, arguments)

# example
weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)"
    % (weechat.info_get("version", ""), weechat.info_get("date", ""))
weechat.prnt("", "WeeChat home is: %s" % weechat.info_get("weechat_dir", ""))

3.18.2. weechat_info_get_hashtable

New in version 0.3.4.

Return info, as hashtable, from WeeChat or a plugin.

Prototype:

struct t_hashtable *weechat_info_get_hashtable (const char *info_name,
                                                struct t_hashtable *hashtable);

Arguments:

info_name: name of info to read:

Plugin	Name	Description	Hashtable (input)	Hashtable (output)
irc	irc_message_parse	parse an IRC message	"message": IRC message, "server": server name (optional)	"tags": tags, "message_without_tags": message without the tags, "nick": nick, "host": host, "command": command, "channel": channel, "arguments": arguments (includes channel)
irc	irc_message_split	split an IRC message (to fit in 512 bytes)	"message": IRC message, "server": server name (optional)	"msg1" … "msgN": messages to send (without final "\r\n"), "args1" … "argsN": arguments of messages, "count": number of messages

hashtable: hashtable with arguments (depends on info asked) (optional, NULL if no argument is needed)

Return value:

hashtable with info asked, NULL if an error occurred

C example:

struct t_hashtable *hashtable_in, *hashtable_out;

hashtable_in = weechat_hashtable_new (8,
                                      WEECHAT_HASHTABLE_STRING,
                                      WEECHAT_HASHTABLE_STRING,
                                      NULL,
                                      NULL);
if (hashtable_in)
{
    weechat_hashtable_set (hashtable_in, "message",
                           ":nick!user@host PRIVMSG #weechat :message here");
    hashtable_out = weechat_info_get_hashtable ("irc_message_parse",
                                                hashtable_in);
    /*
     * now hashtable_out has following keys/values:
     *   "nick"     : "nick"
     *   "host"     : "nick!user@host"
     *   "command"  : "PRIVMSG"
     *   "channel"  : "#weechat"
     *   "arguments": "#weechat :message here"
     */
    weechat_hashtable_free (hashtable_in);
    weechat_hashtable_free (hashtable_out);
}

Script (Python):

# prototype
dict = weechat.info_get_hashtable(info_name, dict_in)

# example
dict_in = { "message": ":nick!user@host PRIVMSG #weechat :message here" }
weechat.prnt("", "message parsed: %s"
             % weechat.info_get_hashtable("irc_message_parse", dict_in))

3.19. Infolists

An infolist is a list of "items". Each item contains variables.

For example, infolist "irc_server" has N items (N is number of IRC servers defined). For each item, there is variables like "name", "buffer", "is_connected", …

Each variable has a type and a value. Possible types are:

integer: any integer value
string: any string value
pointer: any pointer
buffer: buffer with fixed length, containing any data
time: time value

3.19.1. weechat_infolist_new

Create a new infolist.

Prototype:

struct t_infolist *weechat_infolist_new ();

Return value:

pointer to new infolist

C example:

struct t_infolist *infolist = weechat_infolist_new ();

Script (Python):

# prototype
infolist = weechat.infolist_new()

# example
infolist = weechat.infolist_new()

3.19.2. weechat_infolist_new_item

Add an item in an infolist.

Prototype:

struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

Return value:

pointer to new item

C example:

struct t_infolist_item *item = weechat_infolist_new_item (infolist);

Script (Python):

# prototype
item = weechat.infolist_new_item(infolist)

# example
item = weechat.infolist_new_item(infolist)

3.19.3. weechat_infolist_new_var_integer

Add an integer variable to an infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_new_var_integer (struct t_infolist_item *item,
                                                         const char *name,
                                                         int value);

Arguments:

item: infolist item pointer
name: variable name
value: integer value

Return value:

pointer to new variable

C example:

struct t_infolist_var *var = weechat_infolist_new_var_integer (item,
                                                               "my_integer",
                                                               123);

Script (Python):

# prototype
var = weechat.infolist_new_var_integer(item, name, value)

# example
var = weechat.infolist_new_var_integer(item, "my_integer", 123)

3.19.4. weechat_infolist_new_var_string

Add a string variable to an infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_new_var_string (struct t_infolist_item *item,
                                                        const char *name,
                                                        const char *value);

Arguments:

item: infolist item pointer
name: variable name
value: string value

Return value:

pointer to new variable

C example:

struct t_infolist_var *var = weechat_infolist_new_var_string (item,
                                                              "my_string",
                                                              "value");

Script (Python):

# prototype
var = weechat.infolist_new_var_string(item, name, value)

# example
var = weechat.infolist_new_var_string(item, "my_string", "value")

3.19.5. weechat_infolist_new_var_pointer

Add a pointer variable to an infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_new_var_pointer (struct t_infolist_item *item,
                                                         const char *name,
                                                         void *pointer);

Arguments:

item: infolist item pointer
name: variable name
pointer: pointer

Return value:

pointer to new variable

C example:

struct t_infolist_var *var = weechat_infolist_new_var_pointer (item,
                                                               "my_pointer",
                                                               &pointer);

Script (Python):

# prototype
var = weechat.infolist_new_var_pointer(item, name, pointer)

# example
var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer)

3.19.6. weechat_infolist_new_var_buffer

Add a buffer variable to an infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_new_var_buffer (struct t_infolist_item *item,
                                                        const char *name,
                                                        void *pointer,
                                                        int size);

Arguments:

item: infolist item pointer
name: variable name
pointer: pointer to buffer
size: size of buffer

Return value:

pointer to new variable

C example:

char buffer[256];
/* ... */
struct t_infolist_var *var = weechat_infolist_new_var_buffer (item,
                                                              "my_buffer",
                                                              &buffer,
                                                              sizeof (buffer));

Note	This function is not available in scripting API.

3.19.7. weechat_infolist_new_var_time

Add a time variable to an infolist item.

Prototype:

struct t_infolist_var *weechat_infolist_new_var_time (struct t_infolist_item *item,
                                                      const char *name,
                                                      time_t time);

Arguments:

item: infolist item pointer
name: variable name
time: time value

Return value:

pointer to new variable

C example:

struct t_infolist_var *var = weechat_infolist_new_var_time (item,
                                                            "my_time",
                                                            time (NULL));

Script (Python):

# prototype
var = weechat.infolist_new_var_time(item, name, time)

# example
var = weechat.infolist_new_var_time(item, "my_time", int(time.time()))

3.19.8. weechat_infolist_get

Return infolist from WeeChat or a plugin.

Important

Content of infolist is a duplication of actual data. So if you are asking infolist with lot of data (like "buffer_lines"), WeeChat will allocate memory to duplicate all data, and this can take some time.
Instead of using big infolist, it is preferable to use hdata (but infolist may have more info than hdata, which is raw data), see hdata.

Prototype:

struct t_infolist *weechat_infolist_get (const char *infolist_name,
                                         void *pointer,
                                         const char *arguments);

Arguments:

infolist_name: name of infolist to read:

Plugin	Name	Description	Pointer	Arguments
alias	alias	list of aliases	alias pointer (optional)	alias name (can start or end with "*" as wildcard) (optional)
guile	guile_script	list of scripts	script pointer (optional)	script name (can start or end with "*" as wildcard) (optional)
irc	irc_channel	list of channels for an IRC server	channel pointer (optional)	server,channel (channel is optional)
irc	irc_ignore	list of IRC ignores	ignore pointer (optional)	-
irc	irc_nick	list of nicks for an IRC channel	nick pointer (optional)	server,channel,nick (channel and nick are optional)
irc	irc_notify	list of notify	notify pointer (optional)	server name (can start or end with "*" as wildcard) (optional)
irc	irc_server	list of IRC servers	server pointer (optional)	server name (can start or end with "*" as wildcard) (optional)
logger	logger_buffer	list of logger buffers	logger pointer (optional)	-
lua	lua_script	list of scripts	script pointer (optional)	script name (can start or end with "*" as wildcard) (optional)
perl	perl_script	list of scripts	script pointer (optional)	script name (can start or end with "*" as wildcard) (optional)
python	python_script	list of scripts	script pointer (optional)	script name (can start or end with "*" as wildcard) (optional)
relay	relay	list of relay clients	relay pointer (optional)	-
rmodifier	rmodifier	list of rmodifiers	rmodifier pointer (optional)	rmodifier name (can start or end with "*" as joker) (optional)
ruby	ruby_script	list of scripts	script pointer (optional)	script name (can start or end with "*" as wildcard) (optional)
script	script_script	list of scripts	script pointer (optional)	script name with extension (can start or end with "*" as wildcard) (optional)
tcl	tcl_script	list of scripts	script pointer (optional)	script name (can start or end with "*" as wildcard) (optional)
weechat	bar	list of bars	bar pointer (optional)	bar name (can start or end with "*" as wildcard) (optional)
weechat	bar_item	list of bar items	bar item pointer (optional)	bar item name (can start or end with "*" as wildcard) (optional)
weechat	bar_window	list of bar windows	bar window pointer (optional)	-
weechat	buffer	list of buffers	buffer pointer (optional)	buffer name (can start or end with "*" as wildcard) (optional)
weechat	buffer_lines	lines of a buffer	buffer pointer	-
weechat	filter	list of filters	-	filter name (can start or end with "*" as wildcard) (optional)
weechat	history	history of commands	buffer pointer (if not set, return global history) (optional)	-
weechat	hook	list of hooks	hook pointer (optional)	type,arguments (type is command/timer/.., arguments to get only some hooks (can start or end with "*" as wildcard), both are optional)
weechat	hotlist	list of buffers in hotlist	-	-
weechat	key	list of key bindings	-	context ("default", "search", "cursor" or "mouse") (optional)
weechat	layout	list of layouts	-	-
weechat	nicklist	nicks in nicklist for a buffer	buffer pointer	nick_xxx or group_xxx to get only nick/group xxx (optional)
weechat	option	list of options	-	option name (can start or end with "*" as wildcard) (optional)
weechat	plugin	list of plugins	plugin pointer (optional)	plugin name (can start or end with "*" as wildcard) (optional)
weechat	proxy	list of proxies	proxy pointer (optional)	proxy name (can start or end with "*" as wildcard) (optional)
weechat	url_options	options for URL	-	-
weechat	window	list of windows	window pointer (optional)	"current" for current window or a window number (optional)
xfer	xfer	list of xfer	xfer pointer (optional)	-

pointer: pointer to an item, to get only this item in infolist (optional, can be NULL)
arguments: arguments for infolist asked (optional, NULL if no argument is needed)

Return value:

pointer to infolist, NULL if an error occurred

C example:

struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);

Script (Python):

# prototype
infolist = weechat.infolist_get(infolist_name, pointer, arguments)

# example
infolist = weechat.infolist_get("irc_server", "", "")

3.19.9. weechat_infolist_next

Move "cursor" to next item in an infolist. The first call to this function for an infolist moves cursor to first item in infolist.

Prototype:

int weechat_infolist_next (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

Return value:

1 if cursor has been moved on next item, 0 if end of list was reached

C example:

if (weechat_infolist_next (infolist))
{
    /* read variables in item... */
}
else
{
    /* no more item available */
}

Script (Python):

# prototype
rc = weechat.infolist_next(infolist)

# example
rc = weechat.infolist_next(infolist)
if rc:
    # read variables in item...
else:
    # no more item available

3.19.10. weechat_infolist_prev

Move "cursor" to previous item in an infolist. The first call to this function for an infolist moves cursor to last item in infolist.

Prototype:

int weechat_infolist_prev (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

Return value:

1 if cursor has been moved on previous item, 0 if beginning of list was reached

C example:

if (weechat_infolist_prev (infolist))
{
    /* read variables in item... */
}
else
{
    /* no more item available */
}

Script (Python):

# prototype
rc = weechat.infolist_prev(infolist)

# example
rc = weechat.infolist_prev(infolist)
if rc:
    # read variables in item...
else:
    # no more item available

3.19.11. weechat_infolist_reset_item_cursor

Reset "cursor" for infolist.

Prototype:

void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

C example:

weechat_infolist_reset_item_cursor (infolist);

Script (Python):

# prototype
weechat.infolist_reset_item_cursor(infolist)

# example
weechat.infolist_reset_item_cursor(infolist)

3.19.12. weechat_infolist_fields

Return list of fields for current infolist item.

Prototype:

const char *weechat_infolist_fields (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

Return value:

string with list of fields for current infolist item. List is comma separated, and contains letter for type, followed by variable name. Types are: "i" (integer), "s" (string), "p" (pointer), "b" (buffer), "t" (time).

C example:

const char *fields = weechat_infolist_fields (infolist);
/* fields contains something like:
   "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" */

Script (Python):

# prototype
fields = weechat.infolist_fields(infolist)

# example
fields = weechat.infolist_fields(infolist)
# fields contains something like:
# "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time"

3.19.13. weechat_infolist_integer

Return value of integer variable in current infolist item.

Prototype:

int weechat_infolist_integer (struct t_infolist *infolist, const char *var);

Arguments:

infolist: infolist pointer
var: variable name (must be type "integer")

Return value:

integer value of variable

C example:

weechat_printf (NULL, "integer = %d",
                weechat_infolist_integer (infolist, "my_integer"));

Script (Python):

# prototype
value = weechat.infolist_integer(infolist, var)

# example
weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer"))

3.19.14. weechat_infolist_string

Return value of string variable in current infolist item.

Prototype:

const char *weechat_infolist_string (struct t_infolist *infolist, const char *var);

Arguments:

infolist: infolist pointer
var: variable name (must be type "string")

Return value:

string value of variable

C example:

weechat_printf (NULL, "string = %s",
                weechat_infolist_string (infolist, "my_string"));

Script (Python):

# prototype
value = weechat.infolist_string(infolist, var)

# example
weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string"))

3.19.15. weechat_infolist_pointer

Return value of pointer variable in current infolist item.

Prototype:

void *weechat_infolist_pointer (struct t_infolist *infolist, const char *var);

Arguments:

infolist: infolist pointer
var: variable name (must be type "pointer")

Return value:

pointer value of variable

C example:

weechat_printf (NULL, "pointer = 0x%lx",
                weechat_infolist_pointer (infolist, "my_pointer"));

Script (Python):

# prototype
value = weechat.infolist_pointer(infolist, var)

# example
weechat.prnt("", "pointer = 0x%s" % weechat.infolist_pointer(infolist, "my_pointer"))

3.19.16. weechat_infolist_buffer

Return value of buffer variable in current infolist item.

Prototype:

void *weechat_infolist_buffer (struct t_infolist *infolist, const char *var,
                               int *size);

Arguments:

infolist: infolist pointer
var: variable name (must be type "buffer")
size: pointer to integer variable, will be set with buffer size

Return value:

buffer pointer

C example:

int size;
void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size);
weechat_printf (NULL, "buffer = 0x%lx, size = %d",
                pointer, size);

Note	This function is not available in scripting API.

3.19.17. weechat_infolist_time

Return value of time variable in current infolist item.

Prototype:

time_t weechat_infolist_time (struct t_infolist *infolist, const char *var);

Arguments:

infolist: infolist pointer
var: variable name (must be type "time")

Return value:

time value of variable

C example:

weechat_printf (NULL, "time = %ld",
                weechat_infolist_time (infolist, "my_time"));

Script (Python):

# prototype
value = weechat.infolist_time(infolist, var)

# example
weechat.prnt("", "time = %ld" % weechat.infolist_time(infolist, "my_time"))

3.19.18. weechat_infolist_free

Free an infolist.

Prototype:

void weechat_infolist_free (struct t_infolist *infolist);

Arguments:

infolist: infolist pointer

C example:

weechat_infolist_free (infolist);

Script (Python):

# prototype
weechat.infolist_free(infolist)

# example
weechat.infolist_free(infolist)

3.20. Hdata

Functions for hdata (raw access to WeeChat or plugins data).

Important

Hdata provides read-only access to data. It is STRICTLY FORBIDDEN to write something in memory pointed by hdata variables.

3.20.1. weechat_hdata_new

New in version 0.3.6, updated in 0.3.9 and 0.4.0.

Create a new hdata.

Note

hdata vs infolist

Hdata is a fast way to read WeeChat or plugins data. It is similar to infolist, but there are some differences:

it is faster and uses less memory: direct read of data without duplication
it may have different info than infolist: it contains only raw data in structures (infolist may add some extra data for convenience)

Prototype:

struct t_hdata *weechat_hdata_new (const char *hdata_name, const char *var_prev, const char *var_next,
                                   int create_allowed, int delete_allowed,
                                   int (*callback_update)(void *data,
                                                          struct t_hdata *hdata,
                                                          void *pointer,
                                                          struct t_hashtable *hashtable),
                                   void *callback_update_data);

Arguments:

hdata_name: name of hdata
var_prev: name of variable in structure which is a pointer to previous element in list (may be NULL if no such variable is available)
var_next: name of variable in structure which is a pointer to next element in list (may be NULL if no such variable is available)
create_allowed: 1 if create of structure is allowed, otherwise 0 (new in version 0.4.0)
delete_allowed: 1 if delete of structure is allowed, otherwise 0 (new in version 0.3.9)
callback_update: callback to update data in hdata, can be NULL if no update is allowed (new in version 0.3.9), arguments and return value:
- void *data: pointer
- struct t_hdata *hdata: pointer to hdata
- struct t_hashtable *hashtable: hashtable with variables to update (see weechat_hdata_update)
- return value: number of variables updated
callback_update_data: pointer given to update callback when it is called by WeeChat (new in version 0.3.9)

Return value:

pointer to new hdata

C example:

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next", 0, 0, &callback_update, NULL);

Note	This function is not available in scripting API.

3.20.2. weechat_hdata_new_var

New in version 0.3.6, updated in 0.3.9.

Create a new variable in hdata.

Prototype:

void weechat_hdata_new_var (struct t_hdata *hdata, const char *name, int offset, int type,
                            int update_allowed, const char *array_size, const char *hdata_name);

Arguments:

hdata: hdata pointer
name: variable name
offset: offset of variable in structure
type: variable type, one of:
- WEECHAT_HDATA_CHAR
- WEECHAT_HDATA_INTEGER
- WEECHAT_HDATA_LONG
- WEECHAT_HDATA_STRING
- WEECHAT_HDATA_POINTER
- WEECHAT_HDATA_TIME
- WEECHAT_HDATA_HASHTABLE
- WEECHAT_HDATA_OTHER
update_allowed: 1 if update of variable is allowed, otherwise 0 (new in version 0.3.9)
array_size: not NULL only if a variable is an array, and it can be: (new in version 0.3.9)
- name of variable in hdata: this variable will be used as size of array (dynamic size for array)
- integer (as string): fixed size for array
- *: automatic size: the size of array is computed by looking at values, when the first NULL is found (only for type string, pointer or hashtable)
hdata_name: name of a hdata (if it’s a pointer to a structure with hdata)

C example:

struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, 0, "tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, 0, "*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");

The macro "WEECHAT_HDATA_VAR" can be used to shorten code:

WEECHAT_HDATA_VAR(struct t_myplugin_list, name, STRING, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, buffer, POINTER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_count, INTEGER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_array, STRING, 0, "tags_count", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, string_split, STRING, 0, "*", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, prev, POINTER, 0, NULL, "myplugin_list");
WEECHAT_HDATA_VAR(struct t_myplugin_list, next, POINTER, 0, NULL, "myplugin_list");

Note	This function is not available in scripting API.

3.20.3. weechat_hdata_new_list

New in version 0.3.6.

Create a new list pointer in hdata.

Prototype:

void weechat_hdata_new_list (struct t_hdata *hdata, const char *name, void *pointer);

Arguments:

hdata: hdata pointer
name: variable name
pointer: list pointer

C example:

struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, "tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, "*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");

weechat_hdata_new_list (hdata, "buffers", &buffers);
weechat_hdata_new_list (hdata, "last_buffer", &last_buffer);

The macro "WEECHAT_HDATA_LIST" can be used to shorten code:

WEECHAT_HDATA_LIST(buffers);
WEECHAT_HDATA_LIST(last_buffer);

Note	This function is not available in scripting API.

3.20.4. weechat_hdata_get

New in version 0.3.6.

Return hdata for a WeeChat or plugin structure.

Note	Hdata does not contain data, it’s only a hashtable with position of variables in structure. That means you will need this hdata and a pointer to a WeeChat/plugin object to read some data.

Prototype:

struct t_hdata *weechat_hdata_get (const char *hdata_name);

Arguments:

hdata_name: name of hdata:

Plugin	Name	Description	Variables	Update allowed	Lists
guile	guile_callback	callback of a script	script (pointer, hdata: "guile_script") function (string) data (string) config_file (pointer, hdata: "config_file") config_section (pointer, hdata: "config_section") config_option (pointer, hdata: "config_option") hook (pointer) buffer (pointer, hdata: "buffer") bar_item (pointer, hdata: "bar_item") upgrade_file (pointer) prev_callback (pointer, hdata: "guile_callback") next_callback (pointer, hdata: "guile_callback")		-
guile	guile_script	list of scripts	filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) callbacks (pointer, hdata: "guile_callback") unloading (integer) prev_script (pointer, hdata: "guile_script") next_script (pointer, hdata: "guile_script")		last_script scripts
irc	irc_channel	irc channel	type (integer) name (string) topic (string) modes (string) limit (integer) key (string) join_msg_received (hashtable) checking_away (integer) away_message (string) has_quit_server (integer) cycle (integer) part (integer) nick_completion_reset (integer) pv_remote_nick_color (string) hook_autorejoin (pointer) nicks_count (integer) nicks (pointer, hdata: "irc_nick") last_nick (pointer, hdata: "irc_nick") nicks_speaking (pointer) nicks_speaking_time (pointer, hdata: "irc_channel_speaking") last_nick_speaking_time (pointer, hdata: "irc_channel_speaking") join_smart_filtered (hashtable) buffer (pointer, hdata: "buffer") buffer_as_string (string) prev_channel (pointer, hdata: "irc_channel") next_channel (pointer, hdata: "irc_channel")		-
irc	irc_channel_speaking	irc channel_speaking	nick (string) time_last_message (time) prev_nick (pointer, hdata: "irc_channel_speaking") next_nick (pointer, hdata: "irc_channel_speaking")		-
irc	irc_ignore	irc ignore	number (integer) mask (string) regex_mask (pointer) server (string) channel (string) prev_ignore (pointer, hdata: "irc_ignore") next_ignore (pointer, hdata: "irc_ignore")		irc_ignore_list last_irc_ignore
irc	irc_nick	irc nick	name (string) host (string) prefixes (string) prefix (string) away (integer) color (string) prev_nick (pointer, hdata: "irc_nick") next_nick (pointer, hdata: "irc_nick")		-
irc	irc_notify	irc notify	server (pointer, hdata: "irc_server") nick (string) check_away (integer) is_on_server (integer) away_message (string) ison_received (integer) prev_notify (pointer, hdata: "irc_notify") next_notify (pointer, hdata: "irc_notify")		-
irc	irc_redirect	irc redirect	server (pointer, hdata: "irc_server") pattern (string) signal (string) count (integer) current_count (integer) string (string) timeout (integer) command (string) assigned_to_command (integer) start_time (time) cmd_start (hashtable) cmd_stop (hashtable) cmd_extra (hashtable) cmd_start_received (integer) cmd_stop_received (integer) cmd_filter (hashtable) output (string) output_size (integer) prev_redirect (pointer, hdata: "irc_redirect") next_redirect (pointer, hdata: "irc_redirect")		-
irc	irc_redirect_pattern	pattern for irc redirect	name (string) temp_pattern (integer) timeout (integer) cmd_start (string) cmd_stop (string) cmd_extra (string) prev_redirect (pointer, hdata: "irc_redirect_pattern") next_redirect (pointer, hdata: "irc_redirect_pattern")		irc_redirect_patterns last_irc_redirect_pattern
irc	irc_server	irc server	name (string) options (pointer) temp_server (integer) reloading_from_config (integer) reloaded_from_config (integer) addresses_count (integer) addresses_array (string, array_size: "addresses_count") ports_array (integer, array_size: "addresses_count") retry_array (integer, array_size: "addresses_count") index_current_address (integer) current_address (string) current_ip (string) current_port (integer) current_retry (integer) sock (integer) hook_connect (pointer, hdata: "hook") hook_fd (pointer, hdata: "hook") hook_timer_connection (pointer, hdata: "hook") hook_timer_sasl (pointer, hdata: "hook") is_connected (integer) ssl_connected (integer) disconnected (integer) gnutls_sess (other) tls_cert (other) tls_cert_key (other) unterminated_message (string) nicks_count (integer) nicks_array (string, array_size: "nicks_count") nick_first_tried (integer) nick_alternate_number (integer) nick (string) nick_modes (string) isupport (string) prefix_modes (string) prefix_chars (string) nick_max_length (integer) casemapping (integer) chantypes (string) chanmodes (string) reconnect_delay (integer) reconnect_start (time) command_time (time) reconnect_join (integer) disable_autojoin (integer) is_away (integer) away_message (string) away_time (time) lag (integer) lag_check_time (other) lag_next_check (time) lag_last_refresh (time) cmd_list_regexp (pointer) last_user_message (time) last_away_check (time) last_data_purge (time) outqueue (pointer) last_outqueue (pointer) redirects (pointer, hdata: "irc_redirect") last_redirect (pointer, hdata: "irc_redirect") notify_list (pointer, hdata: "irc_notify") last_notify (pointer, hdata: "irc_notify") join_manual (hashtable) join_channel_key (hashtable) join_noswitch (hashtable) buffer (pointer, hdata: "buffer") buffer_as_string (string) channels (pointer, hdata: "irc_channel") last_channel (pointer, hdata: "irc_channel") prev_server (pointer, hdata: "irc_server") next_server (pointer, hdata: "irc_server")		irc_servers last_irc_server
lua	lua_callback	callback of a script	script (pointer, hdata: "lua_script") function (string) data (string) config_file (pointer, hdata: "config_file") config_section (pointer, hdata: "config_section") config_option (pointer, hdata: "config_option") hook (pointer) buffer (pointer, hdata: "buffer") bar_item (pointer, hdata: "bar_item") upgrade_file (pointer) prev_callback (pointer, hdata: "lua_callback") next_callback (pointer, hdata: "lua_callback")		-
lua	lua_script	list of scripts	filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) callbacks (pointer, hdata: "lua_callback") unloading (integer) prev_script (pointer, hdata: "lua_script") next_script (pointer, hdata: "lua_script")		last_script scripts
perl	perl_callback	callback of a script	script (pointer, hdata: "perl_script") function (string) data (string) config_file (pointer, hdata: "config_file") config_section (pointer, hdata: "config_section") config_option (pointer, hdata: "config_option") hook (pointer) buffer (pointer, hdata: "buffer") bar_item (pointer, hdata: "bar_item") upgrade_file (pointer) prev_callback (pointer, hdata: "perl_callback") next_callback (pointer, hdata: "perl_callback")		-
perl	perl_script	list of scripts	filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) callbacks (pointer, hdata: "perl_callback") unloading (integer) prev_script (pointer, hdata: "perl_script") next_script (pointer, hdata: "perl_script")		last_script scripts
python	python_callback	callback of a script	script (pointer, hdata: "python_script") function (string) data (string) config_file (pointer, hdata: "config_file") config_section (pointer, hdata: "config_section") config_option (pointer, hdata: "config_option") hook (pointer) buffer (pointer, hdata: "buffer") bar_item (pointer, hdata: "bar_item") upgrade_file (pointer) prev_callback (pointer, hdata: "python_callback") next_callback (pointer, hdata: "python_callback")		-
python	python_script	list of scripts	filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) callbacks (pointer, hdata: "python_callback") unloading (integer) prev_script (pointer, hdata: "python_script") next_script (pointer, hdata: "python_script")		last_script scripts
ruby	ruby_callback	callback of a script	script (pointer, hdata: "ruby_script") function (string) data (string) config_file (pointer, hdata: "config_file") config_section (pointer, hdata: "config_section") config_option (pointer, hdata: "config_option") hook (pointer) buffer (pointer, hdata: "buffer") bar_item (pointer, hdata: "bar_item") upgrade_file (pointer) prev_callback (pointer, hdata: "ruby_callback") next_callback (pointer, hdata: "ruby_callback")		-
ruby	ruby_script	list of scripts	filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) callbacks (pointer, hdata: "ruby_callback") unloading (integer) prev_script (pointer, hdata: "ruby_script") next_script (pointer, hdata: "ruby_script")		last_script scripts
script	script_script	scripts from repository	name (string) name_with_extension (string) language (integer) author (string) mail (string) version (string) license (string) description (string) tags (string) requirements (string) min_weechat (string) max_weechat (string) md5sum (string) url (string) popularity (integer) date_added (time) date_updated (time) status (integer) version_loaded (string) displayed (integer) install_order (integer) prev_script (pointer, hdata: "script_script") next_script (pointer, hdata: "script_script")		last_script_repo scripts_repo
tcl	tcl_callback	callback of a script	script (pointer, hdata: "tcl_script") function (string) data (string) config_file (pointer, hdata: "config_file") config_section (pointer, hdata: "config_section") config_option (pointer, hdata: "config_option") hook (pointer) buffer (pointer, hdata: "buffer") bar_item (pointer, hdata: "bar_item") upgrade_file (pointer) prev_callback (pointer, hdata: "tcl_callback") next_callback (pointer, hdata: "tcl_callback")		-
tcl	tcl_script	list of scripts	filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) callbacks (pointer, hdata: "tcl_callback") unloading (integer) prev_script (pointer, hdata: "tcl_script") next_script (pointer, hdata: "tcl_script")		last_script scripts
weechat	bar	bar	name (string) options (pointer) items_count (integer) items_subcount (pointer) items_array (pointer) items_buffer (pointer) items_prefix (pointer) items_name (pointer) items_suffix (pointer) bar_window (pointer, hdata: "bar_window") bar_refresh_needed (integer) prev_bar (pointer, hdata: "bar") next_bar (pointer, hdata: "bar")		gui_bars last_gui_bar
weechat	bar_item	bar item	plugin (pointer, hdata: "plugin") name (string) build_callback (pointer) build_callback_data (pointer) prev_item (pointer, hdata: "bar_item") next_item (pointer, hdata: "bar_item")		gui_bar_items last_gui_bar_item
weechat	bar_window	bar window	bar (pointer, hdata: "bar") x (integer) y (integer) width (integer) height (integer) scroll_x (integer) scroll_y (integer) cursor_x (integer) cursor_y (integer) current_size (integer) items_count (integer) items_subcount (pointer) items_content (pointer) items_num_lines (pointer) items_refresh_needed (pointer) screen_col_size (integer) screen_lines (integer) coords_count (integer) coords (pointer) gui_objects (pointer) prev_bar_window (pointer, hdata: "bar_window") next_bar_window (pointer, hdata: "bar_window")		-
weechat	buffer	buffer	plugin (pointer, hdata: "plugin") plugin_name_for_upgrade (string) number (integer) layout_number (integer) layout_number_merge_order (integer) name (string) full_name (string) short_name (string) type (integer) notify (integer) num_displayed (integer) active (integer) print_hooks_enabled (integer) close_callback (pointer) close_callback_data (pointer) title (string) own_lines (pointer, hdata: "lines") mixed_lines (pointer, hdata: "lines") lines (pointer, hdata: "lines") time_for_each_line (integer) chat_refresh_needed (integer) nicklist (integer) nicklist_case_sensitive (integer) nicklist_root (pointer, hdata: "nick_group") nicklist_max_length (integer) nicklist_display_groups (integer) nicklist_count (integer) nicklist_groups_count (integer) nicklist_nicks_count (integer) nicklist_visible_count (integer) nickcmp_callback (pointer) nickcmp_callback_data (pointer) input (integer) input_callback (pointer) input_callback_data (pointer) input_get_unknown_commands (integer) input_buffer (string) input_buffer_alloc (integer) input_buffer_size (integer) input_buffer_length (integer) input_buffer_pos (integer) input_buffer_1st_display (integer) input_undo_snap (pointer, hdata: "input_undo") input_undo (pointer, hdata: "input_undo") last_input_undo (pointer, hdata: "input_undo") ptr_input_undo (pointer, hdata: "input_undo") input_undo_count (integer) completion (pointer, hdata: "completion") history (pointer, hdata: "history") last_history (pointer, hdata: "history") ptr_history (pointer, hdata: "history") num_history (integer) text_search (integer) text_search_exact (integer) text_search_regex (integer) text_search_regex_compiled (pointer) text_search_where (integer) text_search_found (integer) text_search_input (string) highlight_words (string) highlight_regex (string) highlight_regex_compiled (pointer) highlight_tags (string) highlight_tags_count (integer) highlight_tags_array (string, array_size: "highlight_tags_count") hotlist_max_level_nicks (hashtable) keys (pointer, hdata: "key") last_key (pointer, hdata: "key") keys_count (integer) local_variables (hashtable) prev_buffer (pointer, hdata: "buffer") next_buffer (pointer, hdata: "buffer")		gui_buffer_last_displayed gui_buffers last_gui_buffer
weechat	completion	structure with completion	buffer (pointer, hdata: "buffer") context (integer) base_command (string) base_command_arg_index (integer) base_word (string) base_word_pos (integer) position (integer) args (string) direction (integer) add_space (integer) force_partial_completion (integer) completion_list (pointer) word_found (string) word_found_is_nick (integer) position_replace (integer) diff_size (integer) diff_length (integer) partial_completion_list (pointer, hdata: "completion_partial") last_partial_completion (pointer, hdata: "completion_partial")		-
weechat	completion_partial	structure with partial completion	word (string) count (integer) prev_item (pointer, hdata: "completion_partial") next_item (pointer, hdata: "completion_partial")		-
weechat	config_file	config file	plugin (pointer, hdata: "plugin") name (string) filename (string) file (pointer) callback_reload (pointer) callback_reload_data (pointer) sections (pointer, hdata: "config_section") last_section (pointer, hdata: "config_section") prev_config (pointer, hdata: "config_file") next_config (pointer, hdata: "config_file")		config_files last_config_file
weechat	config_option	config option	config_file (pointer, hdata: "config_file") section (pointer, hdata: "config_section") name (string) type (integer) description (string) string_values (string, array_size: "") min* (integer) max (integer) default_value (pointer) value (pointer) null_value_allowed (integer) callback_check_value (pointer) callback_check_value_data (pointer) callback_change (pointer) callback_change_data (pointer) callback_delete (pointer) callback_delete_data (pointer) loaded (integer) prev_option (pointer, hdata: "config_option") next_option (pointer, hdata: "config_option")		-
weechat	config_section	config section	config_file (pointer, hdata: "config_file") name (string) user_can_add_options (integer) user_can_delete_options (integer) callback_read (pointer) callback_read_data (pointer) callback_write (pointer) callback_write_data (pointer) callback_write_default (pointer) callback_write_default_data (pointer) callback_create_option (pointer) callback_create_option_data (pointer) callback_delete_option (pointer) callback_delete_option_data (pointer) options (pointer, hdata: "config_option") last_option (pointer, hdata: "config_option") prev_section (pointer, hdata: "config_section") next_section (pointer, hdata: "config_section")		-
weechat	filter	filter	enabled (integer) name (string) buffer_name (string) num_buffers (integer) buffers (pointer) tags (string) tags_count (integer) tags_array (string, array_size: "tags_count") regex (string) regex_prefix (pointer) regex_message (pointer) prev_filter (pointer, hdata: "filter") next_filter (pointer, hdata: "filter")		gui_filters last_gui_filter
weechat	history	history of commands in buffer	text (string) next_history (pointer, hdata: "history") prev_history (pointer, hdata: "history")	`__create` `__delete`	gui_history last_gui_history
weechat	hotlist	hotlist	priority (integer) creation_time.tv_sec (time) creation_time.tv_usec (long) buffer (pointer) count (integer, array_size: "4") prev_hotlist (pointer, hdata: "hotlist") next_hotlist (pointer, hdata: "hotlist")		gui_hotlist last_gui_hotlist
weechat	input_undo	structure with undo for input line	data (string) pos (integer) prev_undo (pointer, hdata: "input_undo") next_undo (pointer, hdata: "input_undo")		-
weechat	key	a key (keyboard shortcut)	key (string) area_type (pointer) area_name (pointer) area_key (string) command (string) score (integer) prev_key (pointer, hdata: "key") next_key (pointer, hdata: "key")		gui_default_keys gui_default_keys_cursor gui_default_keys_mouse gui_default_keys_search gui_keys gui_keys_cursor gui_keys_mouse gui_keys_search last_gui_default_key last_gui_default_key_cursor last_gui_default_key_mouse last_gui_default_key_search last_gui_key last_gui_key_cursor last_gui_key_mouse last_gui_key_search
weechat	layout	layout	name (string) layout_buffers (pointer, hdata: "layout_buffer") last_layout_buffer (pointer, hdata: "layout_buffer") layout_windows (pointer, hdata: "layout_window") internal_id (integer) internal_id_current_window (integer) prev_layout (pointer, hdata: "layout") next_layout (pointer, hdata: "layout")		gui_layout_current gui_layouts last_gui_layout
weechat	layout_buffer	buffer layout	plugin_name (string) buffer_name (string) number (integer) prev_layout (pointer, hdata: "layout_buffer") next_layout (pointer, hdata: "layout_buffer")		-
weechat	layout_window	window layout	internal_id (integer) parent_node (pointer, hdata: "layout_window") split_pct (integer) split_horiz (integer) child1 (pointer, hdata: "layout_window") child2 (pointer, hdata: "layout_window") plugin_name (string) buffer_name (string)		-
weechat	line	structure with one line	data (pointer, hdata: "line_data") prev_line (pointer, hdata: "line") next_line (pointer, hdata: "line")		-
weechat	line_data	structure with one line data	buffer (pointer, hdata: "buffer") y (integer) date (time) date_printed (time) str_time (string) tags_count (integer) tags_array (string, array_size: "tags_count") displayed (char) highlight (char) refresh_needed (char) prefix (string) prefix_length (integer) message (string)	date (time) date_printed (time) tags_array (string) prefix (string) message (string)	-
weechat	lines	structure with lines	first_line (pointer, hdata: "line") last_line (pointer, hdata: "line") last_read_line (pointer, hdata: "line") lines_count (integer) first_line_not_read (integer) lines_hidden (integer) buffer_max_length (integer) buffer_max_length_refresh (integer) prefix_max_length (integer) prefix_max_length_refresh (integer)		-
weechat	nick	nick in nicklist	group (pointer, hdata: "nick_group") name (string) color (string) prefix (string) prefix_color (string) visible (integer) prev_nick (pointer, hdata: "nick") next_nick (pointer, hdata: "nick")		-
weechat	nick_group	group in nicklist	name (string) color (string) visible (integer) level (integer) parent (pointer, hdata: "nick_group") children (pointer, hdata: "nick_group") last_child (pointer, hdata: "nick_group") nicks (pointer, hdata: "nick") last_nick (pointer, hdata: "nick") prev_group (pointer, hdata: "nick_group") next_group (pointer, hdata: "nick_group")		-
weechat	plugin	plugin	filename (string) handle (pointer) name (string) description (string) author (string) version (string) license (string) charset (string) debug (integer) prev_plugin (pointer, hdata: "plugin") next_plugin (pointer, hdata: "plugin")		last_weechat_plugin weechat_plugins
weechat	proxy	proxy	name (string) options (pointer) prev_proxy (pointer, hdata: "proxy") next_proxy (pointer, hdata: "proxy")		last_weechat_proxy weechat_proxies
weechat	window	window	number (integer) win_x (integer) win_y (integer) win_width (integer) win_height (integer) win_width_pct (integer) win_height_pct (integer) win_chat_x (integer) win_chat_y (integer) win_chat_width (integer) win_chat_height (integer) win_chat_cursor_x (integer) win_chat_cursor_y (integer) bar_windows (pointer, hdata: "bar_window") last_bar_window (pointer, hdata: "bar_window") refresh_needed (integer) gui_objects (pointer) buffer (pointer, hdata: "buffer") layout_plugin_name (string) layout_buffer_name (string) scroll (pointer, hdata: "window_scroll") ptr_tree (pointer, hdata: "window_tree") prev_window (pointer, hdata: "window") next_window (pointer, hdata: "window")		gui_current_window gui_windows last_gui_window
weechat	window_scroll	scroll info in window	buffer (pointer, hdata: "buffer") first_line_displayed (integer) start_line (pointer, hdata: "line") start_line_pos (integer) scrolling (integer) start_col (integer) lines_after (integer) prev_scroll (pointer, hdata: "window_scroll") next_scroll (pointer, hdata: "window_scroll")		-
weechat	window_tree	tree of windows	parent_node (pointer, hdata: "window_tree") split_pct (integer) split_horizontal (integer) child1 (pointer, hdata: "window_tree") child2 (pointer, hdata: "window_tree") window (pointer, hdata: "window")		gui_windows_tree

Return value:

pointer to hdata, NULL if an error occurred

C example:

struct t_hdata *hdata = weechat_hdata_get ("irc_server");

Script (Python):

# prototype
hdata = weechat.hdata_get(hdata_name)

# example
hdata = weechat.hdata_get("irc_server")

3.20.5. weechat_hdata_get_var_offset

New in version 0.3.6.

Return offset of variable in hdata.

Prototype:

int weechat_hdata_get_var_offset (struct t_hdata *hdata, const char *name);

Arguments:

hdata: hdata pointer
name: variable name

Return value:

variable offset, 0 if an error occurred

C example:

int offset = weechat_hdata_get_var_offset (hdata, "name");

Script (Python):

# prototype
offset = weechat.hdata_get_var_offset(hdata, name)

# example
offset = weechat.hdata_get_var_offset(hdata, "name")

3.20.6. weechat_hdata_get_var_type

New in version 0.3.6.

Return type of variable in hdata (as integer).

Prototype:

int weechat_hdata_get_var_type (struct t_hdata *hdata, const char *name);

Arguments:

hdata: hdata pointer
name: variable name

Return value:

variable type, -1 if an error occurred

C example:

int type = weechat_hdata_get_var_type (hdata, "name");
switch (type)
{
    case WEECHAT_HDATA_CHAR:
        /* ... */
        break;
    case WEECHAT_HDATA_INTEGER:
        /* ... */
        break;
    case WEECHAT_HDATA_LONG:
        /* ... */
        break;
    case WEECHAT_HDATA_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_POINTER:
        /* ... */
        break;
    case WEECHAT_HDATA_TIME:
        /* ... */
        break;
    case WEECHAT_HDATA_HASHTABLE:
        /* ... */
        break;
    case WEECHAT_HDATA_OTHER:
        /* ... */
        break;
    default:
        /* variable not found */
        break;
}

Note	This function is not available in scripting API.

3.20.7. weechat_hdata_get_var_type_string

New in version 0.3.6.

Return type of variable in hdata (as string).

Prototype:

const char *weechat_hdata_get_var_type_string (struct t_hdata *hdata, const char *name);

Arguments:

hdata: hdata pointer
name: variable name

Return value:

variable type, NULL if an error occurred

C example:

weechat_printf (NULL, "type = %s", weechat_hdata_get_var_type_string (hdata, "name"));

Script (Python):

# prototype
type = weechat.hdata_get_var_type_string(hdata, name)

# example
weechat.prnt("", "type = %s" % weechat.hdata_get_var_type_string("name"))

3.20.8. weechat_hdata_get_var_array_size

New in version 0.3.9.

Return array size for variable in hdata.

Prototype:

int weechat_hdata_get_var_array_size (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name

Return value:

array size for variable, -1 if variable is not an array or if an error occurred

C example:

int array_size = weechat_hdata_get_var_array_size (hdata, pointer, "name");

Script (Python):

# prototype
array_size = weechat.hdata_get_var_array_size(hdata, pointer, name)

# example
array_size = weechat.hdata_get_var_array_size(hdata, pointer, "name")

3.20.9. weechat_hdata_get_var_array_size_string

New in version 0.3.9.

Return array size for variable in hdata (as string).

Prototype:

const char *weechat_hdata_get_var_array_size_string (struct t_hdata *hdata, void *pointer,
                                                     const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name

Return value:

array size for variable as string, NULL if variable is not an array or if an error occurred

C example:

const char *array_size = weechat_hdata_get_var_array_size_string (hdata, pointer, "name");

Script (Python):

# prototype
array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, name)

# example
array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, "name")

3.20.10. weechat_hdata_get_var_hdata

New in version 0.3.6.

Return hdata for a variable in hdata.

Prototype:

const char *weechat_hdata_get_var_hdata (struct t_hdata *hdata, const char *name);

Arguments:

hdata: hdata pointer
name: variable name

Return value:

hdata for variable, NULL if no hdata or if an error occurred

C example:

weechat_printf (NULL, "hdata = %s", weechat_hdata_get_var_hdata (hdata, "name"));

Script (Python):

# prototype
hdata_name = weechat.hdata_get_var_hdata(hdata, name)

# example
weechat.prnt("", "hdata = %s" % weechat.hdata_get_var_hdata(hdata, "name"))

3.20.11. weechat_hdata_get_var

New in version 0.3.6.

Return pointer to content of variable in hdata.

Prototype:

void *weechat_hdata_get_var (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name

Return value:

pointer to content of variable, NULL if an error occurred

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
void *pointer = weechat_hdata_get_var (hdata, buffer, "name");

Note	This function is not available in scripting API.

3.20.12. weechat_hdata_get_var_at_offset

New in version 0.3.6.

Return pointer to content of variable in hdata, using offset.

Prototype:

void *weechat_hdata_get_var_at_offset (struct t_hdata *hdata, void *pointer, int offset);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
offset: offset of variable

Return value:

pointer to content of variable, NULL if an error occurred

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
int offset = weechat_hdata_get_var_offset (hdata, "name");
void *pointer = weechat_hdata_get_var_at_offset (hdata, buffer, offset);

Note	This function is not available in scripting API.

3.20.13. weechat_hdata_get_list

New in version 0.3.6.

Return list pointer from hdata.

Prototype:

void *weechat_hdata_get_list (struct t_hdata *hdata, const char *name);

Arguments:

hdata: hdata pointer
name: list name

Return value:

list pointer, NULL if an error occurred

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffers = weechat_hdata_get_list (hdata, "gui_buffers");

Script (Python):

# prototype
list = weechat.hdata_get_list(hdata, name)

# example
hdata = weechat.hdata_get("buffer")
buffers = weechat.hdata_get_list(hdata, "gui_buffers")

3.20.14. weechat_hdata_check_pointer

New in version 0.3.7.

Check if a pointer is valid for a hdata and a list pointer.

Prototype:

int weechat_hdata_check_pointer (struct t_hdata *hdata, void *list, void *pointer);

Arguments:

hdata: hdata pointer
list: list pointer
pointer: pointer to check

Return value:

1 if pointer is in list, 0 if not found

C example:

/* check if a buffer pointer is valid */
struct t_hdata *hdata = weechat_hdata_get ("buffer");
if (weechat_hdata_check_pointer (hdata,
                                 weechat_hdata_get_list (hdata, "gui_buffers"),
                                 ptr_buffer))
{
    /* valid pointer */
}
else
{
    /* invalid pointer */
}

Script (Python):

# prototype
rc = weechat.hdata_check_pointer(hdata, list, pointer)

# example
hdata = weechat.hdata_get("buffer")
if weechat.hdata_check_pointer(hdata, weechat.hdata_get_list(hdata, "gui_buffers"), ptr_buffer):
    # valid pointer
    # ...
else:
    # invalid pointer
    # ...

3.20.15. weechat_hdata_move

New in version 0.3.6.

Move pointer to another element in list.

Prototype:

void *weechat_hdata_move (struct t_hdata *hdata, void *pointer, int count);

Arguments:

hdata: hdata pointer
pointer: pointer to a WeeChat/plugin object
count: number of jump(s) to execute (negative or positive integer, different from 0)

Return value:

pointer to element reached, NULL if an error occurred

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();

/* move to next buffer, 2 times */
buffer = weechat_hdata_move (hdata, buffer, 2);

/* move to previous buffer */
if (buffer)
    buffer = weechat_hdata_move (hdata, buffer, -1);

Script (Python):

# prototype
pointer = weechat.hdata_move(hdata, pointer, count)

# example
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()

# move to next buffer, 2 times
buffer = weechat.hdata_move(hdata, buffer, 2)

# move to previous buffer
if buffer:
    buffer = weechat.hdata_move(hdata, buffer, -1)

3.20.16. weechat_hdata_search

New in version 0.4.1.

Search element in a list: the expression search is evaluated for each element in list, until element is found (or end of list).

Prototype:

void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search, int move);

Arguments:

hdata: hdata pointer
pointer: pointer to a WeeChat/plugin object
search: expression to evaluate, default pointer in expression is the name of hdata (and this pointer changes for each element in list); for help on expression, see command /eval in WeeChat User’s guide
move: number of jump(s) to execute after unsuccessful search (negative or positive integer, different from 0)

Return value:

pointer to element found, NULL if not found

C example:

struct t_hdata *hdata = weechat_hdata_get ("irc_server");
void *servers = weechat_hdata_get (hdata, "irc_servers");

/* search irc server with name "freenode" */
void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == freenode", 1);
if (server)
{
    /* ... */
}

Script (Python):

# prototype
pointer = weechat.hdata_search(hdata, pointer, search, count)

# example
hdata = weechat.hdata_get("irc_server")
servers = weechat.hdata_get_list(hdata, "irc_servers")

# search irc server with name "freenode"
server = weechat.hdata_search(hdata, servers, "${irc_server.name} == freenode", 1)
if server:
    # ...

3.20.17. weechat_hdata_char

New in version 0.3.7.

Return value of char variable in structure using hdata.

Prototype:

char weechat_hdata_char (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "char"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

char value of variable

C example:

weechat_printf (NULL, "letter = %c", weechat_hdata_char (hdata, pointer, "letter"));

Script (Python):

# prototype
value = weechat.hdata_char(hdata, pointer, name)

# example
weechat.prnt("", "letter = %c" % weechat.hdata_char(hdata, pointer, "letter"))

3.20.18. weechat_hdata_integer

New in version 0.3.6.

Return value of integer variable in structure using hdata.

Prototype:

int weechat_hdata_integer (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "integer"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

integer value of variable

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "number = %d", weechat_hdata_integer (hdata, buffer, "number"));

Script (Python):

# prototype
value = weechat.hdata_integer(hdata, pointer, name)

# example
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "number = %d" % weechat.hdata_integer(hdata, buffer, "number"))

3.20.19. weechat_hdata_long

New in version 0.3.6.

Return value of long variable in structure using hdata.

Prototype:

long weechat_hdata_long (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "long"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

long value of variable

C example:

weechat_printf (NULL, "longvar = %ld", weechat_hdata_long (hdata, pointer, "longvar"));

Script (Python):

# prototype
value = weechat.hdata_long(hdata, pointer, name)

# example
weechat.prnt("", "longvar = %ld" % weechat.hdata_long(hdata, pointer, "longvar"))

3.20.20. weechat_hdata_string

New in version 0.3.6.

Return value of string variable in structure using hdata.

Prototype:

const char *weechat_hdata_string (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "string"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

string value of variable

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "name = %s", weechat_hdata_string (hdata, buffer, "name"));

Script (Python):

# prototype
value = weechat.hdata_string(hdata, pointer, name)

# example
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "name = %s" % weechat.hdata_string(hdata, buffer, "name"))

3.20.21. weechat_hdata_pointer

New in version 0.3.6.

Return value of pointer variable in structure using hdata.

Prototype:

void *weechat_hdata_pointer (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "pointer"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

pointer value of variable

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "lines = %lx", weechat_hdata_pointer (hdata, buffer, "lines"));

Script (Python):

# prototype
value = weechat.hdata_pointer(hdata, pointer, name)

# example
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "lines = %lx" % weechat.hdata_pointer(hdata, buffer, "lines"))

3.20.22. weechat_hdata_time

New in version 0.3.6.

Return value of time variable in structure using hdata.

Prototype:

time_t weechat_hdata_time (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "time"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

time value of variable

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *ptr = weechat_buffer_search_main ();
ptr = weechat_hdata_pointer (hdata, ptr, "lines");
if (ptr)
{
    hdata = weechat_hdata_get ("lines");
    ptr = weechat_hdata_pointer (hdata, ptr, "first_line");
    if (ptr)
    {
        hdata = weechat_hdata_get ("line");
        ptr = weechat_hdata_pointer (hdata, ptr, "data");
        if (ptr)
        {
            hdata = weechat_hdata_get ("line_data");
            time_t date = weechat_hdata_time (hdata, hdata, "date");
            weechat_printf (NULL, "time of last line displayed = %s", ctime (&date));
        }
    }
}

Script (Python):

# prototype
value = weechat.hdata_time(hdata, pointer, name)

# example
buf = weechat.buffer_search_main()
ptr = weechat.hdata_pointer(weechat.hdata_get("buffer"), buf, "lines")
if ptr:
    ptr = weechat.hdata_pointer(weechat.hdata_get("lines"), ptr, "first_line")
    if ptr:
        ptr = weechat.hdata_pointer(weechat.hdata_get("line"), ptr, "data")
        if ptr:
            date = weechat.hdata_time(weechat.hdata_get("line_data"), ptr, "date")
            weechat.prnt("", "time of first line displayed = %s" % time.strftime("%F %T", time.localtime(int(date))))

3.20.23. weechat_hdata_hashtable

New in version 0.3.7.

Return value of hashtable variable in structure using hdata.

Prototype:

struct t_hashtable *weechat_hdata_hashtable (struct t_hdata *hdata, void *pointer, const char *name);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (must be type "hashtable"); for arrays, the name can be "N|name" where N is the index in array (starting at 0), for example: "2|name"

Return value:

hashtable value of variable (pointer to hashtable)

C example:

struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
struct t_hashtable *hashtable = weechat_hdata_hashtable (hdata, buffer, "local_variables");
weechat_printf (NULL, "%d local variables in core buffer",
                weechat_hashtable_get_integer (hashtable, "items_count"));

Script (Python):

# prototype
hashtable = weechat.hdata_hashtable(hdata, pointer, name)

# example
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
hash = weechat.hdata_hashtable(hdata, buffer, "local_variables")
weechat.prnt("", "local variables in core buffer:")
for key in hash:
    weechat.prnt("", "  %s == %s" % (key, hash[key]))

3.20.24. weechat_hdata_set

New in version 0.3.9.

Set new value for variable in a hdata.

Note	This function can be called only in an update callback (see weechat_hdata_new and weechat_hdata_update), if the variable can be updated.

Prototype:

int weechat_hdata_set (struct t_hdata *hdata, void *pointer, const char *name, const char *value);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
name: variable name (types allowed: char, integer, long, string, pointer, time)
value: new value for variable

Return value:

1 if ok, 0 if error

C example:

weechat_hdata_set (hdata, pointer, "message", "test");

Note	This function is not available in scripting API.

3.20.25. weechat_hdata_update

New in version 0.3.9.

Update data in a hdata.

Prototype:

int weechat_hdata_update (struct t_hdata *hdata, void *pointer, struct t_hashtable *hashtable);

Arguments:

hdata: hdata pointer
pointer: pointer to WeeChat/plugin object
hashtable: variables to update: keys are name of variables, values are new values for variables (keys and values are string), some special keys are allowed:
- key __create_allowed (with any value): return 1 if create is allowed for structure, otherwise 0 (new in version 0.4.0)
- key __delete_allowed (with any value): return 1 if delete is allowed for structure, otherwise 0
- key __update_allowed, value is name of a variable: return 1 if update is allowed for this variable, otherwise 0
- key __delete (with any value): delete structure (if allowed)

Return value:

number of variables updated

C example:

/* subtract one hour on last message displayed in current buffer */

struct t_gui_lines *own_lines;
struct t_gui_line *line;
struct t_gui_line_data  *line_data;
struct t_hdata *hdata;
struct t_hashtable *hashtable;
char str_date[64];

own_lines = weechat_hdata_pointer (weechat_hdata_get ("buffer"), weechat_current_buffer (), "own_lines");
if (own_lines)
{
    line = weechat_hdata_pointer (weechat_hdata_get ("lines"), own_lines, "last_line");
    if (line)
    {
        line_data = weechat_hdata_pointer (weechat_hdata_get ("line"), line, "data");
        hdata = weechat_hdata_get ("line_data");
        hashtable = weechat_hashtable_new (8,
                                           WEECHAT_HASHTABLE_STRING,
                                           WEECHAT_HASHTABLE_STRING,
                                           NULL,
                                           NULL);
        if (hashtable)
        {
            snprintf (str_date, sizeof (str_date), "%ld", ((long int)weechat_hdata_time (hdata, line_data, "date")) - 3600);
            weechat_hashtable_set (hashtable, "date", str_date);
            weechat_hdata_update (hdata, line_data, hashtable);
            weechat_hashtable_free (hashtable);
        }
    }
}

Script (Python):

# prototype
count = weechat.hdata_update(hdata, pointer, hashtable)

# example: subtract one hour on last message displayed in current buffer
own_lines = weechat.hdata_pointer(weechat.hdata_get('buffer'), weechat.current_buffer(), 'own_lines')
if own_lines:
    line = weechat.hdata_pointer(weechat.hdata_get('lines'), own_lines, 'last_line')
    if line:
        line_data = weechat.hdata_pointer(weechat.hdata_get('line'), line, 'data')
        hdata = weechat.hdata_get('line_data')
        weechat.hdata_update(hdata, line_data, { 'date': str(weechat.hdata_time(hdata, line_data, 'date') - 3600) })

3.20.26. weechat_hdata_get_string

New in version 0.3.6.

Return string value of a hdata property.

Prototype:

const char *weechat_hdata_get_string (struct t_hdata *hdata, const char *property);

Arguments:

hdata: hdata pointer
property: property name:
- var_keys: string with list of keys for variables in hdata (format: "key1,key2,key3")
- var_values: string with list of values for variables in hdata (format: "value1,value2,value3")
- var_keys_values: string with list of keys and values for variables in hdata (format: "key1:value1,key2:value2,key3:value3")
- var_prev: name of variable in structure which is a pointer to previous element in list
- var_next: name of variable in structure which is a pointer to next element in list
- list_keys: string with list of keys for lists in hdata (format: "key1,key2,key3")
- list_values: string with list of values for lists in hdata (format: "value1,value2,value3")
- list_keys_values: string with list of keys and values for lists in hdata (format: "key1:value1,key2:value2,key3:value3")

Return value:

string value of property

C example:

weechat_printf (NULL, "variables in hdata: %s", weechat_hdata_get_string (hdata, "var_keys"));
weechat_printf (NULL, "lists in hdata: %s", weechat_hdata_get_string (hdata, "list_keys"));

Script (Python):

# prototype
value = weechat.hdata_get_string(hdata, property)

# example
weechat.prnt("", "variables in hdata: %s" % weechat.hdata_get_string(hdata, "var_keys"))
weechat.prnt("", "lists in hdata: %s" % weechat.hdata_get_string(hdata, "list_keys"))

3.21. Upgrade

Functions for upgrading WeeChat (command "/upgrade").

3.21.1. weechat_upgrade_new

Create or read a file for upgrade.

Prototype:

struct t_upgrade_file *weechat_upgrade_new (const char *filename, int write);

Arguments:

filename: name of file (extension ".upgrade" will be added to this name by WeeChat)
write:
- 1: create file (write mode, before upgrade)
- 0: read file (after upgrade)

Return value:

pointer to upgrade file

C example:

struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file", 1);

Script (Python):

# prototype
upgrade_file = weechat.upgrade_new(filename, write)

# example
upgrade_file = weechat.upgrade_new("my_file", 1)

3.21.2. weechat_upgrade_write_object

Write an object in upgrade file.

Prototype:

int weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file,
                                  int object_id,
                                  struct t_infolist *infolist);

Arguments:

upgrade_file: upgrade file pointer
object_id: id for object
infolist: infolist to write in file

Return value:

1 if ok, 0 if error

C example:

if (weechat_upgrade_write_object (upgrade_file, 1, &infolist))
{
    /* ok */
}
else
{
    /* error */
}

Script (Python):

# prototype
rc = weechat.upgrade_write_object(upgrade_file, object_id, infolist)

# example
weechat.upgrade_write_object(upgrade_file, 1, infolist)

3.21.3. weechat_upgrade_read

Read an upgrade file.

Prototype:

int weechat_upgrade_read (struct t_upgrade_file *upgrade_file,
                          int (*callback_read)(void *data,
                                               struct t_upgrade_file *upgrade_file,
                                               int object_id,
                                               struct t_infolist *infolist),
                          void *callback_read_data);

Arguments:

upgrade_file: upgrade file pointer
callback_read: function called for each object read in upgrade file, arguments and return value:
- void *data: pointer
- struct t_upgrade_file *upgrade_file: pointer to upgrade file
- int object_id: object id
- struct t_infolist *infolist: infolist with content of object
- return value:
  - WEECHAT_RC_OK
  - WEECHAT_RC_ERROR
callback_read_data: pointer given to read callback when it is called by WeeChat

Return value:

1 if ok, 0 if error

C example:

int
my_upgrade_read_cb (struct t_upgrade_file *upgrade_file,
                    int object_id,
                    struct t_infolist *infolist)
{
    /* read variables... */
    return WEECHAT_RC_OK;
}

weechat_upgrade_read (upgrade_file, &my_upgrade_read_cb, NULL);

Script (Python):

# prototype
rc = weechat.upgrade_read(upgrade_file, callback_read, callback_read_data)

# example
def my_upgrade_read_cb(upgrade_file, object_id, infolist):
    # read variables...
    return weechat.WEECHAT_RC_OK

weechat.upgrade_read(upgrade_file, "my_upgrade_read_cb", ""))

3.21.4. weechat_upgrade_close

Close an upgrade file.

Prototype:

void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);

Arguments:

upgrade_file: upgrade file pointer

C example:

weechat_upgrade_close (upgrade_file);

Script (Python):

# prototype
weechat.upgrade_close(upgrade_file)

# example
weechat.upgrade_close(upgrade_file)