API functions

set_charset
iconv_to_internal
iconv_from_internal
ascii_strcasecmp
ascii_strncasecmp
explode_string
free_exploded_string
mkdir_home
exec_on_files
print
print_server
print_infobar
infobar_remove
log
msg_handler_add
cmd_handler_add
timer_handler_add
keyboard_handler_add
event_handler_add
handler_remove
handler_remove_all
modifier_add
modifier_remove
modifier_remove_all
exec_command
get_info
get_dcc_info
free_dcc_info
get_server_info
free_server_info
get_channel_info
free_channel_info
get_nick_info
free_nick_info
get_config
set_config
get_plugin_config
set_plugin_config
get_irc_color
input_color
get_window_info
free_window_info
get_buffer_info
free_buffer_info
get_buffer_data
free_buffer_data

set_charset

Prototype: void set_charset (t_weechat_plugin *plugin, char *charset)

Set new plugin charset.

Arguments:

  • plugin: pointer to plugin structure

  • charset: new charset to use

Example:

plugin->set_charset (plugin, "ISO-8859-1");

iconv_to_internal

Prototype: void iconv_to_internal (t_weechat_plugin *plugin, char *charset, char *string)

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

Arguments:

  • plugin: pointer to plugin structure

  • charset: charset to convert

  • string: string to convert

Return value: converted string.

Note: result has to be free by a call to "free" after use.

Example:

char *str = plugin->iconv_to_internal (plugin, "ISO-8859-1", "iso string: é ŕ");

iconv_from_internal

Prototype: void iconv_from_internal (t_weechat_plugin *plugin, char *charset, char *string)

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

Arguments:

  • plugin: pointer to plugin structure

  • charset: target charset

  • string: string to convert

Return value: converted string.

Note: result has to be free by a call to "free" after use.

Example:

char *str = plugin->iconv_from_internal (plugin, "ISO-8859-1", "utf-8 string: é ŕ");

ascii_strcasecmp

Prototype: int ascii_strcasecmp (t_weechat_plugin *plugin, char *string1, char *string2)

Locale and case independent string comparison.

Arguments:

  • plugin: pointer to plugin structure

  • string1: first string for comparison

  • string2: second string for comparison

Return value: difference between two strings: negative if string1 < string2, zero if string1 == string2, positive if string1 > string2

Example:

if (plugin->ascii_strcasecmp (plugin, "abc", "def") != 0) ...

ascii_strncasecmp

Prototype: int ascii_strncasecmp (t_weechat_plugin *plugin, char *string1, char *string2, int max)

Locale and case independent string comparison, for "max" chars.

Arguments:

  • plugin: pointer to plugin struct

  • string1: first string for comparison

  • string2: second string for comparison

  • max: max number of chars for comparison

Return value: difference between two strings: negative if string1 < string2, zero if string1 == string2, positive if string1 > string2

Example:

if (plugin->ascii_strncasecmp (plugin, "abc", "def", 2) != 0) ...

explode_string

Prototype: char **explode_string (t_weechat_plugin *plugin, char *string, char *separators, int num_items_max, int *num_items)

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

Arguments:

  • plugin: pointer to plugin struct

  • string: string to explode

  • separators: delimiters used for explosion

  • num_items_max: maximum number of items created (0 = no limit)

  • num_items: pointer to int which will contain number of items created

Return value: array of strings, NULL if problem.

Note: result has to be free by a call to "free_exloded_string" after use.

Example:

char **argv;
int argc;
argv = plugin->explode_string (plugin, string, " ", 0, &argc);
...
if (argv != NULL)
    plugin->free_exploded_string (plugin, argv);

free_exploded_string

Prototype: char **free_exploded_string (t_weechat_plugin *plugin, char **string)

Free memory used by a string explosion.

Arguments:

  • plugin: pointer to plugin structure

  • string: string exploded by "explode_string" function

Return value: none.

Example:

char *argv;
int argc;
argv = plugin->explode_string (plugin, string, " ", 0, &argc);
...
if (argv != NULL)
    plugin->free_exploded_string (plugin, argv);

mkdir_home

Prototype: int mkdir_home (t_weechat_plugin *plugin, char *directory)

Create a directory in WeeChat home.

Arguments:

  • plugin: pointer to plugin structure

  • directory: directory to create

Return value: 1 if directory was successfully created, 0 if an error occurred.

Example:

if (!plugin->mkdir_home (plugin, "temp"))
    plugin->print_server(plugin, "Failed to create 'temp' directory in WeeChat home.");

exec_on_files

Prototype: void exec_on_files (t_weechat_plugin *plugin, char *directory, int (*callback)(t_weechat_plugin *, char *))

