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_split
^^^^^^^^^^^^^^^^^^^^

Découpe une chaîne à l'aide de délimiteur(s).

Prototype :

[source,C]
----------------------------------------
char **weechat_string_split (const char *string, const char *separators,
                             int keep_eol, int num_items_max,
                             int *num_items);
----------------------------------------

Paramètres :

* 'string' : chaîne à découper
* 'separators' : délimiteurs utilisés pour le découpage
* '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_split>> après utilisation)

Exemples :

[source,C]
----------------------------------------
char **argv;
int argc;
argv = weechat_string_split ("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_split (argv);

argv = weechat_string_split ("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_split (argv);
----------------------------------------

weechat_string_free_split
^^^^^^^^^^^^^^^^^^^^^^^^^

Libère la mémoire utilisée pour le découpage d'une chaîne.

Prototype :

[source,C]
----------------------------------------
void weechat_string_free_split (char **split_string);
----------------------------------------

Paramètres :

* 'split_string' : chaîne découpée par <<_weechat_string_split>>

Exemple :

[source,C]
----------------------------------------
char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);
----------------------------------------

weechat_string_build_with_split_string
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Construit une chaîne à partir d'une chaîne découpée.

Prototype :

[source,C]
----------------------------------------
char *weechat_string_build_with_split_string (char **split_string
                                              const char *separator);
----------------------------------------

Paramètres :

* 'split_string' : chaîne découpée par la fonction <<_weechat_string_split>>
* 'separator' : chaîne utilisée pour séparer les différentes chaînes

Valeur de retour :

* chaîne construite avec la chaîne découpée (doit être libérée par un appel à
  "free" après utilisation)

Exemple :

[source,C]
----------------------------------------
char **argv;
int argc;
argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc);
char *str = weechat_string_build_with_split_string (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 *out,
                                                     const char *err),
                                     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)
** 'out' : sortie standard de la commande (stdout)
** 'err' : erreurs de la commande (stderr)
* '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 *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Erreur avec la commande '%s'", command);
        return;
    }
    
    if (return_code &gt;= 0)
    {
        weechat_printf (NULL, "return_code = %d", return_code);
    }
    
    if (out)
    {
        weechat_printf (NULL, "stdout : %s", out);
    }
    
    if (err)
    {
        weechat_printf (NULL, "stderr : %s", err);
    }
    
    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);
----------------------------------------
