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

Latest version of this document can be found on this page: http://www.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:

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:

Return value:

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:

Return value:

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:

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:

Return value:

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:

C example:

weechat_charset_set (plugin, "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:

Return value:

C example:

char *str = weechat_iconv_to_internal (plugin, "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:

Return value:

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:

Return value:

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:

Return value:

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:

Return value:

C example:

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

3.2.7. weechat_string_tolower

Convert UTF-8 string to lower case.

Prototype:

void weechat_string_tolower (const char *string);

Arguments:

C example:

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

3.2.8. weechat_string_toupper

Convert UTF-8 string to upper case.

Prototype:

void weechat_string_toupper (const char *string);

Arguments:

C example:

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

3.2.9. weechat_strcasecmp

Locale and case independent string comparison.

Prototype:

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

Arguments:

Return value:

C example:

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

3.2.10. weechat_strncasecmp

Locale and case independent string comparison, for max chars.

Prototype:

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

Arguments:

Return value:

C example:

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

3.2.11. 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:

Return value:

C example:

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

3.2.12. weechat_strcasestr

Locale and case independent string search.

Prototype:

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

Arguments:

Return value:

C example:

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

3.2.13. 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:

Return value:

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.14. weechat_string_replace

Replace all occurences of a string by another string.

Prototype:

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

Arguments:

Return value:

C example:

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

3.2.15. 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:

Return value:

C example:

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

3.2.16. 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:

Return value:

C example:

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

3.2.17. 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:

Return value:

C example:

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

3.2.18. 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:

Return value:

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.19. 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:

Return value:

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.20. 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:

Return value:

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

3.2.21. weechat_string_free_split

Free memory used by a split string.

Prototype:

void weechat_string_free_split (char **split_string);

Arguments:

C example:

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

3.2.22. 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:

Return value:

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

3.2.23. 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:

Return value:

C example:

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

3.2.24. weechat_string_free_split_command

Free memory used by a split command.

Prototype:

void weechat_string_free_split_command (char **split_command);

Arguments:

C example:

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

3.2.25. 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 size);

Arguments:

Return value:

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

3.2.26. weechat_string_remove_color

Remove WeeChat colors from a string.

Prototype:

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

Arguments:

Return value:

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.27. 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:

C example:

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

3.2.28. 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:

Return value:

C example:

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

3.2.29. 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:

Return value:

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.30. 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:

Return value:

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.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:

Return value:

C example:

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

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:

Return value:

C example:

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

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 (const char *string, char replacement);

Arguments:

C example:

weechat_utf8_normalize (string, '?');

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:

Return value:

C example:

char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);

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:

Return value:

C example:

char *next_char = weechat_utf8_next_char (string);

3.3.6. weechat_utf8_char_int

Return UTF-8 char as integer.

Prototype:

int weechat_utf8_char_int (const char *string);

Arguments:

Return value:

C example:

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

3.3.7. weechat_utf8_char_size

Return UTF-8 char size (in bytes).

Prototype:

int weechat_utf8_char_size (const char *string);

Arguments:

Return value:

C example:

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

3.3.8. weechat_utf8_strlen

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

Prototype:

int weechat_utf8_strlen (const char *string);

Arguments:

Return value:

C example:

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

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:

Return value:

C example:

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

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:

Return value:

C example:

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

3.3.11. weechat_utf8_charcmp

Compare two UTF-8 chars.

Prototype:

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

Arguments:

Return value:

C example:

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

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:

Return value:

C example:

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

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:

Return value:

C example:

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

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:

Return value:

C example:

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

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:

Return value:

C example:

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

3.3.16. weechat_utf8_pos

Return position in UTF-8 string.

Prototype:

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

Arguments:

Return value:

C example:

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

3.3.17. weechat_utf8_strndup

Return duplicate string, with length chars max.

Prototype:

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

Arguments:

Return value:

C example:

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

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:

Return value:

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:

Return value:

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:

Return value:

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:

C example:

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

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:

Return value:

C example:

char *content;

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

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:

Return value:

C example:

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

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:

Return value:

C example:

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

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:

C example:

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

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:

C example:

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

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:

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:

Return value:

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, "")

Search an item in a list.

Prototype:

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

Arguments:

Return value:

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_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:

Return value:

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.5. 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:

