API functions

ascii_strcasecmp
ascii_strncasecmp
explode_string
free_exploded_string
exec_on_files
printf
printf_server
printf_infobar
msg_handler_add
cmd_handler_add
handler_remove
handler_remove_all
exec_command
get_info
get_dcc_info
free_dcc_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 tu 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->printf_server (plugin, "file: %s", file);
    return 1;
}
...
plugin->exec_on_files (plugin, "/tmp", &callback);

printf

Prototype: void printf (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->printf (plugin, NULL, NULL, "hello");
plugin->printf (plugin, NULL, "#weechat", "hello");
plugin->printf (plugin, "freenode", "#weechat", "hello");

printf_server

Prototype: void printf_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->printf_server (plugin, "hello");

printf_infobar

Prototype: void printf_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->printf_infobar (plugin, 5, "hello");

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

  • 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->printf (plugin, serveur, 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 commandes (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 successfulle completed

Example:

int cmd_test (t_weechat_plugin *plugin, char *server,
              char *command, char *arguments, char *handler_args,
              void *handler_pointer)
{
    plugin->printf (plugin, serveur, 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);

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
    weechat_dir WeeChat home dir (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");

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.

FieldDescription
serverIRC server
channelIRC channel
type DCC type: 0 = chat received, 1 = chat sent, 2 = file received, 3 = file sent
status DCC status: 0 = waiting, 1 = connecting, 2 = active, 3 = finished, 4 = failed, 5 = interrupted by user
start_timedate/time of DCC creation
start_transferdate/time of DCC transfert start
addrIP address of remote user
portport used for DCC
nickremote nick
filenamefile name
local_filenamelocal file name
sizefile size
posposition in file
start_resumestart position after interruption
bytes_per_sec number of bytes per second since transfert start

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->printf_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_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 occured.

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