From af12f3e99cf9b05f6eb31e326f1a569bf8b8b002 Mon Sep 17 00:00:00 2001 From: Sebastien Helleu Date: Sun, 24 Feb 2008 10:45:55 +0100 Subject: XML doc files (weechat.XX.xml) splitted in many XML files --- doc/en/plugin_api.en.xml | 3528 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3528 insertions(+) create mode 100644 doc/en/plugin_api.en.xml (limited to 'doc/en/plugin_api.en.xml') diff --git a/doc/en/plugin_api.en.xml b/doc/en/plugin_api.en.xml new file mode 100644 index 000000000..3fb993bc7 --- /dev/null +++ b/doc/en/plugin_api.en.xml @@ -0,0 +1,3528 @@ + + + + +
+ API functions + +
+ set_charset + + + Prototype: + + void set_charset (t_weechat_plugin *plugin, char *charset) + + + + Set new plugin charset. + + + Arguments: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : charset to convert + + + + + : 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: + + + + : pointer to plugin structure + + + + + : target charset + + + + + : 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: + + + + : pointer to plugin structure + + + + + : first string for comparison + + + + + : 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: + + + + : pointer to plugin struct + + + + + : first string for comparison + + + + + : second string for comparison + + + + + : 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: + + + + : pointer to plugin struct + + + + + : string to explode + + + + + : delimiters used for explosion + + + + + : maximum number of items + created (0 = no limit) + + + + + : 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : directory for searching files + + + + + : 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: + + + + : pointer to plugin structure + + + + + : internal name of server to find + buffer for message display (may be NULL) + + + + + : name of channel to find buffer + for message display (may be NULL) + + + + + : message + + + + + + To display colored text, there are following codes: + + + + + Code + Description + + + + + 0x02 + + bold text + + + + 0x03 + "xx" + + text color "xx" + (see for colors) + + + + 0x03 + "xx,yy" + + text color "xx" + and background "yy" + (see for colors) + + + + 0x0F + + disable color and attributes + + + + 0x12 + + reverse video (revert text color with background) + + + + 0x1F + + underlined text + + + + + + Note: the same code (without number for 0x03) may be used to stop + the attribute. + + + Return value: none. + + + Examples: + +plugin->print (plugin, NULL, NULL, "hello"); +plugin->print (plugin, NULL, "#weechat", "hello"); +plugin->print (plugin, "freenode", "#weechat", "hello"); +plugin->print (plugin, NULL, NULL, + "test: \x02 bold \x0F\x03%02d blue \x03%02d green", + plugin->get_irc_color (plugin, "blue"), + plugin->get_irc_color (plugin, "green")); + + +
+ +
+ print_server + + + Prototype: + + void print_server (t_weechat_plugin *plugin, + char *message, ...) + + + + Display a message on current server buffer. + + + Arguments: + + + + : pointer to plugin structure + + + + + : message + + + + + + To display colored text, see . + + + 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : internal name of server to find + buffer for log (may be NULL) + + + + + : name of channel to find buffer + for log (may be NULL) + + + + + : 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + + Name + Description + + + + + weechat_pv + private 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 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 + + + + + + + : arguments given to function + when called + + + + + : 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: + + + + : pointer to plugin structure + + + + + : the new command name, which + may be an existing command (be careful, replaced command + will not be available until plugin is unloaded) + + + + + : short command description + (displayed by /help command) + + + + + : short description of command + arguments (displayed by /help command) + + + + + : long description + of command arguments (displayed by /help command) + + + + + : 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: + + + + + Code + Description + + + + + %- + no completion for argument + + + %* + + repeat last completion for all following arguments + (this code has to be at the end of completion + template, preceded by "|") + + + + %a + alias + + + %A + + alias and commands (WeeChat, IRC and plugins) + + + + %c + current channel + + + %C + all channels (including queries) + + + %f + file name + + + %h + plugins commands + + + %i + IRC commands (sent) + + + %I + IRC commands (received) + + + %k + key functions + + + %m + nick on current server + + + %M + + nicks on current server (on all open channels) + + + + %n + nicks of current channel + + + %N + nicks and hostnames of current channel + + + %o + setup options + + + %O + plugin options + + + %p + default "part" message + + + %q + default "quit" message + + + %s + current server name + + + %S + all servers names + + + %t + topic of current channel + + + %v + setup option value + + + %V + plugin option value + + + %w + WeeChat commands + + + + + + + + + : 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 + + + + + + + : arguments given to function + when called + + + + + : 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: + + + + : pointer to plugin structure + + + + + : interval (in seconds) between + two calls of 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. + + + + + : arguments given to function + when called + + + + + : 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: + + + + : pointer to plugin structure + + + + + : 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 + + + + + + + + : arguments given to function + when called + + + + + : 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: + + + + : pointer to plugin structure + + + + + : event (see table below) + + + + + : function called + + + It uses following prototype: + + int my_function (t_weechat_plugin *plugin, + int argc, char **argv, + char *handler_args, void *handler_pointer) + + + + Arguments depend on event (see table below). + + + + + : arguments given to function + when called + + + + + : pointer given to function + when called + + + + + + List of events: + + + + + Event + Description + Arguments + + + + + buffer_open + a buffer was open + + argc = 1, argv = { buffer number } + + + + buffer_close + a buffer was closed + + argc = 1, argv = { buffer number } + + + + buffer_move + a buffer was moved + + argc = 2, argv = { new buffer number, old number } + + + + + + + + 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : 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: + + + + : pointer to plugin structure + + + + + : modifier type: + + + + + Type + Description + + + + + irc_in + called 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) + + + + + + + + + + : 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 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 + + + + + + + : arguments given to function + when called + + + + + : 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : 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: + + + + : pointer to plugin structure + + + + + : internal name of server for + executing command (may be NULL) + + + + + : name of channel for executing + command (may be NULL) + + + + + : 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: + + + + : pointer to plugin structure + + + + + : name of info to read: + + + + + Info + Description + + + + + version + WeeChat's version + + + nick + nick + + + channel + + name of channel (NULL for a server or private) + + + + server + name 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_libdir + WeeChat system lib directory + + + weechat_sharedir + WeeChat system share directory + + + + + + + + + : 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: + + + + : pointer to plugin structure + + + + + + Return value: linked list of DCC. + + + + + Type + Field + Description + + + + + char * + server + IRC server + + + char * + channel + IRC channel + + + int + type + + 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_t + start_time + date/time of DCC creation + + + time_t + start_transfer + date/time of DCC transfer start + + + unsigned long + addr + IP address of remote user + + + int + port + port used for DCC + + + char * + nick + remote nick + + + char * + filename + file name + + + char * + local_filename + local file name + + + int + filename_suffix + suffix if renaming file + + + unsigned long + size + file size + + + unsigned long + pos + position in file + + + unsigned long + start_resume + start position after interruption + + + unsigned long + bytes_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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + + Return value: linked list of IRC servers. + + + + + Type + Field + Description + + + + + char * + name + server internal name + + + int + autoconnect + 1 if autoconnect at start-up, 0 otherwise + + + int + autoreconnect + + 1 if autoreconnect when disconnected, + 0 otherwise + + + + int + autoreconnect_delay + delay before trying again connection + + + int + command_line + + 1 if server was on command line (so it is temporary), + 0 otherwise + + + + char * + address + server address (host or IP) + + + int + port + port + + + int + ipv6 + IPv6 connection + + + int + ssl + SSL connection + + + char * + password + server password + + + char * + nick1 + first nickname + + + char * + nick2 + alternate nickname + + + char * + nick3 + second alternate nickname + + + char * + username + user name + + + char * + real name + real name + + + char * + command + command run once connected + + + int + command_delay + delay after execution of command + + + char * + autojoin + channels joined automatically + + + int + autorejoin + + 1 if channels are rejoined when kicked, + 0 otherwise + + + + char * + notify_levels + channels notify levels + + + char * + charset_decode_iso + channels charsets for decoding ISO + + + char * + charset_decode_utf + channels charsets for decoding UTF + + + char * + charset_encode + channels charsets for encoding messages + + + int + is_connected + 1 if connected to server, 0 otherwise + + + int + ssl_connected + 1 if connected with SSL, 0 otherwise + + + char * + nick + current nickname + + + int + is_away + 1 if away, 0 otherwise + + + time_t + away_time + time when user is marking as away + + + int + lag + lag (in milliseconds) + + + t_plugin_server_info * + prev_server + pointer to previous server info + + + t_plugin_server_info * + next_server + pointer 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : internal server name + + + + + + Return value: linked list of IRC channels for server. + + + + + Type + Field + Description + + + + + int + type + 0 for a channel, 1 for a private + + + char * + name + name of channel + + + char * + topic + topic of channel + + + char * + modes + channel modes + + + int + limit + user limit + + + char * + key + channel key + + + int + nicks_count + number of nicks on channel + + + t_plugin_channel_info * + prev_channel + pointer to previous channel info + + + t_plugin_channel_info * + next_channel + pointer 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : internal server name + + + + + : channel name + + + + + + Return value: linked list of nicks on channel. + + + + + Type + Field + Description + + + + + char * + nick + nick name + + + char * + host + hostname + + + int + flags + + 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_nick + pointer to previous nick info + + + t_plugin_nick_info * + next_nick + pointer 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : name of option to update + + + + + : 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : name of option to update + + + + + : 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: + + + + : pointer to plugin structure + + + + + : color name + Allowed colors are: + + + + + Color name + Value + + + + + white + 0 + + + black + 1 + + + blue + 2 + + + green + 3 + + + lightred + 4 + + + red + 5 + + + magenta + 6 + + + brown + 7 + + + yellow + 8 + + + lightgreen + 9 + + + cyan + 10 + + + lightcyan + 11 + + + lightblue + 12 + + + lightmagenta + 13 + + + gray + 14 + + + lightgray + 15 + + + + + + + + + + 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: + + + + : pointer to plugin structure + + + + + : color for text (if < 0, then input + buffer is refresh, and there's no change in input buffer + content) + + + + + : start position for color (if < 0, + then mask is reinitialized) + + + + + : 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: + + + + : pointer to plugin structure + + + + + + Return value: linked list of WeeChat windows. + + + + + Type + Field + Description + + + + + int + win_x + horizontal position of window + + + int + win_y + vertical position of window + + + int + win_width + width of window + + + int + win_height + height of window + + + int + win_width_pct + width % (compared to parent window) + + + int + win_height_pct + height % (compared to parent window) + + + int + num_buffer + number of displayed buffer + + + t_plugin_window_info * + prev_window + pointer to previous window info + + + t_plugin_window_info * + next_window + pointer 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + + Return value: linked list of WeeChat buffers. + + + + + Type + Field + Description + + + + + int + type + buffer type: 0=standard, 1=DCC, 2=raw IRC data + + + int + number + buffer number + + + int + num_displayed + number of windows displaying buffer + + + char * + server_name + server name for buffer (may be NULL) + + + char * + channel_name + channel name for buffer (may be NULL) + + + int + notify_level + notify level for buffer + + + char * + log_filename + log filename (NULL means not logging) + + + t_plugin_buffer_info * + prev_buffer + pointer to previous buffer info + + + t_plugin_buffer_info * + next_buffer + pointer 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: + + + + : pointer to plugin structure + + + + + : 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: + + + + : pointer to plugin structure + + + + + : internal name of server + + + + + : channel name + + + + + + Return value: buffer content (linked list of lines). + + + + + Type + Field + Description + + + + + time_t + date + date and time + + + char * + nick + nick + + + char * + data + line content (color codes are removed) + + + t_plugin_buffer_line * + prev_line + pointer to previous line + + + t_plugin_buffer_line * + next_line + pointer 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: + + + + : pointer to plugin structure + + + + + : pointer to buffer line list + returned by "get_buffer_data" function + + + + + + Return value: none. + + + Example: + plugin->free_buffer_data (plugin, buffer_line); + +
+ +
-- cgit v1.2.3