Return value:

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.6. weechat_list_set

Set new value for an item.

Prototype:

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

Arguments:

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.7. weechat_list_next

Return next item in list.

Prototype:

struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);

Arguments:

Return value:

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.8. weechat_list_prev

Return previous item in list.

Prototype:

struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);

Arguments:

Return value:

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.9. weechat_list_string

Return string value of an item.

Prototype:

const char *weechat_list_string (struct t_weelist_item *item);

Arguments:

Return value:

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.10. weechat_list_size

Return size of list (number of items).

Prototype:

char *weechat_list_size (struct t_weelist *weelist);

Arguments:

Return value:

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.11. weechat_list_remove

Remove an item in a list.

Prototype:

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

Arguments:

C example:

weechat_list_remove (list, item);

Script (Python):

# prototype
weechat.list_remove(list, item)

# example
weechat.list_remove(list, item)

3.6.12. weechat_list_remove_all

Remove all items in a list.

Prototype:

void weechat_list_remove_all (struct t_weelist *weelist);

Arguments:

C example:

weechat_list_remove_all (list);

Script (Python):

# prototype
weechat.list_remove_all(list)

# example
weechat.list_remove_all(list)

3.6.13. weechat_list_free

Free a list.

Prototype:

void weechat_list_free (struct t_weelist *weelist);

Arguments:

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 int (*callback_hash_key)(struct t_hashtable *hashtable,
                                                                             const void *key),
                                           int (*callback_keycmp)(struct t_hashtable *hashtable,
                                                                  const void *key1,
                                                                  const void *key2));

Arguments:

Return value:

C example:

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

3.7.2. weechat_hashtable_set_with_size

New in version 0.3.3.

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

Prototype:

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

Arguments:

Return value:

C example:

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

3.7.3. weechat_hashtable_set

New in version 0.3.3.

Add or update item in a hashtable.

Prototype:

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

Arguments:

Return value:

C example:

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

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:

Return value:

C example:

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

3.7.5. weechat_hashtable_map

New in version 0.3.3.

Call a function on all hashtable entries.

Prototype:

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

Arguments:

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

3.7.6. 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:

Return value:

C example:

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

3.7.7. 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:

Return value:

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_00001"  = "key1"
     "testhash_value_00001" = "value 1"
     "testhash_name_00002"  = "key2"
     "testhash_value_00002" = "value 2"
*/

3.7.8. 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:

C example:

weechat_hashtable_remove (hashtable, "my_key");

3.7.9. 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:

C example:

weechat_hashtable_remove_all (hashtable);

3.7.10. weechat_hashtable_free

New in version 0.3.3.

Free a hashtable.

Prototype:

void weechat_hashtable_free (struct t_hashtable *hashtable);

Arguments:

C example:

weechat_hashtable_free (hashtable);

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:

Return value:

Note
File is NOT created on disk by this function. It will be created by call to function weechat_write_config. 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:

Return value:

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

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_RC_OK

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:

Return value:

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,
    int (*callback_change)(void *data,
                           struct t_config_option *option),
    void *callback_change_data,
    int (*callback_delete)(void *data,
                           struct t_config_option *option),
    void *callback_delete_data);

Arguments:

Return value:

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 weechat.WEECHAT_RC_OK

def option4_change_cb(data, option):
    # ...
    return weechat.WEECHAT_RC_OK

def option4_delete_cb(data, option):
    # ...
    return weechat.WEECHAT_RC_OK

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, 100, "lightblue", "lightblue", 0,
    "", "",
    "", "",
    "", "")

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:

Return value:

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:

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 */
}

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

Arguments:

C example:

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

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

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:

Return value:

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:

Return value:

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:

Return value:

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:

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

Return value:

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:

Return value:

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:

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:

Return value:

C example:

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

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:

Return value:

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:

Return value:

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:

Return value:

C example:

if (weechat_config_boolean (option))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}

Script (Python):

# prototype
value = weechat.config_option_boolean(option)

# example
if weechat.config_option_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:

Return value:

C example:

if (weechat_config_boolean_default (option))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}

Script (Python):

# prototype
value = weechat.config_option_boolean_default(option)

# example
if weechat.config_option_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:

Return value:

C example:

int value = weechat_config_integer (option);

Script (Python):

# prototype
value = weechat.config_option_integer(option)

