diff options
| -rw-r--r-- | doc/en/CMakeLists.txt | 4 | ||||
| -rw-r--r-- | doc/en/Makefile.am | 4 | ||||
| -rw-r--r-- | doc/en/weechat_plugin_api.en.txt | 86 | ||||
| -rw-r--r-- | doc/fr/CMakeLists.txt | 28 | ||||
| -rw-r--r-- | doc/fr/Makefile.am | 12 | ||||
| -rw-r--r-- | doc/fr/weechat_plugin_api.fr.txt | 7252 | ||||
| -rw-r--r-- | src/core/wee-utf8.c | 8 | ||||
| -rw-r--r-- | src/core/wee-utf8.h | 2 | ||||
| -rw-r--r-- | src/plugins/weechat-plugin.h | 4 |
9 files changed, 7331 insertions, 69 deletions
diff --git a/doc/en/CMakeLists.txt b/doc/en/CMakeLists.txt index 185bb8bf9..b652eb42d 100644 --- a/doc/en/CMakeLists.txt +++ b/doc/en/CMakeLists.txt @@ -17,7 +17,7 @@ # user's guide ADD_CUSTOM_COMMAND( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_user.en.html - COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_user.en.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_user.en.txt + COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a toclevels=3 -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_user.en.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_user.en.txt DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/weechat_user.en.txt ${CMAKE_CURRENT_SOURCE_DIR}/autogen/user/*.txt @@ -29,7 +29,7 @@ INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_user.en.html DESTINATION share # plugin API reference ADD_CUSTOM_COMMAND( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.en.html - COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.en.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_plugin_api.en.txt + COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a toclevels=3 -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.en.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_plugin_api.en.txt DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/weechat_plugin_api.en.txt ${CMAKE_CURRENT_SOURCE_DIR}/autogen/plugin_api/*.txt diff --git a/doc/en/Makefile.am b/doc/en/Makefile.am index 9f309e4cd..cfad59768 100644 --- a/doc/en/Makefile.am +++ b/doc/en/Makefile.am @@ -35,11 +35,11 @@ all-local: weechat_user.en.html \ # user's guide weechat_user.en.html: weechat_user.en.txt $(wildcard autogen/user/*.txt) - $(ASCIIDOC) -a toc -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_user.en.html weechat_user.en.txt + $(ASCIIDOC) -a toc -a toclevels=3 -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_user.en.html weechat_user.en.txt # plugin API reference weechat_plugin_api.en.html: weechat_plugin_api.en.txt $(wildcard autogen/plugin_api/*.txt) - $(ASCIIDOC) -a toc -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_plugin_api.en.html weechat_plugin_api.en.txt + $(ASCIIDOC) -a toc -a toclevels=3 -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_plugin_api.en.html weechat_plugin_api.en.txt # scripting guide weechat_scripting.en.html: weechat_scripting.en.txt diff --git a/doc/en/weechat_plugin_api.en.txt b/doc/en/weechat_plugin_api.en.txt index 97cdacdbd..d69b502ce 100644 --- a/doc/en/weechat_plugin_api.en.txt +++ b/doc/en/weechat_plugin_api.en.txt @@ -129,7 +129,7 @@ Load plugin Copy file 'libtoto.so' into system plugins directory (for example '/usr/local/lib/weechat/plugins') or into user's plugins directory (for example -'/home/xxxxx/.weechat/plugins'). +'/home/xxx/.weechat/plugins'). Under WeeChat: @@ -662,7 +662,8 @@ Example: [source,C] ---------------------------------------- -char *str = weechat_string_remove_quotes (string, " 'abc' ", "'"); /* result: "abc" */ +char *str = weechat_string_remove_quotes (string, " 'I can't' ", "'"); +/* result: "I can't" */ /* ... */ free (str); ---------------------------------------- @@ -1425,19 +1426,19 @@ int pos = weechat_utf8_pos ("chêne", 4); /* == 3 */ weechat_utf8_strndup ^^^^^^^^^^^^^^^^^^^^ -Return duplicate string, with max N chars. +Return duplicate string, with 'length' chars max. Prototype: [source,C] ---------------------------------------- -char *weechat_utf8_strndup (const char *string, int max_chars); +char *weechat_utf8_strndup (const char *string, int length); ---------------------------------------- Arguments: * 'string': string -* 'max_chars': max chars +* 'length': max chars to duplicate Return value: @@ -3390,8 +3391,8 @@ const char *weechat_config_get_plugin (const char *option_name); Arguments: -* 'option_name': option name, WeeChat will add prefix "plugins.var.xxxx." - (where "xxxx" is current plugin name) +* 'option_name': option name, WeeChat will add prefix "plugins.var.xxx." + (where "xxx" is current plugin name) Return value: @@ -3420,8 +3421,8 @@ int weechat_config_is_set_plugin (const char *option_name); Arguments: -* 'option_name': option name, WeeChat will add prefix "plugins.var.xxxx." - (where "xxxx" is current plugin name) +* 'option_name': option name, WeeChat will add prefix "plugins.var.xxx." + (where "xxx" is current plugin name) Return value: @@ -3455,8 +3456,8 @@ int weechat_config_set_plugin (const char *option_name, const char *value); Arguments: -* 'option_name': option name, WeeChat will add prefix "plugins.var.xxxx." - (where "xxxx" is current plugin name) +* 'option_name': option name, WeeChat will add prefix "plugins.var.xxx." + (where "xxx" is current plugin name) * 'value': new value for option Return value: @@ -3501,8 +3502,8 @@ int weechat_config_unset_plugin (const char *option_name); Arguments: -* 'option_name': option name, WeeChat will add prefix "plugins.var.xxxx." - (where xxxx is current plugin name) +* 'option_name': option name, WeeChat will add prefix "plugins.var.xxx." + (where xxx is current plugin name) Return value: @@ -4934,7 +4935,7 @@ void weechat_unhook (struct t_hook *hook); Arguments: -* 'hook': something hooked with "weechat_hook_xxxx()" +* 'hook': something hooked with "weechat_hook_xxx()" Example: @@ -6015,7 +6016,7 @@ Example: [source,C] ---------------------------------------- -eechat_bar_item_update ("myitem"); +weechat_bar_item_update ("myitem"); ---------------------------------------- weechat_bar_item_remove @@ -6027,7 +6028,7 @@ Prototype: [source,C] ---------------------------------------- -oid weechat_bar_item_remove (struct t_gui_bar_item *item); +void weechat_bar_item_remove (struct t_gui_bar_item *item); ---------------------------------------- Arguments: @@ -6099,15 +6100,15 @@ Arguments: * 'name': bar name * 'hidden': ** 'on': bar is hidden -** 'off': bas is visible +** 'off': bar is visible * 'priority': bar priority (integer) * 'type': ** 'root': bar displayed once, outside windows ** 'window': bar displayed in each window -* 'condition': condition for displaying bar, one of following: +* 'condition': condition for displaying bar: ** 'active': bar is displayed in active window only -** 'inactive': bar is displayed in inactive window(s) only -** 'nicklist': bar is displayed in window(s) with nicklist +** 'inactive': bar is displayed in inactive windows only +** 'nicklist': bar is displayed in windows with nicklist * 'position': 'top', 'bottom', 'left' or 'right' * 'filling_top_bottom': ** 'horizontal': items are filled horizontally (space after each item) @@ -6255,8 +6256,8 @@ Arguments: * 'buffer': buffer pointer (command is executed on this buffer, use NULL for WeeChat core buffer) -* 'command': command to execute (if beginning with a "/"), or text is sent to - buffer (without leading "/") +* 'command': command to execute (if beginning with a "/"), or text to send to + buffer Example: @@ -6291,7 +6292,7 @@ Arguments: * 'proxy': proxy name to use * 'sock': socket to use -* 'address': address (hostname or IP) +* 'address': address (hostname or IP address) * 'port': port Return value: @@ -6331,7 +6332,7 @@ Arguments: * 'proxy': proxy name to use * 'sock': socket to use -* 'address': address (hostname or IP) +* 'address': address * 'port': port Return value: @@ -6499,7 +6500,8 @@ Example: [source,C] ---------------------------------------- struct t_infolist_var *var = weechat_infolist_new_variable_integer (item, - "my_integer", 123); + "my_integer", + 123); ---------------------------------------- weechat_infolist_new_var_string @@ -6531,7 +6533,8 @@ Example: [source,C] ---------------------------------------- struct t_infolist_var *var = weechat_infolist_new_variable_integer (item, - "my_string", "value"); + "my_string", + "value"); ---------------------------------------- weechat_infolist_new_var_pointer @@ -6563,7 +6566,8 @@ Example: [source,C] ---------------------------------------- struct t_infolist_var *var = weechat_infolist_new_variable_pointer (item, - "my_pointer", &something); + "my_pointer", + &something); ---------------------------------------- weechat_infolist_new_var_buffer @@ -6598,8 +6602,10 @@ Example: ---------------------------------------- char buffer[256]; /* ... */ -struct t_infolist_var *var = weechat_infolist_new_variable_buffer (item, "my_buffer", - &buffer, sizeof (buffer)); +struct t_infolist_var *var = weechat_infolist_new_variable_buffer (item, + "my_buffer", + &buffer, + sizeof (buffer)); ---------------------------------------- weechat_infolist_new_var_time @@ -6631,7 +6637,8 @@ Example: [source,C] ---------------------------------------- struct t_infolist_var *var = weechat_infolist_new_variable_time (item, - "my_time", time (NULL)); + "my_time", + time (NULL)); ---------------------------------------- weechat_infolist_get @@ -6687,7 +6694,7 @@ Arguments: Return value: -* 1 if pointer is now on next item, 0 if end of list was reached +* 1 if cursor has been moved on next item, 0 if end of list was reached Example: @@ -6722,7 +6729,8 @@ Arguments: Return value: -* 1 if pointer is now on previous item, 0 if beginning of list was reached +* 1 if cursor has been moved on previous item, 0 if beginning of list was + reached Example: @@ -6817,7 +6825,7 @@ Example: [source,C] ---------------------------------------- -weechat_printf (NULL, "integer value = %d", +weechat_printf (NULL, "integer = %d", weechat_infolist_integer (infolist, "my_integer")); ---------------------------------------- @@ -6846,7 +6854,7 @@ Example: [source,C] ---------------------------------------- -weechat_printf (NULL, "string value = %s", +weechat_printf (NULL, "string = %s", weechat_infolist_string (infolist, "my_string")); ---------------------------------------- @@ -6875,7 +6883,7 @@ Example: [source,C] ---------------------------------------- -weechat_printf (NULL, "pointer value = 0x%lx", +weechat_printf (NULL, "pointer = 0x%lx", weechat_infolist_pointer (infolist, "my_pointer")); ---------------------------------------- @@ -6908,7 +6916,7 @@ Example: ---------------------------------------- int size; void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size); -weechat_printf (NULL, "buffer pointer = 0x%lx, size = %d", +weechat_printf (NULL, "buffer = 0x%lx, size = %d", pointer, size); ---------------------------------------- @@ -6937,7 +6945,7 @@ Example: [source,C] ---------------------------------------- -weechat_printf (NULL, "time value = 0x%ld", +weechat_printf (NULL, "time = 0x%ld", weechat_infolist_time (infolist, "my_time")); ---------------------------------------- @@ -6968,7 +6976,7 @@ weechat_infolist_free (infolist); Upgrade ~~~~~~~ -Functions for upgrading WeeChat. +Functions for upgrading WeeChat (command "/upgrade"). weechat_upgrade_new ^^^^^^^^^^^^^^^^^^^ @@ -6992,7 +7000,7 @@ Arguments: Return value: -* pointer to new upgrade file +* pointer to upgrade file Example: diff --git a/doc/fr/CMakeLists.txt b/doc/fr/CMakeLists.txt index 95aa91131..f604494da 100644 --- a/doc/fr/CMakeLists.txt +++ b/doc/fr/CMakeLists.txt @@ -17,7 +17,7 @@ # user's guide ADD_CUSTOM_COMMAND( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_user.fr.html - COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_user.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_user.fr.txt + COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a toclevels=3 -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_user.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_user.fr.txt DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/weechat_user.fr.txt ${CMAKE_CURRENT_SOURCE_DIR}/autogen/user/*.txt @@ -27,16 +27,16 @@ ADD_CUSTOM_TARGET(doc-user-fr ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/weechat_us INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_user.fr.html DESTINATION share/doc/${PROJECT_NAME}) # plugin API reference -#ADD_CUSTOM_COMMAND( -# OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.fr.html -# COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_plugin_api.fr.txt -# DEPENDS -# ${CMAKE_CURRENT_SOURCE_DIR}/weechat_plugin_api.fr.txt -# ${CMAKE_CURRENT_SOURCE_DIR}/autogen/plugin_api/*.txt -# COMMENT "Building weechat_plugin_api.fr.html" -#) -#ADD_CUSTOM_TARGET(doc-plugin-api-fr ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.fr.html) -#INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.fr.html DESTINATION share/doc/${PROJECT_NAME}) +ADD_CUSTOM_COMMAND( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.fr.html + COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a toclevels=3 -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_plugin_api.fr.txt + DEPENDS + ${CMAKE_CURRENT_SOURCE_DIR}/weechat_plugin_api.fr.txt + ${CMAKE_CURRENT_SOURCE_DIR}/autogen/plugin_api/*.txt + COMMENT "Building weechat_plugin_api.fr.html" +) +ADD_CUSTOM_TARGET(doc-plugin-api-fr ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.fr.html) +INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_plugin_api.fr.html DESTINATION share/doc/${PROJECT_NAME}) # scripting guide #ADD_CUSTOM_COMMAND( @@ -52,7 +52,7 @@ INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_user.fr.html DESTINATION share # FAQ ADD_CUSTOM_COMMAND( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_faq.fr.html - COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_faq.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_faq.fr.txt + COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_faq.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_faq.fr.txt DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/weechat_faq.fr.txt COMMENT "Building weechat_faq.fr.html" @@ -63,7 +63,7 @@ INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_faq.fr.html DESTINATION share/ # quickstart ADD_CUSTOM_COMMAND( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_quickstart.fr.html - COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_quickstart.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_quickstart.fr.txt + COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_quickstart.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_quickstart.fr.txt DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/weechat_quickstart.fr.txt COMMENT "Building weechat_quickstart.fr.html" @@ -74,7 +74,7 @@ INSTALL(FILES ${CMAKE_CURRENT_BINARY_DIR}/weechat_quickstart.fr.html DESTINATION # tester's guide ADD_CUSTOM_COMMAND( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/weechat_tester.fr.html - COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_tester.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_tester.fr.txt + COMMAND ${ASCIIDOC_EXECUTABLE} ARGS -a toc -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="${VERSION}" -n -o ${CMAKE_CURRENT_BINARY_DIR}/weechat_tester.fr.html ${CMAKE_CURRENT_SOURCE_DIR}/weechat_tester.fr.txt DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/weechat_tester.fr.txt COMMENT "Building weechat_tester.fr.html" diff --git a/doc/fr/Makefile.am b/doc/fr/Makefile.am index fac433719..ac8d0380d 100644 --- a/doc/fr/Makefile.am +++ b/doc/fr/Makefile.am @@ -31,27 +31,27 @@ all-local: weechat_user.fr.html \ # user's guide weechat_user.fr.html: weechat_user.fr.txt $(wildcard autogen/user/*.txt) - $(ASCIIDOC) -a toc -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_user.fr.html weechat_user.fr.txt + $(ASCIIDOC) -a toc -a toclevels=3 -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_user.fr.html weechat_user.fr.txt # plugin API reference weechat_plugin_api.fr.html: weechat_plugin_api.fr.txt $(wildcard autogen/plugin_api/*.txt) - $(ASCIIDOC) -a toc -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_plugin_api.fr.html weechat_plugin_api.fr.txt + $(ASCIIDOC) -a toc -a toclevels=3 -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_plugin_api.fr.html weechat_plugin_api.fr.txt # scripting guide weechat_scripting.fr.html: weechat_scripting.fr.txt - $(ASCIIDOC) -a toc -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_scripting.fr.html weechat_scripting.fr.txt + $(ASCIIDOC) -a toc -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_scripting.fr.html weechat_scripting.fr.txt # FAQ weechat_faq.fr.html: weechat_faq.fr.txt - $(ASCIIDOC) -a toc -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_faq.fr.html weechat_faq.fr.txt + $(ASCIIDOC) -a toc -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_faq.fr.html weechat_faq.fr.txt # quickstart weechat_quickstart.fr.html: weechat_quickstart.fr.txt - $(ASCIIDOC) -a toc -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_quickstart.fr.html weechat_quickstart.fr.txt + $(ASCIIDOC) -a toc -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_quickstart.fr.html weechat_quickstart.fr.txt # tester's guide weechat_tester.fr.html: weechat_tester.fr.txt - $(ASCIIDOC) -a toc -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_tester.fr.html weechat_tester.fr.txt + $(ASCIIDOC) -a toc -a toc_title='Table des matières' -a date=`date "+%F"` -a revision="$(VERSION)" -n -o weechat_tester.fr.html weechat_tester.fr.txt # install docs diff --git a/doc/fr/weechat_plugin_api.fr.txt b/doc/fr/weechat_plugin_api.fr.txt new file mode 100644 index 000000000..c0f74d1e5 --- /dev/null +++ b/doc/fr/weechat_plugin_api.fr.txt @@ -0,0 +1,7252 @@ +Référence API Extension WeeChat +=============================== +FlashCode <flashcode@flashtux.org> + + +Ce manuel documente le client de messagerie instantanée WeeChat, il fait +partie de WeeChat. + +La dernière version de ce document peut être téléchargée sur cette page : +http://weechat.flashtux.org/doc.php + + +[[introduction]] +Introduction +------------ + +WeeChat (Wee Enhanced Environment for Chat) est un client de discussion libre, +rapide et léger, conçu pour différents systèmes d'exploitation. + +Ce manuel documente l'API WeeChat des extensions, utilisée par les extensions +en C pour interagir avec le coeur de WeeChat. + +[[plugins_in_weechat]] +Extensions dans in WeeChat +-------------------------- + +Une extension est un programme C qui peut appeler des fonctions WeeChat +définies dans une interface. + +Ce programme C n'a pas besoin des sources WeeChat pour être compilé et peut +être dynamiquement chargé dans WeeChat avec la commande `/plugin`. + +Cette extension doit être une bibliothèque dynamique, pour un chargement +dynamique par le système d'exploitation. +Sous GNU/Linux, le fichier a une extension ".so" et ".dll" sous Windows. + +L'extension doit inclure le fichier "weechat-plugin.h" (disponible dans le code +source WeeChat). +Ce fichier définit les structures et types utilisés pour communiquer avec +WeeChat. + +[[macros]] +Macros +~~~~~~ + +L'extension doit utiliser des macros (pour définir quelques variables) : + +WEECHAT_PLUGIN_NAME("name"):: + nom de l'extension + +WEECHAT_PLUGIN_DESCRIPTION("description"):: + description courte de l'extension + +WEECHAT_PLUGIN_VERSION("1.0"):: + version de l'extension + +WEECHAT_PLUGIN_LICENSE("GPL3"):: + licence de l'extension + +[[main_functions]] +Fonctions principales +~~~~~~~~~~~~~~~~~~~~~ + +L'extension doit utiliser deux fonctions : + +* weechat_plugin_init +* weechat_plugin_end + +weechat_plugin_init +^^^^^^^^^^^^^^^^^^^ + +Cette fonction est appelée quand l'extension est chargée par WeeChat. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_plugin_init (struct t_weechat_plugin *plugin, + int argc, char *argv[]); +---------------------------------------- + +Paramètres : + +* 'plugin' : pointeur vers la structure d'extension WeeChat +* 'argc' : nombre de paramètres pour l'extension (donnés sur la ligne de + commande par l'utilisateur) +* 'argv' : paramètres pour l'extension + +Valeur de retour : + +* 'WEECHAT_RC_OK' si ok (l'extension sera chargée) +* 'WEECHAT_RC_ERROR' si erreur (l'extension ne sera PAS chargée) + +weechat_plugin_end +^^^^^^^^^^^^^^^^^^ + +Cette fonction est appelée quand l'extension est déchargée par WeeChat. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_plugin_end (struct t_weechat_plugin *plugin); +---------------------------------------- + +Paramètres : + +* 'plugin' : pointeur vers la structure d'extension WeeChat + +Valeur de retour : + +* 'WEECHAT_RC_OK' si ok +* 'WEECHAT_RC_ERROR' si erreur + +[[compile_plugin]] +Compilation de l'extension +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +La compilation ne nécessite pas les sources de WeeChat, seul le fichier + 'weechat-plugin.h' est requis. + +Pour compiler l'extension qui n'a qu'un fichier "toto.c" (sous GNU/Linux): + +---------------------------------------- +$ gcc -fPIC -Wall -c toto.c +$ gcc -shared -fPIC -o libtoto.so toto.o +---------------------------------------- + +[[load_plugin]] +Chargement de l'extension +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Copiez le fichier 'libtoto.so' dans le répertoire système des extensions (par +exemple '/usr/local/lib/weechat/plugins') ou dans le répertoire utilisateur des +extensions (par exemple '/home/xxx/.weechat/plugins'). + +Sous WeeChat : + +---------------------------------------- +/plugin load toto +---------------------------------------- + +[[plugin_example]] +Exemple d'extension +~~~~~~~~~~~~~~~~~~~ + +Exemple complet d'extension, qui ajoute une commande '/double' : affiche deux +fois les paramètres sur le tampon courant, ou exécute deux fois une commande +(ok ce n'est pas très utile, mais c'est juste un exemple !) : + +[source,C] +---------------------------------------- +#include <stdlib.h> + +#include "weechat-plugin.h" + +WEECHAT_PLUGIN_NAME("double"); +WEECHAT_PLUGIN_DESCRIPTION("Extension de test pour WeeChat"); +WEECHAT_PLUGIN_AUTHOR("FlashCode <flashcode@flashtux.org>"); +WEECHAT_PLUGIN_VERSION("0.1"); +WEECHAT_PLUGIN_LICENSE("GPL3"); + +struct t_weechat_plugin *weechat_plugin = NULL; + + +/* callback pour la commande "/double" */ + +int +commande_double_cb (void *data, struct t_gui_buffer *buffer, int argc, + char **argv, char **argv_eol) +{ + /* pour que le compilateur C soit content */ + (void) data; + (void) buffer; + (void) argv; + + if (argc > 1) + { + weechat_command (NULL, argv_eol[1]); + weechat_command (NULL, argv_eol[1]); + } + + return WEECHAT_RC_OK; +} + +int +weechat_plugin_init (struct t_weechat_plugin *plugin, + int argc, char *argv[]) +{ + weechat_plugin = plugin; + + weechat_hook_command ("double", + "Affiche deux fois un message " + "ou exécute deux fois une commande", + "message | commande", + "message : message à afficher deux fois\n" + "commande : commande à exécuter deux fois", + NULL, + &commande_double_cb, NULL); + + return WEECHAT_RC_OK; +} + +int +weechat_plugin_end (struct t_weechat_plugin *plugin) +{ + /* pour que le compilateur C soit content */ + (void) plugin; + + return WEECHAT_RC_OK; +} +---------------------------------------- + +[[c_plugin_api]] +API extension C +--------------- + +[[plugins]] +Extensions +~~~~~~~~~~ + +Fonctions pour obtenir des informations sur les extensions. + +weechat_plugin_get_name +^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne le nom d'une extension. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin); +---------------------------------------- + +Paramètres : + +* 'plugin' : pointeur vers la structure d'extension WeeChat (peut être NULL) + +Valeur de retour : + +* nom de l'extension, "core" pour le coeur de WeeChat (si le pointeur vers + l'extension est NULL) + +Exemple : + +[source,C] +---------------------------------------- +const char *name = weechat_plugin_get_name (plugin); +---------------------------------------- + +[[strings]] +Chaînes de caractères +~~~~~~~~~~~~~~~~~~~~~ + +Plusieurs fonctions sur les chaînes de caractères sont déjà disponibles via +les fonctions standard du C, mais il est recommandé d'utiliser celles de l'API +car elles sont ok avec UTF-8 et la locale. + +weechat_charset_set +^^^^^^^^^^^^^^^^^^^ + +Définit le nouveau jeu de caractères (le jeu de caractères par défaut est +'UTF-8', donc si votre extension utilise 'UTF-8', vous n'avez pas besoin +d'appeler cette fonction). + +Prototype : + +[source,C] +---------------------------------------- +void weechat_charset_set (const char *charset); +---------------------------------------- + +Paramètres : + +* 'charset' : nouveau jeu de caractères à utiliser + +Exemple : + +[source,C] +---------------------------------------- +weechat_charset_set (plugin, "iso-8859-1"); +---------------------------------------- + +weechat_iconv_to_internal +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Convertit une chaîne vers le jeu de caractères interne (UTF-8). + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_iconv_to_internal (const char *charset, const char *string); +---------------------------------------- + +Paramètres : + +* 'charset' : jeu de caractères à convertir +* 'string' : chaîne à convertir + +Valeur de retour : + +* chaîne convertie (doit être libérée par un appel à "free" après utilisation) + +Exemple : + +[source,C] +---------------------------------------- +char *str = weechat_iconv_to_internal (plugin, "iso-8859-1", "iso string : é à"); +/* ... */ +free (str); +---------------------------------------- + +weechat_iconv_from_internal +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Convertie une chaîne du jeu de caractères interne (UTF-8) vers un autre. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_iconv_from_internal (const char *charset, const char *string); +---------------------------------------- + +Paramètres : + +* 'charset' : jeu de caractères cible +* 'string' : chaîne à convertir + +Valeur de retour : + +* chaîne convertie (doit être libérée par un appel à "free" après utilisation) + +Exemple : + +[source,C] +---------------------------------------- +char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string : é à"); +/* ... */ +free (str); +---------------------------------------- + +weechat_gettext +^^^^^^^^^^^^^^^ + +Retourne la chaîne traduite (dépend de la langue locale). + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_gettext (const char *string); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne à traduire + +Valeur de retour : + +* chaîne traduite + +Exemple : + +[source,C] +---------------------------------------- +char *str = weechat_gettext ("hello !"); +---------------------------------------- + +weechat_ngettext +^^^^^^^^^^^^^^^^ + +Retourne la chaîne traduite, en utilisant le singulier ou le pluriel, selon +le paramètre 'count'. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_ngettext (const char *string, const char *plural, + int count); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne à traduire, au singulier +* 'plural' : chaîne à traduire, au pluriel +* 'count' : utilisé pour choisir entre le singulier et le pluriel (le choix est + fonction de la langue utilisée) + +Valeur de retour : + +* chaîne traduite + +Exemple : + +[source,C] +---------------------------------------- +char *str = weechat_ngettext ("file", "files", num_files); +---------------------------------------- + +weechat_strndup +^^^^^^^^^^^^^^^ + +Retourne la chaîne dupliquée, avec au plus 'length' caractères. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_strndup (const char *string, int length); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne à dupliquer +* 'length' : nombre maximum de caractères à dupliquer + +Valeur de retour : + +* chaîne dupliquée (doit être libérée par un appel à "free" après utilisation) + +Exemple : + +[source,C] +---------------------------------------- +char *str = weechat_strndup ("abcdef", 3); /* résultat : "abc" */ +/* ... */ +free (str); +---------------------------------------- + +weechat_string_tolower +^^^^^^^^^^^^^^^^^^^^^^ + +Convertit une chaîne UTF-8 en minuscules. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_string_tolower (const char *string); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne à convertir + +Exemple : + +[source,C] +---------------------------------------- +char *str = "AbCdé"; +weechat_string_tolower (str); /* str vaut maintenant : "abcdé" */ +---------------------------------------- + +weechat_string_toupper +^^^^^^^^^^^^^^^^^^^^^^ + +Convertir une chaîne UTF-8 en majuscules. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_string_toupper (const char *string); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne à convertir + +Exemple : + +[source,C] +---------------------------------------- +char *str = "AbCdé"; +weechat_string_tolower (str); /* str vaut maintenant : "ABCDé" */ +---------------------------------------- + +weechat_strcasecmp +^^^^^^^^^^^^^^^^^^ + +Comparaison de chaînes indépendante de la locale et de la casse. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_strcasecmp (const char *string1, const char *string2); +---------------------------------------- + +Paramètres : + +* 'string1' : première chaîne à comparer +* 'string2' : seconde chaîne à comparer + +Valeur de retour : + +* différence entre les deux chaînes : +** négative si string1 < string2 +** zéro si string1 == string2 +** positive si string1 > string2 + +Exemple : + +[source,C] +---------------------------------------- +int diff = weechat_strcasecmp ("aaa", "CCC"); /* == -2 */ +---------------------------------------- + +weechat_strcmp_ignore_chars +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Comparaison de chaînes indépendante de la locale (et en option de la casse), en +ignorant des caractères. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_strcmp_ignore_chars (const char *string1, const char *string2, + const char *chars_ignored, + int case_sensitive); +---------------------------------------- + +Paramètres : + +* 'string1' : première chaîne à comparer +* 'string2' : seconde chaîne à comparer +* 'chars_ignored' : chaîne avec les caractères à ignorer +* 'case_sensitive' : 1 pour une comparaison tenant compte de la casse, sinon 0 + +Valeur de retour : + +* différence entre les deux chaînes : +** négative si string1 < string2 +** zéro si string1 == string2 +** positive si string1 > string2 + +Exemple : + +[source,C] +---------------------------------------- +int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1); /* == -3 */ +---------------------------------------- + +weechat_strcasestr +^^^^^^^^^^^^^^^^^^ + +Recherche de chaîne indépendante de la locale et de la casse. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_strcasestr (const char *string, const char *search); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'search' : chaîne à rechercher dans 'string' + +Valeur de retour : + +* pointeur vers la chaîne trouvée, ou NULL si non trouvée + +Exemple : + +[source,C] +---------------------------------------- +char *pos = weechat_strcasestr ("aBcDeF", "de"); /* résultat : pointeur vers "DeF" */ +---------------------------------------- + +weechat_string_match +^^^^^^^^^^^^^^^^^^^^ + +Vérifie si une chaîne correspond à un masque. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_string_match (const char *string, const char *mask, + int case_sensitive); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'mask' : masque, peut commencer ou se terminer par "`*`" (aucune autre "`*`" + n'est autorisée dans le masque) + +Valeur de retour : + +* 1 si la chaîne correspond au masque, sinon 0 + +Exemple : + +[source,C] +---------------------------------------- +int match1 = weechat_string_match ("abcdef", "abc*", 0); /* == 1 */ +int match2 = weechat_string_match ("abcdef", "*dd*", 0); /* == 0 */ +int match3 = weechat_string_match ("abcdef", "*def", 0); /* == 1 */ +int match4 = weechat_string_match ("abcdef", "*de*", 0); /* == 1 */ +---------------------------------------- + +weechat_string_replace +^^^^^^^^^^^^^^^^^^^^^^ + +Remplace toutes les occurences d'une chaîne par une autre chaîne. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_string_replace (const char *string, const char *search, + const char *replace); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'search' : chaîne à remplacer +* 'replace' : remplacement pour la chaîne 'search' + +Valeur de retour : + +* chaîne avec 'search' remplacée par 'replace' (doit être libérée par un appel + à "free" après utilisation) + +Exemple : + +[source,C] +---------------------------------------- +char *str = weechat_string_replace ("test, test", "s", "x"); /* résultat : "text" */ +/* ... */ +free (str); +---------------------------------------- + +weechat_string_remove_quotes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Supprime les apostrophes/guillemets au début et à la fin d'une chaîne (ignore +les blancs s'ils sont avant la première apostrophe ou après la dernière). + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_string_remove_quotes (const char *string, const char *quotes); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'quotes' : chaîne avec la liste des apostrophes/guillemets à supprimer + +Valeur de retour : + +* chaîne sans les apostrophes/guillemets au début et à la fin (doit être + libérée par un appel à "free" après utilisation) + +Exemple : + +[source,C] +---------------------------------------- +char *str = weechat_string_remove_quotes (string, " 'aujourd'hui' ", "'"); +/* résultat : "aujourd'hui" */ +/* ... */ +free (str); +---------------------------------------- + +weechat_string_strip +^^^^^^^^^^^^^^^^^^^^ + +Supprime des caractères au début et/ou à la fin d'une chaîne. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_string_strip (const char *string, int left, int right, + const char *chars); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'left' : supprime les caractères en début de chaîne si différent de 0 +* 'right' : supprime les caractères en fin de chaîne si different de 0 +* 'chars' : chaîne avec les caractères à supprimer + +Valeur de retour : + +* chaîne avec les caractères supprimés (doit être libérée par un appel à "free" + après utilisation) + +Exemple : + +[source,C] +---------------------------------------- +char *str = weechat_string_strip (".abc -", 0, 1, "- ."); /* résultat : ".abc" */ +/* ... */ +free (str); +---------------------------------------- + +weechat_string_has_highlight +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Vérifie si une chaîne a un ou plusieurs "highlights", en utilisant une liste +de mots "highlight". + +Prototype : + +[source,C] +---------------------------------------- +int weechat_string_has_highlight (const char *string, + const char highlight_words); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'highlight_words' : liste de mots "highlight", séparés par des virgules + +Valeur de retour : + +* 1 si la chaîne a un ou plusieurs "highlights", sinon 0 + +Exemple : + +[source,C] +---------------------------------------- +int hl = weechat_string_has_highlight ("my test string", "test,word2"); /* == 1 */ +---------------------------------------- + +weechat_string_mask_to_regex +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne une expression régulière ("regex"), construite avec un masque où le +seul caractère spécial est "`*`". Tous les autres caractères spéciaux +d'expression régulière sont échappés. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_string_mask_to_regex (const char *mask); +---------------------------------------- + +Paramètres : + +* 'mask' : masque + +Valeur de retour : + +* expression régulière, sous forme de chaîne (doit être libérée par un appel à + "free" après utilisation) + +Exemple : + +[source,C] +---------------------------------------- +char *str_regex = weechat_string_mask_to_regex ("test*mask"); +/* résultat : "test.*mask" */ +/* ... */ +free (str_regex); +---------------------------------------- + +weechat_string_explode +^^^^^^^^^^^^^^^^^^^^^^ + +Explosion d'une chaîne à l'aide de délimiteur(s). + +Prototype : + +[source,C] +---------------------------------------- +char **weechat_string_explode (const char *string, const char *separators, + int keep_eol, int num_items_max, + int *num_items); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne à exploser +* 'separators' : délimiteurs utilisés pour l'explosion +* 'keep_eol' : si différent de 0, alors chaque argument contiendra toutes les + chaînes jusqu'à la fin de la ligne (voir exemple ci-dessous) +* 'num_items_max' : nombre maximum de chaînes à créer (0 = pas de limite) +* 'num_items' : pointeur vers un entier qui contiendra le nombre de chaînes + créées + +Valeur de retour : + +* tableau de chaînes, NULL en cas de problème (doit être libéré par un appel à + <<_weechat_string_free_exploded>> après utilisation) + +Exemples : + +[source,C] +---------------------------------------- +char **argv; +int argc; +argv = weechat_string_explode ("abc de fghi", " ", 0, 0, &argc); +/* résultat : argv[0] == "abc" + argv[1] == "de" + argv[2] == "fghi" + argv[3] == NULL + argc == 3 +*/ +weechat_string_free_exploded (argv); + +argv = weechat_string_explode ("abc de fghi", " ", 1, 0, &argc); +/* résultat : argv[0] == "abc de fghi" + argv[1] == "de fghi" + argv[2] == "fghi" + argv[3] == NULL + argc == 3 +*/ +weechat_string_free_exploded (argv); +---------------------------------------- + +weechat_string_free_exploded +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Libère la mémoire utilisée pour l'explosion d'une chaîne. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_string_free_exploded (char **exploded_string); +---------------------------------------- + +Paramètres : + +* 'exploded_string' : chaîne explosée par <<_weechat_string_explode>> + +Exemple : + +[source,C] +---------------------------------------- +char *argv; +int argc; +argv = weechat_string_explode (string, " ", 0, 0, &argc); +/* ... */ +weechat_string_free_exploded (argv); +---------------------------------------- + +weechat_string_build_with_exploded +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Construit une chaîne à partir d'une chaîne explosée. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_string_build_with_exploded (char **exploded_string, + const char *separator); +---------------------------------------- + +Paramètres : + +* 'exploded_string' : chaîne explosée par la fonction <<_weechat_string_explode>> +* 'separator' : chaîne utilisée pour séparer les différentes chaînes + +Valeur de retour : + +* chaîne construite avec la chaîne explosée (doit être libérée par un appel à + "free" après utilisation) + +Exemple : + +[source,C] +---------------------------------------- +char **argv; +int argc; +argv = weechat_string_explode ("abc def ghi", " ", 0, 0, &argc); +char *str = weechat_string_build_with_exploded (argv, ";"); +/* str == "abc;def;ghi" */ +/* ... */ +free (str); +---------------------------------------- + +weechat_string_split_command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Eclate une liste de commandes séparées par 'separator' (qui peut être échappé +par "\" dans la chaîne). + +Prototype : + +[source,C] +---------------------------------------- +char **weechat_string_split_command (const char *command, char separator); +---------------------------------------- + +Paramètres : + +* 'command' : commande à éclater +* 'separator' : séparateur + +Valeur de retour : + +* tableau de chaînes, NULL en cas de problème (doit être libéré par un appel à + <<_weechat_free_split_command>> après utilisation) + +Exemple : + +[source,C] +---------------------------------------- +char **argv = weechat_string_split_command ("/commande1 arg;/commande2", ';'); +/* résultat : argv[0] == "/commande1 arg" + argv[1] == "/commande2" +*/ +weechat_free_split_command (argv); +---------------------------------------- + +weechat_string_free_split_command +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Libère la mémoire utilisée par une commande éclatée. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_string_free_split_command (char **split_command); +---------------------------------------- + +Paramètres : + +* 'split_command' : commande éclatée par <<_weechat_string_split_command>> + +Exemple : + +[source,C] +---------------------------------------- +char **argv = weechat_string_split_command ("/commande1 arg;/commande2", ';'); +/* ... */ +weechat_free_split_command (argv); +---------------------------------------- + +weechat_string_format_size +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Construit une chaîne avec une taille de fichier formatée et une unité traduite +dans la langue locale. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_string_format_size (unsigned long size); +---------------------------------------- + +Paramètres : + +* 'size' : taille (en octets) + +Valeur de retour : + +* chaîne formatée (doit être libérée par un appel à "free" après utilisation) + +Exemples : + +[source,C] +---------------------------------------- +/* exemples avec la langue française */ + +char *str = weechat_string_format_size (0); /* str == "0 octet" */ +/* ... */ +free (str); + +char *str = weechat_string_format_size (200); /* str == "200 octets" */ +/* ... */ +free (str); + +char *str = weechat_string_format_size (1536); /* str == "1.5 Ko" */ +/* ... */ +free (str); + +char *str = weechat_string_format_size (2097152); /* str == "2 Mo" */ +/* ... */ +free (str); +---------------------------------------- + +weechat_string_remove_color +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Supprime les couleurs WeeChat dans une chaîne. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_string_remove_color (const char *string, + const char *replacement); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'replacement' : si non NULL et non vide, les couleurs WeeChat sont remplacées + par le premier caractère de cette chaine, sinon les codes couleurs WeeChat et + les caractères suivants (rattachés à la couleur) sont supprimés de la chaîne + +Valeur de retour : + +* chaîne sans couleur (doit être libérée par un appel à "free" après + utilisation) + +Exemples : + +[source,C] +---------------------------------------- +/* supprime les codes couleur */ +char *str = weechat_string_remove_color (ma_chaine1, NULL); +/* ... */ +free (str); + +/* remplace les codes couleur par "?" */ +char *str = weechat_string_remove_color (ma_chaine2, "?"); +/* ... */ +free (str); +---------------------------------------- + +[[utf-8]] +UTF-8 +~~~~~ + +Fonctions pour les chaînes UTF-8. + +weechat_utf8_has_8bits +^^^^^^^^^^^^^^^^^^^^^^ + +Vérifie si une chaîne a des caractères 8-bits. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_utf8_has_8bits (const char *string); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne + +Valeur de retour : + +* 1 si la chaîne a des caractères 8-bits, 0 s'il y a seulement des caractères + 7-bits + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_utf8_has_8bits (string)) +{ + /* ... */ +} +---------------------------------------- + +weechat_utf8_is_valid +^^^^^^^^^^^^^^^^^^^^^ + +Vérifie si une chaîne est valide UTF-8. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_utf8_is_valid (const char *string, char **error); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'error' : si non NULL, '*error' est alimenté avec le pointeur vers le premier + caractère non valide dans la chaîne, s'il y en a + +Valeur de retour : + +* 1 si la chaîne UTF-8 est valide, sinon 0 + +Exemple : + +[source,C] +---------------------------------------- +char *error; +if (weechat_utf8_is_valid (string, &error)) +{ + /* ... */ +} +else +{ + /* "error" pointe vers le premier caractère invalide */ +} +---------------------------------------- + +weechat_utf8_normalize +^^^^^^^^^^^^^^^^^^^^^^ + +Normalise une chaîne UTF-8 : supprime tous les caractères non valides UTF-8 +en les remplaçant par un caractère. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_utf8_normalize (const char *string, char replacement); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'replacement' : caractère de remplacement pour les caractères non valides + +Exemple : + +[source,C] +---------------------------------------- +weechat_utf8_normalize (string, '?'); +---------------------------------------- + +weechat_utf8_prev_char +^^^^^^^^^^^^^^^^^^^^^^ + +Retourne un pointeur vers le caractère UTF-8 précédent dans une chaîne. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_utf8_prev_char (const char *string_start, const char *string); +---------------------------------------- + +Paramètres : + +* 'string_start' : début de la chaîne (la fonction ne retournera pas un + caractère situé avant ce pointeur) +* 'string' : pointeur vers la chaîne (doit être >= 'string_start') + +Valeur de retour : + +* pointeur vers le caractère UTF-8 précédent, NULL si non trouvé (début de + chaîne atteint) + +Exemple : + +[source,C] +---------------------------------------- +char *prev_char = weechat_utf8_prev_char (string, ptr_in_string); +---------------------------------------- + +weechat_utf8_next_char +^^^^^^^^^^^^^^^^^^^^^^ + +Retourne un pointeur vers le caractère UTF-8 suivant dans une chaîne. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_utf8_next_char (const char *string); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne + +Valeur de retour : + +* pointeur vers le caractère UTF-8 suivant, NULL si non trouvé (fin de la + chaîne atteinte) + +Exemple : + +[source,C] +---------------------------------------- +char *next_char = weechat_utf8_next_char (string); +---------------------------------------- + +weechat_utf8_char_size +^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la taille d'un caractère UTF-8 (en octets). + +Prototype : + +[source,C] +---------------------------------------- +int weechat_utf8_char_size (const char *string); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne + +Valeur de retour : + +* taille du caractère UTF-8 (en octets) + +Exemple : + +[source,C] +---------------------------------------- +int char_size = weechat_utf8_char_size ("être"); /* == 2 */ +---------------------------------------- + +weechat_utf8_strlen +^^^^^^^^^^^^^^^^^^^ + +Retourne la taille d'une chaîne UTF-8 (en nombre de caractères UTF-8). + +Prototype : + +[source,C] +---------------------------------------- +int weechat_utf8_strlen (const char *string); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne + +Valeur de retour : + +* longueur de la chaîne UTF-8 (nombre de caractères UTF-8) + +Exemple : + +[source,C] +---------------------------------------- +int length = weechat_utf8_strlen ("chêne"); /* == 5 */ +---------------------------------------- + +weechat_utf8_strnlen +^^^^^^^^^^^^^^^^^^^^ + +Retourne la taille d'une chaîne UTF-8 (en nombre de caractères UTF-8), pour au +maximum 'bytes' octets dans la chaîne. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_utf8_strnlen (const char *string, int bytes); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'bytes' : nombre maximum d'octets + +Valeur de retour : + +* longueur de la chaîne UTF-8 (nombre de caractères UTF-8) + +Exemple : + +[source,C] +---------------------------------------- +int length = weechat_utf8_strnlen ("chêne", 4); /* == 3 */ +---------------------------------------- + +weechat_utf8_strlen_screen +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne le nombre de caractères nécessaires pour afficher la chaîne UTF-8 +sur l'écran. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_utf8_strlen_screen (const char *string); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne + +Valeur de retour : + +* nombre de caractères nécessaires pour afficher la chaîne UTF-8 sur l'écran + +Exemple : + +[source,C] +---------------------------------------- +int length_on_screen = weechat_utf8_strlen_screen ("é"); /* == 1 */ +---------------------------------------- + +weechat_utf8_charcasecmp +^^^^^^^^^^^^^^^^^^^^^^^^ + +Compare deux caractères UTF-8 en ignorant la casse. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_utf8_charcasecmp (const char *string1, const char *string2); +---------------------------------------- + +Paramètres : + +* 'string1' : première chaîne pour la comparaison +* 'string2' : seconde chaîne pour la comparaison + +Valeur de retour : + +* différence entre le premier caractère de chaque chaîne : +** négative si char1 < char2 +** zéro si char1 == char2 +** positive si char1 > char2 + +Exemple : + +[source,C] +---------------------------------------- +int diff = weechat_utf8_charcasecmp ("aaa", "CCC"); /* == -2 */ +---------------------------------------- + +weechat_utf8_char_size_screen +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne le nombre de caractères nécessaires pour afficher le caractère UTF-8 +sur l'écran. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_utf8_char_size_screen (const char *string); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne + +Valeur de retour : + +* nombre de caractères nécessaires pour afficher le caractère UTF-8 sur l'écran + +Exemple : + +[source,C] +---------------------------------------- +int length_on_screen = weechat_utf8_char_size_screen ("é"); /* == 1 */ +---------------------------------------- + +weechat_utf8_add_offset +^^^^^^^^^^^^^^^^^^^^^^^ + +Avancer de N caractères dans une chaîne UTF-8. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_utf8_add_offset (const char *string, int offset); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'offset' : nombre de caractères + +Valeur de retour : + +* pointeur vers la chaîne, N caractères après (NULL s'il est impossible + d'atteindre cette position dans la chaîne) + +Exemple : + +[source,C] +---------------------------------------- +char *str = "chêne"; +char *str2 = weechat_utf8_add_offset (str, 3); /* pointe vers "ne" */ +---------------------------------------- + +weechat_utf8_real_pos +^^^^^^^^^^^^^^^^^^^^^ + +Retourne la position réelle dans une chaîne UTF-8. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_utf8_real_pos (const char *string, int pos); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'pos' : position (en nombre de caractères) + +Valeur de retour : + +* position réelle (en octets) + +Exemple : + +[source,C] +---------------------------------------- +int pos = weechat_utf8_real_pos ("chêne", 3); /* == 4 */ +---------------------------------------- + +weechat_utf8_pos +^^^^^^^^^^^^^^^^ + +Retourne la position dans une chaîne UTF-8. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_utf8_pos (const char *string, int real_pos); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'real_pos' : position (en octets) + +Valeur de retour : + +* position (en nombre de caractères) + +Exemple : + +[source,C] +---------------------------------------- +int pos = weechat_utf8_pos ("chêne", 4); /* == 3 */ +---------------------------------------- + +weechat_utf8_strndup +^^^^^^^^^^^^^^^^^^^^ + +Retourne une chaîne dupliquée, avec au plus 'length' caractères. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_utf8_strndup (const char *string, int length); +---------------------------------------- + +Paramètres : + +* 'string' : chaîne +* 'length' : nombre maximum de caractères à dupliquer + +Valeur de retour : + +* chaîne dupliquée (doit être libérée avec un appel à "free" après utilisation) + +Exemple : + +[source,C] +---------------------------------------- +char *string = weechat_utf8_strndup ("chêne", 3); /* retourne "chê" */ +/* ... */ +free (str); +---------------------------------------- + +[[directories]] +Répertoires +~~~~~~~~~~~ + +Fonctions liées aux répertoires. + +weechat_mkdir_home +^^^^^^^^^^^^^^^^^^ + +Crée un répertoire dans le répertoire de WeeChat. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_mkdir_home (char *directory, int mode); +---------------------------------------- + +Paramètres : + +* 'directory' : nom du répertoire à créer +* 'mode' : mode pour le répertoire + +Valeur de retour : + +* 1 si le répertoire est créé, 0 en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +if (!weechat_mkdir_home ("temp")) +{ + /* erreur */ +} +---------------------------------------- + +weechat_mkdir +^^^^^^^^^^^^^ + +Crée un répertoire. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_mkdir (char *directory, int mode); +---------------------------------------- + +Paramètres : + +* 'directory' : nom du répertoire à créer +* 'mode' : mode pour le répertoire + +Valeur de retour : + +* 1 si le répertoire est créé, 0 en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +if (!weechat_mkdir ("/tmp/mydir")) +{ + /* erreur */ +} +---------------------------------------- + +weechat_mkdir_parents +^^^^^^^^^^^^^^^^^^^^^ + +Crée un répertoire et ses parents si besoin. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_mkdir_parents (char *directory, int mode); +---------------------------------------- + +Paramètres : + +* 'directory' : nom du répertoire à créer +* 'mode' : mode pour le répertoire + +Valeur de retour : + +* 1 si le répertoire est créé, 0 en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +if (!weechat_mkdir_parents ("/tmp/my/dir")) +{ + /* erreur */ +} +---------------------------------------- + +weechat_exec_on_files +^^^^^^^^^^^^^^^^^^^^^ + +Balaye les fichiers dans un répertoire et exécute un "callback" pour chaque +fichier. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_exec_on_files (const char *directory, + int hidden_files, + void *data, + void (*callback)(void *data, + const char *filename)); +---------------------------------------- + +Paramètres : + +* 'directory' : répertoire où chercher les fichiers +* 'hidden_files' : 1 pour inclure les fichiers cachés, sinon 0 +* 'data' : pointeur donné au "callback" lorsqu'il est appelé par WeeChat +* 'callback' : fonction appelée pour chaque fichier trouvé, paramètres : +** 'void *data' : pointeur +** 'const char *filename' : nom de fichier trouvé + +Exemple : + +[source,C] +---------------------------------------- +void callback (void *data, const char *filename) +{ + /* ... */ +} +... +weechat_exec_on_files ("/tmp", 0, NULL, &callback); +---------------------------------------- + +[[util]] +Util +~~~~ + +Quelques fonctions utiles. + +weechat_timeval_cmp +^^^^^^^^^^^^^^^^^^^ + +Compare deux structures "timeval". + +Prototype : + +[source,C] +---------------------------------------- +int weechat_timeval_cmp (struct timeval *tv1, struct timeval *tv2); +---------------------------------------- + +Paramètres : + +* 'tv1' : première structure "timeval" +* 'tv2' : seconde structure "timeval" + +Valeur de retour : + +* -1 si tv1 < tv2 +* zéro si tv1 == tv2 +* +1 si tv1 > tv2 + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_timeval_cmp (&tv1, &tv2) > 0) +{ + /* tv1 > tv2 */ +} +---------------------------------------- + +weechat_timeval_diff +^^^^^^^^^^^^^^^^^^^^ + +Retourne la différence (en millisecondes) entre deux structures "timeval". + +Prototype : + +[source,C] +---------------------------------------- +long weechat_timeval_diff (struct timeval *tv1, struct timeval *tv2); +---------------------------------------- + +Paramètres : + +* 'tv1' : première structure "timeval" +* 'tv2' : seconde structure "timeval" + +Valeur de retour : + +* différence en millisecondes + +Exemple : + +[source,C] +---------------------------------------- +long diff = weechat_timeval_diff (&tv1, &tv2); +---------------------------------------- + +weechat_timeval_add +^^^^^^^^^^^^^^^^^^^ + +Ajoute un intervalle (en millisecondes) à une structure "timeval". + +Prototype : + +[source,C] +---------------------------------------- +void weechat_timeval_add (struct timeval *tv, long interval); +---------------------------------------- + +Paramètres : + +* 'tv' : structure "timeval" +* 'interval' : intervalle (en millisecondes) + +Exemple : + +[source,C] +---------------------------------------- +weechat_timeval_add (&tv, 2000); /* add 2 seconds */ +---------------------------------------- + +[[sorted_lists]] +Listes triées +~~~~~~~~~~~~~ + +Fonctions pour les listes triées. + +weechat_list_new +^^^^^^^^^^^^^^^^ + +Crée une nouvelle liste. + +Prototype : + +[source,C] +---------------------------------------- +struct t_weelist *weechat_list_new (); +---------------------------------------- + +Valeur de retour : + +* pointeur vers la nouvelle liste + +Exemple : + +[source,C] +---------------------------------------- +struct t_weelist *list = weechat_list_new (); +---------------------------------------- + +weechat_list_add +^^^^^^^^^^^^^^^^ + +Ajoute un élément dans une liste. + +Prototype : + +[source,C] +---------------------------------------- +struct t_weelist_item *weechat_list_add (struct t_weelist *weelist, + const char *data, + const char *where, + void *user_data); +---------------------------------------- + +Paramètres : + +* 'weelist' : pointeur vers la liste +* 'data' : donnée à insérer dans la liste +* 'where' : position dans la liste : +** 'WEECHAT_LIST_POS_SORT' : ajout dans la liste, en gardant la liste triée +** 'WEECHAT_LIST_POS_BEGINNING' : ajout en début de liste +** 'WEECHAT_LIST_POS_END' : ajout en fin de liste +* 'user_data' : un pointeur quelconque + +Valeur de retour : + +* pointeur vers le nouvel élément + +Exemple : + +[source,C] +---------------------------------------- +struct t_weelist_item *my_item = + weechat_list_add (list, "ma donnée", WEECHAT_LIST_POS_SORT, NULL); +---------------------------------------- + +weechat_list_search +^^^^^^^^^^^^^^^^^^^ + +Recherche un élément dans une liste. + +Prototype : + +[source,C] +---------------------------------------- +struct t_weelist_item *weechat_list_search (struct t_weelist *weelist, + const char *data); +---------------------------------------- + +Paramètres : + +* 'weelist' : pointeur vers la liste +* 'data' : donnée à chercher dans la liste + +Valeur de retour : + +* pointeur vers l'élément trouvé, NULL si aucun élément n'a été trouvé + +Exemple : + +[source,C] +---------------------------------------- +struct t_weelist_item *item = weechat_list_search (list, "ma donnée"); +---------------------------------------- + +weechat_list_casesearch +^^^^^^^^^^^^^^^^^^^^^^^ + +Recherche un élément dans la liste, sans tenir compte de la casse. + +Prototype : + +[source,C] +---------------------------------------- +struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist, + const char *data); +---------------------------------------- + +Paramètres : + +* 'weelist' : pointeur vers la liste +* 'data' : données à chercher dans la liste + +Valeur de retour : + +* pointeur vers l'élément trouvé, NULL si aucun élément n'a été trouvé + +Exemple : + +[source,C] +---------------------------------------- +struct t_weelist_item *item = weechat_list_casesearch (list, "ma donnée"); +---------------------------------------- + +weechat_list_get +^^^^^^^^^^^^^^^^ + +Retourne un élément de la liste par sa position. + +Prototype : + +[source,C] +---------------------------------------- +struct t_weelist_item *weechat_list_get (struct t_weelist *weelist, + int position); +---------------------------------------- + +Paramètres : + +* 'weelist' : pointeur vers la liste +* 'position' : position dans la liste (le premier élément est 0) + +Valeur de retour : + +* pointeur vers l'élément trouvé, NULL si aucun élément n'a été trouvé + +Exemple : + +[source,C] +---------------------------------------- +struct t_weelist_item *item = weechat_list_get (list, 0); /* premier élément */ +---------------------------------------- + +weechat_list_set +^^^^^^^^^^^^^^^^ + +Affecte une nouvelle valeur pour un élément. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_list_set (struct t_weelist_item *item, const char *value); +---------------------------------------- + +Paramètres : + +* 'item' : pointeur vers l'élément +* 'value' : nouvelle valeur pour l'élément + +Exemple : + +[source,C] +---------------------------------------- +weechat_list_set (item, "nouvelle donnée"); +---------------------------------------- + +weechat_list_next +^^^^^^^^^^^^^^^^^ + +Retourne l'éléement suivant dans la liste. + +Prototype : + +[source,C] +---------------------------------------- +struct t_weelist_item *weechat_list_next (struct t_weelist_item *item); +---------------------------------------- + +Paramètres : + +* 'item' : pointeur vers l'élément + +Valeur de retour : + +* pointeur vers l'élément suivant, NULL si le pointeur était sur le dernier + élément de la liste + +Exemple : + +[source,C] +---------------------------------------- +struct t_weelist_item *next_item = weechat_list_next_item (item); +---------------------------------------- + +weechat_list_prev +^^^^^^^^^^^^^^^^^ + +Retourne l'élément précédent dans la liste. + +Prototype : + +[source,C] +---------------------------------------- +struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item); +---------------------------------------- + +Paramètres : + +* 'item' : pointeur vers l'élément + +Valeur de retour : + +* pointeur vers l'élément précédent, NULL si le pointeur était sur le premier + élément de la liste + +Exemple : + +[source,C] +---------------------------------------- +struct t_weelist_item *prev_item = weechat_list_prev_item (item); +---------------------------------------- + +weechat_list_string +^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur de l'élément sous forme de chaîne. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_list_string (struct t_weelist_item *item); +---------------------------------------- + +Paramètres : + +* 'item' : pointeur vers l'élément + +Valeur de retour : + +* valeur de l'élément + +Exemple : + +[source,C] +---------------------------------------- +char *value = weechat_list_string (item); +---------------------------------------- + +weechat_list_size +^^^^^^^^^^^^^^^^^ + +Retourne la taille de la liste (nombre d'éléments). + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_list_size (struct t_weelist *weelist); +---------------------------------------- + +Paramètres : + +* 'weelist' : pointeur vers la liste + +Valeur de retour : + +* taille de la liste (nombre d'éléments), 0 si la liste est vide + +Exemple : + +[source,C] +---------------------------------------- +int size = weechat_list_size (list); +---------------------------------------- + +weechat_list_remove +^^^^^^^^^^^^^^^^^^^ + +Supprime un élément de la liste. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_list_remove (struct t_weelist *weelist, + struct t_weelist_item *item); +---------------------------------------- + +Paramètres : + +* 'weelist' : pointeur vers la liste +* 'item' : pointeur vers l'élément + +Exemple : + +[source,C] +---------------------------------------- +weechat_list_remove (list, item); +---------------------------------------- + +weechat_list_remove_all +^^^^^^^^^^^^^^^^^^^^^^^ + +Supprime tous les éléments de la liste. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_list_remove_all (struct t_weelist *weelist); +---------------------------------------- + +Paramètres : + +* 'weelist' : pointeur vers la liste + +Exemple : + +[source,C] +---------------------------------------- +weechat_list_remove_all (list); +---------------------------------------- + +weechat_list_free +^^^^^^^^^^^^^^^^^ + +Supprime une liste. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_list_free (struct t_weelist *weelist); +---------------------------------------- + +Paramètres : + +* 'weelist' : pointeur vers la liste + +Exemple : + +[source,C] +---------------------------------------- +weechat_list_free (list); +---------------------------------------- + +[[configuration_files]] +Fichiers de configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Fonctions pour les fichiers de configuration. + +weechat_config_new +^^^^^^^^^^^^^^^^^^ + +Crée un nouveau fichier de configuration. + +Prototype : + +[source,C] +---------------------------------------- +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); +---------------------------------------- + +Paramètres : + +* 'name' : nom du nouveau fichier de configuration (sans chemin ou extension) +* 'callback_reload' : fonction appelée quand le fichier de configuration est + rechargé avec `/reload` (optionnel, peut être NULL), paramètres : +** 'void *data' : pointeur +** 'struct t_config_file *config_file' : pointeur vers le fichier de + configuration +* 'callback_reload_data' : pointeur donné au "callback" de rechargement + lorsqu'il est appelé par WeeChat + +Valeur de retour : + +* pointeur vers le nouveau fichier de configuration, NULL en cas d'erreur + +[NOTE] +Le fichier n'est PAS créé sur le disque par cette fonction. Il sera créé par +l'appel à la fonction <<_weechat_write_config>>. Vous ne devriez appeler cette +fonction qu'après avoir créé les sections (avec <<_weechat_config_new_section>>) +et les options (avec <<_weechat_config_new_option>>). + +Exemple : + +[source,C] +---------------------------------------- +int +my_config_reload_cb (void *data, struct t_config_file *config_file) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +struct t_config_file *config_file = weechat_config_new ("test", + &my_config_reload_cb, + NULL); +---------------------------------------- + +weechat_config_new_section +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Crée une nouvelle section dans un fichier de configuration. + +Prototype : + +[source,C] +---------------------------------------- +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, + int (*callback_read)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, + const char *value), + void *callback_read_data, + int (*callback_write)(void *data, + struct t_config_file *config_file, + const char *section_name), + void *callback_write_data, + int (*callback_write_default)(void *data, + struct t_config_file *config_file, + const char *section_name); + void *callback_write_default_data, + int (*callback_create_option)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, + const char *value), + void *callback_create_option_data, + int (*callback_delete_option)(void *data, + struct t_config_file *config_file, + struct t_config_section *section, + struct t_config_option *option), + void *callback_delete_option_data); +---------------------------------------- + +Paramètres : + +* 'config_file' : pointeur vers le fichier de configuration +* 'name' : nom de la section +* 'user_can_add_options' : 1 si l'utilisateur peut créer de nouvelles options + dans la section, ou 0 si c'est interdit +* 'user_can_delete_options' : 1 si l'utilisateur peut supprimer des options + dans la section, ou 0 si c'est interdit +* 'callback_read' : fonction appelée quand une option de la section est lue + depuis le disque (devrait être NULL dans la plupart des cas, sauf si des + options de la section nécessitent une fonction personnalisée), paramètres : +** 'void *data' : pointeur +** 'struct t_config_file *config_file' : pointeur vers le fichier de + configuration +** 'struct t_config_section *section' : pointeur vers la section +** 'const char *option_name' : nom de l'option +** 'const char *value' : valeur +* 'callback_read_data' : pointeur donné au "callback" quand il est appelé par + WeeChat +* 'callback_write' : fonction appelée lorsque la section est écrite dans le + fichier (devrait être NULL dans la plupart des cas, sauf si la section + nécessite d'être écrite par une fonction personnalisée), paramètres : +** 'void *data' : pointeur +** 'struct t_config_file *config_file' : pointeur vers le fichier de + configuration +** 'struct t_config_section *section' : pointeur vers la section +** 'const char *option_name' : nom de l'option +* callback_write_data : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat +* callback_write_default : fonction appelée lorsque les valeurs par défaut + doivent être écrites dans le fichier, paramètres : +** 'void *data' : pointeur +** 'struct t_config_file *config_file' : pointeur vers le fichier de + configuration +** 'const char *section_name' : nom de la section +* 'callback_write_default_data' : pointeur donné au "callback" lorsqu'il est + appelé par WeeChat +* 'callback_create_option' : fonction appelée lorsqu'une nouvelle option est + créée dans la section (NULL si la section n'autorise pas la création de + nouvelles options), paramètres : +** 'void *data' : pointeur +** 'struct t_config_file *config_file' : pointeur vers le fichier de + configuration +** 'struct t_config_section *section' : pointeur vers la section +** 'const char *option_name' : nom de l'option +** 'const char *value' : valeur +* 'callback_create_option_data' : pointeur donné au "callback" lorsqu'il est + appelé par WeeChat +* 'callback_delete_option' : fonction appelée lorsqu'une option est supprimée + de la section (NULL si la section n'autorise pas la suppression d'options), + paramètres : +** 'void *data' : pointeur +** 'struct t_config_file *config_file' : pointeur vers le fichier de + configuration +** 'struct t_config_section *section' : pointeur vers la section +** 'struct t_config_option *option' : pointeur vers l'option +* 'callback_delete_option_data' : pointeur donné au "callback" lorsqu'il est + appelé par WeeChat + +Valeur de retour : + +* pointeur vers la nouvelle section du fichier de configuration, NULL en cas + d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +ma_section_read_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, const char *option_name, + const char *value) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +ma_section_write_cb (void *data, struct t_config_file *config_file, + const char *section_name) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +ma_section_write_default_cb (void *data, struct t_config_file *config_file, + const char *section_name) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +ma_section_create_option_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name, const char *value) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +int +ma_section_delete_option_cb (void *data, struct t_config_file *config_file, + struct t_config_section *section, + struct t_config_option *option) +{ + /* ... */ + + return WEECHAT_RC_OK; +} + +/* section standard, l'utilisateur ne peut pas ajouter/supprimer des options */ +struct t_config_section *new_section1 = + weechat_config_new_section (config_file, "section1", 0, 0, + NULL, NULL, /* callback de lecture */ + NULL, NULL, /* callback d'écriture */ + NULL, NULL, /* callback d'écriture (valeurs par défaut) */ + NULL, NULL, /* callback de création d'option */ + NULL, NULL); /* callback de suppression d'option */ + +/* section spéciale, l'utilisateur peut ajouter/supprimer des options, et les + options nécessitent un callback pour la lecture/écriture */ +struct t_config_section *new_section2 = + weechat_config_new_section (config_file, "section2", 1, 1, + &ma_section_read_cb, NULL, + &ma_section_write_cb, NULL, + &ma_section_write_default_cb, NULL, + &ma_section_create_option_cb, NULL, + &ma_section_delete_option_cb, NULL); +---------------------------------------- + +weechat_config_search_section +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Recherche une section dans un fichier de configuration. + +Prototype : + +[source,C] +---------------------------------------- +struct t_config_section *weechat_config_search_section ( + struct t_config_file *config_file, + const char *section_name); +---------------------------------------- + +Paramètres : + +* 'config_file' : pointeur vers le fichier de configuration +* 'section_name' : nom de la section à chercher + +Valeur de retour : + +* pointeur vers la section trouvée, ou NULL si la section n'a pas été trouvée + +Exemple : + +[source,C] +---------------------------------------- +struct t_config_section *section = weechat_config_search_section (config_file, + "section"); +---------------------------------------- + +weechat_config_new_option +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Crée une nouvelle option dans une section d'un fichier de configuration. + +Prototype : + +[source,C] +---------------------------------------- +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, + const char *description, + const char *string_values, + int min, + int max, + const char *default_value, + const char *value, + int null_value_allowed, + int (*callback_check_value)(void *data, + struct t_config_option *option, + const char *value), + void *callback_check_value_data, + int (*callback_change)(void *data, + struct t_config_option *option), + void *callback_change_data, + int (*callback_delete)(void *data, + struct t_config_option *option), + void *callback_delete_data); +---------------------------------------- + +Paramètres : + +* 'config_file' : pointeur vers le fichier de configuration +* 'section' : pointeur vers la section +* 'name' : nom de l'option +* 'type' : type de l'option : +** 'boolean' : valeur booléenne (on/off) +** 'integer' : valeur entière (avec en option une chaîne pour chaque valeur) +** 'string' : une chaîne de caractères +** 'color' : une couleur +* 'description' : description de l'option +* 'string_values' : valeurs sous forme de chaîne (séparées par "|"), utilisées + pour le type 'integer' (optionnel) +* 'min' : valeur minimum (pour le type 'integer') +* 'max' : valeur maximum (pour le type 'integer') +* 'default_value' : valeur par défaut de l'option (utilisée quand l'option est + réinitialisée) +* 'value' : valeur de l'option +* 'null_value_allowed' : 1 si 'null' (valeur non définie) est autorisé pour + l'option, sinon 0 +* 'callback_check_value' : fonction appelée pour vérifier la nouvelle valeur + de l'option (optionnel), paramètres : +** 'void *data' : pointeur +** 'struct t_config_option *option' : pointeur vers l'option +** 'const char *value' : nouvelle valeur pour l'option +* 'callback_check_value_data' : pointeur donné au "callback" lorsqu'il est + appelé par WeeChat +* 'callback_change' : fonction appelée lorsque la valeur de l'option a changé + (optionnel), paramètres : +** 'void *data' : pointeur +** 'struct t_config_option *option' : pointeur vers l'option +* 'callback_change_data' : pointeur donné au "callback" lorsqu'il est appelé + par WeeChat +* 'callback_delete' : fonction appelée lorsque l'option est supprimée + (optionnel), paramètres : +** 'void *data' : pointeur +** 'struct t_config_option *option' : pointeur vers l'option +* 'callback_delete_data' : pointeur donné au "callback" lorsqu'il est appelé + par WeeChat + +Valeur de retour : + +* pointeur vers la nouvelle option de la section, NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +/* boolean */ +struct t_config_option *option1 = + weechat_config_new_option (config_file, section, + "option1", "Mon option, type booléen" + NULL, /* valeurs sous forme de chaînes */ + 0, 0, /* min, max */ + "on", /* défaut */ + "on", /* valeur */ + 0, /* valeur null autorisée */ + NULL, NULL, /* callback de vérification */ + NULL, NULL, /* callback de changement de valeur */ + NULL, NULL); /* callback de suppression de l'option */ + +/* integer */ +struct t_config_option *option2 = + weechat_config_new_option (config_file, section, + "option2", "Mon option, type entier" + NULL, /* valeurs sous forme de chaînes */ + 0, 100, /* min, max */ + "15", /* défaut */ + "15", /* valeur */ + 0, /* valeur null autorisée */ + NULL, NULL, /* callback de vérification */ + NULL, NULL, /* callback de changement de valeur */ + NULL, NULL); /* callback de suppression de l'option */ + +/* integer (with string values) */ +struct t_config_option *option3 = + weechat_config_new_option (config_file, section, + "option3", + "Mon option, type entier " + "(avec valeurs sous forme de chaînes)" + "top|bottom|left|right", /* valeurs sous forme de chaînes */ + 0, 0, /* min, max */ + "bottom", /* défaut */ + "bottom", /* valeur */ + 0, /* valeur null autorisée */ + NULL, NULL, /* callback de vérification */ + NULL, NULL, /* callback de changement de valeur */ + NULL, NULL); /* callback de suppression de l'option */ + +/* string */ +struct t_config_option *option4 = + weechat_config_new_option (config_file, section, + "option4", "Mon option, type chaîne" + NULL, /* valeurs sous forme de chaînes */ + 0, 0, /* min, max */ + "test", /* défaut */ + "test", /* valeur */ + 1, /* valeur null autorisée */ + NULL, NULL, /* callback de vérification */ + NULL, NULL, /* callback de changement de valeur */ + NULL, NULL); /* callback de suppression de l'option */ + +/* color */ +struct t_config_option *option5 = + weechat_config_new_option (config_file, section, + "option5", "Mon option, type couleur" + NULL, /* valeurs sous forme de chaînes */ + 0, 0, /* min, max */ + "lightblue", /* défaut */ + "lightblue", /* valeur */ + 0, /* valeur null autorisée */ + NULL, NULL, /* callback de vérification */ + NULL, NULL, /* callback de changement de valeur */ + NULL, NULL); /* callback de suppression de l'option */ +---------------------------------------- + +weechat_config_search_option +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Recherche une option dans une section d'un fichier de configuration. + +Prototype : + +[source,C] +---------------------------------------- +struct t_config_option *weechat_config_search_option ( + struct t_config_file *config_file, + struct t_config_section *section, + const char *option_name); +---------------------------------------- + +Paramètres : + +* 'config_file' : pointeur vers le fichier de configuration +* 'section' : pointeur vers la section +* 'name' : nom de l'option à rechercher + +Valeur de retour : + +* pointeur vers l'option trouvée, NULL si l'option n'a pas été trouvée + +Exemple : + +[source,C] +---------------------------------------- +struct t_config_option *option = + weechat_config_search_option (config_file, section, "option"); +---------------------------------------- + +weechat_config_search_with_string +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Recherche une option avec le nom complet. + +Prototype : + +[source,C] +---------------------------------------- +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); +---------------------------------------- + +Paramètres : + +* 'option_name' : nom complet de l'option (format : "fichier.section.option") +* 'config_file' : pointeur vers un pointeur sur un fichier de configuration, + sera alimenté avec le pointeur vers le fichier de configuration de l'option + trouvée +* 'section' : pointeur vers un pointeur sur une section, sera alimenté avec le + pointeur vers la section de l'option trouvée +* 'option' : pointeur vers un pointeur sur une option, sera alimenté avec le + pointeur vers l'option trouvée + +Exemple : + +[source,C] +---------------------------------------- +struct t_config_file *ptr_config_file; +struct t_config_section *ptr_section; +struct t_config_option *ptr_option; + +weechat_config_search_with_string ("fichier.section.option", + &ptr_config_file, + &ptr_section, + &ptr_option); +if (ptr_option) +{ + /* option trouvée */ +} +else +{ + /* option non trouvée */ +} +---------------------------------------- + +weechat_config_string_to_boolean +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Vérifie si un texte est "vrai" ou "faux", au sens booléen. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_string_to_boolean (const char *text); +---------------------------------------- + +Paramètres : + +* 'text' : texte à analyser + +Valeur de retour : + +* 1 si le texte est "vrai" ("on", "yes", "y", "true", "t", "1") +* 0 si le texte est "faux" ("off", "no", "n", "false", "f", "0") + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_config_string_to_boolean (option_value)) +{ + /* la valeur est "vrai" */ +} +else +{ + /* la valeur est "faux" */ +} +---------------------------------------- + +weechat_config_option_reset +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Réinitialise une option à sa valeur par défaut. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_option_reset (struct t_config_option *option, + int run_callback); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option +* 'run_callback' : 1 pour appeler le "callback" si la valeur de l'option est + changée, sinon 0 + +Valeur de retour : + +* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' si la valeur de l'option a été + réinitialisée +* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' si la valeur n'a pas changé +* 'WEECHAT_CONFIG_OPTION_SET_ERROR' en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +switch (weechat_config_option_reset (option, 1)) +{ + case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: + /* .... */ + break; + case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: + /* .... */ + break; + case WEECHAT_CONFIG_OPTION_SET_ERROR: + /* .... */ + break; +} +---------------------------------------- + +weechat_config_option_set +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Affecter une nouvelle valeur pour une option. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_option_set (struct t_config_option *option, + const char *value, int run_callback); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option +* 'value' : nouvelle valeur pour l'option +* 'run_callback' : 1 pour appeler le "callback" si la valeur de l'option est + changée, sinon 0 + +Valeur de retour : + +* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' si la veleur de l'option a été changée +* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' si la valeur n'a pas changé +* 'WEECHAT_CONFIG_OPTION_SET_ERROR' en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +switch (weechat_config_option_set (option, "new_value", 1)) +{ + case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: + /* .... */ + break; + case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: + /* .... */ + break; + case WEECHAT_CONFIG_OPTION_SET_ERROR: + /* .... */ + break; +} +---------------------------------------- + +weechat_config_option_set_null +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Affecter "null" (valeur indéfinie) à une option. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_option_set_null (struct t_config_option *option, + int run_callback); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option +* 'run_callback' : 1 pour appeler le "callback" si la valeur de l'option est + changée (elle n'était pas "null"), sinon 0 + +[NOTE] +Vous pouvez affecter "null" à une option seulement si c'est autorisé pour +l'option (voir <<_weechat_config_new_option>>). + +Valeur de retour : + +* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' si la valeur de l'option a été changée +* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' si la valeur n'a pas changé +* 'WEECHAT_CONFIG_OPTION_SET_ERROR' en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +switch (weechat_config_option_set_null (option, 1)) +{ + case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: + /* .... */ + break; + case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: + /* .... */ + break; + case WEECHAT_CONFIG_OPTION_SET_ERROR: + /* .... */ + break; +} +---------------------------------------- + +weechat_config_option_unset +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Réinitialiser ou supprimer une option. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_option_unset (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Valeur de retour : + +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' si la valeur de l'option n'a pas + été réinitialisée +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' si la valeur de l'option a été + réinitialisée +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' si l'option a été supprimée +* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +switch (weechat_config_option_unset (option)) +{ + case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET: + /* .... */ + break; + case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET: + /* .... */ + break; + case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED: + /* .... */ + break; + case WEECHAT_CONFIG_OPTION_UNSET_ERROR: + /* .... */ + break; +} +---------------------------------------- + +weechat_config_option_rename +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Renomme une option. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_config_option_rename (struct t_config_option *option, + const char *new_name); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option +* 'new_name' : nouveau nom pour l'option + +Exemple : + +[source,C] +---------------------------------------- +weechat_config_option_rename (option, "nouveau_nom"); +---------------------------------------- + +weechat_config_option_get_pointer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne un pointeur vers une propriété de l'option. + +Prototype : + +[source,C] +---------------------------------------- +void *weechat_config_option_get_pointer (struct t_config_option *option, + const char *property); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option +* 'property' : nom de la propriété : +** 'config_file' : pointeur vers le fichier de configuration + ('struct t_config_file *') +** 'section' : pointeur vers la section ('struct t_config_section *') +** 'name' : nom de l'option ('char *') +** 'type' : type de l'option ('int *') +** 'description' : description de l'option ('char *') +** 'string_values' : valeurs sous forme de chaîne ('char *') +** 'min' : valeur minimum ('int *') +** 'max' : valeur maximum ('int *') +** 'default_value' : valeur par défaut (dépend du type) +** 'value' : valeur courante (dépend du type) +** 'prev_option' : pointeur vers l'option précédente + ('struct t_config_option *') +** 'next_option' : pointeur vers l'option suivante + ('struct t_config_option *') + +Valeur de retour : + +* pointeur vers la propriété demandée + +Exemple : + +[source,C] +---------------------------------------- +char *description = weechat_config_option_get_pointer (option, "description"); +---------------------------------------- + +weechat_config_option_is_null +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Vérifie si une option est "null" (valeur non définie). + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_option_is_null (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Valeur de retour : + +* 1 si la valeur de l'option est "null" +* 0 si la valeur de l'option n'est pas "null" + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_config_option_is_null (option)) +{ + /* value is "null" */ +} +else +{ + /* value is not "null" */ +} +---------------------------------------- + +weechat_config_boolean +^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur booléenne de l'option. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_boolean (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Valeur de retour : + +* valeur booléenne de l'option (0 ou 1) + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_config_boolean (option)) +{ + /* la valeur est "vrai" */ +} +else +{ + /* la valeur est "faux" */ +} +---------------------------------------- + +weechat_config_boolean_default +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur booléenne par défaut de l'option. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_boolean_default (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Valeur de retour : + +* valeur booléenne par défaut de l'option (0 ou 1) + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_config_boolean_default (option)) +{ + /* la valeur est "vrai" */ +} +else +{ + /* la valeur est "faux" */ +} +---------------------------------------- + +weechat_config_integer +^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur entière de l'option. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_integer (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Valeur de retour : + +* valeur entière de l'option + +Exemple : + +[source,C] +---------------------------------------- +int value = weechat_config_integer (option); +---------------------------------------- + +weechat_config_integer_default +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur entière par défaut de l'option. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_integer_default (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Valeur de retour : + +* valeur entière par défaut de l'option + +Exemple : + +[source,C] +---------------------------------------- +int value = weechat_config_integer_default (option); +---------------------------------------- + +weechat_config_string +^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur de l'option, sous forme de chaîne. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_config_string (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Valeur de retour : + +* valeur de l'option, sous forme de chaîne + +Exemple : + +[source,C] +---------------------------------------- +const char *value = weechat_config_string (option); +---------------------------------------- + +weechat_config_string_default +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur par défaut de l'option, sous forme de chaîne. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_config_integer_default (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Valeur de retour : + +* valeur par défaut de l'option, sous forme de chaîne + +Exemple : + +[source,C] +---------------------------------------- +const char *value = weechat_config_string_default (option); +---------------------------------------- + +weechat_config_color +^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur de l'option, sous forme de couleur. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_config_color (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Valeur de retour : + +* valeur de l'option sous forme de couleur (chaîne avec le nom de la couleur) + +Exemple : + +[source,C] +---------------------------------------- +const char *color = weechat_config_color (option); +---------------------------------------- + +weechat_config_color_default +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur par défaut de l'option, sous forme de couleur. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_config_color_default (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Valeur de retour : + +* valeur par défaut de l'option sous forme de couleur (chaîne avec le nom de la + couleur) + +Exemple : + +[source,C] +---------------------------------------- +const char *color = weechat_config_color_default (option); +---------------------------------------- + +weechat_config_write_option +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ecrit une ligne dans le fichier de configuration avec l'option et sa valeur +(cette fonction doit être appelée uniquement dans un "callback" "write" ou +"write_default" pour une section). + +Prototype : + +[source,C] +---------------------------------------- +void weechat_config_write_option (struct t_config_file *config_file, + struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'config_file' : pointeur vers le fichier de configuration +* 'option' : pointeur vers l'option + +Exemple : + +[source,C] +---------------------------------------- +int +ma_section_write_cb (void *data, struct t_config_file *config_file, + const char *section_name) +{ + weechat_config_write_line (config_file, "ma_section", NULL); + + weechat_config_write_option (config_file, option); + + return WEECHAT_RC_OK; +} +---------------------------------------- + +weechat_config_write_line +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ecrit une ligne dans un fichier de configuration (cette fonction doit être +appelée uniquement dans un "callback" "write" ou "write_default" pour une +section). + +Prototype : + +[source,C] +---------------------------------------- +void weechat_config_write_line (struct t_config_file *config_file, + const char *option_name, + const char *value, ...); +---------------------------------------- + +Paramètres : + +* 'config_file' : pointeur vers le fichier de configuration +* 'option_name' : nom de l'option +* 'value' : valeur (si NULL, alors la ligne est écrite avec le nom de la + section, par example : "[section]") + +Exemple : + +[source,C] +---------------------------------------- +int +ma_section_write_cb (void *data, struct t_config_file *config_file, + const char *section_name) +{ + weechat_config_write_line (config_file, "ma_section", NULL); + + weechat_config_write_line (config_file, "option", "%s;%d", + "value", 123); + + return WEECHAT_RC_OK; +} +---------------------------------------- + +weechat_config_write +^^^^^^^^^^^^^^^^^^^^ + +Ecrit un fichier de configuration sur le disque. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_write (struct t_config_file *config_file); +---------------------------------------- + +Paramètres : + +* 'config_file' : pointeur vers le fichier de configuration. + +Valeur de retour : + +* 'WEECHAT_CONFIG_WRITE_OK' si la configuration a été écrite +* 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR' s'il n'y a pas eu suffisamment de mémoire +* 'WEECHAT_CONFIG_WRITE_ERROR' si une autre erreur s'est produite + +Exemple : + +[source,C] +---------------------------------------- +switch (weechat_config_write (config_file)) +{ + case WEECHAT_CONFIG_WRITE_OK: + /* ... */ + break; + case WEECHAT_CONFIG_WRITE_MEMORY_ERROR: + /* ... */ + break; + case WEECHAT_CONFIG_WRITE_ERROR: + /* ... */ + break; +} +---------------------------------------- + +weechat_config_read +^^^^^^^^^^^^^^^^^^^ + +Lit un fichier de configuration depuis le disque. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_read (struct t_config_file *config_file); +---------------------------------------- + +Paramètres : + +* 'config_file' : pointeur vers le fichier de configuration + +Valeur de retour : + +* 'WEECHAT_CONFIG_READ_OK' si la configuration a été chargée +* 'WEECHAT_CONFIG_READ_MEMORY_ERROR' s'il n'y a pas eu suffisamment de mémoire +* 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' si le fichier n'a pas été trouvé + +Exemple : + +[source,C] +---------------------------------------- +switch (weechat_config_read (config_file)) +{ + case WEECHAT_CONFIG_READ_OK: + /* ... */ + break; + case WEECHAT_CONFIG_READ_MEMORY_ERROR: + /* ... */ + break; + case WEECHAT_CONFIG_READ_FILE_NOT_FOUND: + /* ... */ + break; +} +---------------------------------------- + +weechat_config_reload +^^^^^^^^^^^^^^^^^^^^^ + +Relit un fichier de configuration depuis le disque. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_reload (struct t_config_file *config_file); +---------------------------------------- + +Paramètres : + +* 'config_file' : pointeur vers le fichier de configuration + +Valeur de retour : + +* 'WEECHAT_CONFIG_READ_OK' si la configuration a été rechargée +* 'WEECHAT_CONFIG_READ_MEMORY_ERROR' s'il n'y a pas eu suffisamment de mémoire +* 'WEECHAT_CONFIG_READ_FILE_NOT_FOUND' si le fichier n'a pas été trouvé + +Exemple : + +[source,C] +---------------------------------------- +switch (weechat_config_reload (config_file)) +{ + case WEECHAT_CONFIG_READ_OK: + /* ... */ + break; + case WEECHAT_CONFIG_READ_MEMORY_ERROR: + /* ... */ + break; + case WEECHAT_CONFIG_READ_FILE_NOT_FOUND: + /* ... */ + break; +} +---------------------------------------- + +weechat_config_option_free +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Libère une option. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_config_option_free (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'option' : pointeur vers l'option + +Exemple : + +[source,C] +---------------------------------------- +weechat_config_option_free (option); +---------------------------------------- + +weechat_config_section_free_options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Libère toutes les options dans une section. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_config_section_free_options (struct t_config_section *section); +---------------------------------------- + +Paramètres : + +* 'section' : pointeur vers la section + +Exemple : + +[source,C] +---------------------------------------- +weechat_config_section_free_options (section); +---------------------------------------- + +weechat_config_section_free +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Libère une section. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_config_section_free (struct t_config_option *option); +---------------------------------------- + +Paramètres : + +* 'section' : pointeur vers la section + +Exemple : + +[source,C] +---------------------------------------- +weechat_config_section_free (section); +---------------------------------------- + +weechat_config_free +^^^^^^^^^^^^^^^^^^^ + +Libère un fichier de configuration. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_config_free (struct t_config_file *config_file); +---------------------------------------- + +Paramètres : + +* 'config_file' : pointeur vers le fichier de configuration + +Exemple : + +[source,C] +---------------------------------------- +weechat_config_free (config_file); +---------------------------------------- + +weechat_config_get +^^^^^^^^^^^^^^^^^^ + +Recherche une option avec le nom complet. + +Prototype : + +[source,C] +---------------------------------------- +struct t_config_option *weechat_config_get (const char *option_name); +---------------------------------------- + +Paramètres : + +* 'option_name' : nom complet de l'option (format : "fichier.section.option") + +Valeur de retour : + +* pointeur vers l'option trouvée, NULL si l'option n'a pas été trouvée + +Exemple : + +[source,C] +---------------------------------------- +struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format"); +---------------------------------------- + +weechat_config_get_plugin +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Recherche une option dans le fichier de configuration des extensions +(plugins.conf). + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_config_get_plugin (const char *option_name); +---------------------------------------- + +Paramètres : + +* 'option_name' : nom de l'option, WeeChat ajoutera le préfixe + "plugins.var.xxx." (où "xxx" est le nom de l'extension courante) + +Valeur de retour : + +* valeur de l'option trouvée, NULL si l'option n'a pas été trouvée + +Exemple : + +[source,C] +---------------------------------------- +/* si l'extension courante est "test", alors on cherche la valeur de l'option + "plugins.var.test.option" dans le fichier plugins.conf */ +char *value = weechat_config_get_plugin ("option"); +---------------------------------------- + +weechat_config_is_set_plugin +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Vérifie si une option existe dans le fichier de configuration des extensions +(plugins.conf). + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_is_set_plugin (const char *option_name); +---------------------------------------- + +Paramètres : + +* 'option_name' : nom de l'option, WeeChat ajoutera le préfixe + "plugins.var.xxx." (où "xxx" est le nom de l'extension courante) + +Valeur de retour : + +* 1 si l'option est définie, 0 si l'option n'existe pas + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_config_is_set_plugin ("option")) +{ + /* l'option existe */ +} +else +{ + /* l'option n'existe pas */ +} +---------------------------------------- + +weechat_config_set_plugin +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Affecter une nouvelle valeur pour une option dans le fichier de configuration +des extensions (plugins.conf). + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_set_plugin (const char *option_name, const char *value); +---------------------------------------- + +Paramètres : + +* 'option_name' : nom de l'option, WeeChat ajoutera le préfixe + "plugins.var.xxx." (où "xxx" est le nom de l'extension courante) +* 'value' : nouvelle valeur pour l'option + +Valeur de retour : + +* 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED' si la valeur de l'option a été changée +* 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE' si la valeur n'a pas changé +* 'WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND' si l'option n'a pas été trouvée +* 'WEECHAT_CONFIG_OPTION_SET_ERROR' en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +switch (weechat_config_set_plugin ("option", "valeur_test")) +{ + case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED: + /* ... */ + break; + case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE: + /* ... */ + break; + case WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND: + /* ... */ + break; + case WEECHAT_CONFIG_OPTION_SET_ERROR: + /* ... */ + break; +} +---------------------------------------- + +weechat_config_unset_plugin +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Supprime une option du fichier de configuration des extensions (plugins.conf). + +Prototype : + +[source,C] +---------------------------------------- +int weechat_config_unset_plugin (const char *option_name); +---------------------------------------- + +Paramètres : + +* 'option_name' : nom de l'option, WeeChat ajoutera le préfixe + "plugins.var.xxx." (où "xxx" est le nom de l'extension courante) + +Valeur de retour : + +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET' si la valeur de l'option n'a pas + été réinitialisée +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_RESET' si la valeur de l'option a été + réinitialisée +* 'WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED' si l'option a été supprimée +* 'WEECHAT_CONFIG_OPTION_UNSET_ERROR' en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +switch (weechat_config_unset_plugin ("option")) +{ + case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET: + /* ... */ + break; + case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET: + /* ... */ + break; + case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED: + /* ... */ + break; + case WEECHAT_CONFIG_OPTION_UNSET_ERROR: + /* ... */ + break; +} +---------------------------------------- + +[[display]] +Affichage +~~~~~~~~~ + +Fonctions pour afficher du texte dans les tampons. + +weechat_prefix +^^^^^^^^^^^^^^ + +Retourne un préfixe. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_prefix (const char *prefix); +---------------------------------------- + +Paramètres : + +* 'prefix' : nom du préfixe : + +[width="60%",cols="^2,^1,^2,5",options="header"] +|======================================== +| Préfixe | Valeur | Couleur | Description +| 'error' | `=!=` | jaune | message d'erreur +| 'network' | `--` | violet | message du réseau +| 'action' | `*` | blanc | action personnelle +| 'join' | `-->` | vert clair | quelqu'un a rejoint la discussion +| 'quit' | `<--` | rouge clair | quelqu'un a quitté la discussion +|======================================== + +[NOTE] +Les valeurs et couleurs peuvent être configurées avec la commande `/set`. + +Valeur de retour : + +* valeur du préfixe (chaîne avec le préfixe et des codes couleur), chaîne vide + si le préfixe n'a pas été trouvé + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "%sCeci est une erreur...", weechat_prefix ("error")); +---------------------------------------- + +weechat_color +^^^^^^^^^^^^^ + +Retourne une chaîne avec un code couleur pour affichage. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_color (const char *color_name); +---------------------------------------- + +Paramètres : + +* 'color_name' : nom de la couleur, parmi : +** une option WeeChat (de weechat.color.xxx), par exemple 'chat_delimiters' +** une couleur avec un fond optionnel, par exemple 'yellow' ou 'yellow,red' +** un attribut : +*** 'bold' : activer le gras +*** '-bold' : désactiver le gras +*** 'reverse' : activer la vidéo inverse +*** '-reverse' : désactiver la vidéo inverse +*** 'italic' : activer l'italique +*** '-italic' : désactiver l'italique +*** 'underline' : activer le souligné +*** '-underline' : désactiver le souligné +** nom d'une couleur de barre : +*** 'bar_fg' : couleur de texte pour la barre +*** 'bar_delim' : couleur des délimiteurs pour la barre +*** 'bar_bg' : couleur de fond pour la barre + +Valeur de retour : + +* chaîne avec le code couleur, ou un code couleur de réinitialisation si la + couleur n'a pas été trouvée + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "Color : %sbleu %scouleur par défaut %sjaune sur rouge", + weechat_color ("blue"), + weechat_color ("chat"), + weechat_color ("yellow,red")); +---------------------------------------- + +weechat_printf +^^^^^^^^^^^^^^ + +Affiche un message sur un tampon. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon, si NULL, le message est affiché sur le + tampon WeeChat +* 'message' : message à afficher + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "Bonjour sur le tampon WeeChat"); +weechat_printf (buffer, "Bonjour sur ce tampon"); +---------------------------------------- + +weechat_printf_date +^^^^^^^^^^^^^^^^^^^ + +Affiche un message sur un tampon, en utilisant une date personnalisée. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_printf_date (struct t_gui_buffer *buffer, time_t date, + const char *message, ...); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon, si NULL, le message est affiché sur le + tampon Weechat +* 'date' : date pour le message +* 'message' : message à afficher + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf_date (NULL, time (NULL) - 120, "Bonjour, il y a 2 minutes"); +---------------------------------------- + +weechat_printf_tags +^^^^^^^^^^^^^^^^^^^ + +Affiche un message sur un tampon, avec des étiquettes ("tags") personnalisées. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_printf_tags (struct t_gui_buffer *buffer, const char *tags, + const char *message, ...); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon, si NULL, le message est affiché sur le + tampon Weechat +* 'tags' : liste d'étiquettes ("tags") séparées par des virgules +* 'message' : message à afficher + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf_tags (NULL, "notify_message", + "Message avec une étiquette 'notify_message'"); +---------------------------------------- + +weechat_printf_date_tags +^^^^^^^^^^^^^^^^^^^^^^^^ + +Affiche un message sur un tampon, en utilisant une date et des étiquettes +("tags") personnalisées. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date, + const char *tags, const char *message, ...); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon, si NULL, le message est affiché sur le + tampon Weechat +* 'date' : date pour le message +* 'tags' : liste d'étiquettes ("tags") séparées par des virgules +* 'message' : message à afficher + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message", + "Message il y a 2 minutes avec une étiquette 'notify_message'"); +---------------------------------------- + +weechat_printf_y +^^^^^^^^^^^^^^^^ + +Affiche un message sur une ligne d'un tampon avec contenu libre. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_printf_y (struct t_gui_buffer *buffer, int y, + const char *message, ...); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'y' : numéro de ligne (la première ligne est 0) +* 'message' : message à afficher + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf_y (buffer, 2, "Mon message sur la 3ème ligne"); +---------------------------------------- + +weechat_log_printf +^^^^^^^^^^^^^^^^^^ + +Ecrit un message dans le fichier de log WeeChat (weechat.log). + +Prototype : + +[source,C] +---------------------------------------- +void weechat_log_printf (const char *message, ...); +---------------------------------------- + +Paramètres : + +* 'message' : message à écrire + +Exemple : + +[source,C] +---------------------------------------- +weechat_log_printf ("Mon message dans le fichier log"); +---------------------------------------- + +[[hooks]] +Hooks +~~~~~ + +weechat_hook_command +^^^^^^^^^^^^^^^^^^^^ + +Accroche une commande. + +Prototype : + +[source,C] +---------------------------------------- +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); +---------------------------------------- + +Paramètres : + +* 'command' : nom de la commande +* 'description' : description de la commande (affiché avec `/help command`) +* 'args' : paramètres pour la commande (affichés avec `/help command`) +* 'args_description' : description des paramètres (affichée avec + `/help command`) +* 'completion' : modèlé pour la complétion de la commande : liste des + complétions pour chaque paramètre, séparés par des espaces. Plusieurs + complétions sont possibles pour un paramètre, séparées par "|". Plusieurs + modèles de complétions sont possibles pour une même commande, séparés par + "||". Les codes complétions par défaut sont : +include ::autogen/plugin_api/completions.txt[] +** codes spéciaux : +*** '%%command' : réutiliser le modèle de complétion de la commande 'command' +*** '%-' : arrêter la complétion +*** '%*' : répéter la dernière complétion +* 'callback' : fonction appelée lorsque la commande est utilisée, paramètres : +** 'void *data' : pointeur +** 'struct t_gui_buffer *buffer' : tampon où la commande est exécutée +** 'int argc' : nombre de paramètres passés à la commande +** 'char **argv' : paramètres pour la commande +** 'char **argv_eol' : paramètres pour la commande (jusqu'à fin de ligne pour + chaque paramètre) +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Par exemple, si la commande appelée est `/command abc def ghi`, alors argv et +argv_eol contiendront les valeurs suivantes : + +* 'argv' : +** 'argv[0]' == "abc" +** 'argv[1]' == "def" +** 'argv[2]' == "ghi" +* 'argv_eol' : +** 'argv_eol[0]' == "abc def ghi" +** 'argv_eol[1]' == "def ghi" +** 'argv_eol[2]' == "ghi" + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +ma_commande_cb (void *data, struct t_gui_buffer *buffer, int argc, + char **argv, char **argv_eol) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +/* cet exemple s'inspire de la commande /filter */ +struct t_hook *my_command_hook = + weechat_hook_command (/* nom de la commande */ + "monfiltre", + /* description */ + "description de monfiltre", + /* paramètres */ + "[list] | [enable|disable|toggle [nom]] | " + "[add nom extension.tampon tags regex] | " + "[del nom|-all]", + /* description des paramètres */ + "description of arguments...", + /* complétion */ + "list" + " || enable %(filters_names)" + " || disable %(filters_names)" + " || toggle %(filters_names)" + " || add %(filters_names) %(buffers_plugins_names)|*" + " || del %(filters_names)|-all", + /* callback */ + &ma_commande_cb, + /* callback_data */ + NULL); +---------------------------------------- + +weechat_hook_command_run +^^^^^^^^^^^^^^^^^^^^^^^^ + +Intercepter une commande lorsqu'elle est exécutée par WeeChat. + +Prototype : + +[source,C] +---------------------------------------- +struct t_hook *weechat_hook_command_run (const char *command, + int (*callback)(void *data, + struct t_gui_buffer *buffer, + const char *command), + void *callback_data); +---------------------------------------- + +Paramètres : + +* 'command' : commande à intercepter, peut commencer ou se terminer par le + caractère joker "*" +* 'callback' : fonction appelée lorsque la commande est exécutée, paramètres : +** 'void *data' : pointeur +** 'struct t_gui_buffer *buffer' : tampon où la command est exécutée +** 'const char *command' : la commande exécutée, avec ses paramètres +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +[NOTE] +Le "callback" peut retourner 'WEECHAT_RC_OK' ou 'WEECHAT_RC_OK_EAT' (la +commande ne sera pas exécutée par WeeChat après le "callback"). + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +ma_commande_interceptee_cb (void *data, struct t_gui_buffer *buffer, + const char *command) +{ + weechat_printf (NULL, + "Vous voulez compléter ? Je mange la commande, ahah !"); + return WEECHAT_RC_OK_EAT; +} + +struct t_hook *my_command_run_hook = + weechat_hook_command_run ("/input complete*", + &ma_commande_interceptee_cb, NULL); +---------------------------------------- + +weechat_hook_timer +^^^^^^^^^^^^^^^^^^ + +Accroche un "timer" (fonction appelée à intervalles réguliers). + +Prototype : + +[source,C] +---------------------------------------- +struct t_hook *weechat_hook_timer (long interval, + const char *align_second, + const char *max_calls, + int (*callback)(void *data, + int remaining_calls), + void *callback_data); +---------------------------------------- + +Paramètres : + +* 'interval' : intervalle entre deux appels (en millisecondes, donc 1000 = 1 + seconde) +* 'align_second' : alignement sur la seconde. Par exemple, si la date courante + est 09:00, si l'intervalle est 60000 (60 secondes), et que align_second = 60, + alors le timer sera appelé chaque minutes quand la seconde sera 00 +* 'max_calls' : nombre maximum d'appels au timer (si 0, le timer n'a pas de + fin) +* 'callback' : fonction appelée quand le délai est atteint, paramètres : +** 'void *data' : pointeur +** 'int remaining_calls' : nombre d'appels restants (-1 si le timer n'a pas de + fin) +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +mon_timer_cb (void *data, int remaining_calls) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +/* timer appelé toutes les 20 secondes */ +struct t_hook *my_timer_hook = + weechat_hook_timer (20 * 1000, 0, 0, &mon_timer_cb, NULL); +---------------------------------------- + +weechat_hook_fd +^^^^^^^^^^^^^^^ + +Accroche un descripteur de fichier (fichier ou socket). + +Prototype : + +[source,C] +---------------------------------------- +struct t_hook *weechat_hook_fd (int fd, + int flag_read, + int flag_write, + int flag_exception, + int (*callback)(void *data, int fd), + void *callback_data); +---------------------------------------- + +Paramètres : + +* 'fd' : descripteur de fichier +* 'flag_read' : 1 = intercepter un évènement de lecture, 0 = ignorer +* 'flag_write' : 1 = intercepter un évènement d'éctiture, 0 = ignorer +* 'flag_exception' : 1 = intercepter un évènement d'exception, 0 = ignorer +* 'callback' : fonction appelée lorsqu'un des évènements sélectionnés se + produit pour le fichier (ou la socket), paramètres : +** 'void *data' : pointeur +** 'int fd' : descripteur de fichier +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +mon_fd_cb (void *data, int fd) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +int sock = socket (AF_INET, SOCK_STREAM, 0); +/* définir les options de la socket */ +/* ... */ +struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &mon_fd_cb, NULL); +---------------------------------------- + +weechat_hook_process +^^^^^^^^^^^^^^^^^^^^ + +Accroche un processus (lancé par un fork), et intercepter sa sortie. + +Prototype : + +[source,C] +---------------------------------------- +struct t_hook *weechat_hook_process (const char *command, + int timeout, + int (*callback)(void *data, + const char *command, + int return_code, + const char *stdout, + const char *stderr), + void *callback_data); +---------------------------------------- + + +Paramètres : + +* 'command' : commande à lancer dans le processus fils +* 'timeout' : timeout pour la commande (en millisecondes): après ce délai, le + processus fils est tué (0 signifie pas de limite) +* 'callback' : function appelée quand des données du fils sont disponibles, or + ou quand le fils s'est terminé, paramètres : +** 'void *data' : pointeur +** 'const char *command' : commande exécutée par le fils +** 'int return_code' : code retour : +*** '>= 0' : code retour du fils +*** '< 0' : 'WEECHAT_HOOK_PROCESS_OK_RUNNING' (données disponibles, mais le + fils tourne toujours) ou 'WEECHAT_HOOK_PROCESS_ERROR' (erreur en lançant + la commande) +** 'stdout' : sortie standard de la commande +** 'stderr' : erreurs de la commande +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +mon_processus_cb (void *data, const char *command, int return_code, + const char *stdout, const char *stderr) +{ + if (return_code == WEECHAT_HOOK_PROCESS_ERROR) + { + weechat_printf (NULL, "Erreur avec la commande '%s'", command); + return; + } + + if (return_code >= 0) + { + weechat_printf (NULL, "return_code = %d", return_code); + } + + if (stdout) + { + weechat_printf (NULL, "stdout : %s", stdout); + } + + if (stderr) + { + weechat_printf (NULL, "stderr : %s", stderr); + } + + return WEECHAT_RC_OK; +} + +struct t_hook *mon_process_hook = weechat_hook_process ("ls", 5000, + &mon_processus_cb, NULL); +---------------------------------------- + +weechat_hook_connect +^^^^^^^^^^^^^^^^^^^^ + +Accroche une connexion (connexion à une machine distante en tâche de fond). + +Prototype : + +[source,C] +---------------------------------------- +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); +---------------------------------------- + +Paramètres : + +* 'address' : nom ou adresse IP de la machine à laquelle se connecter +* 'port' : numéro de port +* 'sock' : socket utilisée pour la connexion +* 'ipv6' : 1 pour utiliser IPv6, 0 pour utiliser IPv4 +* 'gnutls_sess' : GnuTLS session (optionnel) +* 'callback' : fonction appelée lorsque la connexion est ok ou a échoué, + paramètres : +** 'void *data' : pointeur +** 'int status' : connection status : +*** 'WEECHAT_HOOK_CONNECT_OK' : connextion ok +*** 'WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND' : adresse non trouvée +*** 'WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND' : adresse IP non trouvée +*** 'WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED' : connexion refusée +*** 'WEECHAT_HOOK_CONNECT_PROXY_ERROR' : erreur avec le proxy +*** 'WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR' : erreur avec le nom local +*** 'WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR' : erreur d'initialisation GnuTLS +*** 'WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR' : erreur avec la + "poignée de main" GnuTLS +*** 'WEECHAT_HOOK_CONNECT_MEMORY_ERROR' : mémoire insuffisante +** 'const char *ip_address' : adresse IP trouvée +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +ma_connexion_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 *mon_connect_hook = weechat_hook_connect ("my.server.org", 1234, + sock, 0, NULL, NULL, + &ma_connexion_cb, NULL); +---------------------------------------- + +weechat_hook_print +^^^^^^^^^^^^^^^^^^ + +Intercepte un message affiché. + +Prototype : + +[source,C] +---------------------------------------- +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, + int displayed, + int highlight, + const char *prefix, + const char *message), + void *callback_data); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon, si NULL, les messages de tous les tampons + sont interceptés +* 'tags' : seulement les messages avec ces étiquettes ("tags") (liste séparée + par des virgules) seront interceptés (optionnel) +* 'message' : seulement les messages contenant cette chaîne seront interceptés + (optionnel) +* 'strip_colors' : si 1, les couleurs seront supprimées du message affiché, + avant d'appeler le "callback" +* 'callback' : fonction appelée lorsqu'un message est affiché, paramètres : +** 'void *data' : pointeur +** 'struct t_gui_buffer *buffer' : pointeur vers le tampon +** 'time_t date' : date +** 'int tags_count' : nombre d'étiquettes ("tags") de la ligne +** 'const char **tags' : tableau avec les étiquettes ("tags") de la ligne +** 'int displayed' : 1 si la ligne est affichée, 0 si elle est filtrée (cachée) +** 'int highlight' : 1 si la ligne contient un highlight, sinon 0 +** 'const char *prefix' : préfixe +** 'const char *message' : message +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +mon_print_cb (void *data, struct t_gui_buffer *buffer, time_t date, + int tags_count, const char **tags, + int displayed, int highlight, + const char *prefix, const char *message) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +/* intercepter tous les messages, de tous les tampons, sans couleur */ +struct t_hook *mon_print_hook = + weechat_hook_print (NULL, NULL, NULL, 1, &mon_print_cb, NULL); +---------------------------------------- + +weechat_hook_signal +^^^^^^^^^^^^^^^^^^^ + +S'accroche à un signal. + +Prototype : + +[source,C] +---------------------------------------- +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); +---------------------------------------- + +Paramètres : + +* 'signal' : signal à intercepter, peut commencer ou se terminer par "*" : + +[width="80%",cols="^1,^3,^3,5",options="header"] +|======================================== +| Extension | Signal | Paramètres | Description + +| irc | xxx,irc_in_yyy ^1^ | chaîne : message | + message irc du serveur (avant utilisation par l'extension irc) + +| irc | xxx,irc_in2_yyy ^1^ | chaîne : message | + message irc du serveur (après utilisation par l'extension irc) + +| irc | xxx,irc_out_yyy ^1^ | chaîne : message | + message irc envoyé au serveur + +| irc | irc_ctcp | chaîne : message | + CTCP reçu + +| irc | irc_dcc | chaîne message | + nouveau DCC + +| irc | irc_pv | chaîne : message | + message privé reçu + +| irc | irc_channel_opened | pointeur : tampon | + canal ouvert + +| irc | irc_pv_opened | pointeur : tampon | + discussion privée ouverte + +| irc | irc_server_connecting | chaîne : nom du serveur | + connexion en cours au serveur + +| irc | irc_server_connected | chaîne : nom du serveur | + connecté au serveur + +| irc | irc_server_disconnected | chaîne : nom du serveur | + déconnecté du serveur + +| irc | irc_ignore_removing | pointeur : ignore | + suppression d'un ignore en cours + +| irc | irc_ignore_removed | - | + ignore supprimé + +| logger | logger_start | pointeur : tampon | + démarrage de l'enregistrement sur disque pour le tampon + +| logger | logger_stop | pointeur : tampon | + fin de l'enregistrement sur disque pour le tampon + +| logger | logger_backlog | pointeur : tampon | + affichage du backlog pour le tampon + +| weechat | buffer_closing | pointeur : tampon | + fermeture du tampon en cours + +| weechat | buffer_closed | pointeur : tampon | + tampon fermé + +| weechat | buffer_lines_hidden | pointeur : tampon | + lignes cachées dans le tampon + +| weechat | buffer_localvar_added | pointeur : tampon | + variable locale ajoutée + +| weechat | buffer_localvar_changed | pointeur : tampon | + variable locale modifiée + +| weechat | buffer_localvar_removed | pointeur : tampon | + variable locale supprimée + +| weechat | buffer_moved | pointeur : tampon | + tampon déplacé + +| weechat | buffer_opened | pointeur : tampon | + tampon ouvert + +| weechat | buffer_renamed | pointeur : tampon | + tampon renommé + +| weechat | buffer_switch | pointeur : tampon | + basculement vers un autre tampon + +| weechat | buffer_title_changed | pointeur : tampon | + titre du tampon changé + +| weechat | buffer_type_changed | pointeur : tampon | + type de tampon changé + +| weechat | debug_dump | - | + requête de "dump" + +| weechat | filter_added | pointeur : filtre | + filtre ajouté + +| weechat | filter_removing | pointre : filtre | + suppression de filtre en cours + +| weechat | filter_removed | - | + filtre supprimé + +| weechat | filter_enabled | - | + filtres activés + +| weechat | filter_disabled | - | + filtres désactivés + +| weechat | hotlist_changed | - | + la hotlist a changé + +| weechat | input_paste_pending | - | + coller de lignes en cours + +| weechat | input_search | - | + recherche de texte dans le tampon + +| weechat | input_text_changed | - | + texte modifié dans la barre "input" + +| weechat | input_text_cursor_moved | - | + curseur déplacé dans la barre "input" + +| weechat | key_pressed | chaîne : touche appuyée | + touche appuyée + +| weechat | nicklist_changed | - | + la liste des pseudos a changé + +| weechat | partial_completion | - | + une complétion partielle a été faite + +| weechat | quit | chaîne : paramètres pour le /quit | + la commande `/quit` a été exécutée par l'utilisateur + +| weechat | upgrade | - | + la commande `/upgrade` a été exécutée par l'utilisateur + +| weechat | weechat_highlight | chaîne : message avec le préfixe | + un highlight est survenu + +| weechat | weechat_pv | chaîne : message avec le préfixe | + un message privé a été affiché + +| weechat | window_scrolled | pointeur : fenêtre | + défilement dans la fenêtre + +| weechat | window_unzooming | pointeur : fenêtre courante | + fin du zoom en cours sur la fenêtre + +| weechat | window_unzoomed | pointeur : fenêtre courante | + fin du zoom effectué sur la fenêtre + +| weechat | window_zooming | pointeur : fenêtre courante | + zoom en cours sur la fenêtre + +| weechat | window_zoomed | pointeur : fenêtre courante | + zomm effectué sur la fenêtre + +| xfer | xfer_add | pointeur : infolist avec l'info xfer | + nouveau xfer + +| xfer | xfer_send_ready | pointeur : infolist avec l'info xfer | + xfer ready + +| xfer | xfer_accept_resume | pointeur : infolist avec l'info xfer | + le xfer accepte la reprise (envoi) + +| xfer | xfer_send_accept_resume | pointeur : infolist avec l'info xfer | + le xfer accepte la reprise (envoi) + +| xfer | xfer_start_resume | pointeur : infolist avec l'info xfer | + redémarrage + +| xfer | xfer_resume_ready | pointer : infolist avec l'info xfer | + redémarrage prêt +|======================================== + +[NOTE] +^1^ 'xxx' est le nom du serveur IRC, 'yyy' est le nom d'une commande IRC. + +* 'callback' : fonction appelée quand le signal est reçu, paramètres : +** 'void *data' : pointeur +** 'const char *signal' : signal reçu +** 'const char *type_data' : type de donnée reçu avec le signal : +*** 'WEECHAT_HOOK_SIGNAL_STRING' : chaîne de caractères +*** 'WEECHAT_HOOK_SIGNAL_INT' : nombre entier +*** 'WEECHAT_HOOK_SIGNAL_POINTER' : pointeur +** 'void *signal_data' : données envoyées avec le signal +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +mon_signal_cb (void *data, const char *signal, const char *type_data, + void *signal_data) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +/* intercepter le signal "quit" */ +struct t_hook *mon_signal_hook = weechat_hook_signal ("quit", + &mon_signal_cb, NULL); +---------------------------------------- + +weechat_hook_signal_send +^^^^^^^^^^^^^^^^^^^^^^^^ + +Envoie un signal. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_hook_signal_send (const char *signal, const char *type_data, + void *signal_data); +---------------------------------------- + +Paramètres : + +* 'signal' : signal à envoyer +* 'type_data' : type de données à envoyer avec le signal (voir + <<_weechat_hook_signal>>) +* 'signal_data' : données envoyées avec le signal + +Exemple : + +[source,C] +---------------------------------------- +weechat_hook_signal_send ("mon_signal", WEECHAT_HOOK_SIGNAL_STRING, ma_chaine); +---------------------------------------- + +weechat_hook_config +^^^^^^^^^^^^^^^^^^^ + +S'accroche à une option de configuration. + +Prototype : + +[source,C] +---------------------------------------- +struct t_hook *weechat_hook_config (const char *option, + int (*callback)(void *data, + const char *option, + const char *value), + void *callback_data); +---------------------------------------- + +Paramètres : + +* 'option' : option, le format est le nom complet, celui utilisé avec la + commande `/set` (par exemple : `weechat.look.item_time_format`) +* 'callback' : fonction appelée lorsque l'option de configuration est modifiée, + paramètres : +** 'void *data' : pointeur +** 'const char *option' : nom de l'option +** 'const char *value' : nouvelle valeur pour l'option +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +ma_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 *mon_config_hook = weechat_hook_config ("weechat.look.item_time_format", + &ma_config_cb, NULL); +---------------------------------------- + +weechat_hook_completion +^^^^^^^^^^^^^^^^^^^^^^^ + +Accroche une complétion. + +Prototype : + +[source,C] +---------------------------------------- +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); +---------------------------------------- + +Paramètres : + +* 'completion_item' : nom de l'objet de complétion, après vous pouvez utiliser + '%(nom)' dans une commande (paramètre 'completion') +* 'callback' : fonction appelée lorsque la complétion est utilisée + (l'utilisateur est en train de compléter quelque chose qui fait appel à cette + complétion), paramètres : +** 'void *data' : pointeur +** 'const char *completion_item' : nom de la complétion +** 'struct t_gui_buffer *buffer' : tampon où la complétion est effectuée +** 'struct t_gui_completion *completion' : structure utilisée pour ajouter + les mots pour la complétion (voir <<_weechat_hook_completion_list_add>>) +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +[NOTE] +Les noms de complétion sont globaux (partagés entre WeeChat et les extensions). +Il est donc recommandé de choisir un nom avec un préfixe unique, comme +"monextension_xxx" (où "xxx" est le nom de votre complétion). + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +ma_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 *mon_completion_hook = weechat_hook_completion ("monextension_item", + &ma_completion_cb, NULL); +---------------------------------------- + +weechat_hook_completion_list_add +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ajoute un mot pour une complétion. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_hook_completion_list_add (struct t_gui_completion *completion, + const char *word, + int nick_completion, + const char *where); +---------------------------------------- + +Paramètres : + +* 'completion' : pointeur vers la complétion +* 'word' : mot à ajouter +* 'nick_completion' : 1 si le mot est un pseudo, sinon 0 +* 'where' : pposition où sera inséré le mot dans la liste : +** 'WEECHAT_LIST_POS_SORT' : n'importe où, pour maintenir la liste triée +** 'WEECHAT_LIST_POS_BEGINNING' : au début de la liste +** 'WEECHAT_LIST_POS_END' : à la fin de la liste + +Exemple : voir <<_weechat_hook_completion>>. + +weechat_hook_modifier +^^^^^^^^^^^^^^^^^^^^^ + +Accroche un "modifieur". + +Prototype : + +[source,C] +---------------------------------------- +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); +---------------------------------------- + +Paramètres : + +* 'modifier' : nom du "modifieur", liste des "modifieurs" utilisés par WeeChat + ou des extensions : + +[width="100%",cols="^1,^2,3,4,4",options="header"] +|======================================== +| Extension | "Modifieur" | Données du "modifieur" | Chaîne | Sortie + +| charset | charset_decode | + extension.nom_tampon | + toute chaîne | + chaîne décodée depuis le jeu de caractères trouvé pour l'extension/tampon + vers UTF-8 + +| charset | charset_encode | + extension.nom_tampon | + toute chaîne | + chaîne encodée depuis UTF-8 vers le jeu de caractères trouvé pour + l'extension/tampon + +| irc | irc_color_decode | + "1" pour garder les couleurs, "0" pour les supprimer | + toute chaîne | + chaîne avec dec codes couleur WeeChat, ou sans couleur + +| irc | irc_color_encode | + "1" pour garder les couleurs, "0" pour les supprimer | + toute chaîne | + chaîne avec des codes couleur IRC, ou sans couleur + +| irc | irc_in_xxx ^1^ | + nom de serveur | + contenu du message reçu du serveur IRC | + nouveau contenu du message + +| irc | irc_out_xxx ^1^ | + nom de serveur | + contenu du message qui va être envoyé au serveur IRC | + nouveau contenu du message + +| weechat | bar_condition_yyy ^2^ | + chaîne avec un pointeur vers la fenêtre ("0x123..") | + chaîne vide | + "1" pour afficher la barre, "0" pour la cacher + +| weechat | input_text_content | + chaîne avec un pointeur vers le tampon ("0x123..") | + chaîne saisie par l'utilisateur | + nouvelle chaîne + +| weechat | input_text_display | + chaîne avec un pointeur vers le tampon ("0x123..") | + chaîne saisie par l'utilisateur, sans le code du curseur dedans | + nouvelle chaîne, pour affichage seulement (les données de l'utilisateur ne + sont pas changées) + +| weechat | input_text_display_with_cursor | + chaîne avec un pointeur vers le tampon ("0x123..") | + chaîne saisie par l'utilisateur, avec le code du curseur dedans | + nouvelle chaîne, pour affichage seulement (les données de l'utilisateur ne + sont pas changées) + +| weechat | weechat_print | + extension;nom_tampon;étiquettes | + message affiché | + nouveau message affiché +|======================================== + +[NOTE] +^1^ 'xxx' est un nom de commande IRC. + +^2^ 'yyy' est le nom de la barre. + +* 'callback' : fonction appelée lorsque le "modifieur" est utilisé, paramètres : +** 'void *data' : pointeur +** 'const char *modifier' : nom du "modifieur" +** 'const char *modifier_data' : données pour le "modifieur" +** 'const char *string' : chaîne à modifier (la fonction doit retourner une + copie de cette chaîne, aucun changement n'est autorisé dans cette chaîne) +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +char * +mon_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) + 5; + result = malloc (length); + if (result) + { + /* ajouter "xxx" à chaque message affiché */ + snprintf (result, length, "%s xxx", string); + } + + return result; +} + +struct t_hook *mon_modifier_hook = weechat_hook_modifier ("weechat_print", + &mon_modifier_cb, NULL); +---------------------------------------- + +weechat_hook_modifier_exec +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Exécute un ou plusieurs "modifieurs". + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_hook_modifier_exec (const char *modifier, + const char *modifier_data, + const char *string); +---------------------------------------- + +Paramètres : + +* 'modifier' : nom du "modifieur" +* 'modifier_data' : données du "modifieur" +* 'string' : chaîne à modifier + +Valeur de retour : + +* chaîne modifiée, NULL si aucun changement n'a été fait dans la chaîne par le + ou les "modifieurs" + +Exemple : + +[source,C] +---------------------------------------- +char *new_string = weechat_hook_modifier_exec ("mon_modifier", + mes_donnees, ma_chaine); +---------------------------------------- + +weechat_hook_info +^^^^^^^^^^^^^^^^^ + +Accroche une information. + +Prototype : + +[source,C] +---------------------------------------- +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); +---------------------------------------- + +Paramètres : + +* 'info_name' : nom de l'information +* 'description' : description +* 'callback' : fonction appelée quand l'information est demandée, paramètres : +** 'void *data' : pointeur +** 'const char *info_name' : nom de l'information +** 'const char *arguments' : paramètres additionnels, dépendant de + l'information +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +const char * +mon_info_cb (void *data, const char *info_name, const char *arguments) +{ + /* ... */ + return pointeur_vers_chaine; +} + +/* ajoute l'information "mon_info" */ +struct t_hook *mon_info_hook = weechat_hook_info ("mon_info", + "Une information", + &mon_info_cb, NULL); +---------------------------------------- + +weechat_hook_infolist +^^^^^^^^^^^^^^^^^^^^^ + +Accroche une infolist. + +Prototype : + +[source,C] +---------------------------------------- +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); +---------------------------------------- + +Paramètres : + +* 'infolist_name' : nom de l'infolist +* 'description' : description +* 'callback' : fonction appelée quand l'infolist est demandée, paramètres : +** 'void *data' : pointeur +** 'const char *infolist_name' : nom de l'infolist +** 'void *pointer' : pointeur vers un objet que l'infolist doit retourner (pour + obtenir unituqment cet objet dans l'infolist) +** 'const char *arguments' : paramètres additionnels, dépendant de l'infolist +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau "hook", NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +struct t_infolist * +mon_infolist_cb (void *data, const char *infolist_name, void *pointer, + const char *arguments) +{ + struct t_infolist *mon_infolist; + + /* construction de l'infolist */ + /* ... */ + + return mon_infolist; +} + +/* ajoute l'infolist "mon_infolist" */ +struct t_hook *mon_infolist = weechat_hook_infolist ("mon_infolist", + "Mon infolist", + &mon_infolist_cb, NULL); +---------------------------------------- + +weechat_unhook +^^^^^^^^^^^^^^ + +Décroche quelque chose qui est a été accroché. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_unhook (struct t_hook *hook); +---------------------------------------- + +Paramètres : + +* 'hook' : quelque chose d'accroché avec "weechat_hook_xxx()" + +Exemple : + +[source,C] +---------------------------------------- +struct t_hook *mon_hook = weechat_hook_command ( /* ... */ ); +/* ... */ +weechat_unhook (mon_hook); +---------------------------------------- + +weechat_unhook_all +^^^^^^^^^^^^^^^^^^ + +Décroche tout ce qui a été accroché par l'extension courante. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_unhook_all (); +---------------------------------------- + +Exemple : + +[source,C] +---------------------------------------- +weechat_unhook_all (); +---------------------------------------- + +[[buffers]] +Buffers +~~~~~~~ + +Fonctions pour créer/interroger/fermer les tampons. + +weechat_buffer_new +^^^^^^^^^^^^^^^^^^ + +Ouvre un nouveau tampon. + +Prototype : + +[source,C] +---------------------------------------- +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); +---------------------------------------- + +Paramètres : + +* 'name' : nom du tampon (doit être unique pour l'extension) +* 'input_callback' : fonction appelée lorsque du texte saisi est envoyé au + tampon, paramètres : +*** 'void *data' : pointeur +*** 'struct t_gui_buffer *buffer' : pointeur vers le tampon +*** 'const char *input_data' : données en entrée +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat +* 'close_callback' : fonction appelée lorsque le tampon est fermé, paramètres : +*** 'void *data' : pointeur +*** 'struct t_gui_buffer *buffer' : pointeur vers le tampon +* 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouveau tampon, NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +mon_input_cb (void *data, struct t_gui_buffer *buffer, const char *input_data) +{ + weechat_printf (buffer, "Texte : %s", input_data); + return WEECHAT_RC_OK; +} + +int +mon_close_cb (void *data, struct t_gui_buffer *buffer) +{ + weechat_printf (NULL, "Le tampon '%s' va être fermé !", + weechat_buffer_get_string (buffer, "name")); + return WEECHAT_RC_OK; +} + +struct t_gui_buffer *my_buffer = weechat_buffer_new ("mon_buffer", + &mon_input_cb, NULL, + &mon_close_cb, NULL); +---------------------------------------- + +weechat_current_buffer +^^^^^^^^^^^^^^^^^^^^^^ + +Retourne un pointeur vers le tampon courant (le tampon affiché par la fenêtre +courante). + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_buffer *weechat_current_buffer (); +---------------------------------------- + +Valeur de retour : + +* pointeur vers le tampon courant + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (weechat_current_buffer (), "Texte sur le tampon courant"); +---------------------------------------- + +weechat_buffer_search +^^^^^^^^^^^^^^^^^^^^^ + +Recherche un tampon par l'extension et/ou le nom. + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_buffer *weechat_buffer_search (const char *plugin, + const char *name); +---------------------------------------- + +Paramètres : + +* 'plugin' : nom de l'extension +* 'name' : nom du tampon, si c'est NULL ou une chaîne vide, le tampon courant + est retourné (tampon affiché par la fenêtre courante) + +Valeur de retour : + +* pointeur vers le tampon trouvé, NULL s'il n'a pas été trouvé + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_buffer *my_buffer = weechat_buffer_search ("mon_extension", + "mon_tampon"); +---------------------------------------- + +weechat_buffer_search_main +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Recherche le tampon principal de WeeChat (tampon 'core', premier tampon +affiché lorsque WeeChat démarre). + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_buffer *weechat_buffer_search_main (); +---------------------------------------- + +Valeur de retour : + +* pointeur vers le tampon principal WeeChat (tampon 'core') + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main (); +---------------------------------------- + +weechat_buffer_clear +^^^^^^^^^^^^^^^^^^^^ + +Efface le contenu d'un tampon. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_buffer_clear (struct t_gui_buffer *buffer); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_buffer *mon_tampon = weechat_buffer_search ("mon_extension", + "mon_tampon"); +if (mon_tampon) +{ + weechat_buffer_clear (my_buffer); +} +---------------------------------------- + +weechat_buffer_close +^^^^^^^^^^^^^^^^^^^^ + +Ferme un tampon. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_buffer_close (struct t_gui_buffer *buffer); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_buffer *mon_tampon = weechat_buffer_new ("mon_tampon", + &mon_input_cb, NULL, + &mon_close_cb, NULL); +/* ... */ +weechat_buffer_close (mon_tampon); +---------------------------------------- + +weechat_buffer_merge +^^^^^^^^^^^^^^^^^^^^ + +Mélange le tampon avec un autre tampon : les deux tampons continueront +d'exister chacun de leur côté, mais avec le même numéro, et WeeChat affichera +les lignes des deux tampons (lignes mélangées). + +Prototype : + +[source,C] +---------------------------------------- +void weechat_buffer_merge (struct t_gui_buffer *buffer, + struct t_gui_buffer *target_buffer); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'target_buffer' : tampon cible avec lequel on doit mélanger + +Exemple : + +[source,C] +---------------------------------------- +/* mélange le tampon courant avec le tampon "core" */ +weechat_buffer_merge (weechat_current_buffer (), + weechat_buffer_search_main ()); +---------------------------------------- + +weechat_buffer_unmerge +^^^^^^^^^^^^^^^^^^^^^^ + +Supprime le mélange d'un tampon. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_buffer_unmerge (struct t_gui_buffer *buffer, + int number); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'number' : numéro cible pour le tampon détaché, s'il est < 1, alors le tampon + sera déplacé vers le numéro du tampon + 1 + +Exemple : + +[source,C] +---------------------------------------- +weechat_buffer_unmerge (weechat_current_buffer (), 1); +---------------------------------------- + +weechat_buffer_get_integer +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne une valeur entière pour une propriété du tampon. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_buffer_get_integer (struct t_gui_buffer *buffer, + const char *property); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'property' : nom de la propriété : +** 'number' : numéro du tampon (commence à 1) +** 'num_displayed' : nombre de fenêtres affichant ce tampon +** 'notify' : niveau de notification du tampon +** 'lines_hidden' : 1 si au moins une ligne est cachée dans le tampon + (filtrée), ou 0 si toutes les lignes sont affichées +** 'prefix_max_length' : longueur maximale du préfixe dans ce tampon +** 'time_for_each_line' : 1 si l'heure est affichée pour chaque ligne du tampon + (par défaut), sinon 0 +** 'text_search' : type de recherche de texte : +*** 0 : pas de recherche en cours +*** 1 : recherche arrière (vers les messages les plus anciens) +*** 2 : recherche avant (vers les messages les plus récents) +** 'text_search_exact' : 1 si la recherche de texte est sensible à la casse +** 'text_search_found' : 1 si du texte a été trouvé, sinon 0 + +Valeur de retour : + +* valeur entière de la propriété + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "mon numéro de tampon est : %d", + weechat_buffer_get_integer (mon_tampon, "number")); +---------------------------------------- + +weechat_buffer_get_string +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur d'une propriété sous forme de chaîne. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_buffer_get_string (struct t_gui_buffer *buffer, + const char *property); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'property' : nom de la propriété : +** 'plugin' : nom de l'extension qui a créé ce tampon ("core" pour le tampon + principal WeeChat) +** 'name' : nom du tampon +** 'short_name' : nom court du tampon +** 'tilte' : titre du tampon +** 'input' : texte saisi +** 'localvar_xxx' : contenu de la variable locale "xxx" (remplacer "xxx" par le + nom de la variable locale à lire) + +Valeur de retour : + +* valeur de la propriété, sous forme de chaîne + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "name / short name of buffer are : %s / %s", + weechat_buffer_get_string (my_buffer, "name"), + weechat_buffer_get_string (my_buffer, "short_name")); +---------------------------------------- + +weechat_buffer_get_pointer +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur d'une propriété sous forme d'un pointeur. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_buffer_pointer (struct t_gui_buffer *buffer, + const char *property); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'property' : nom de la propriété : +** 'plugin' : pointeur vers l'extension qui a créé le tampon (NULL pour le + tampon principal WeeChat) + +Valeur de retour : + +* valeur de la propriété, sous forme de pointeur + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "pointeur vers l'extension de mon tampon : %lx", + weechat_buffer_get_pointer (mon_tampon, "plugin")); +---------------------------------------- + +weechat_buffer_set +^^^^^^^^^^^^^^^^^^ + +Affecte une valeur à une propriété d'un tampon. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property, + const char *value); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'property' et 'value' : nom de la propriété, avec sa valeur : + +[width="100%",cols="^2,4,8",options="header"] +|======================================== +| Nom | Valeur | Description + +| hotlist | "+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, + WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT | + "+": active la hotlist (option globale, le pointeur vers le tampon n'est pas + utilisé) + + "-": désactive la hotlist (option globale, le pointeur vers le tampon n'est + pas utilisé) + + priorité : ajouter ce tampon dans la hotlist avec cette priorité + +| unread | (sans objet) | + définit le marqueur de données non lues après la dernière ligne du tampon + +| display | "1", "auto" | + "1": basculer vers ce tampon dans la fenêtre active + + "auto": basculer vers ce tampon dans la fenêtre active, le marqueur de + données non lues n'est pas réinitialisé + +| number | numéro | + déplace le tampon vers ce numéro + +| name | toute chaîne | + change le nom du tampon + +| short_name | toute chaîne | + change le nom court du tampon + +| type | "formatted" ou "free" | + définit le type de tampon : "formatted" (pour afficher les messages d'une + discussion), ou "free" (pour du contenu libre) + +| notify | "0", "1", "2", "3" | + définit le niveau de notification du tampon : "0" = ne jamais ajouter à la + hotlist, "1" = ajouter pour les highlights seulement, "2" = ajouter pour les + highlights et les messages, "3" = ajouter pour tous les messages + +| title | toute chaîne | + change le titre du tampon + +| time_for_each_line | "0" ou "1" | + "0" pour cacher l'heure sur toutes les lignes du tampon, "1" pour afficher + l'heure sur toutes les lignes (par défaut pour un nouveau tampon) + +| nicklist | "0" ou "1" | + "0" pour supprimer la liste des pseudos du tampon, "1" pour ajouter la liste + des pseudos du tampon + +| nicklist_case_sensitive | "0" ou "1" | + "0" pour avoir la liste des pseudos insensible à la casse, "1" pour avoir + la liste des pseudos sensible à la casse + +| nicklist_display_groups | "0" ou "1" | + "0" pour cacher les groupes de la liste des pseudos, "1" pour afficher les + groupes de la liste des pseudos + +| highlight_words | "-" ou une liste de mots séparés par des virgules | + "-" est une valeur spécials pour désactiver tout highlight sur ce tampon, ou + une liste de mots à mettre en valeur dans ce tampon, par exemple : + "abc,def,ghi" + +| highlight_tags | liste d'étiquettes ("tags") séparées par des virgules | + liste d'étiquettes ("tags") à mettre en valeur pour ce tampon + +| key_bind_xxx | toute chaîne | + associe la nouvelle touche 'xxx', spécifique à ce tampon, la valeur est la + commande à exécuter pour cette touche + +| key_unbind_xxx | (sans objet) | + supprime la touche 'xxx' pour ce tampon + +| input | toute chaîne | + change le contenu de la zone de saisie + +| input_get_unknown_commands | "0" ou "1" | + "0" pour désactiver les commandes inconnues sur ce tampon (comportement par + défaut), "1" pour recevoir les commandes inconnues, par exemple si + l'utilisateur tape "/commandeinconnue", le tampon le recevra (pas d'erreur + sur la commande inconnue) + +| localvar_set_xxx | toute chaîne | + change la valeur de la variable locale 'xxx' (la variable est créée si elle + n'existe pas) + +| localvar_del_xxx | N/A | + supprime la variable locale 'xxx' +|======================================== + +Exemple : + +[source,C] +---------------------------------------- +/* désactive la hotlist (pour tous les tampons) */ +weechat_buffer_set (NULL, "hotlist", "-"); + +/* active à nouveaula hotlist */ +weechat_buffer_set (NULL, "hotlist", "+"); + +/* change le nom du tampon */ +weechat_buffer_set (mon_tampon, "name", "nouveau_nom"); + +/* ajoute une variable locale "toto" avec la valeur "abc" */ +weechat_buffer_set (mon_tampon, "localvar_set_toto", "abc"); + +/* supprime la variable locale "toto" */ +weechat_buffer_set (mon_tampon, "localvar_del_toto", NULL); +---------------------------------------- + +weechat_buffer_set_pointer +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Affecte un pointeur à une propriété d'un tampon. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property, + void *pointer); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'property' et 'value' : nom de la propriété, avec sa valeur : +** 'close_callback' : définit la fonction "callback" de fermeture du tampon +** 'close_callback_data' : définit les données pour le "callback" de fermeture + du tampon +** 'input_callback' : définit la fonction de "callback" pour les données en + entrée +** 'input_callback_data' : définit les données pour le "callback" des données + en entrée + +Exemple : + +[source,C] +---------------------------------------- +int +mon_close_cb (void *data, struct t_gui_buffer *buffer) +{ + /* ... */ + return WEECHAT_RC_OK; +} + +weechat_buffer_set_pointer (mon_tampon, "close_callback", &mon_close_cb); +---------------------------------------- + +weechat_buffer_string_replace_local_var +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Remplace les variables locales dans une chaîne par leurs valeurs, en utilisant +les variables locales du tampon. + +Prototype : + +[source,C] +---------------------------------------- +char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer, + const char *string); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'string' : chaîne avec du texte et des variables locales, au format "$var" + +Valeur de retour : + +* chaîne avec les valeurs des variables locales + +Exemple : + +[source,C] +---------------------------------------- +weechat_buffer_set (mon_tampon, "localvar_set_toto", "abc"); + +char *str = weechat_buffer_string_replace_local_var (mon_tampon, + "test avec $toto"); +/* str contient "test avec abc" */ +---------------------------------------- + +[[windows]] +Fenêtres +~~~~~~~~ + +Fonctions pour interroger les fenêtres. + +weechat_current_window +^^^^^^^^^^^^^^^^^^^^^^ + +Retourne le pointeur vers la fenêtre courante. + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_window *weechat_current_window (); +---------------------------------------- + +Valeur de retour : + +* pointeur vers la fenêtre courante + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_window *current_window = weechat_current_window (); +---------------------------------------- + +weechat_window_get_integer +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur entière d'une propriété de la fenêtre. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_window_get_integer (struct t_gui_window *window, + const char *property); +---------------------------------------- + +Paramètres : + +* 'window' : pointeur vers la fenêtre +* 'property' : nom de la propriété : +** 'win_x' : position X de la fenêtre dans le terminal (la première colonne est + 0) +** 'win_y' : position Y de la fenêtre dans le terminal (la première ligne est + 0) +** 'win_width' : largeur de la fenêtre, en caractères +** 'win_height' : hauteur de la fenêtre, en caractères +** 'win_width_pct' : taille en pourcentage, en comparaison avec la fenêtre + parente (par exemple 50 indique une largeur de moitié) +** 'win_height_pct' : taille en pourcentage, en comparaison avec la fenêtre + parente (par exemple 50 indique une hauteur de moitié) +** 'win_chat_x' : position X de la fenêtre de discussion ("chat") dans le + terminal (la première colonne est 0) +** 'win_chat_y' : position Y de la fenêtre de discussion ("chat") dans le + terminal (la première ligne est 0) +** 'win_chat_width' : largeur de la fenêtre de discussion ("chat"), en + caractères +** 'win_chat_height' : hauteur de la fenêtre de discussion ("chat"), en + caractères +** 'first_line_displayed' : 1 si la première du tampon est affichée à l'écran, + sinon 0 +** 'scroll' : 1 s'il y a un défilement en cours dans la fenêtre (la dernière + ligne n'est pas affichée) +** 'scroll_lines_after' : nombre de lignes non affichées après la dernière + ligne affichée (lors d'un défilement) + +Valeur de retour : + +* valeur entière de la propriété + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "la fenêtre courante est en position (x,y): (%d,%d)", + weechat_window_get_integer (weechat_current_window (), "win_x"), + weechat_window_get_integer (weechat_current_window (), "win_y")); +---------------------------------------- + +weechat_window_get_string +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur d'une propriété de la fenêtre sous forme d'une chaîne. + +[NOTE] +Cette fonction n'est pas utilisée aujourd'hui, elle est réservée pour une +version future. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_window_get_string (struct t_gui_window *window, + const char *property); +---------------------------------------- + +Paramètres : + +* 'window' : pointeur vers la fenêtre +* 'property' : nom de la propriété + +Valeur de retour : + +* valeur de la propriété, sous forme de chaîne + +weechat_window_get_pointer +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur d'une propriété, sous forme d'un pointeur. + +Prototype : + +[source,C] +---------------------------------------- +void *weechat_window_get_pointer (struct t_gui_window *window, + const char *property); +---------------------------------------- + +Paramètres : + +* 'window' : pointeur vers la fenêtre +* 'property' : nom de la propriété : +** 'current' : pointeur vers la fenêtre courante +** 'buffer' : pointeur vers le tampon affiché par la fenêtre + +Valeur de retour : + +* valeur de la propriété, sous forme de pointeur + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, + "tampon affiché dans la fenêtre courante : %lx", + weechat_window_get_pointer (weechat_current_window (), "buffer")); +---------------------------------------- + +[[nicklist]] +Nicklist +~~~~~~~~ + +Fonctions pour la liste des pseudos. + +weechat_nicklist_add_group +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ajoute un groupe dans la liste des pseudos. + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer, + struct t_gui_nick_group *parent_group, + const char *name, + const char *color, + int visible); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'parent_group' : pointeur vers le parent du groupe, NULL si le groupe n'a pas + de parent (racine de la liste des pseudos) +* 'name' : nom du groupe +* 'visible' : +** '1' : le groupe et ses sous-groupes/pseudos sont visibles +** '0' : le groupe et ses sous-groupes/pseudos sont cachés +* 'color' : nom de l'option contenant la couleur : +** une option WeeChat, par exemple 'weechat.color.nicklist_group' +** une couleur avec un fond optionnel, par exemple 'yellow' ou 'yellow,red' +** nom d'une couleur de barre : +*** 'bar_fg' : couleur de texte pour la barre +*** 'bar_delim' : couleur des délimiteurs pour la barre +*** 'bar_bg' : couleur de fond pour la barre + +[NOTE] +Le nom du groupe peut commencer par un ou plusieurs chiffres, suivis d'un pipe +("|"), puis du nom du groupe. Quand une telle chaîne est trouvée au début, elle +est utilisée pour trier les groupes dans la liste des pseudos. Par exemple les +groupes "1|test" et "2|abc" seront affichés dans cet ordre: "test" en premier, +puis "abc" en second. + +Valeur de retour : + +* pointeur vers le nouveau groupe, NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_nick_group *mon_group = + weechat_nicklist_add_group (mon_tampon, + mon_groupe_parent, + "groupe_test", + "weechat.color.nicklist_group", + 1); +---------------------------------------- + +weechat_nicklist_search_group +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Recherche un groupe dans la liste des pseudos. + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_nick_group *weechat_nicklist_search_group (struct t_gui_buffer *buffer, + struct t_gui_nick_group *from_group, + const char *name); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'from_group' : recherche depuis ce groupe seulement, si NULL, alors recherche + dans toute la liste des pseudos +* 'name' : nom du groupes à rechercher + +Valeur de retour : + +* pointeur vers le groupe trouvé, NULL s'il n'est pas trouvé + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer, + NULL, "test_group"); +---------------------------------------- + +weechat_nicklist_add_nick +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ajoute un pseudo dans un groupe. + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_nick_group *weechat_nicklist_add_nick (struct t_gui_buffer *buffer, + struct t_gui_nick_group *group, + const char *name, + const char *color, + const char *prefix, + const char *prefix_color, + int visible); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'group' : pointeur vers le groupe +* 'name' : nom du pseudo +* 'color' : nom de l'option contenant la couleur pour le pseudo : +** une option WeeChat, par exemple 'weechat.color.nicklist_group' +** une couleur avec un fond optionnel, par exemple 'yellow' ou 'yellow,red' +** nom d'une couleur de barre : +*** 'bar_fg' : couleur de texte pour la barre +*** 'bar_delim' : couleur des délimiteurs pour la barre +*** 'bar_bg' : couleur de fond pour la barre +* 'prefix' : préfixe affiché avant le pseudo +* 'prefix_color' : nom de l'option contenant la couleur pour le préfixe : +** une option WeeChat, par exemple 'weechat.color.nicklist_group' +** une couleur avec un fond optionnel, par exemple 'yellow' ou 'yellow,red' +** nom d'une couleur de barre : +*** 'bar_fg' : couleur de texte pour la barre +*** 'bar_delim' : couleur des délimiteurs pour la barre +*** 'bar_bg' : couleur de fond pour la barre +* 'visible' : +** '1' : le pseudo est visible +** '0' : le pseudo est caché + +Valeur de retour : + +* pointeur vers le nouveau pseudo, NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_nick *my_nick = + weechat_nicklist_add_nick (my_buffer, my_group, + "test_nick", + (nick_away) ? "weechat.color.nicklist_away" : "bar_fg", + "@", "lightgreen", + 1); +---------------------------------------- + +weechat_nicklist_search_nick +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Recherche un pseudo dans la liste des pseudos. + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_nick *weechat_nicklist_search_nick (struct t_gui_buffer *buffer, + struct t_gui_nick_group *from_group, + const char *name); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'from_group' : recherche depuis ce groupe seulement, si NULL, alors recherche + dans toute la liste des pseudos +* 'name' : nom du pseudo à rechercher + +Valeur de retour : + +* pointeur vers le pseudo trouvé, NULL s'il n'est pas trouvé + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer, + NULL, "test_nick"); +---------------------------------------- + +weechat_nicklist_remove_group +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Supprime un groupe de la liste des pseudos. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_nicklist_remove_group (struct t_gui_buffer *buffer, + struct t_gui_nick_group *group); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'group' : pointeur vers le groupe à supprimer (tous les sous-groupes/pseudos + seront supprimés également) + +Exemple : + +[source,C] +---------------------------------------- +weechat_nicklist_remove_group (my_buffer, my_group); +---------------------------------------- + +weechat_nicklist_remove_nick +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Supprime un pseudo de la liste des pseudos. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_nicklist_remove_nick (struct t_gui_buffer *buffer, + struct t_gui_nick *nick); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon +* 'nick' : pointeur vers le pseudo à supprimer + +Exemple : + +[source,C] +---------------------------------------- +weechat_nicklist_remove_nick (my_buffer, my_nick); +---------------------------------------- + +weechat_nicklist_remove_all +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Supprime tous les groupes/pseudos de la liste des pseudos. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_nicklist_remove_all (struct t_gui_buffer *buffer); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon + +Exemple : + +[source,C] +---------------------------------------- +weechat_nicklist_remove_all (my_buffer); +---------------------------------------- + +[[bars]] +Barres +~~~~~~ + +Fonctions pour les barres. + +weechat_bar_item_search +^^^^^^^^^^^^^^^^^^^^^^^ + +Recherche un objet de barre. + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_bar_item *weechat_bar_item_search (const char *name); +---------------------------------------- + +Paramètres : + +* 'name' : nom de l'objet de barre + +Valeur de retour : + +* pointeur vers l'objet de barre trouvé, NULL s'il n'a pas été trouvé + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem"); +---------------------------------------- + +weechat_bar_item_new +^^^^^^^^^^^^^^^^^^^^ + +Créé un nouvel objet de barre. + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_bar_item *weechat_bar_item_new (const char *name, + char *(build_callback)(void *data, + struct t_gui_bar_item *item, + struct t_gui_window *window), + void *build_callback_data); +---------------------------------------- + +Paramètres : + +* 'name' : nom de l'objet de barre +* 'build_callback' : fonction appelée lorsque l'objet est construit : elle doit + retourner le contenu de l'objet de barre +* 'build_callback_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* pointeur vers le nouvel objet de barre, NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +char * +mon_callback (void *data, + struct t_gui_bar_item *item, + struct t_gui_window *window) +{ + return strdup ("mon contenu"); +} + +struct t_gui_bar_item *my_item = weechat_bar_item_new ("monobjet", + &mon_callback, + NULL); +---------------------------------------- + +weechat_bar_item_update +^^^^^^^^^^^^^^^^^^^^^^^ + +Met à jour le contenu d'un objet de barre, en appelant son "callback" de +construction. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_bar_item_update (const char *name); +---------------------------------------- + +Paramètres : + +* 'name' : nom de l'objet de barre + +Exemple : + +[source,C] +---------------------------------------- +weechat_bar_item_update ("monobjet"); +---------------------------------------- + +weechat_bar_item_remove +^^^^^^^^^^^^^^^^^^^^^^^ + +Supprime un objet de barre. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_bar_item_remove (struct t_gui_bar_item *item); +---------------------------------------- + +Paramètres : + +* 'item' : bar item pointer + +Exemple : + +[source,C] +---------------------------------------- +weechat_bar_item_remove (&my_item); +---------------------------------------- + +weechat_bar_search +^^^^^^^^^^^^^^^^^^ + +Recherche une barre. + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_bar_item *weechat_bar_search (const char *name); +---------------------------------------- + +Paramètres : + +* 'name' : nom de la barre + +Valeur de retour : + +* pointeur vers la barre trouvée, NULL si elle n'est pas trouvée + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_bar *bar = weechat_bar_search ("my_barre"); +---------------------------------------- + +weechat_bar_new +^^^^^^^^^^^^^^^ + +Créé une nouvelle barre. + +Prototype : + +[source,C] +---------------------------------------- +struct t_gui_bar *weechat_bar_new (const char *name, + const char *hidden, + const char *priority, + const char *type, + const char *condition, + const char *position, + const char *filling_top_bottom, + const char *filling_left_right, + const char *size, + const char *size_max, + const char *color_fg, + const char *color_delim, + const char *color_bg, + const char *separator, + const char *items); +---------------------------------------- + +Paramètres : + +* 'name' : nom de la barre +* 'hidden' : +** 'on' : la barre est cachée +** 'off' : la barre est visible +* 'priority' : priorité de la barre (nombre entier) +* 'type' : +** 'root' : la barre est affichée une seule fois, hors des fenêtres +** 'window' : la barre est affichée dans chaque fenêtre +* 'condition' : condition pour afficher la barre : +** 'active' : la barre est affichée dans la fenêtre active seulement +** 'inactive' : la barre est affichée dans les fenêtres inactives seulement +** 'nicklist' : la barre est affichée dans les fenêtres possédant une liste des + pseudos +* 'position' : 'top' (en haut), 'bottom' (en bas), 'left' (à gauche) ou 'right' + (à droite) +* 'filling_top_bottom' : +** 'horizontal' : les objets sont remplis horizontallement (avec un espace + entre chaque objet) +** 'vertical' : les objets sont remplis verticalement (avec une nouvelle ligne + entre chaque objet) +** 'columns_horizontal' : les objets sont remplis horizontallement, affichés + sous forme de colonnes +** 'columns_vertical' : les objets sont remplis verticalement, affichés sous + forme de colonnes +* 'filling_left_right' : +** 'horizontal' : les objets sont remplis horizontallement (avec un espace + entre chaque objet) +** 'vertical' : les objets sont remplis verticalement (avec une nouvelle ligne + entre chaque objet) +** 'columns_horizontal' : les objets sont remplis horizontallement, affichés + sous forme de colonnes +** 'columns_vertical' : les objets sont remplis verticalement, affichés sous + forme de colonnes +* 'size' : taille de la barre en caractères (0 indique une taille automatique) +* 'size_max' : taille maximum de la barre (0 pour pas de maximum) +* 'color_fg' : couleur du texte dans la barre +* 'color_delim' : couleur pour les délimiteurs dans la barre +* 'color_bg' : couleur de fond pour la barre +* 'separator' : +** 'on' : la barre a un séparateur avec les autres fenêtres/barres +** 'off' : pas de séparateur +* 'items' : liste des objets dans la barre, séparés par une virbule (espace + entre les objets), ou "+" (objets collés) + +Valeur de retour : + +* pointeur vers la nouvelle barre, NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +struct t_gui_bar *my_bar = weechat_bar_new ("mybar", + "off", + 100, + "window", + "", + "top", + "horizontal", + "vertical", + "0", + "5", + "default", + "cyan", + "blue", + "off", + "time,buffer_number+buffer_name"); +---------------------------------------- + +weechat_bar_set +^^^^^^^^^^^^^^^ + +Affecte une nouvelle valeur pour une propriété de la barre. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_bar_set (struct t_gui_bar *bar, const char *property, + const char *value); +---------------------------------------- + +Paramètres : + +* 'name' : nom de la barre +* 'property' : name, hidden, priority, conditions, position, filling_top_bottom, + filling_left_right, size, size_max, color_fg, color_delim, color_bg, + separator, items (voir <<_weechat_bar_new>>) +* 'value' : nouvelle valeur pour la propriété + +Valeur de retour : + +* 1 si la valeur a été affectée, 0 en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +weechat_bar_set (ma_barre, "position", "bottom"); +---------------------------------------- + +weechat_bar_update +^^^^^^^^^^^^^^^^^^ + +Met à jour le contenu d'une barre à l'écran. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_bar_update (const char *name); +---------------------------------------- + +Paramètres : + +* 'name' : nom de la barre + +Exemple : + +[source,C] +---------------------------------------- +weechat_bar_update ("ma_barre"); +---------------------------------------- + +weechat_bar_remove +^^^^^^^^^^^^^^^^^^ + +Supprime une barre. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_bar_remove (struct t_gui_bar *bar); +---------------------------------------- + +Paramètres : + +* 'bar' : pointeur vers la barre + +Exemple : + +[source,C] +---------------------------------------- +weechat_bar_remove (ma_barre); +---------------------------------------- + +[[commands]] +Commandes +~~~~~~~~~ + +Fonctions pour exécuter des commandes WeeChat. + +weechat_command +^^^^^^^^^^^^^^^ + +Exécute une commande. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_command (struct t_gui_buffer *buffer, const char *command); +---------------------------------------- + +Paramètres : + +* 'buffer' : pointeur vers le tampon (la commande est exécutée sur ce tampon, + NULL pour le tampon "core") +* 'command' : commande à exécuter (si elle commence par "/"), ou texte à + envoyer au tampon + +Exemple : + +[source,C] +---------------------------------------- +weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"), + "/whois FlashCode"); +---------------------------------------- + +[[network]] +Réseau +~~~~~~ + +Fonctions pour le réseau. + +weechat_network_pass_proxy +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Etablit une connexion/authentification avec un proxy. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_network_pass_proxy (const char *proxy, + int sock, + const char *address, + int port); +---------------------------------------- + +Paramètres : + +* 'proxy' : nom du proxy à utiliser +* 'sock' : socket à utiliser +* 'address' : addresse (nom de machine ou adresse IP) +* 'port' : port + +Valeur de retour : + +* 1 si la connexion est ok, 0 en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_network_pass_proxy ("mon_proxy", sock, "irc.freenode.net", 6667)) +{ + /* OK */ +} +else +{ + /* erreur */ +} +---------------------------------------- + +weechat_network_connect_to +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Etablit une connexion à une machine distante. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_network_connect_to (const char *proxy, + int sock, + unsigned long address, + int port); +---------------------------------------- + +Paramètres : + +* 'proxy' : nom du proxy à utiliser +* 'sock' : socket à utiliser +* 'address' : addresse +* 'port' : port + +Valeur de retour : + +* 1 si la connexion est ok, 0 en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +struct sockaddr_in addr; +socklen_t length; +unsigned long address; + +memset (&addr, 0, sizeof (struct sockaddr_in)); +length = sizeof (addr); +getsockname (sock, (struct sockaddr *) &addr, &length); +addr.sin_family = AF_INET; +address = ntohl (addr.sin_addr.s_addr); + +if (weechat_network_connect_to (NULL, sock, address, 6667)) +{ + /* OK */ +} +else +{ + /* erreur */ +} +---------------------------------------- + +[[infos]] +Infos +~~~~~ + +Fonctions pour obtenir des informations. + +weechat_info_get +^^^^^^^^^^^^^^^^ + +Retourne une information de WeeChat ou d'une extension. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_info_get (const char *info_name, const char *arguments); +---------------------------------------- + +Paramètres : + +* 'info_name' : nom de l'information à lire : +include ::autogen/plugin_api/infos.txt[] +* 'arguments' : paramètres pour l'information demandée (optionnels, NULL si + aucun paramètre n'est nécessaire) + +Valeur de retour : + +* chaîne avec l'information demandée, NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "La version de WeeChat est : %s (compilée le %s)", + weechat_info_get ("version", NULL), + weechat_info_get ("date", NULL)); +weechat_printf (NULL, "Le répertoire de WeeChat est : %s", + weechat_info_get ("weechat_dir")); +---------------------------------------- + +[[infolists]] +Infolists +~~~~~~~~~ + +Une "infolist" est une liste composée d'objets ("items"). Chaque objet contient +des variables. + +Par exemple, l'infolist "irc_server" a N objets (N est le nombre de serveurs +IRC définis). Pour chaque objet, il y a des variables, comme "name", "buffer", +"is_connected", ... + +Chaque variable a un type et une valeur. Les types possibles sont : + +* 'integer' : nombre entier +* 'string' : chaîne de caractères +* 'pointer' : pointeur +* 'buffer' : tampon avec une taille fixe, peut contenit n'importe quel type + de données +* 'time' : date/heure + +weechat_infolist_new +^^^^^^^^^^^^^^^^^^^^ + +Créé une "infolist". + +Prototype : + +[source,C] +---------------------------------------- +struct t_infolist *weechat_infolist_new (); +---------------------------------------- + +Valeur de retour : + +* pointeur vers la nouvelle "infolist" + +Exemple : + +[source,C] +---------------------------------------- +struct t_infolist *infolist = weechat_infolist_new (); +---------------------------------------- + +weechat_infolist_new_item +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ajoute un objet dans l'infolist. + +Prototype : + +[source,C] +---------------------------------------- +struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist + +Valeur de retour : + +* pointeur vers le nouvel objet + +Exemple : + +[source,C] +---------------------------------------- +struct t_infolist_item *item = weechat_infolist_new_item (infolist); +---------------------------------------- + +weechat_infolist_new_var_integer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ajoute une variable de type "integer" dans l'objet de l'infolist. + +Prototype : + +[source,C] +---------------------------------------- +struct t_infolist_var *weechat_infolist_new_var_integer (struct t_infolist_item *item, + const char *name, + int value); +---------------------------------------- + +Paramètres : + +* 'item' : pointeur vers l'objet de l'infolist +* 'name' : nom de la variable +* 'value' : valeur + +Valeur de retour : + +* pointeur vers la nouvelle variable + +Exemple : + +[source,C] +---------------------------------------- +struct t_infolist_var *var = weechat_infolist_new_variable_integer (item, + "mon_entier", + 123); +---------------------------------------- + +weechat_infolist_new_var_string +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ajoute une variable de type "string" dans l'objet de l'infolist. + +Prototype : + +[source,C] +---------------------------------------- +struct t_infolist_var *weechat_infolist_new_var_string (struct t_infolist_item *item, + const char *name, + const char *value); +---------------------------------------- + +Paramètres : + +* 'item' : pointeur vers l'objet de l'infolist +* 'name' : nom de la variable +* 'value' : valeur + +Valeur de retour : + +* pointeur vers la nouvelle variable + +Exemple : + +[source,C] +---------------------------------------- +struct t_infolist_var *var = weechat_infolist_new_variable_integer (item, + "ma_chaine", + "valeur"); +---------------------------------------- + +weechat_infolist_new_var_pointer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ajoute une variable de type "pointer" dans l'objet de l'infolist. + +Prototype : + +[source,C] +---------------------------------------- +struct t_infolist_var *weechat_infolist_new_var_pointer (struct t_infolist_item *item, + const char *name, + void *pointer); +---------------------------------------- + +Paramètres : + +* 'item' : pointeur vers l'objet de l'infolist +* 'name' : nom de la variable +* 'pointer' : pointeur + +Valeur de retour : + +* pointeur vers la nouvelle variable + +Exemple : + +[source,C] +---------------------------------------- +struct t_infolist_var *var = weechat_infolist_new_variable_pointer (item, + "mon_pointer", + xo&quelque_chose); +---------------------------------------- + +weechat_infolist_new_var_buffer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ajoute une variable de type "buffer" dans l'objet de l'infolist. + +Prototype : + +[source,C] +---------------------------------------- +struct t_infolist_var *weechat_infolist_new_var_buffer (struct t_infolist_item *item, + const char *name, + void *pointer, + int size); +---------------------------------------- + +Paramètres : + +* 'item' : pointeur vers l'objet de l'infolist +* 'name' : nom de la variable +* 'pointer' : pointeur +* 'size' : taille du tampon + +Valeur de retour : + +* pointeur vers la nouvelle variable + +Exemple : + +[source,C] +---------------------------------------- +char buffer[256]; +/* ... */ +struct t_infolist_var *var = weechat_infolist_new_variable_buffer (item, + "mon_buffer", + &buffer, + sizeof (buffer)); +---------------------------------------- + +weechat_infolist_new_var_time +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ajoute une variable de type "time" dans l'objet de l'infolist. + +Prototype : + +[source,C] +---------------------------------------- +struct t_infolist_var *weechat_infolist_new_var_time (struct t_infolist_item *item, + const char *name, + time_t time); +---------------------------------------- + +Paramètres : + +* 'item' : pointeur vers l'objet de l'infolist +* 'name' : nom de la variable +* 'time' : valeur + +Valeur de retour : + +* pointeur vers la nouvelle variable + +Exemple : + +[source,C] +---------------------------------------- +struct t_infolist_var *var = weechat_infolist_new_variable_time (item, + "mon_time", + time (NULL)); +---------------------------------------- + +weechat_infolist_get +^^^^^^^^^^^^^^^^^^^^ + +Retourne une "infolist" de WeeChat ou d'une extension. + +Prototype : + +[source,C] +---------------------------------------- +struct t_infolist *weechat_infolist_get (const char *infolist_name, + void *pointer, + const char *arguments); +---------------------------------------- + +Paramètres : + +* 'infolist_name' : nom de l'infolist à lire : +include ::autogen/plugin_api/infolists.txt[] +* 'pointer' : pointeur vers un objet, pour n'obtenir que celui-ci dans + l'infolist (optionnel, peut être NULL) +* 'arguments' : paramètres pour l'infolist demandée (optionnels, NULL si aucun + paramètre n'est nécessaire) + +Valeur de retour : + +* pointeur vers l'infolist, NULL en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL); +---------------------------------------- + +weechat_infolist_next +^^^^^^^^^^^^^^^^^^^^^ + +Déplace le "curseur" vers l'objet suivant dans l'infolist. Le premier appel à +cette fonction sur une infolist déplace le curseur sur le premier objet de +l'infolist. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_infolist_next (struct t_infolist *infolist); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist + +Valeur de retour : + +* 1 si le curseur a été déplacé sur l'objet suivant, 0 si la fin de la liste a + été atteinte + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_infolist_next (infolist)) +{ + /* lecture des variables dans l'objet... */ +} +else +{ + /* pas d'autre objet disponible */ +} +---------------------------------------- + +weechat_infolist_prev +^^^^^^^^^^^^^^^^^^^^^ + +Déplace le "curseur" vers l'objet précédent dans l'infolist. Le premier appel à +cette fonction sur une infolist déplace le curseur sur le dernier objet de +l'infolist. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_infolist_prev (struct t_infolist *infolist); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist + +Valeur de retour : + +* 1 si le curseur a été déplacé sur l'objet précédent, 0 si le début de liste a + été atteint + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_infolist_prev (infolist)) +{ + /* lecture des variables dans l'objet... */ +} +else +{ + /* pas d'autre objet disponible */ +} +---------------------------------------- + +weechat_infolist_reset_item_cursor +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Réinitialise le "curseur" de l'infolist. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_infolist_reset_item_cursor (struct t_infolist *infolist); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist + +Exemple : + +[source,C] +---------------------------------------- +weechat_infolist_reset_item_cursor (infolist); +---------------------------------------- + +weechat_infolist_fields +^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la liste des champs pour l'objet courant de l'infolist. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_infolist_fields (struct t_infolist *infolist); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist + +Valeur de retour : + +* chaîne avec la liste des champs pour l'objet courant de l'infolist. La liste, + séparée par des virgules, contient la lettre pour le type, suivi du nom de la + variable. Les types sont : "i" (nombre entier), "s" (chaîne), "p" (pointeur), + "b" (buffer), "t" (date/heure). + +Exemple : + +[source,C] +---------------------------------------- +const char *fields = weechat_infolist_fields (infolist); +/* fields contient quelque chose comme : + "i:mon_entier,s:ma_chaine,p:mon_pointeur,b:mon_buffer,t:ma_date" */ +---------------------------------------- + +weechat_infolist_integer +^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur de la variable de l'objet courant de l'infolist, sous forme +d'entier. + +Prototype : + +[source,C] +---------------------------------------- +int weechat_infolist_integer (struct t_infolist *infolist, const char *var); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist +* 'var' : nom de la variable (doit être de type "integer") + +Valeur de retour : + +* valeur de la variable, sous forme d'entier + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "entier = %d", + weechat_infolist_integer (infolist, "mon_entier")); +---------------------------------------- + +weechat_infolist_string +^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur de la variable de l'objet courant de l'infolist, sous forme +de chaîne de caractères. + +Prototype : + +[source,C] +---------------------------------------- +const char *weechat_infolist_string (struct t_infolist *infolist, const char *var); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist +* 'var' : nom de la variable (doit être de type "string") + +Valeur de retour : + +* valeur de la variable, sous forme de chaîne + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "chaîne = %s", + weechat_infolist_string (infolist, "ma_chaine")); +---------------------------------------- + +weechat_infolist_pointer +^^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur de la variable de l'objet courant de l'infolist, sous forme +de pointeur. + +Prototype : + +[source,C] +---------------------------------------- +void *weechat_infolist_pointer (struct t_infolist *infolist, const char *var); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist +* 'var' : nom de la variable (doit être de type "pointer") + +Valeur de retour : + +* valeur de la variable, sous forme de pointeur + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "pointeur = 0x%lx", + weechat_infolist_pointer (infolist, "mon_pointer")); +---------------------------------------- + +weechat_infolist_buffer +^^^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur de la variable de l'objet courant de l'infolist, sous forme +de buffer. + +Prototype : + +[source,C] +---------------------------------------- +void *weechat_infolist_buffer (struct t_infolist *infolist, const char *var, + int *size); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist +* 'var' : nom de la variable (doit être de type "buffer") +* 'size' : pointeur vers une variable entière, qui sera alimenté avec la taille + de la zone + +Valeur de retour : + +* pointeur vers le "buffer" + +Exemple : + +[source,C] +---------------------------------------- +int size; +void *pointer = weechat_infolist_buffer (infolist, "mon_buffer", &size); +weechat_printf (NULL, "buffer = 0x%lx, taille = %d", + pointer, size); +---------------------------------------- + +weechat_infolist_time +^^^^^^^^^^^^^^^^^^^^^ + +Retourne la valeur de la variable de l'objet courant de l'infolist, sous forme +de date/heure. + +Prototype : + +[source,C] +---------------------------------------- +time_t weechat_infolist_time (struct t_infolist *infolist, const char *var); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist +* 'var' : nom de la variable (doit être de type "time") + +Valeur de retour : + +* valeur de la variable, sous forme de date/heure + +Exemple : + +[source,C] +---------------------------------------- +weechat_printf (NULL, "date/heure = 0x%ld", + weechat_infolist_time (infolist, "mon_time")); +---------------------------------------- + +weechat_infolist_free +^^^^^^^^^^^^^^^^^^^^^ + +Libère une infolist. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_infolist_free (struct t_infolist *infolist); +---------------------------------------- + +Paramètres : + +* 'infolist' : pointeur vers l'infolist + +Exemple : + +[source,C] +---------------------------------------- +weechat_infolist_free (infolist); +---------------------------------------- + +[[upgrade]] +Mise à jour +~~~~~~~~~~~ + +Fonctions pour la mise à jour de WeeChat (commande "/upgrade"). + +weechat_upgrade_new +^^^^^^^^^^^^^^^^^^^ + +Créé ou lit un fichier pour la mise à jour. + +Prototype : + +[source,C] +---------------------------------------- +struct t_upgrade_file *weechat_upgrade_new (const char *filename, int write); +---------------------------------------- + +Paramètres : + +* 'filename' : nom du fichier (l'extension ".upgrade" sera ajoutée + automatiquement par WeeChat) +* 'write' : +** '1' : création du fichier (mode écriture, avant la mise à jour) +** '0' : lecture du fichier (après la mise à jour) + +Valeur de retour : + +* pointeur vers le fichier de mise à jour + +Exemple : + +[source,C] +---------------------------------------- +struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("mon_fichier", 1); +---------------------------------------- + +weechat_upgrade_write_object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Ecrit un objet dans le fichier de mise à jour. + +Prototype : + +[source,C] +---------------------------------------- +struct t_upgrade_file *weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file, + int object_id, + struct t_infolist *infolist); +---------------------------------------- + +Paramètres : + +* 'upgrade_file' : pointeur vers le fichier de mise à jour +* 'object_id' : identifiant de l'objet +* 'infolist' : infolist à écrire dans le fichier + +Valeur de retour : + +* 1 si ok, 0 en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +if (weechat_upgrade_write_object (upgrade_file, 1, &infolist)) +{ + /* ok */ +} +else +{ + /* erreur */ +} +---------------------------------------- + +weechat_upgrade_read +^^^^^^^^^^^^^^^^^^^^ + +Lit un fichier de mise à jour. + +Prototype : + +[source,C] +---------------------------------------- +struct t_upgrade_file *weechat_upgrade_read (struct t_upgrade_file *upgrade_file, + int (*callback_read)(void *data, + struct t_upgrade_file *upgrade_file, + int object_id, + struct t_infolist *infolist), + void *callback_read_data); +---------------------------------------- + +Paramètres : + +* 'upgrade_file' : pointeur vers le fichier de mise à jour +* 'callback_read' : fonction appelée pour chaque objet lu dans le fichier de + mise à jour +* 'callback_read_data' : pointeur donné au "callback" lorsqu'il est appelé par + WeeChat + +Valeur de retour : + +* 1 si ok, 0 en cas d'erreur + +Exemple : + +[source,C] +---------------------------------------- +int +mon_upgrade_read_cb (struct t_upgrade_file *upgrade_file, + int object_id, + struct t_infolist *infolist) +{ + /* lecture des variables... */ + return WEECHAT_RC_OK; +} + +weechat_upgrade_read (upgrade_file, &mon_upgrade_read_cb, NULL); +---------------------------------------- + +weechat_upgrade_close +^^^^^^^^^^^^^^^^^^^^^ + +Ferme un fichier de mise à jour. + +Prototype : + +[source,C] +---------------------------------------- +void weechat_upgrade_close (struct t_upgrade_file *upgrade_file); +---------------------------------------- + +Paramètres : + +* 'upgrade_file' : pointeur vers le fichier de mise à jour + +Exemple : + +[source,C] +---------------------------------------- +weechat_upgrade_close (upgrade_file); +---------------------------------------- diff --git a/src/core/wee-utf8.c b/src/core/wee-utf8.c index 33255fbaf..9e43bce58 100644 --- a/src/core/wee-utf8.c +++ b/src/core/wee-utf8.c @@ -562,17 +562,17 @@ utf8_pos (const char *string, int real_pos) */ char * -utf8_strndup (const char *string, int max_chars) +utf8_strndup (const char *string, int length) { const char *end; - if (!string || (max_chars < 0)) + if (!string || (length < 0)) return NULL; - if (max_chars == 0) + if (length == 0) return strdup (""); - end = utf8_add_offset (string, max_chars); + end = utf8_add_offset (string, length); if (!end || (end == string)) return strdup (string); diff --git a/src/core/wee-utf8.h b/src/core/wee-utf8.h index df6ef1c46..ca599f10b 100644 --- a/src/core/wee-utf8.h +++ b/src/core/wee-utf8.h @@ -50,6 +50,6 @@ extern int utf8_char_size_screen (const char *string); extern char *utf8_add_offset (const char *string, int offset); extern int utf8_real_pos (const char *string, int pos); extern int utf8_pos (const char *string, int real_pos); -extern char *utf8_strndup (const char *string, int max_chars); +extern char *utf8_strndup (const char *string, int length); #endif /* wee-utf8.h */ diff --git a/src/plugins/weechat-plugin.h b/src/plugins/weechat-plugin.h index ea84b1176..4de2335d7 100644 --- a/src/plugins/weechat-plugin.h +++ b/src/plugins/weechat-plugin.h @@ -187,7 +187,7 @@ struct t_weechat_plugin char *(*utf8_add_offset) (const char *string, int offset); int (*utf8_real_pos) (const char *string, int pos); int (*utf8_pos) (const char *string, int real_pos); - char *(*utf8_strndup) (const char *string, int max_chars); + char *(*utf8_strndup) (const char *string, int length); /* directories */ int (*mkdir_home) (const char *directory, int mode); @@ -743,6 +743,8 @@ extern int weechat_plugin_end (struct t_weechat_plugin *plugin); weechat_plugin->utf8_real_pos(__string, __pos) #define weechat_utf8_pos(__string, __real_pos) \ weechat_plugin->utf8_pos(__string, __real_pos) +#define weechat_utf8_strndup(__string, __length) \ + weechat_plugin->utf8_strndup(__string, __length) /* directories */ #define weechat_mkdir_home(__directory, __mode) \ |