From 861bc2fbfdd1f6a8c3b0fc95434178bc172ea83a Mon Sep 17 00:00:00 2001 From: Sebastien Helleu Date: Mon, 10 Nov 2008 18:05:48 +0100 Subject: Add some API functions in Developer guide --- doc/en/dev/plugin_c_api.en.xml | 1186 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 1118 insertions(+), 68 deletions(-) (limited to 'doc/en/dev/plugin_c_api.en.xml') diff --git a/doc/en/dev/plugin_c_api.en.xml b/doc/en/dev/plugin_c_api.en.xml index 877e041b0..96727e95e 100644 --- a/doc/en/dev/plugin_c_api.en.xml +++ b/doc/en/dev/plugin_c_api.en.xml @@ -448,8 +448,11 @@ int weechat_strncasecmp (const char *string1, const char *string2, int max); Prototype: -int weechat_strcmp_ignore_chars (const char *string1, const char *string2, - const char *chars_ignored, int case_sensitive); +int weechat_strcmp_ignore_chars ( + const char *string1, + const char *string2, + const char *chars_ignored, + int case_sensitive); @@ -535,8 +538,10 @@ int weechat_strcasestr (const char *string, const char *search); Prototype: -int weechat_string_match (const char *string, const char *mask, - int case_sensitive); +int weechat_string_match ( + const char *string, + const char *mask, + int case_sensitive); @@ -584,7 +589,7 @@ int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */ Prototype: char *weechat_string_replace (const char *string, const char *search, - const char *replace); + const char *replace); @@ -672,8 +677,11 @@ char *weechat_string_remove_quotes (const char *string, const char *quotes); Prototype: -char *weechat_string_strip (const char *string, int left, int right, - const char *chars); +char *weechat_string_strip ( + const char *string, + int left, + int right, + const char *chars); @@ -724,8 +732,9 @@ char *weechat_string_strip (const char *string, int left, int right, Prototype: -char *weechat_string_has_highlight (const char *string, - const char highlight_words); +char *weechat_string_has_highlight ( + const char *string, + const char highlight_words); @@ -794,9 +803,10 @@ char *weechat_string_mask_to_regex (const char *mask); Prototype: -char **weechat_string_explode (const char *string, - const char *separators, int keep_eol, - int num_items_max, int *num_items); +char **weechat_string_explode ( + const char *string, + const char *separators, int keep_eol, + int num_items_max, int *num_items); @@ -915,8 +925,9 @@ weechat_string_free_exploded (, argv); Prototype: -char **weechat_string_build_with_exploded (char **exploded_string, - const char *separator); +char **weechat_string_build_with_exploded ( + char **exploded_string, + const char *separator); @@ -1662,8 +1673,10 @@ int weechat_mkdir_parents (char *directory, int mode); Prototype: -void weechat_exec_on_files (const char *directory, void *data, - int (*callback)(void *data, const char *filename)); +void weechat_exec_on_files ( + const char *directory, + void *data, + int (*callback)(void *data, const char *filename)); @@ -1686,7 +1699,30 @@ void weechat_exec_on_files (const char *directory, void *data, : function called for each file - found + found, arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + char * + filename + filename found + + + + @@ -1866,8 +1902,10 @@ struct t_weelist *weechat_list_new (); Prototype: -struct t_weelist_item *weechat_list_add (struct t_weelist *weelist, - const char *data, const char *where); +struct t_weelist_item *weechat_list_add ( + struct t_weelist *weelist, + const char *data, + const char *where); @@ -1910,8 +1948,9 @@ struct t_weelist_item *weechat_list_add (struct t_weelist *weelist, Prototype: -struct t_weelist_item *weechat_list_search (struct t_weelist *weelist, - const char *data); +struct t_weelist_item *weechat_list_search ( + struct t_weelist *weelist, + const char *data); @@ -1947,8 +1986,9 @@ struct t_weelist_item *weechat_list_search (struct t_weelist *weelist, Prototype: -struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist, - const char *data); +struct t_weelist_item *weechat_list_casesearch ( + struct t_weelist *weelist, + const char *data); @@ -1984,8 +2024,9 @@ struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist, Prototype: -struct t_weelist_item *weechat_list_get (struct t_weelist *weelist, - int position); +struct t_weelist_item *weechat_list_get ( + struct t_weelist *weelist, + int position); @@ -2181,8 +2222,9 @@ char *weechat_list_size (struct t_weelist *weelist); Prototype: -void weechat_list_remove (struct t_weelist *weelist, - struct t_weelist_item *item); +void weechat_list_remove ( + struct t_weelist *weelist, + struct t_weelist_item *item); @@ -2282,7 +2324,8 @@ void weechat_list_free (struct t_weelist *weelist); Prototype: -struct t_config_file *weechat_config_new (const char *name, +struct t_config_file *weechat_config_new ( + const char *name, int (*callback_reload)(void *data, struct t_config_file *config_file), void *callback_reload_data); @@ -2304,7 +2347,30 @@ struct t_config_file *weechat_config_new (const char *name, : callback called when configuration file is reloaded with /reload (optional, may be - NULL) + NULL), arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_config_file * + config_file + configuration file pointer + + + + @@ -2354,7 +2420,8 @@ struct t_config_file *config_file = weechat_config_new ("test", Prototype: -struct t_config_section *weechat_config_new_section (struct t_config_file *config_file, +struct t_config_section *weechat_config_new_section ( + struct t_config_file *config_file, const char *name, int user_can_add_options, int user_can_delete_options, @@ -2418,7 +2485,46 @@ struct t_config_section *weechat_config_new_section (struct t_config_file *confi : callback called when an option in section is read from disk (should be NULL for most cases, - except if options in your section need custom function) + except if options in your section need custom function), + arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_config_file * + config_file + configuration file pointer + + + struct t_config_section * + section + section pointer + + + const char * + option_name + name of option + + + const char * + value + value + + + + @@ -2432,7 +2538,40 @@ struct t_config_section *weechat_config_new_section (struct t_config_file *confi : callback called when section is written in file (should be NULL for most cases, except if your - section needs to be written by a custom function) + section needs to be written by a custom function), arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_config_file * + config_file + configuration file pointer + + + struct t_config_section * + section + section pointer + + + const char * + option_name + name of option + + + + @@ -2445,7 +2584,35 @@ struct t_config_section *weechat_config_new_section (struct t_config_file *confi : callback called when - default values for section must be written in file + default values for section must be written in file, arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_config_file * + config_file + configuration file pointer + + + char * + section_name + name of section + + + + @@ -2459,7 +2626,45 @@ struct t_config_section *weechat_config_new_section (struct t_config_file *confi : callback called when a new option is created in section (NULL if section does not allow - new options to be created) + new options to be created), arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_config_file * + config_file + configuration file pointer + + + struct t_config_section * + section + section pointer + + + const char * + option_name + name of option + + + const char * + value + value + + + + @@ -2473,7 +2678,40 @@ struct t_config_section *weechat_config_new_section (struct t_config_file *confi : callback called when an option is deleted (NULL if section does not allow options to be - deleted) + deleted), arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_config_file * + config_file + configuration file pointer + + + struct t_config_section * + section + section pointer + + + struct t_config_option *option + option + option pointer + + + + @@ -2568,8 +2806,9 @@ struct t_config_section *new_section2 = Prototype: -struct t_config_section *weechat_config_search_section (struct t_config_file *config_file, - const char *section_name); +struct t_config_section *weechat_config_search_section ( + struct t_config_file *config_file, + const char *section_name); @@ -2607,7 +2846,8 @@ struct t_config_section *section = weechat_config_search_section (config_file, " Prototype: -struct t_config_option *weechat_config_new_option (struct t_config_file *config_file, +struct t_config_option *weechat_config_new_option ( + struct t_config_file *config_file, struct t_config_section *section, const char *name, const char *type, @@ -2619,7 +2859,7 @@ struct t_config_option *weechat_config_new_option (struct t_config_file *config_ const char *value, int (*callback_check_value)(void *data, struct t_config_option *option, - const char *value), + const char *value), void *callback_check_value_data, int (*callback_change)(void *data, struct t_config_option *option), @@ -2705,7 +2945,35 @@ struct t_config_option *weechat_config_new_option (struct t_config_file *config_ : callback called to check - new value for an option (optional) + new value for an option (optional), arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_config_option * + option + option pointer + + + const char * + value + new value for option + + + + @@ -2718,7 +2986,30 @@ struct t_config_option *weechat_config_new_option (struct t_config_file *config_ : callback called when value of - option has changed (optional) + option has changed (optional), arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_config_option * + option + option pointer + + + + @@ -2731,7 +3022,30 @@ struct t_config_option *weechat_config_new_option (struct t_config_file *config_ : callback called when option - will be deleted (optional) + will be deleted (optional), arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_config_option * + option + option pointer + + + + @@ -2819,9 +3133,10 @@ struct t_config_option *option5 = Prototype: -struct t_config_option *weechat_config_search_option (struct t_config_file *config_file, - struct t_config_section *section, - const char *option_name); +struct t_config_option *weechat_config_search_option ( + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name); @@ -2865,10 +3180,11 @@ struct t_config_option *option = Prototype: -void weechat_config_search_with_string (const char *option_name, - struct t_config_file **config_file, - struct t_config_section **section, - struct t_config_option **option); +void weechat_config_search_with_string ( + const char *option_name, + struct t_config_file **config_file, + struct t_config_section **section, + struct t_config_option **option); @@ -2977,8 +3293,9 @@ else Prototype: -int weechat_config_option_reset (struct t_config_option *option, - int run_callback); +int weechat_config_option_reset ( + struct t_config_option *option, + int run_callback); @@ -3030,8 +3347,9 @@ switch (weechat_config_option_reset (option, 1)) Prototype: -int weechat_config_option_set (struct t_config_option *option, - const char *value, int run_callback); +int weechat_config_option_set ( + struct t_config_option *option, + const char *value, int run_callback); @@ -3139,8 +3457,9 @@ switch (weechat_config_option_unset (option)) Prototype: -void weechat_config_option_rename (struct t_config_option *option, - const char *new_name); +void weechat_config_option_rename ( + struct t_config_option *option, + const char *new_name); @@ -3175,8 +3494,9 @@ weechat_config_option_rename (option, "new_name"); Prototype: -void *weechat_config_option_get_pointer (struct t_config_option *option, - const char *property); +void *weechat_config_option_get_pointer ( + struct t_config_option *option, + const char *property); @@ -3417,9 +3737,10 @@ char *weechat_config_color (struct t_config_option *option); Prototype: -void weechat_config_write_line (struct t_config_file *config_file, - const char *option_name, - const char *value, ...); +void weechat_config_write_line ( + struct t_config_file *config_file, + const char *option_name, + const char *value, ...); @@ -3983,8 +4304,9 @@ weechat_printf (buffer, "Hello on this buffer"); Prototype: -void weechat_printf_date (struct t_gui_buffer *buffer, time_t date, - const char *message, ...); +void weechat_printf_date ( + struct t_gui_buffer *buffer, time_t date, + const char *message, ...); @@ -4025,8 +4347,10 @@ weechat_printf (NULL, time (NULL) - 120, "Hello, 2 minutes ago"); Prototype: -void weechat_printf_tags (struct t_gui_buffer *buffer, const char *tags, - const char *message, ...); +void weechat_printf_tags ( + struct t_gui_buffer *buffer, + const char *tags, + const char *message, ...); @@ -4067,8 +4391,11 @@ weechat_printf_tags (NULL, "notify_message", "Hello with a message notify tag"); Prototype: -void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date, - const char *tags, const char *message, ...); +void weechat_printf_date_tags ( + struct t_gui_buffer *buffer, + time_t date, + const char *tags, + const char *message, ...); @@ -4115,8 +4442,10 @@ weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message", Prototype: -void weechat_printf_y (struct t_gui_buffer *buffer, int y, - const char *message, ...); +void weechat_printf_y ( + struct t_gui_buffer *buffer, + int y, + const char *message, ...); @@ -4148,6 +4477,727 @@ void weechat_printf_y (struct t_gui_buffer *buffer, int y, Example: weechat_printf_y (buffer, 2, "My message on third line"); + + + + + + + + +
+ Hooks + + + Functions to hook/unhook something. + + +
+ weechat_hook_command + + + Prototype: + +struct t_hook *weechat_hook_command ( + const char *command, + const char *description, + const char *args, + const char *args_description, + const char *completion, + int (*callback)(void *data, + struct t_gui_buffer *buffer, + int argc, char **argv, + char **argv_eol), + void *callback_data); + + + + Hook a command. + + + Arguments: + + + + : new command name + + + + + : description of command (displayed + with /help command) + + + + + : arguments for command (displayed with + /help command) + + + + + : description of arguments + (displayed with /help command) + + + + + : completion template for command: + list of completions for each arguments, separated by space. Many + completions are possible for one argument, separated by "|". + Default completion codes are: + + + + + Code + Completion + + + + + %- + Stop completion + + + %* + Repeat last completion + + + %b + Buffers names + + + %c + Configuration files + + + %f + Filename + + + %F + Filters + + + %h + Commands hooked + + + %i + Infos hooked + + + %I + Infolists hooked + + + %n + Nick + + + %o + Configuration option + + + %p + Plugin name + + + %P + Plygin commands + + + %r + Bar names + + + %v + Value of configuration opeion + + + %w + WeeChat commands + + + %(xxx) + Custom completion by plugin (xxx is a completion + code added by a plugin) + + + + + + + + + : function called when command is used, + arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_gui_buffer * + buffer + buffer where command is executed + + + int + argc + argument count + + + char ** + argv + arguments + + + char ** + argv_eol + arguments (until end of line) + + + + + + + For example, if command called is + /command abc def ghi, then argv and argv_eol + contain following values: + + argv[0] == "abc" + argv[1] == "def" + argv[2] == "ghi" + argv_eol[0] == "abc def ghi" + argv_eol[1] == "def ghi" + argv_eol[2] == "ghi" + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Example: + +int +my_command_cb (void *data, struct t_gui_buffer *buffer, int argc, + char **argv, char **argv_eol) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +struct t_hook *my_command = weechat_hook_command ("mycommand", + "description of my command", + "[command [buffer]]", + "command: WeeChat or plugin command\n" + " buffer: buffer name", + "%w|%p %b", &my_command_cb, NULL); + + +
+ +
+ weechat_hook_timer + + + Prototype: + +struct t_hook *weechat_hook_timer ( + long interval, + const char *align_second, + const char *max_calls, + int (*callback)(void *data), + void *callback_data); + + + + Hook a timer. + + + Arguments: + + + + : interval between two calls + (milliseconds, so 1000 = 1 second) + + + + + : alignment on a second: align timer + on a second. For example, if current time is 09:00, if + interval = 60000 (60 seconds), and align_second = 60, then timer + is called each minute when second is 00. + + + + + : number of calls to timer (if 0, then + timer has no end) + + + + + : function called when time is reached, + arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Example: + +int +my_timer_cb (void *data) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +/* timer called each 20 seconds */ +struct t_hook *my_timer = weechat_hook_timer (20 * 1000, 0, 0, + &my_timer_cb, NULL); + + +
+ +
+ weechat_hook_fd + + + Prototype: + +struct t_hook *weechat_hook_fd ( + int fd, + int flag_read, + int flag_write, + int flag_exception, + int (*callback)(void *data), + void *callback_data); + + + + Hook a file descriptor (file or socket). + + + Arguments: + + + + : file descriptor + + + + + : 1 for catching read event, 0 for + ignoring it + + + + + : 1 for catching write event, 0 for + ignoring it + + + + + : 1 for catching exception event, + 0 for ignoring it + + + + + : function called when a selected event + occurs, arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Example: + +int +my_fd_cb (void *data) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +int sock = socket (AF_INET, SOCK_STREAM, 0); +/* set socket options */ +/* ... */ +/* hook socket */ +struct t_hook *my_fd = weechat_hook_fd (sock, + 1, 0, 0, + &my_fd_cb, NULL); + + +
+ +
+ weechat_hook_connect + + + Prototype: + +struct t_hook *weechat_hook_connect ( + const char *address, + int port, + int sock, + int ipv6, + void *gnutls_sess, + const char *local_hostname, + int (*callback)(void *data, + int status, + const char *ip_address), + void *callback_data); + + + + Hook a connection (background connection to a remote host). + + + Arguments: + + + + : name or IP address to connect to + + + + + : port number + + + + + : socket used to connect + + + + + : 1 to use IPv6, 0 to use IPv4 + + + + + : GnuTLS session (optional) + + + + + : function called when connection is ok + or failed, arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + int + status + + constant with connection status: + + + WEECHAT_HOOK_CONNECT_OK + + + WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND + + + WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND + + + WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED + + + WEECHAT_HOOK_CONNECT_PROXY_ERROR + + + WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR + + + WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR + + + WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR + + + WEECHAT_HOOK_CONNECT_MEMORY_ERROR + + + + + + void * + data + pointer + + + + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Example: + +int +my_connect_cb (void *data, int status, const char *ip_address) +{ + switch (status) + { + case WEECHAT_HOOK_CONNECT_OK: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_PROXY_ERROR: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: + /* ... */ + break; + case WEECHAT_HOOK_CONNECT_MEMORY_ERROR: + /* ... */ + break; + } + return WEECHAT_RC_OK; +} + +struct t_hook *my_connect = weechat_hook_fd (sock, + 1, 0, 0, + &my_connect_cb, NULL); + + +
+ +
+ weechat_hook_print + + + Prototype: + +struct t_hook *weechat_hook_print ( + struct t_gui_buffer *buffer, + const char *tags, + const char *message, + int strip_colors, + int (*callback)(void *data, + struct t_gui_buffer *buffer, + time_t date, + int tags_count, + const char **tags, + const char *prefix, + const char *message), + void *callback_data); + + + + Hook a message printed. + + + Arguments: + + + + : buffer pointer, if NULL, messages from + any buffer are catched + + + + + : only messages with these tags (comma + separated list) will be catched (optional) + + + + + : only messages with this string will be + catched (optional) + + + + + : colors will be stripped from + message displayed, before calling callback + + + + + : function called when message is + printed, arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_gui_buffer * + buffer + buffer pointer + + + time_t + date + date + + + int + tags_count + number of tags for line + + + const char ** + tags + tags for line + + + const char * + prefix + prefix + + + char * + message + message + + + + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Example: + +int +my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date, + int tags_count, const char **tags, + const char *prefix, const char *message) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +/* catch all messages, on all buffers, without color */ +struct t_hook *my_print = weechat_hook_print (NULL, NULL, NULL, 1, + &my_print_cb, NULL);
-- cgit v1.2.3