# example
if weechat.config_option_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:

Return value:

C example:

int value = weechat_config_integer_default (option);

Script (Python):

# prototype
value = weechat.config_option_integer_default(option)

# example
if weechat.config_option_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:

Return value:

C example:

const char *value = weechat_config_string (option);

Script (Python):

# prototype
value = weechat.config_option_string(option)

# example
value = weechat.config_option_string(option):

3.8.22. weechat_config_string_default

Return default string value of option.

Prototype:

const char *weechat_config_integer_default (struct t_config_option *option);

Arguments:

Return value:

C example:

const char *value = weechat_config_string_default (option);

Script (Python):

# prototype
value = weechat.config_option_string_default(option)

# example
value = weechat.config_option_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:

Return value:

C example:

const char *color = weechat_config_color (option);

Script (Python):

# prototype
value = weechat.config_option_color(option)

# example
value = weechat.config_option_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:

Return value:

C example:

const char *color = weechat_config_color_default (option);

Script (Python):

# prototype
value = weechat.config_option_color_default(option)

# example
value = weechat.config_option_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:

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:

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:

Return value:

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:

Return value:

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:

Return value:

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:

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:

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_option *option);

Arguments:

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:

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:

Return value:

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:

Return value:

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:

Return value:

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:

Return value:

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_is_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_unset_plugin

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

Prototype:

int weechat_config_unset_plugin (const char *option_name);

Arguments:

Return value:

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. Display

Functions to display text in buffers.

3.9.1. weechat_prefix

Return a prefix.

Prototype:

const char *weechat_prefix (const char *prefix);

Arguments:

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:

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.9.2. weechat_color

Return a string color code for display.

Prototype:

const char *weechat_color (const char *color_name);

Arguments:

Return value:

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.9.3. weechat_printf

Display a message on a buffer.

Prototype:

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

Arguments:

C example:

weechat_printf (NULL, "Hello on WeeChat buffer");
weechat_printf (buffer, "Hello on this buffer");

Script (Python):

# prototype
weechat.prnt(buffer, message)

# example
weechat.prnt("", "Hello on WeeChat buffer")
weechat.prnt(buffer, "Hello on this buffer")
Note
Function is called "print" in scripts ("prnt" in Python).

3.9.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:

C example:

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

3.9.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:

C example:

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

3.9.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:

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.9.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:

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.9.8. weechat_log_printf

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

Prototype:

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

Arguments:

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.10. Hooks

3.10.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:

Default completion codes are:

Plugin Name Description

alias

alias

list of aliases

aspell

aspell_langs

list of supported langs for aspell

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_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

ruby

ruby_script

list of scripts

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

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

nicks

nicks in nicklist of current buffer

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

weechat_commands

weechat commands

xfer

nick

nicks of DCC chat

Special codes:

Return value:

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 contain following values:

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.10.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:

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

Return value:

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.10.3. weechat_hook_timer

Hook a timer.

Prototype:

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

Arguments:

Return value:

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.10.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:

Return value:

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.10.5. weechat_hook_process

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

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:

Return value:

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.10.6. 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 sock,
                                     int ipv6,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *local_hostname,
                                     int (*callback)(void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     const char *error,
                                                     const char *ip_address),
                                     void *callback_data);

Arguments:

Return value:

C example:

int
my_connect_cb (void *data, int status, int gnutls_rc, 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;
    }
    return WEECHAT_RC_OK;
}

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

Script (Python):

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

