From 45716ee2138e04fd347c136c78d3580f938d9b5f Mon Sep 17 00:00:00 2001 From: Sebastien Helleu Date: Thu, 27 Nov 2008 17:06:41 +0100 Subject: Add new plugin API functions in english developer guide --- doc/en/dev/plugin_c_api.en.xml | 1148 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 1117 insertions(+), 31 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 956a79c12..c02711127 100644 --- a/doc/en/dev/plugin_c_api.en.xml +++ b/doc/en/dev/plugin_c_api.en.xml @@ -1752,7 +1752,7 @@ void weechat_exec_on_files ( pointer - char * + const char * filename filename found @@ -2642,7 +2642,7 @@ struct t_config_section *weechat_config_new_section ( configuration file pointer - char * + const char * section_name name of section @@ -4730,6 +4730,9 @@ struct t_hook *weechat_hook_command ( + + Return value: pointer to new hook, NULL if error occured. + Example: @@ -4741,12 +4744,13 @@ my_command_cb (void *data, struct t_gui_buffer *buffer, int argc, 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); +struct t_hook *my_command_hook = + 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); @@ -4823,6 +4827,9 @@ struct t_hook *weechat_hook_timer ( + + Return value: pointer to new hook, NULL if error occured. + Example: @@ -4834,8 +4841,8 @@ my_timer_cb (void *data) } /* timer called each 20 seconds */ -struct t_hook *my_timer = weechat_hook_timer (20 * 1000, 0, 0, - &my_timer_cb, NULL); +struct t_hook *my_timer_hook = + weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL); @@ -4916,6 +4923,9 @@ struct t_hook *weechat_hook_fd ( + + Return value: pointer to new hook, NULL if error occured. + Example: @@ -4930,9 +4940,8 @@ 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); +struct t_hook *my_fd_hook = + weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL); @@ -5060,6 +5069,9 @@ struct t_hook *weechat_hook_connect ( + + Return value: pointer to new hook, NULL if error occured. + Example: @@ -5099,9 +5111,8 @@ my_connect_cb (void *data, int status, const char *ip_address) return WEECHAT_RC_OK; } -struct t_hook *my_connect = weechat_hook_fd (sock, - 1, 0, 0, - &my_connect_cb, NULL); +struct t_hook *my_connect_hook = + weechat_hook_fd (sock, 1, 0, 0, &my_connect_cb, NULL); @@ -5202,7 +5213,7 @@ struct t_hook *weechat_hook_print ( prefix - char * + const char * message message @@ -5219,6 +5230,9 @@ struct t_hook *weechat_hook_print ( + + Return value: pointer to new hook, NULL if error occured. + Example: @@ -5232,26 +5246,1098 @@ my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date, } /* catch all messages, on all buffers, without color */ -struct t_hook *my_print = weechat_hook_print (NULL, NULL, NULL, 1, - &my_print_cb, NULL); +struct t_hook *my_print_hook = + weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL); - - - - -
- Buffers +
+ weechat_hook_signal + + + Prototype: + +struct t_hook *weechat_hook_signal ( + const char *signal, + int (*callback)(void *data, + const char *signal, + const char *type_data, + void *signal_data), + void *callback_data); + + + + Hook a signal. + + + Arguments: + + + + : signal to catch + + + + + : function called when signal is + received, arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + const char * + signal + signal received + + + const char * + type_data + + type of data sent with signal: + WEECHAT_HOOK_SIGNAL_STRING, WEECHAT_HOOK_SIGNAL_INT + or WEECHAT_HOOK_SIGNAL_POINTER + + + + void * + signal_data + data sent with signal + + + + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Return value: pointer to new hook, NULL if error occured. + + + Example: + +int +my_signal_cb (void *data, const char *signal, const char *type_data, + void *signal_data) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +/* catch signal "quit", sent by WeeChat when /quit command is executed */ +struct t_hook *my_signal_hook = + weechat_hook_signal ("quit", &my_signal_cb, NULL); + + +
- - Functions to create/query/close buffers. - +
+ weechat_hook_signal_send + + + Prototype: + +void weechat_hook_signal_send ( + const char *signal, + const chat *type_data, + void *signal_data); + + + + Send a signal. + + + Arguments: + + + + : signal to send + + + + + : type of data sent with signal + (see ) + + + + + : data sent with signal + + + + + + Example: + +weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string); + + +
- - Missing doc! - +
+ weechat_hook_config + + + Prototype: + +struct t_hook *weechat_hook_config ( + const char *option, + int (*callback)(void *data, + const char *option, + const char *value), + void *callback_data); + + + + Hook a configuration option. + + + Arguments: + + + + : option, format is full name, as used + with /set command (for example: + weechat.look.item_time_format) + + + + + : function called when configuration + option is changed, arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + const char * + option + name of option + + + const char * + value + new value for option + + + + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Return value: pointer to new hook, NULL if error occured. + + + Example: + +int +my_config_cb (void *data, const char *option, const char *value) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +/* catch changes to option "weechat.look.item_time_format" */ +struct t_hook *my_config_hook = + weechat_hook_config ("weechat.look.item_time_format", + &my_config_cb, NULL); + + +
+ +
+ weechat_hook_completion + + + Prototype: + +struct t_hook *weechat_hook_completion ( + const char *completion_item, + int (*callback)(void *data, + const char *completion_item, + struct t_gui_buffer *buffer, + struct t_gui_completion *completion), + void *callback_data); + + + + Hook a completion. + + + Arguments: + + + + : name of completion item, + after you can use %(name) in a command hooked + (argument "completion", see + ) + + + + + : function called when completion item + is used (user is completing something using this item), + arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + const char * + completion_item + name of completion item + + + struct t_gui_buffer * + buffer + buffer where completion was done + + + struct t_gui_completion * + completion + + structure used to add words for completion + (see + ) + + + + + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Return value: pointer to new hook, NULL if error occured. + + + Example: + +int +my_completion_cb (void *data, const char *completion_item, + struct t_gui_buffer *buffer, + struct t_gui_completion *completion) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +struct t_hook *my_completion_hook = + weechat_hook_completion ("myitem", + &my_completion_cb, NULL); + + +
+ +
+ weechat_hook_completion_list_add + + + Prototype: + +void weechat_hook_completion_list_add ( + struct t_gui_completion *completion, + const char *word, + int nick_completion, + const char *where); + + + + Add a word for a completion. + + + Arguments: + + + + : completion pointer + + + + + : word to add + + + + + : 1 if word is a nick, 0 if word + is not a nick + + + + + : position where word will be inserted in + list: WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING or + WEECHAT_LIST_POS_END + + + + + + Example: + +int +my_completion_cb (void *data, const char *completion_item, + struct t_gui_buffer *buffer, + struct t_gui_completion *completion) +{ + weechat_hook_completion_list_add (completion, "word1", + 0, WEECHAT_LIST_POS_SORT); + weechat_hook_completion_list_add (completion, "test_word2", + 0, WEECHAT_LIST_POS_SORT); + return WEECHAT_RC_OK; +} + +struct t_hook *my_completion_hook = + weechat_hook_completion ("myitem", + &my_completion_cb, NULL); + + +
+ +
+ weechat_hook_modifier + + + Prototype: + +struct t_hook *weechat_hook_modifier ( + const char *modifier, + char *(*callback)(void *data, + const char *modifier, + const char *modifier_data, + const char *string), + void *callback_data); + + + + Hook a modifier. + + + Arguments: + + + + : modifier name (you should look at + core and plugins doc to find name of existing modifiers) + + + + + : function called when modifier is + received, arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + const char * + modifier + name of modifier + + + const char * + modifier_data + modifier data + + + const char * + string + + string to modify (function must return copy of this + string, no changes are allowed in this string) + + + + + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Return value: pointer to new hook, NULL if error occured. + + + Example: + +char * +my_modifier_cb (void *data, const char *modifier, + const char *modifier_data, + const char *string) +{ + char *result; + int length; + + if (!string) + return NULL; + + length = strlen (string) + 4; + result = malloc (length); + if (result) + { + /* add "xxx" to any message printed */ + snprintf (result, length, "%s xxx", string); + } + + return result; +} + +struct t_hook *my_modifier_hook = + weechat_hook_modifier ("weechat_print", + &my_modifier_cb, NULL); + + +
+ +
+ weechat_hook_modifier_exec + + + Prototype: + +char *weechat_hook_modifier_exec ( + const char *modifier, + const char *modifier_data, + const char *string); + + + + Execute modifier(s). + + + Arguments: + + + + : modifier name + + + + + : modifier data + + + + + : string to modify + + + + + + Return value: string modified, NULL if no changes in string were + made by modifier(s). + + + Example: + + char *new_string = + weechat_hook_modifier_exec ("my_modifier", my_data, my_string); + + +
+ +
+ weechat_hook_info + + + Prototype: + +struct t_hook *weechat_hook_info ( + const char *info_name, + const char *description, + const char *(*callback)(void *data, + const char *info_name, + const char *arguments), + void *callback_data); + + + + Hook an information: callback will return pointer to info asked. + + + Arguments: + + + + : name of info + + + + + : description + + + + + : function called when info is asked, + arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + const char * + info_name + name of info to return + + + const char * + arguments + additional arguments, depending on info + + + + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Return value: pointer to new hook, NULL if error occured. + + + Example: + +const char * +my_info_cb (void *data, const char *info_name, const char *arguments) +{ + /* ... */ + return pointer_to_string; +} + +/* add info "my_info" */ +struct t_hook *my_info = + weechat_hook_info ("my_info", "Some info about something", + &my_info_cb, NULL); + + +
+ +
+ weechat_hook_infolist + + + Prototype: + +struct t_hook *weechat_hook_infolist ( + const char *infolist_name, + const char *description, + const char *(*callback)(void *data, + const char *infolist_name, + void *pointer, + const char *arguments), + void *callback_data); + + + + Hook an infolist: callback will return pointer to infolist asked. + + + Arguments: + + + + : name of infolist + + + + + : description + + + + + : function called when infolist is asked, + arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + const char * + infolist_name + name of infolist to return + + + void * + pointer + + pointer to an item infolist must return (to get only + one item in infolist) + + + + const char * + arguments + additional arguments, depending on infolist + + + + + + + + + : pointer given to callback when it + is called by WeeeChat + + + + + + Return value: pointer to new hook, NULL if error occured. + + + Example: + +struct t_infolist * +my_infolist_cb (void *data, const char *infolist_name, void *pointer, + const char *arguments) +{ + /* ... build infolist ... */ + return my_infolist; +} + +/* add info "my_infolist" */ +struct t_hook *my_infolist = + weechat_hook_infolist ("my_infolist", "Infolist with some data", + &my_infolist_cb, NULL); + + +
+ +
+ weechat_unhook + + + Prototype: + +void weechat_unhook (struct t_hook *hook); + + + + Unhook something hooked. + + + Arguments: + + + + : something hooked with weechat_hook_xxxx() + + + + + + Example: + +struct t_hook *my_hook = weechat_hook_command (...); +/* ... */ +weechat_unhook (my_hook); + + +
+ +
+ weechat_unhook_all + + + Prototype: + +void weechat_unhook_all (); + + + + Unhook everything that has been hooked by current plugin. + + + Example: + +weechat_unhook_all (); + + +
+ +
+ + + +
+ Buffers + + + Functions to create/query/close buffers. + + +
+ weechat_buffer_new + + + Prototype: + +struct t_gui_buffer *weechat_buffer_new ( + const char *name, + int (*input_callback)(void *data, + struct t_gui_buffer *buffer, + const char *input_data), + void *input_callback_data, + int (*close_callback)(void *data, + struct t_gui_buffer *buffer), + void *close_callback_data); + + + + Open a new buffer. + + + Arguments: + + + + : name of buffer (must be unique) + + + + + : function called when input text + is entered on buffer, arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_gui_buffer * + buffer + buffer pointer + + + const char * + input_data + input data + + + + + + + + + : pointer given to input + callback when it is called by WeeeChat + + + + + : function called when buffer is + closed, arguments: + + + + + Type + Name + Description + + + + + void * + data + pointer + + + struct t_gui_buffer * + buffer + buffer pointer + + + + + + + + + : pointer given to close + callback when it is called by WeeeChat + + + + + + Return value: pointer to new buffer, NULL if error occured. + + + Example: + +int +my_input_cb (void *data, struct t_gui_buffer *buffer, const char *input_data) +{ + weechat_printf (buffer, "Text: %s", input_data); + return WEECHAT_RC_OK; +} + +int +my_close_cb (void *data, struct t_gui_buffer *buffer) +{ + weechat_printf (NULL, "Buffer '%s' will be closed!", + weechat_buffer_get_string (buffer, "name")); + return WEECHAT_RC_OK; +} + +struct t_gui_buffer *my_buffer = + weechat_buffer_new ("my_buffer", + &my_input_cb, NULL, &my_close_cb, NULL); + + +
+ +
+ weechat_current_buffer + + + Prototype: + +struct t_gui_buffer *weechat_current_buffer (); + + + + Return pointer to current buffer (buffer displayed by current window). + + + Return value: pointer to current buffer. + + + Example: + +struct t_gui_buffer *current_buffer = weechat_current_buffer (); + + +
+ + + +
+ weechat_buffer_clear + + + Prototype: + +void weechat_buffer_clear (struct t_gui_buffer *buffer); + + + + Clear content of a buffer. + + + Arguments: + + + + : buffer pointer + + + + + + Example: + +struct t_gui_buffer *my_buffer = weechat_buffer_search ("myplugin", "my_buffer"); +if (my_buffer) +{ + weechat_buffer_clear (my_buffer); +} + + +
+ +
+ weechat_buffer_close + + + Prototype: + +void weechat_buffer_close (struct t_gui_buffer *buffer) + + + + Close a buffer. + + + Arguments: + + + + : buffer pointer + + + + + + Example: + +struct t_gui_buffer *my_buffer = + weechat_buffer_new ("my_buffer", + &my_input_cb, NULL, &my_close_cb, NULL); +/* ... */ +weechat_buffer_close (my_buffer); + + +
-- cgit v1.2.3