Execute a function on all files of a directory.

Arguments:

  • plugin: pointer to plugin structure

  • directory: directory for searching files

  • callback: function called for each file found

Return value: none.

Example:

int callback (t_weechat_plugin *plugin, char *file)
{
    plugin->print_server (plugin, "file: %s", file);
    return 1;
}
...
plugin->exec_on_files (plugin, "/tmp", &callback);

print

Prototype: void print (t_weechat_plugin *plugin, char *server, char *channel, char *message, ...)

Display a message on a WeeChat buffer, identified by server and channel (both may be NULL for current buffer).

Arguments:

  • plugin: pointer to plugin structure

  • server: internal name of server to find buffer for message display (may be NULL)

  • channel: name of channel to find buffer for message display (may be NULL)

  • message: message

Return value: none.

Examples:

plugin->print (plugin, NULL, NULL, "hello");
plugin->print (plugin, NULL, "#weechat", "hello");
plugin->print (plugin, "freenode", "#weechat", "hello");

print_server

Prototype: void print_server (t_weechat_plugin *plugin, char *message, ...)

Display a message on current server buffer.

Arguments:

  • plugin: pointer to plugin structure

  • message: message

Return value: none.

Example:

plugin->print_server (plugin, "hello");

print_infobar

Prototype: void print_infobar (t_weechat_plugin *plugin, int time, char *message, ...)

Display a message in infobar for a specified time.

Arguments:

  • plugin: pointer to plugin structure

  • time: time (in seconds) for displaying message (0 = never erased)

Return value: none.

Example:

plugin->print_infobar (plugin, 5, "hello");

infobar_remove

Prototype: void infobar_remove (t_weechat_plugin *plugin, int count)

Remove one or more messages in infobar stack.

Arguments:

  • plugin: pointer to plugin structure

  • count: number of messages to remove (if argument is <= 0, then all messages are removed)

Return value: none.

Example:

plugin->infobar_remove (1);

log

Prototype: void log (t_weechat_plugin *plugin, char *server, char *channel, char *message, ...)

Write a message in log file for a server or a channel.

Arguments:

  • plugin: pointer to plugin structure

  • server: internal name of server to find buffer for log (may be NULL)

  • channel: name of channel to find buffer for log (may be NULL)

  • message: message

Return value: none.

Example:

plugin->log (plugin, "freenode", "#weechat", "test");

msg_handler_add

Prototype: t_plugin_handler *msg_handler_add (t_weechat_plugin *plugin, char *message, t_plugin_handler_func *function, char *handler_args, void *handler_pointer)

Add an IRC message handler, called when an IRC message is received.

Arguments:

  • plugin: pointer to plugin structure

  • message: name of IRC message ("*" for all messages). To know list of IRC messages, please consult RFCs 1459 and 2812. Moreover you can use a special name, prefixed by "weechat_" to catch special events, as written in table below:

    NameDescription
    weechat_pvprivate message received
    weechat_highlight message with highlight (on a channel or pv)
    weechat_ctcp CTCP message received (VERSION, PING, ..)
    weechat_dcc DCC message received (chat or file)

  • function: function called when message is received

    It uses following prototype: int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer)

    Argument argc is set to 3, following values are set in argv array:

    • argv[0] = server name

    • argv[1] = IRC message

    • argv[2] = command arguments

  • handler_args: arguments given to function when called

  • handler_pointer: pointer given to function when called

Return value: pointer to new message handler.

Note: function called when message is received has to return one of following values:

  • PLUGIN_RC_KO: function failed

  • PLUGIN_RC_OK: function successfully completed

  • PLUGIN_RC_OK_IGNORE_WEECHAT: message will not be sent to WeeChat

  • PLUGIN_RC_OK_IGNORE_PLUGINS: message will not be sent to other plugins

  • PLUGIN_RC_OK_IGNORE_ALL: message will not be sent to WeeChat neither other plugins

  • PLUGIN_RC_OK_WITH_HIGHLIGHT: function successfully completed and make "highlight" on received message

Example:

int msg_kick (t_weechat_plugin *plugin, int argc, char **argv,
              char *handler_args, void *handler_pointer)
{
    plugin->print (plugin, argv[0], NULL, "KICK received");
    return PLUGIN_RC_OK;
}
...
t_plugin_handler *msg_handler;
msg_handler = plugin->msg_handler_add (plugin, "KICK",
                                       &msg_kick, NULL, NULL);

cmd_handler_add

Prototype: t_plugin_handler *cmd_handler_add (t_weechat_plugin *plugin, char *command, char *description, char *arguments, char *arguments_description, char *completion_template, t_plugin_handler_func *fonction, char *handler_args, void *handler_pointer)