# example
def my_connect_cb(data, status, gnutls_rc, 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:
        # ...
    return weechat.WEECHAT_RC_OK

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

3.10.7. 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:

Return value:

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.10.8. 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:

Plugin Signal Arguments Description

irc

xxx,irc_in_yyy (1)

string: message

irc message from server (before irc plugin uses it, signal sent only if message is not ignored)

irc

xxx,irc_in2_yyy (1)

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 (1)

string: message

irc message from server (before irc plugin uses it, signal sent even if message is ignored)

irc

xxx,irc_raw_in2_yyy (1)

string: message

irc message from server (after irc plugin uses it, signal sent even if message is ignored)

irc

xxx,irc_out_yyy (1)

string: message

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_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

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

weechat

buffer_closing

pointer: buffer

closing buffer

weechat

buffer_closed

pointer: buffer

buffer closed

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_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

string: new date, format: "2010-01-31"

day of system date has changed

weechat

debug_dump

-

dump request

weechat

filter_added

pointer: filter

filter added

weechat

filter_removing

pointer: filter

removing filter

weechat

filter_removed

-

filter added

weechat

filter_enabled

-

filters enabled

weechat

filter_disabled

-

filters disabled

weechat

hotlist_changed

-

hotlist changed

weechat

input_paste_pending

-

paste pending

weechat

input_search

-

text search in buffer

weechat

input_text_changed

-

input text changed

weechat

input_text_cursor_moved

-

input text cursor moved

weechat

key_pressed

string: key pressed

key pressed

weechat

nicklist_group_added

string: buffer pointer + "," + group name

group added in nicklist

weechat

nicklist_group_removed

string: buffer pointer + "," + group name

group removed from nicklist

weechat

nicklist_nick_added

string: buffer pointer + "," + nick name

nick added in nicklist

weechat

nicklist_nick_removed

string: buffer pointer + "," + nick name

nick removed from nicklist

weechat

partial_completion

-

partial completion happened

weechat

quit

string: arguments for /quit

command /quit issued by user

weechat

upgrade

-

command /upgrade issued by user

weechat

weechat_highlight

string: message with prefix

highlight happened

weechat

weechat_pv

string: message with prefix

private message displayed

weechat

window_scrolled

pointer: window

scroll in window

weechat

window_unzooming

pointer: current window

unzooming window

weechat

window_unzoomed

pointer: current window

window unzoomed

weechat

window_zooming

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

pointer: infolist with xfer info

xfer has ended

Note
(1) xxx is IRC server name, yyy is IRC command name.

Return value:

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.10.9. weechat_hook_signal_send

Send a signal.

Prototype:

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

Arguments:

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)

3.10.10. 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:

Return value:

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.10.11. 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:

Note
Completion names are global (shared accross 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:

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.10.12. 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:

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.10.13. 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:

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_in_xxx (1)

server name

content of message received from IRC server

new content of message

irc

irc_out_xxx (1)

server name

content of message about to be sent to IRC server

new content of message

weechat

bar_condition_yyy (2)

string with window pointer ("0x123..")

empty string

"1" to display bar, "0" to hide it

weechat

history_add

string with buffer pointer ("0x123..")

input buffer (from user) to add in command history (buffer and global)

string added to command history

weechat

input_text_content

string with buffer pointer ("0x123..")

input buffer (from user)

new content of input buffer

weechat

input_text_display

string with buffer pointer ("0x123..")

input buffer (from user), without cursor tag

new content of input buffer, for display only (input buffer is not changed)

weechat

input_text_display_with_cursor

string with buffer pointer ("0x123..")

input buffer (from user), with cursor tag

new content of input buffer, for display only (input buffer is not changed)

weechat

weechat_print

plugin;buffer_name;tags

message printed

new message printed

Note
(1) xxx is IRC command name.
(2) yyy is bar name.

Return value:

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.10.14. weechat_hook_modifier_exec

Execute modifier(s).

Prototype:

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

Arguments:

Return value:

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.10.15. weechat_hook_info

Hook an information.

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:

Return value:

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.10.16. 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,
                                      const char *(*callback)(void *data,
                                                              const char *infolist_name,
                                                              void *pointer,
                                      const char *arguments),
                                      void *callback_data);

Arguments:

Return value:

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.10.17. weechat_unhook

Unhook something hooked.

Prototype:

void weechat_unhook (struct t_hook *hook);

Arguments:

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.10.18. 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.11. Buffers

Functions to create/query/close buffers.

3.11.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:

Return value:

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.11.2. weechat_current_buffer

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

Prototype:

struct t_gui_buffer *weechat_current_buffer ();

Return value:

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

Search a buffer by plugin and/or name.

Prototype:

struct t_gui_buffer *weechat_buffer_search (const char *plugin,
                                            const char *name);

Arguments:

Return value:

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.11.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:

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.11.5. weechat_buffer_clear

Clear content of a buffer.

Prototype:

void weechat_buffer_clear (struct t_gui_buffer *buffer);

Arguments:

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.11.6. weechat_buffer_close

Close a buffer.

Prototype:

