API functions

ascii_strcasecmp
ascii_strncasecmp
explode_string
free_exploded_string
exec_on_files
print
print_server
print_infobar
infobar_remove
log
msg_handler_add
cmd_handler_add
timer_handler_add
handler_remove
handler_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

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

exec_on_files

Prototype: void exec_on_files (t_weechat_plugin *plugin, char *repertoire, 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. 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

  • 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

Example:

int msg_kick (t_weechat_plugin *plugin, char *server, char *command,
              char *arguments, char *handler_args, void *handler_pointer)
{
    plugin->print (plugin, server, NULL, "KICK received");
    return PLUGIN_RC_OK;
}
...
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 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
    %Cchannels of current server
    %hplugins commands
    %iIRC commands (sent)
    %IIRC commands (received)
    %kkey functions
    %nnicks of current channel
    %osetup options
    %pdefault "part" message
    %qdefault "quit" message
    %scurrent server name
    %Sall servers names
    %ttopic of current channel
    %vsetup option value
    %wWeeChat commands

  • function: function called when command is executed

  • 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, char *server,
              char *command, char *arguments, char *handler_args,
              void *handler_pointer)
{
    plugin->print (plugin, server, NULL,
                   "test command, nick: %s",
                   (arguments) ? arguments : "none");
    return PLUGIN_RC_OK;
}
...
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

  • 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_timer (t_weechat_plugin *plugin, char *server, char *command,
              char *arguments, char *handler_args, void *handler_pointer)
{
    plugin->print (plugin, NULL, NULL, "my timer");
    return PLUGIN_RC_OK;
}
...
plugin->timer_handler_add (plugin, 60, &my_timer);

handler_remove

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

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

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
    away"away" flag
    inactivity number of seconds since last key was pressed
    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);

free (version);
free (nick);
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
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");