Add a WeeChat command handler, called when user uses command (for example /command).

Arguments:

  • plugin: pointer to plugin structure

  • command: the new command name, which may be an existing command (be careful, replaced command will not be available until plugin is unloaded)

  • description: short command description (displayed by /help command)

  • arguments: short description of command arguments (displayed by /help command)

  • arguments_description: long description of command arguments (displayed by /help command)

  • completion_template: template for completion, like "abc|%w def|%i" which means "abc" or a WeeChat command for first argument, "def" or IRC command for second. An empty string lets WeeChat complete any argument with a nick from current channel, NULL or "-" disable completion for all command arguments.

    Following codes can be used:

    CodeDescription
    %-no completion for argument
    %aalias
    %A alias and commands (WeeChat, IRC and plugins)
    %ccurrent channel
    %Call channels (including queries)
    %ffile name
    %hplugins commands
    %iIRC commands (sent)
    %IIRC commands (received)
    %kkey functions
    %mnick on current server
    %M nicks on current server (on all open channels)
    %nnicks of current channel
    %Nnicks and hostnames of current channel
    %osetup options
    %Oplugin options
    %pdefault "part" message
    %qdefault "quit" message
    %scurrent server name
    %Sall servers names
    %ttopic of current channel
    %vsetup option value
    %Vplugin option value
    %wWeeChat commands

  • function: function called when command is executed

    It uses following prototype: int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer)

    Argument argc is set to 3, following values are set in argc array:

    • argv[0] = server name

    • argv[1] = command

    • argv[2] = command arguments

  • handler_args: arguments given to function when called

  • handler_pointer: pointer given to function when called

Return value: pointer to new command handler.

Note: function called when command is executed has to return one of following values:

  • PLUGIN_RC_KO: function failed

  • PLUGIN_RC_OK: function successfully completed

Example:

int cmd_test (t_weechat_plugin *plugin, int argc, char **argv,
              char *handler_args, void *handler_pointer)
{
    plugin->print (plugin, argv[0], NULL,
                   "test command, nick: %s",
                   (argv[2]) ? argv[2] : "none");
    return PLUGIN_RC_OK;
}
...
t_plugin_handler *cmd_handler;
cmd_handler = plugin->cmd_handler_add (plugin, "test", "Test command",
                                       "[nick]", "nick: nick of channel",
                                       "%n", &cmd_test, NULL, NULL);

timer_handler_add

Prototype: t_plugin_handler *timer_handler_add (t_weechat_plugin *plugin, int interval, t_plugin_handler_func *function, char *handler_args, void *handler_pointer)

Add a timer handler which periodically calls a function.

Arguments:

  • plugin: pointer to plugin structure

  • interval: interval (in seconds) between two calls of function.

  • function: function called

    It uses following prototype: int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer)

    Argument argc is set to 0, and argv is set to NULL.

  • handler_args: arguments given to function when called

  • handler_pointer: pointer given to function when called

Return value: pointer to new timer handler.

Note: function called has to return one of following values:

  • PLUGIN_RC_KO: function failed

  • PLUGIN_RC_OK: function successfully completed

Example:

int my_timer (t_weechat_plugin *plugin, int argc, char **argv,
              char *handler_args, void *handler_pointer)
{
    plugin->print (plugin, NULL, NULL, "my timer");
    return PLUGIN_RC_OK;
}
...
t_plugin_handler *timer_handler;
timer_handler = plugin->timer_handler_add (plugin, 60, &my_timer);

keyboard_handler_add

Prototype: t_plugin_handler *keyboard_handler_add (t_weechat_plugin *plugin, t_plugin_handler_func *function, char *handler_args, void *handler_pointer)

Add a keyboard handler, called for any key pressed.

Arguments:

  • plugin: pointer to plugin structure

  • function: function called

    It uses following prototype: int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer)

    Argument argc is set to 3, following values are set in argc array:

    • argv[0] = key pressed (name of internal function or '*' followed by a key code)

    • argv[1] = command line before key action

    • argv[2] = command line after key action

  • handler_args: arguments given to function when called

  • handler_pointer: pointer given to function when called

Return value: pointer to new message handler.

Note: function called has to return one of following values:

  • PLUGIN_RC_KO: function failed

  • PLUGIN_RC_OK: function successfully completed

Example:

int my_keyb (t_weechat_plugin *plugin, int argc, char **argv,
             char *handler_args, void *handler_pointer)
{
    if (argc == 2)
    {
        plugin->print (plugin, NULL, NULL, "key pressed: %s", argv[0]);
        if (argv[1] && (argv[1][0] == '1'))
            plugin->print (plugin, NULL, NULL, "input text changed");
        else
            plugin->print (plugin, NULL, NULL, "input text not changed");
    }
    return PLUGIN_RC_OK;
}
...
t_plugin_handler *keyb_handler;
keyb_handler = plugin->keyboard_handler_add (plugin, &my_keyb);

event_handler_add

Prototype: t_plugin_handler *event_handler_add (t_weechat_plugin *plugin, char *event, t_plugin_handler_func *function, char *handler_args, void *handler_pointer)

Add an event handler, called when an event happens.

Arguments:

  • plugin: pointer to plugin structure

  • event : event, see table below:

    EventDescription
    buffer_opena buffer was open
    buffer_closea buffer was closed

  • function: function called

    It uses following prototype: int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *handler_args, void *handler_pointer)

    Argument argc is set to 1, argv[0] is number of buffer open/closed.

  • handler_args: arguments given to function when called

  • handler_pointer: pointer given to function when called

Return value: pointer to new event handler.

Note: function called has to return one of following values:

  • PLUGIN_RC_KO: function failed

  • PLUGIN_RC_OK: function successfully completed

Example:

int my_event (t_weechat_plugin *plugin, int argc, char **argv,
              char *handler_args, void *handler_pointer)
{
    plugin->print (plugin, NULL, NULL, "my_event");
    return PLUGIN_RC_OK;
}
...
t_plugin_handler *event_handler;
event_handler = plugin->event_handler_add (plugin, "buffer_open",
                                           &my_event);

handler_remove

Prototype: void handler_remove (t_weechat_plugin *plugin, t_plugin_handler *handler)

Remove a command or message handler.

Arguments:

  • plugin: pointer to plugin structure

  • handler: handler to remove

Return value: none.

Example:

plugin->handler_remove (plugin, my_handler);

handler_remove_all

Prototype: void handler_remove_all (t_weechat_plugin *plugin)

Remove all handlers for a plugin.

Arguments:

  • plugin: pointer to plugin structure

Return value: none.

Example:

plugin->handler_remove_all (plugin);

modifier_add

Prototype: t_plugin_modifier *modifier_add (t_weechat_plugin *plugin, char *type, char *message, t_plugin_modifier_func *function, char *modifier_args, void *modifier_pointer)

Add a message modifier.

Arguments:

  • plugin: pointer to plugin structure

  • type: modifier type:

    TypeDescription
    irc_incalled for incoming IRC messages
    irc_user called for each user message (or command) (before WeeChat parses message)
    irc_out called for outgoing messages, immediately before sending it to IRC server (this includes messages sent automatically by WeeChat to server)

  • message: name of IRC message (used only for types "irc_in" and "irc_out"). To know list of IRC messages, please consult RFCs 1459 and 2812. Moreover, special value "*" means all messages (no filter).

  • function: function called

    It uses following prototype: int my_function (t_weechat_plugin *plugin, int argc, char **argv, char *modifier_args, void *modifier_pointer)

    Argument argc is set to 2, following values are set in argv array:

    • argv[0] = server name

    • argv[1] = message

  • modifier_args: arguments given to function when called

  • modifier_pointer: pointer given to function when called

Return value: pointer to new message modifier.

Note: function has to return modified string, or NULL if no changes are made to message. If function returns empty string, then message is dropped and will not be read at all by WeeChat (be careful when dropping messages!). Returned string must have been allocated by malloc() and will be freed (with call to free()) automatically by WeeChat after use.

Example:

char *adder (t_weechat_plugin *plugin, int argc, char **argv,
             char *modifier_args, void *modifier_pointer)
{
    char *string;
    string = (char *)malloc (strlen (argv[1]) + 16);
    strcpy (string, argv[1]);
    strcat (string, "test");
    return string;
}
...
t_plugin_modifier *modifier;
modifier = plugin->modifier_add (plugin, "irc_in", "privmsg",
                                 &adder, NULL, NULL);

modifier_remove

Prototype: void modifier_remove (t_weechat_plugin *plugin, t_plugin_modifier *modifier)

Remove a message modifier.

Arguments:

  • plugin: pointer to plugin structure

  • modifier: modifier to remove

Return value: none.

Example:

plugin->modifier_remove (plugin, my_modifier);

modifier_remove_all

Prototype: void modifier_remove_all (t_weechat_plugin *plugin)

Remove all modifiers for a plugin.

Arguments:

  • plugin: pointer to plugin structure

Return value: none.

Example:

plugin->modifier_remove_all (plugin);

exec_command

Prototype: void exec_command (t_weechat_plugin *plugin, char *server, char *channel, char *command)