void weechat_buffer_close (struct t_gui_buffer *buffer);

Arguments:

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.11.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:

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.11.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:

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.11.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:

Return value:

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.11.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:

Return value:

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.11.11. weechat_buffer_get_pointer

Return pointer value of a buffer property.

Prototype:

const char *weechat_buffer_pointer (struct t_gui_buffer *buffer,
                                    const char *property);

Arguments:

Return value:

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: %lx" % weechat.buffer_get_pointer(my_buffer, "plugin"))

3.11.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:

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

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_tags

comma separated list of tags

comma separated list of tags to highlight in this buffer

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 behaviour), "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.buffet_set(my_buffer, "name", "my_new_name")

# add new local variable "toto" with value "abc"
weechat.buffet_set(my_buffer, "localvar_set_toto", "abc")

# remove local variable "toto"
weechat.buffet_set(my_buffer, "localvar_del_toto", "")

3.11.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:

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

3.11.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:

Return value:

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. Windows

Functions to query windows.

3.12.1. weechat_current_window

Return pointer to current window.

Prototype:

struct t_gui_window *weechat_current_window ();

Return value:

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.12.2. 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:

Return value:

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.12.3. 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:

Return value:

3.12.4. 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:

Return value:

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: %lx"
    % weechat.window_get_pointer(weechat.current_window(), "buffer"))

3.12.5. weechat_window_set_title

Set title for terminal.

Prototype:

void weechat_window_set_title (const char *title);

Arguments:

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.13. Nicklist

Functions for buffer nicklist.

3.13.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:

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:

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.13.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:

Return value:

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.13.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:

Return value:

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.13.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:

Return value:

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.13.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:

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.13.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:

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.13.7. weechat_nicklist_remove_all

Remove all groups/nicks from a nicklist.

Prototype:

void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);

Arguments:

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. Bars

Functions for bars.

Search a bar item.

Prototype:

struct t_gui_bar_item *weechat_bar_item_search (const char *name);

Arguments:

Return value:

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.14.2. weechat_bar_item_new

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),
                                             void *build_callback_data);

Arguments:

Return value:

C example:

char *
my_build_callback (void *data,
                   struct t_gui_bar_item *item,
                   struct t_gui_window *window)
{
    return strdup ("my content");
}

struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                       &my_build_callback,
                                                       NULL);

Script (Python):

# prototype
bar_item = weechat.bar_item_new(name, build_callback, build_callback_data)

# example
def my_build_callback(data, item, window):
    return "my content"

bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")

3.14.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:

C example:

weechat_bar_item_update ("myitem");

Script (Python):

# prototype
weechat.bar_item_update(name)

# example
weechat.bar_item_update("myitem")

3.14.4. weechat_bar_item_remove

Remove a bar item.

Prototype:

void weechat_bar_item_remove (struct t_gui_bar_item *item);

Arguments:

C example:

weechat_bar_item_remove (&my_item);

Script (Python):

# prototype
weechat.bar_item_remove(item)

# example
weechat.bar_item_remove(myitem)

Search a bar.

Prototype:

struct t_gui_bar *weechat_bar_search (const char *name);

Arguments:

Return value:

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.14.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:

Return value:

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.14.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:

Return value:

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.14.8. weechat_bar_update

Refresh content of a bar on screen.

Prototype:

void weechat_bar_update (const char *name);

Arguments:

C example:

weechat_bar_update ("mybar");

Script (Python):

# prototype
weechat.bar_update(name)

# example
weechat.bar_update("mybar")

3.14.9. weechat_bar_remove

Remove a bar.

Prototype:

void weechat_bar_remove (struct t_gui_bar *bar);

Arguments:

C example:

weechat_bar_remove (mybar);

Script (Python):

# prototype
weechat.bar_remove(bar)

# example
weechat.bar_remove(my_bar)

3.15. Commands

Functions for executing WeeChat commands.

3.15.1. weechat_command

Execute a command.

Prototype:

void weechat_command (struct t_gui_buffer *buffer, const char *command);

Arguments:

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.16. Network

Network functions.

3.16.1. weechat_network_pass_proxy

Establish a connection/authentification to a proxy.

Prototype:

int weechat_network_pass_proxy (const char *proxy,
                                int sock,
                                const char *address,
                                int port);

Arguments:

Return value:

C example:

if (weechat_network_pass_proxy ("my_proxy", sock, "irc.freenode.net", 6667))
{
    /* OK */
}
else
{
    /* error */
}

3.16.2. weechat_network_connect_to

Establish a connection to a remote host.

Prototype:

int weechat_network_connect_to (const char *proxy,
                                int sock,
                                unsigned long address,
                                int port);

Arguments:

Return value:

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 */
}

3.17. Infos

Functions to get infos.

3.17.1. weechat_info_get

Return info from WeeChat or a plugin.

Prototype:

const char *weechat_info_get (const char *info_name, const char *arguments);

Arguments:

Plugin Name Description Arguments

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

channel name

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

weechat

charset_internal

WeeChat internal charset

-

weechat

charset_terminal

terminal charset

-

weechat

date

WeeChat compilation date

-

weechat

dir_separator

directory separator

-

weechat

filters_enabled

1 if filters are enabled

-

weechat

inactivity

keyboard inactivity (seconds)

-

weechat

version

WeeChat version

-

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

-

Return value:

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. 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:

3.18.1. weechat_infolist_new

Create a new infolist.

Prototype:

struct t_infolist *weechat_infolist_new ();

Return value:

C example:

struct t_infolist *infolist = weechat_infolist_new ();

Script (Python):

# prototype
infolist = weechat.infolist_new()

# example
infolist = weechat.infolist_new()

3.18.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:

Return value:

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.18.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:

Return value:

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.18.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:

Return value:

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.18.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:

Return value:

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.18.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:

Return value:

C example:

char buffer[256];
/* ... */
struct t_infolist_var *var = weechat_infolist_new_variable_buffer (item,
                                                                   "my_buffer",
                                                                   &buffer,
                                                                   sizeof (buffer));

3.18.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:

Return value:

C example:

struct t_infolist_var *var = weechat_infolist_new_variable_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.18.8. weechat_infolist_get

Return infolist from WeeChat or a plugin.

Prototype:

struct t_infolist *weechat_infolist_get (const char *infolist_name,
                                         void *pointer,
                                         const char *arguments);

Arguments:

Plugin Name Description Pointer Arguments

alias

alias

list of aliases

alias pointer (optional)

alias name (can start or end with "*" as wildcard) (optional)

irc

irc_channel

list of channels for an IRC server

channel pointer (optional)

server name

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

-

ruby

ruby_script

list of scripts

script pointer (optional)

script name (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 type: command, timer, .. (optional)

weechat

hotlist

list of buffers in hotlist

-

-

weechat

key

list of key bindings

-

-

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

window

list of windows

window pointer (optional)

window name (can start or end with "*" as wildcard) (optional)

xfer

xfer

list of xfer

xfer pointer (optional)

-

Return value:

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.18.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:

Return value:

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.18.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:

Return value:

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.18.11. weechat_infolist_reset_item_cursor

Reset "cursor" for infolist.

Prototype:

void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);

Arguments:

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.18.12. weechat_infolist_fields

Return list of fields for current infolist item.

Prototype:

const char *weechat_infolist_fields (struct t_infolist *infolist);

Arguments:

Return value:

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.18.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:

Return value:

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.18.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:

Return value:

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.18.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:

Return value:

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%lx" % weechat.infolist_pointer(infolist, "my_pointer"))

3.18.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:

Return value:

C example:

int size;
void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size);
weechat_printf (NULL, "buffer = 0x%lx, size = %d",
                pointer, size);

3.18.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:

Return value:

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.18.18. weechat_infolist_free

Free an infolist.

Prototype:

void weechat_infolist_free (struct t_infolist *infolist);

Arguments:

C example:

weechat_infolist_free (infolist);

Script (Python):

# prototype
weechat.infolist_free(infolist)

# example
weechat.infolist_free(infolist)

3.19. Upgrade

Functions for upgrading WeeChat (command "/upgrade").

3.19.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:

Return value:

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.19.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:

Return value:

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.19.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:

Return value:

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.19.4. weechat_upgrade_close

Close an upgrade file.

Prototype:

void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);

Arguments:

C example:

weechat_upgrade_close (upgrade_file);

Script (Python):

# prototype
weechat.upgrade_close(upgrade_file)

# example
weechat.upgrade_close(upgrade_file)