Execute a WeeChat command (or send a message to a channel).

Arguments:

  • plugin: pointer to plugin structure

  • server: internal name of server for executing command (may be NULL)

  • channel: name of channel for executing command (may be NULL)

  • command: command

Return value: none.

Examples:

plugin->exec_command (plugin, NULL, NULL, "/help nick");
plugin->exec_command (plugin, "freenode", "#weechat", "hello");

get_info

Prototype: char *get_info (t_weechat_plugin *plugin, char *info, char *server)

Return an info about WeeChat or a channel.

Arguments:

  • plugin: pointer to plugin structure

  • info : name of info to read:

    InfoDescription
    versionWeeChat's version
    nicknick
    channel name of channel (NULL for a server or private)
    servername of server
    type buffer type: 0=standard, 1=DCC, 2=raw IRC data
    away"away" flag
    inactivity number of seconds since last key was pressed
    input content of command line for current window
    input_mask content of color mask for command line
    input_pos cursor position in command line
    weechat_dir WeeChat home directory (by default: ~/.weechat/)
    weechat_libdirWeeChat system lib directory
    weechat_sharedirWeeChat system share directory

  • server: internal name of server for reading info (if needed)

Return value: information asked, NULL if not found.

Note: result has to be free by a call to "free" function after use.

Examples:

char *version = plugin->get_info (plugin, "version", NULL);
char *nick = plugin->get_info (plugin, "nick", "freenode");
char *inactivity = plugin->get_info (plugin, "inactivity", NULL);

plugin->print (plugin, NULL, NULL,
               "WeeChat version %s, you are %s on freenode "
               "(inactive for %s seconds)",
               version, nick, inactivity);

if (version)
    free (version);
if (nick)
    free (nick);
if (inactivity)
    free (inactivity);

get_dcc_info

Prototype: t_plugin_info_dcc *get_dcc_info (t_weechat_plugin *plugin)

Return list of DCC currently active or finished.

Arguments:

  • plugin: pointer to plugin structure

Return value: linked list of DCC.

TypeFieldDescription
char *serverIRC server
char *channelIRC channel
inttype DCC type: 0 = chat received, 1 = chat sent, 2 = file received, 3 = file sent
int*status DCC status: 0 = waiting, 1 = connecting, 2 = active, 3 = finished, 4 = failed, 5 = interrupted by user
time_tstart_timedate/time of DCC creation
time_tstart_transferdate/time of DCC transfer start
unsigned longaddrIP address of remote user
intportport used for DCC
char *nickremote nick
char *filenamefile name
char *local_filenamelocal file name
intfilename_suffixsuffix if renaming file
unsigned longsizefile size
unsigned longposposition in file
unsigned longstart_resumestart position after interruption
unsigned longbytes_per_sec number of bytes per second since transfer start
t_plugin_dcc_info *prev_dcc pointer to previous DCC info
t_plugin_dcc_info *next_dcc pointer to next DCC info

Note: result has to be free by a call to "free_dcc_info" function after use.

Examples:

t_plugin_dcc_info *dcc_info = plugin->get_dcc_info (plugin);
for (ptr_dcc = dcc_info; ptr_dcc; ptr_dcc = ptr_dcc->next_dcc)
{
    plugin->print_server (plugin, "DCC type=%d, with: %s",
                          ptr_dcc->type, ptr_dcc->nick);
}
if (dcc_info)
    plugin->free_dcc_info (plugin, dcc_info);

free_dcc_info

Prototype: void free_dcc_info (t_weechat_plugin *plugin, t_plugin_dcc_info *dcc_info)

Free memory used by a DCC list.

Arguments:

  • plugin: pointer to plugin structure

  • dcc_info: pointer to DCC list returned by "get_dcc_info" function

Return value: none.

Example:

plugin->free_dcc_info (plugin, dcc_info);

get_server_info

Prototype: t_plugin_server_info *get_server_info (t_weechat_plugin *plugin)

Return list of IRC servers (connected or not).

Arguments:

  • plugin: pointer to plugin structure

Return value: linked list of IRC servers.

TypeFieldDescription
char *nameserver internal name
intautoconnect1 if autoconnect at start-up, 0 otherwise
intautoreconnect 1 if autoreconnect when disconnected, 0 otherwise
intautoreconnect_delaydelay before trying again connection
intcommand_line 1 if server was on command line (so it is temporary), 0 otherwise
char *addressserver address (host or IP)
intportport
intipv6IPv6 connection
intsslSSL connection
char *passwordserver password
char *nick1first nickname
char *nick2alternate nickname
char *nick3second alternate nickname
char *usernameuser name
char *real namereal name
char *commandcommand run once connected
intcommand_delaydelay after execution of command
char *autojoinchannels joined automatically
intautorejoin 1 if channels are rejoined when kicked, 0 otherwise
char *notify_levelschannels notify levels
char *charset_decode_isochannels charsets for decoding ISO
char *charset_decode_utfchannels charsets for decoding UTF
char *charset_encodechannels charsets for encoding messages
intis_connected1 if connected to server, 0 otherwise
intssl_connected1 if connected with SSL, 0 otherwise
char *nickcurrent nickname
intis_away1 if away, 0 otherwise
time_taway_timetime when user is marking as away
intlaglag (in milliseconds)
t_plugin_server_info *prev_serverpointer to previous server info
t_plugin_server_info *next_serverpointer to next server info

Note: result has to be free by a call to "free_server_info" function after use.

Example:

t_plugin_server_info *server_info, *ptr_server_info;
server_info = plugin->get_server_info (plugin);
if (server_info)
{
    for (ptr_server_info = server_info; ptr_server_info;
         ptr_server_info = ptr_server_info->next_server)
    {
        plugin->print (plugin, NULL, NULL,
                       "server: %s, address: %s, port: %d %s",
                       ptr_server_info->name,
                       ptr_server_info->address,
                       ptr_server_info->port,
                       (ptr_server_info->is_connected) ? "(connected)" : "");
    }
    plugin->free_server_info (plugin, server_info);
}

free_server_info

Prototype: void free_server_info (t_weechat_plugin *plugin, t_plugin_server_info *server_info)

Free memory used by server info list.

Arguments:

  • plugin: pointer to plugin structure

  • server_info: pointer to server list returned by "get_server_info" function

Return value: none.

Example:

plugin->free_server_info (plugin, server_info);

get_channel_info

Prototype: t_plugin_channel_info *get_channel_info (t_weechat_plugin *plugin, char *server)

Return list of IRC channels for a server.

Arguments:

  • plugin: pointer to plugin structure

  • server: internal server name

Return value: linked list of IRC channels for server.

TypeFieldDescription
inttype0 for a channel, 1 for a private
char *namename of channel
char *topictopic of channel
char *modeschannel modes
intlimituser limit
char *keychannel key
intnicks_countnumber of nicks on channel
t_plugin_channel_info *prev_channelpointer to previous channel info
t_plugin_channel_info *next_channelpointer to next channel info

Note: result has to be free by a call to "free_channel_info" function after use.

Example:

t_plugin_channel_info *channel_info, *ptr_chan_info;
channel_info = plugin->get_channel_info (plugin, "freenode");
if (channel_info)
{
    for (ptr_chan_info = channel_info; ptr_chan_info;
         ptr_chan_info = ptr_chan_info->next_channel)
    {
        plugin->print (plugin, NULL, NULL,
                       "  %s (type %d)",
                       ptr_chan_info->name,
                       ptr_chan_info->type);
    }
    plugin->free_channel_info (plugin, channel_info);
}

free_channel_info

Prototype: void free_channel_info (t_weechat_plugin *plugin, t_plugin_channel_info *channel_info)

Free memory used by channel info list.

Arguments:

  • plugin: pointer to plugin structure

  • channel_info: pointer to channel info list returned by "get_channel_info" function

Return value: none.

Example:

plugin->free_channel_info (plugin, channel_info);

get_nick_info

Prototype: t_plugin_nick_info *get_nick_info (t_weechat_plugin *plugin, char *server, char *channel)

Return list of nicks for a channel.

Arguments:

  • plugin: pointer to plugin structure

  • server: internal server name

  • channel: channel name

Return value: linked list of nicks on channel.

TypeFieldDescription
char *nicknick name
char *hosthostname
intflags nick flags, binary "or" between values (1 = channel owner, 2 = channel admin, 4 = op, 8 = halfop, 16 = voice, 32 = away)
t_plugin_nick_info *prev_nickpointer to previous nick info
t_plugin_nick_info *next_nickpointer to next nick info

Note: result has to be free by a call to "free_nick_info" function after use.

Example:

t_plugin_nick_info *nick_info, *ptr_nick_info;
nick_info = plugin->get_nick_info (plugin, "freenode", "#weechat");
if (nick_info)
{
    for (ptr_nick_info = nick_info; ptr_nick_info;
         ptr_nick_info = ptr_nick_info->next_nick)
    {
        plugin->print (plugin, NULL, NULL,
                       "  %s (flags: %d)",
                       ptr_nick_info->nick,
                       ptr_nick_info->flags);
    }
    plugin->free_nick_info (plugin, nick_info);
}

free_nick_info

Prototype: void free_nick_info (t_weechat_plugin *plugin, t_plugin_nick_info *nick_info)

Free memory used by nick info list.

Arguments:

  • plugin: pointer to plugin structure

  • nick_info: pointer to nick info list returned by "get_nick_info" function

Return value: none.

Example:

plugin->free_nick_info (plugin, nick_info);

get_config

Prototype: char *get_config (t_weechat_plugin *plugin, char *option)

Return value of a WeeChat config option.

Arguments:

  • plugin: pointer to plugin structure

  • option: name of option to read

Return value: option value, NULL if not found.

Note: result has to be free by a call to "free" function after use.

Examples:

char *value1 = plugin->get_config (plugin, "look_set_title");
char *value2 = plugin->get_config (plugin, "freenode.server_autojoin");

set_config

Prototype: int set_config (t_weechat_plugin *plugin, char *option, char *value)

Update value of a WeeChat config option.

Arguments:

  • plugin: pointer to plugin structure

  • option: name of option to update

  • value: new value for option

Return value: 1 if option was successfully updated, 0 if an error occurred.

Example:

plugin->set_config (plugin, "look_nicklist", "off");

get_plugin_config

Prototype: char *get_plugin_config (t_weechat_plugin *plugin, char *option)

Return value of a plugin option. Option is read from file "~/.weechat/plugins.rc" and is like: "plugin.option=value" (note: plugin name is automatically added).

Arguments:

  • plugin: pointer to plugin structure

  • option: name of option to read

Return value: option value, NULL if not found.

Note: result has to be free by a call to "free" function after use.

Example:

char *value = plugin->get_plugin_config (plugin, "my_var");

set_plugin_config

Prototype: int set_plugin_config (t_weechat_plugin *plugin, char *option, char *value)

Update value of a plugin option. Option is written in file "~/.weechat/plugins.rc" and is like: "plugin.option=value" (note: plugin name is automatically added).

Arguments:

  • plugin: pointer to plugin structure

  • option: name of option to update

  • value: new value for option

Return value: 1 if option was successfully updated, 0 if an error occurred.

Example:

plugin->set_plugin_config (plugin, "my_var", "value");

get_irc_color

Prototype: int get_irc_color (t_weechat_plugin *plugin, char *color_name)

Get IRC color index with name.

Arguments:

  • plugin: pointer to plugin structure

  • color_name: color name Allowed colors are:

    Color nameValue
    white0
    black1
    blue2
    green3
    lightred4
    red5
    magenta6
    brown7
    yellow8
    lightgreen9
    cyan10
    lightcyan11
    lightblue12
    lightmagenta13
    gray14
    lightgray15

Return value: IRC color index, -1 if color is not found.

Example:

int color_blue = plugin->get_irc_color (plugin, "blue"); /* return 2 */

input_color

Prototype: void input_color (t_weechat_plugin *plugin, int color, int start, int length)

Add color in input buffer.

Arguments:

  • plugin: pointer to plugin structure

  • color: color for text (if < 0, then input buffer is refresh, and there's no change in input buffer content)

  • start: start position for color (if < 0, then mask is reinitialized)

  • length: length for color (if <= 0, then mask is reinitialized)

Return value: none.

Example:

plugin->input_color (plugin, plugin->get_irc_color (plugin, "blue"), 10, 5);

get_window_info

Prototype: t_plugin_window_info *get_window_info (t_weechat_plugin *plugin)

Return list of WeeChat windows.

Arguments:

  • plugin: pointer to plugin structure

Return value: linked list of WeeChat windows.

TypeFieldDescription
intwin_xhorizontal position of window
intwin_yvertical position of window
intwin_widthwidth of window
intwin_heightheight of window
intwin_width_pctwidth % (compared to parent window)
intwin_height_pctheight % (compared to parent window)
intnum_buffernumber of displayed buffer
t_plugin_window_info *prev_windowpointer to previous window info
t_plugin_window_info *next_windowpointer to next window info

Note: result has to be free by a call to "free_window_info" function after use.

Example:

t_plugin_window_info *window_info, *ptr_window;

window_info = plugin->get_window_info (plugin);
if (window_info)
{
    for (ptr_window = window_info; ptr_window; ptr_window = ptr_window->next_window)
    {
        plugin->print (plugin, NULL, NULL, "--- window info ---");
        plugin->print (plugin, NULL, NULL, "(%d,%d), size: %dx%d, %%size: %d%%x%d%%",
                       ptr_window->win_x, ptr_window->win_y,
                       ptr_window->win_width, ptr_window->win_height,
                       ptr_window->win_width_pct, ptr_window->win_height_pct);
        plugin->print (plugin, NULL, NULL, "num_buffer: %d", ptr_window->num_buffer);
    }
    plugin->free_window_info (plugin, window_info);
}
else
    plugin->print (plugin, NULL, NULL, "no window info!");

free_window_info

Prototype: void free_window_info (t_weechat_plugin *plugin, t_plugin_window_info *window_info)

Free memory used by window info list.

Arguments:

  • plugin: pointer to plugin structure

  • window_info: pointer to window info list returned by "get_window_info" function

Return value: none.

Example:

plugin->free_window_info (plugin, window_info);

get_buffer_info

Prototype: t_plugin_buffer_info *get_buffer_info (t_weechat_plugin *plugin)

Return list of WeeChat buffers.

Arguments:

  • plugin: pointer to plugin structure

Return value: linked list of WeeChat buffers.

TypeFieldDescription
inttypebuffer type: 0=standard, 1=DCC, 2=raw IRC data
intnumberbuffer number
intnum_displayednumber of windows displaying buffer
char *server_nameserver name for buffer (may be NULL)
char *channel_namechannel name for buffer (may be NULL)
intnotify_levelnotify level for buffer
char *log_filenamelog filename (NULL means not logging)
t_plugin_buffer_info *prev_bufferpointer to previous buffer info
t_plugin_buffer_info *next_bufferpointer to next buffer info

Note: result has to be free by a call to "free_buffer_info" function after use.

Example:

t_plugin_buffer_info *buffer_info, *ptr_buffer;

buffer_info = plugin->get_buffer_info (plugin);
if (buffer_info)
{
    for (ptr_buffer = buffer_info; ptr_buffer; ptr_buffer = ptr_buffer->next_buffer)
    {
        plugin->print (plugin, NULL, NULL, "--- buffer info ---");
        plugin->print (plugin, NULL, NULL, "type: %d", ptr_buffer->type);
        plugin->print (plugin, NULL, NULL, "number: %d", ptr_buffer->number);
        plugin->print (plugin, NULL, NULL, "num_displayed: %d", ptr_buffer->num_displayed);
        plugin->print (plugin, NULL, NULL, "server: %s", ptr_buffer->server_name);
        plugin->print (plugin, NULL, NULL, "channel: %s", ptr_buffer->channel_name);
        plugin->print (plugin, NULL, NULL, "notify level: %d", ptr_buffer->notify_level);
        plugin->print (plugin, NULL, NULL, "log filename: %s", ptr_buffer->log_filename);
    }
    plugin->free_buffer_info (plugin, buffer_info);
}
else
    plugin->print (plugin, NULL, NULL, "no buffer info!");

free_buffer_info

Prototype: void free_buffer_info (t_weechat_plugin *plugin, t_plugin_buffer_info *buffer_info)

Free memory used by buffer info list.

Arguments:

  • plugin: pointer to plugin structure

  • buffer_info: pointer to buffer info list returned by "get_buffer_info" function

Return value: none.

Example:

plugin->free_buffer_info (plugin, buffer_info);

get_buffer_data

Prototype: t_plugin_buffer_data *get_buffer_info (t_weechat_plugin *plugin, char *server, char *channel)

Return content of buffer.

Arguments:

  • plugin: pointer to plugin structure

  • server: internal name of server

  • channel: channel name

Return value: buffer content (linked list of lines).

TypeFieldDescription
time_tdatedate and time
char *nicknick
char *dataline content (color codes are removed)
t_plugin_buffer_line *prev_linepointer to previous line
t_plugin_buffer_line *next_linepointer to next line

Note: result has to be free by a call to "free_buffer_data" function after use.

Example:

t_plugin_buffer_line *buffer_line, *ptr_line;
char text_time[256];

buffer_line = plugin->get_buffer_data (plugin);
if (buffer_line)
{
    for (ptr_line = buffer_line; ptr_line; ptr_line = ptr_line->next_line)
    {
        strftime (text_time, sizeof (text_time), "%x %X", localtime (&(ptr_line->date)));
        plugin->print (plugin, NULL, NULL, "date: %s, nick: %s, data: %s",
                       text_time, ptr_line->nick, ptr_line->data);
    }
    plugin->free_buffer_data (plugin, buffer_line);
}

free_buffer_data

Prototype: void free_buffer_data (t_weechat_plugin *plugin, t_plugin_buffer_line *buffer_line)

Free memory used by buffer line list.

Arguments:

  • plugin: pointer to plugin structure

  • buffer_line: pointer to buffer line list returned by "get_buffer_data" function

Return value: none.

Example:

plugin->free_buffer_data (plugin, buffer_line);