= Référence API extension WeeChat
:author: Sébastien Helleu
:email: flashcode@flashtux.org
:lang: fr
:toc: left
:toclevels: 4
:toc-title: Table des matières
:sectnums:
:sectnumlevels: 3
:docinfo1:


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 :
https://weechat.org/doc


[[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 cœur de WeeChat.

[[plugins_in_weechat]]
== Extensions dans 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

WEECHAT_PLUGIN_PRIORITY(1000)::
    priorité de l'extension (facultatif, voir ci-dessous)

[[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)

[[plugin_priority]]
===== Priorité de l'extension

Lorsque les extensions sont automatiquement chargées (par exemple au
démarrage), WeeChat charge d'abord toutes les extensions, puis appelle les
fonctions _init_, en utilisant la priorité définie dans chaque extension.
Une grande priorité signifie que la fonction _init_ est appelée en premier.

La priorité par défaut est 1000 (avec une telle priorité, l'extension est
chargée après toutes les extensions par défaut).

Les extensions par défaut de WeeChat sont initialisées dans cet ordre :

include::autogen/plugin_api/plugins_priority.adoc[]

==== 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("Sébastien Helleu <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 (const void *pointer, 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, 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;
}
----

[[plugin_api]]
== API extension

Les chapitres ci-dessous décrivent les fonctions de l'API, classées par
catégorie.

Pour chaque fonction, on donne :

* une description de la fonction,
* le prototype en C,
* le détail des paramètres,
* la valeur de retour,
* un exemple en C,
* un exemple en script Python (la syntaxe pour les autres langages de script est
  similaire).

[[plugins]]
=== Extensions

Fonctions pour obtenir des informations sur les extensions.

==== plugin_get_name

Retourner 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 cœur de WeeChat (si le pointeur vers
  l'extension est NULL)

Exemple en C :

[source,C]
----
const char *name = weechat_plugin_get_name (plugin);
----

Script (Python) :

[source,python]
----
# prototype
name = weechat.plugin_get_name(plugin)

# exemple
plugin = weechat.buffer_get_pointer(weechat.current_buffer(), "plugin")
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.

==== charset_set

Définir 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 en C :

[source,C]
----
weechat_charset_set ("iso-8859-1");
----

Script (Python) :

[source,python]
----
# prototype
weechat.charset_set(charset)

# exemple
weechat.charset_set("iso-8859-1")
----

==== iconv_to_internal

Convertir 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 supprimée par un appel à "free" après utilisation)

Exemple en C :

[source,C]
----
char *str = weechat_iconv_to_internal ("iso-8859-1", "chaîne iso : é à");
/* ... */
free (str);
----

Script (Python) :

[source,python]
----
# prototype
str = weechat.iconv_to_internal(charset, string)

# exemple
str = weechat.iconv_to_internal("iso-8859-1", "chaîne iso : é à")
----

==== iconv_from_internal

Convertir 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 supprimée par un appel à "free" après utilisation)

Exemple en C :

[source,C]
----
char *str = weechat_iconv_from_internal ("iso-8859-1", "chaîne utf-8 : é à");
/* ... */
free (str);
----

Script (Python) :

[source,python]
----
# prototype
str = weechat.iconv_from_internal(charset, string)

# exemple
str = weechat.iconv_from_internal("iso-8859-1", "chaîne utf-8 : é à")
----

==== gettext

Retourner 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 en C :

[source,C]
----
char *str = weechat_gettext ("hello");
----

Script (Python) :

[source,python]
----
# prototype
str = weechat.gettext(string)

# exemple
str = weechat.gettext("hello")
----

==== ngettext

Retourner 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 en C :

[source,C]
----
char *str = weechat_ngettext ("file", "files", num_files);
----

Script (Python) :

[source,python]
----
# prototype
str = weechat.ngettext(string, plural, count)

# exemple
num_files = 2
str = weechat.ngettext("file", "files", num_files)
----

==== strndup

Retourner 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 supprimée par un appel à "free" après utilisation)

Exemple en C :

[source,C]
----
char *str = weechat_strndup ("abcdef", 3);  /* résultat : "abc" */
/* ... */
free (str);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_tolower

Convertir une chaîne UTF-8 en minuscules.

Prototype :

[source,C]
----
void weechat_string_tolower (char *string);
----

Paramètres :

* _string_ : chaîne à convertir

Exemple en C :

[source,C]
----
char str[] = "AbCdé";
weechat_string_tolower (str);  /* str vaut maintenant : "abcdé" */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_toupper

Convertir une chaîne UTF-8 en majuscules.

Prototype :

[source,C]
----
void weechat_string_toupper (char *string);
----

Paramètres :

* _string_ : chaîne à convertir

Exemple en C :

[source,C]
----
char str[] = "AbCdé";
weechat_string_toupper (str);  /* str vaut maintenant : "ABCDé" */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== strcasecmp

_Mis à jour dans la 1.0._

Comparer deux chaînes indépendemment 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 :

* -1 si string1 < string2
* 0 si string1 == string2
* 1 si string1 > string2

Exemple en C :

[source,C]
----
int diff = weechat_strcasecmp ("aaa", "CCC");  /* == -2 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== strcasecmp_range

_WeeChat ≥ 0.3.7, mis à jour dans la 1.0._

Comparer deux chaînes indépendemment de la locale et de la casse, avec un
intervalle pour comparer la casse.

Prototype :

[source,C]
----
int weechat_strcasecmp_range (const char *string1, const char *string2, int range);
----

Paramètres :

* _string1_ : première chaîne à comparer
* _string2_ : seconde chaîne à comparer
* _range_ : nombre de caractères pour la comparaison de casse, par exemple :
** 26 : `+A-Z+` deviennent en minuscules `a-z`
** 29 : `+A-Z [ \ ]+` deviennent minuscules `+a-z { | }+`
** 30 : `+A-Z [ \ ] ^+` deviennent minuscules `+a-z { | } ~+`

[NOTE]
Les valeurs 29 et 30 sont utilisés par quelques protocoles comme IRC.

Valeur de retour :

* -1 si string1 < string2
* 0 si string1 == string2
* 1 si string1 > string2

Exemple en C :

[source,C]
----
int diff = weechat_strcasecmp_range ("nick{away}", "NICK[away]", 29);  /* == 0 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== strncasecmp

_Mis à jour dans la 1.0._

Comparer deux chaînes indépendemment de la locale et de la casse, pour _max_
caractères.

Prototype :

[source,C]
----
int weechat_strncasecmp (const char *string1, const char *string2, int max);
----

Paramètres :

* _string1_ : première chaîne à comparer
* _string2_ : seconde chaîne à comparer
* _max_ : nombre maximum de caractères à comparer

Valeur de retour :

* -1 si string1 < string2
* 0 si string1 == string2
* 1 si string1 > string2

Exemple en C :

[source,C]
----
int diff = weechat_strncasecmp ("aabb", "aacc", 2);  /* == 0 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== strncasecmp_range

_WeeChat ≥ 0.3.7, mis à jour dans la 1.0._

Comparer deux chaînes indépendemment de la locale et de la casse, pour _max_
caractères, avec un intervalle pour comparer la casse.

Prototype :

[source,C]
----
int weechat_strncasecmp_range (const char *string1, const char *string2, int max, int range);
----

Paramètres :

* _string1_ : première chaîne à comparer
* _string2_ : seconde chaîne à comparer
* _max_ : nombre maximum de caractères à comparer
* _range_ : nombre de caractères pour la comparaison de casse, par exemple :
** 26 : `+A-Z+` deviennent en minuscules `+a-z+`
** 29 : `+A-Z [ \ ]+` deviennent minuscules `+a-z { | }+`
** 30 : `+A-Z [ \ ] ^+` deviennent minuscules `+a-z { | } ~+`

[NOTE]
Les valeurs 29 et 30 sont utilisés par quelques protocoles comme IRC.

Valeur de retour :

* -1 si string1 < string2
* 0 si string1 == string2
* 1 si string1 > string2

Exemple en C :

[source,C]
----
int diff = weechat_strncasecmp_range ("nick{away}", "NICK[away]", 6, 29);  /* == 0 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== strcmp_ignore_chars

_Mis à jour dans la 1.0._

Comparer deux chaînes indépendemment 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 :

* -1 si string1 < string2
* 0 si string1 == string2
* 1 si string1 > string2

Exemple en C :

[source,C]
----
int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1);  /* == -3 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== strcasestr

_Mis à jour dans la 1.3._

Rechercher une chaîne indépendemment de la locale et de la casse.

Prototype :

[source,C]
----
const 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
  (_WeeChat ≥ 1.3_ : le pointeur retourné est un _const char *_ au lieu d'un
  _char *_)

Exemple en C :

[source,C]
----
const char *pos = weechat_strcasestr ("aBcDeF", "de");  /* résultat : pointeur vers "DeF" */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== strlen_screen

_WeeChat ≥ 0.4.2._

Retourner le nombre de caractères nécessaires pour afficher la chaîne UTF-8
sur l'écran.
Les caractères non affichables ont une longueur de 1 (c'est la différence avec
la fonction <<_utf8_strlen_screen,utf8_strlen_screen>>).

Prototype :

[source,C]
----
int weechat_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 en C :

[source,C]
----
int length_on_screen = weechat_strlen_screen ("é");  /* == 1 */
----

Script (Python) :

[source,python]
----
# prototype
length = weechat.strlen_screen(string)

# exemple
length = weechat.strlen_screen("é")  # 1
----

==== string_match

_Mis à jour dans la 1.0._

Vérifier 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 avec des caractères joker (`+*+`), chaque joker correspond à 0
  ou plusieurs caractères dans la chaîne
* _case_sensitive_ : 1 pour une comparaison tenant compte de la casse, sinon 0

[NOTE]
Depuis la version 1.0, les caractères joker sont autorisés à l'intérieur du
masque (pas seulement au début et à la fin du masque).

Valeur de retour :

* 1 si la chaîne correspond au masque, sinon 0

Exemple en C :

[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 */
int match5 = weechat_string_match ("abcdef", "*b*d*", 0);  /* == 1 */
----

Script (Python) :

[source,python]
----
# prototype
match = weechat.string_match(string, mask, case_sensitive)

# exemples
match1 = weechat.string_match("abcdef", "abc*", 0)   # 1
match2 = weechat.string_match("abcdef", "*dd*", 0)   # 0
match3 = weechat.string_match("abcdef", "*def", 0)   # 1
match4 = weechat.string_match("abcdef", "*de*", 0)   # 1
match5 = weechat.string_match("abcdef", "*b*d*", 0)  # 1
----

==== string_expand_home

_WeeChat ≥ 0.3.3._

Remplacer le `+~+` en début de chaîne par le répertoire "home". Si la chaîne ne
débute pas par `+~+`, alors une chaîne identique est retournée.

Prototype :

[source,C]
----
char *weechat_string_expand_home (const char *path);
----

Paramètres :

* _path_ : chemin

Valeur de retour :

* chemin avec le `+~+` en début remplacé par le répertoire "home" (doit être
  supprimé par un appel à "free" après utilisation)

Exemple en C :

[source,C]
----
char *str = weechat_string_expand_home ("~/fichier.txt");
/* résultat : "/home/xxx/fichier.txt" */
/* ... */
free (str);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_eval_path_home

_WeeChat ≥ 1.3._

Évaluer un chemin en 3 étapes :

. remplacer le `%h` du début par le répertoire maison de WeeChat,
. remplacer le `+~+` du début par le répertoire maison de l'utilisateur (appel à
  <<_string_expand_home,string_expand_home>>),
. évaluer les variables (voir <<_string_eval_expression,string_eval_expression>>).

Prototype :

[source,C]
----
char *weechat_string_eval_path_home (const char *path,
                                     struct t_hashtable *pointers,
                                     struct t_hashtable *extra_vars,
                                     struct t_hashtable *options);
----

Paramètres :

* _path_ : chemin
* _pointers_ : table de hachage pour l'appel à la fonction
  <<_string_eval_expression,string_eval_expression>>
* _extra_vars_ : table de hachage pour l'appel à la fonction
  <<_string_eval_expression,string_eval_expression>>
* _options_ : table de hachage pour l'appel à la fonction
  <<_string_eval_expression,string_eval_expression>>

Valeur de retour :

* chemin évalué (doit être supprimé par un appel à "free" après utilisation)

Exemple en C :

[source,C]
----
char *str = weechat_string_expand_home ("%h/test");
/* résultat : "/home/xxx/.weechat/test" */
/* ... */
free (str);
----

Script (Python) :

[source,python]
----
# prototype
path = weechat.string_eval_path_home(path, pointers, extra_vars, options)

# exemple
path = weechat.string_eval_path_home("%h/test", "", "", "")
# path == "/home/xxx/.weechat/test"
----

==== string_remove_quotes

Supprimer les apostrophes/guillemets au début et à la fin d'une chaîne (les
espaces avant la première apostrophe ou après la dernière sont ignorés).

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
  supprimée par un appel à "free" après utilisation)

Exemple en C :

[source,C]
----
char *str = weechat_string_remove_quotes (string, " 'aujourd'hui' ", "'");
/* résultat : "aujourd'hui" */
/* ... */
free (str);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_strip

Supprimer 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 différent de 0
* _chars_ : chaîne avec les caractères à supprimer

Valeur de retour :

* chaîne avec les caractères supprimés (doit être supprimée par un appel à
  "free" après utilisation)

Exemple en C :

[source,C]
----
char *str = weechat_string_strip (".abc -", 0, 1, "- .");  /* résultat : ".abc" */
/* ... */
free (str);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_convert_escaped_chars

_WeeChat ≥ 1.0._

Convertir les caractères échappés par leur valeur :

* `+\"+` : double guillemet droit
* `+\\+` : barre oblique inversée
* `+\a+` : alerte (BEL)
* `+\b+` : retour arrière
* `+\e+` : échappement
* `+\f+` : saut de page
* `+\n+` : nouvelle ligne
* `+\r+` : retour chariot
* `+\t+` : tabulation horizontale
* `+\v+` : tabulation verticale
* `+\0ooo+` : caractère sous forme de valeur octale (`ooo` a 0 à 3 chiffres)
* `+\xhh+` : caractère sous forme de valeur hexadécimale (`hh` a 1 à 2 chiffres)
* `+\uhhhh+` : caractère unicode sous forme de valeur hexadécimale
  (`hhhh` a 1 à 4 chiffres)
* `+\Uhhhhhhhh+` : caractère unicode sous forme de valeur hexadécimale
  (`hhhhhhhh` a 1 à 8 chiffres)

Prototype :

[source,C]
----
char *weechat_string_convert_escaped_chars (const char *string);
----

Paramètres :

* _string_ : chaîne

Valeur de retour :

* chaîne avec les caractères échappés remplacés par leur valeur (doit être
  supprimée par un appel à "free" après utilisation)

Exemple en C :

[source,C]
----
char *str = weechat_string_convert_escaped_chars ("snowman : \\u2603");
/* str == "snowman : ☃" */
/* ... */
free (str);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_mask_to_regex

Retourner 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 supprimée par un appel à
  "free" après utilisation)

Exemple en C :

[source,C]
----
char *str_regex = weechat_string_mask_to_regex ("test*mask");
/* résultat : "test.*mask" */
/* ... */
free (str_regex);
----

Script (Python) :

[source,python]
----
# prototype
regex = weechat.string_mask_to_regex(mask)

# exemple
regex = weechat.string_mask_to_regex("test*mask")  # "test.*mask"
----

==== string_regex_flags

_WeeChat ≥ 0.3.7._

Retourner un pointeur dans la chaîne après les "flags" et le masque avec les
"flags" pour compiler l'expression régulière.

Prototype :

[source,C]
----
const char *weechat_string_regex_flags (const char *regex, int default_flags, int *flags)
----

Paramètres :

* _regex_ : expression régulière POSIX étendue
* _default_flags_ : combinaison des valeurs suivantes (voir `man regcomp`) :
** REG_EXTENDED
** REG_ICASE
** REG_NEWLINE
** REG_NOSUB
* _flags_ : la valeur du pointer est alimentée avec les "flags" utilisés dans
  l'expression régulière ("flags" par défaut + "flags" définis dans l'expression
  régulière)

Les "flags" doivent être au début de l'expression régulière. Le format est :
"(?eins-eins)chaîne".

Les "flags" autorisés sont :

* _e_ : expression régulière POSIX étendue (_REG_EXTENDED_)
* _i_ : insensible à la casse (_REG_ICASE_)
* _n_ : les opérateurs qui cherchent n'importe quel caractère ne trouvent pas
  les nouvelles lignes (_REG_NEWLINE_)
* _s_ : le support d'adressage des sous-chaînes de correspondance n'est pas
  requis (_REG_NOSUB_)

Valeur de retour :

* pointeur dans la _regex_, après les "flags"

Exemple en C :

[source,C]
----
const char *regex = "(?i)test";
int flags;
const char *ptr_regex = weechat_string_regex_flags (regex, REG_EXTENDED, &flags);
/* ptr_regex == "test", flags == REG_EXTENDED | REG_ICASE */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_regcomp

_WeeChat ≥ 0.3.7._

Compiler une expression régulière avec des "flags" optionnels en début de chaîne
(pour le format des "flags", voir <<_string_regex_flags,string_regex_flags>>).

Prototype :

[source,C]
----
int weechat_string_regcomp (void *preg, const char *regex, int default_flags)
----

Paramètres :

* _preg_ : pointeur vers la structure _regex_t_
* _regex_ : expression régulière POSIX étendue
* _default_flags_ : combinaison des valeurs suivantes (voir `man regcomp`) :
** REG_EXTENDED
** REG_ICASE
** REG_NEWLINE
** REG_NOSUB

Valeur de retour :

* même code retour que la fonction `regcomp` (0 si ok, autre valeur pour une
  erreur, voir `man regcomp`)

Exemple en C :

[source,C]
----
regex_t my_regex;
if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) != 0)
{
    /* erreur */
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_has_highlight

Vérifier 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 en C :

[source,C]
----
int hl = weechat_string_has_highlight ("my test string", "test,word2");  /* == 1 */
----

Script (Python) :

[source,python]
----
# prototype
highlight = weechat.string_has_highlight(string, highlight_words)

# exemple
highlight = weechat.string_has_highlight("my test string", "test,word2")  # 1
----

==== string_has_highlight_regex

_WeeChat ≥ 0.3.4._

Vérifier si une chaîne a un ou plusieurs "highlights", en utilisant une
expression régulière POSIX étendue. +
Pour au moins une correspondance dans la chaîne, elle doit être entourée de
délimiteurs (caractères différents de : alphanumérique, `+-+`, `+_+` et `+|+`).

Prototype :

[source,C]
----
int weechat_string_has_highlight_regex (const char *string, const char *regex);
----

Paramètres :

* _string_ : chaîne
* _regex_ : expression régulière POSIX étendue

Valeur de retour :

* 1 si la chaîne a un ou plusieurs "highlights", sinon 0

Exemple en C :

[source,C]
----
int hl = weechat_string_has_highlight_regex ("my test string", "test|word2");  /* == 1 */
----

Script (Python) :

[source,python]
----
# prototype
highlight = weechat.string_has_highlight_regex(string, regex)

# exemple
highlight = weechat.string_has_highlight_regex("my test string", "test|word2")  # 1
----

==== string_replace

Remplacer toutes les occurrences 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 supprimée par un appel
  à "free" après utilisation)

Exemple en C :

[source,C]
----
char *str = weechat_string_replace ("test, test", "s", "x");  /* résultat : "text" */
/* ... */
free (str);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_replace_regex

_WeeChat ≥ 1.0._

Remplacer du texte dans une chaîne en utilisant une expression régulière, du
texte de remplacement et un "callback" optionnel.

Prototype :

[source,C]
----
char *weechat_string_replace_regex (const char *string, void *regex,
                                    const char *replace, const char reference_char,
                                    char *(*callback)(void *data, const char *text),
                                    void *callback_data);
----

Paramètres :

* _string_ : chaîne
* _regex_ : pointeur vers une expression régulière (structure _regex_t_)
  compilée avec la fonction WeeChat <<_string_regcomp,string_regcomp>> ou regcomp
  (voir `man regcomp`)
* _replace_ : texte de remplacement, où les références suivantes sont
  autorisées :
** `+$0+` à `+$99+` : correspondance 0 à 99 dans l'expression régulière (0 est la
   correspondance entière, 1 à 99 sont les groupes capturés entre parenthèses)
** `+$++` : la dernière correspondance (avec le numéro le plus élevé)
** `+$.*N+` : correspondance `+N+` (peut être `+++` ou de `+0+` à `+99+`), avec
   tous les caractères remplacés par `+*+` (le caractère `+*+` peut être n'importe quel
   caractère entre l'espace (32) et `+~+` (126))
* _reference_char_ : le caractère utilisé pour les références aux
  correspondances (en général `+$+`)
* _callback_ : un "callback" optionnel appelé pour chaque référence dans
  _replace_ (sauf pour les correspondances remplacées par un caractère); le
  "callback" doit retourner :
** une chaîne nouvellement allouée : elle est utilisée en texte de remplacement
   (elle est libérée après utilisation)
** NULL : le texte reçu dans le "callback" est utilisé comme texte de
   remplacement (sans changement)
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé

Valeur de retour :

* chaîne avec le texte remplacé, NULL en cas de problème (doit être supprimée
  par un appel à "free" après utilisation)

Exemple en C :

[source,C]
----
regex_t my_regex;
char *string;
if (weechat_string_regcomp (&my_regex, "([0-9]{4})-([0-9]{2})-([0-9]{2})",
                            REG_EXTENDED) == 0)
{
    string = weechat_string_replace_regex ("date : 2014-02-14", &my_regex,
                                           "$3/$2/$1", '$', NULL, NULL);
    /* string == "date : 14/02/2014" */
    if (string)
        free (string);
    regfree (&my_regex);
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_split

Découper 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 paramètre contiendra toutes les
  chaînes jusqu'à la fin de la ligne (voir exemple ci-dessous)
** 0 : chaque chaîne contiendra un mot
** 1 : chaque chaîne contiendra toute la chaîne jusqu'à la fin de la ligne (voir
   exemple ci-dessous)
** 2 : comme 1, mais ne supprime pas les séparateurs en fin de chaîne avant le
   découpage _(WeeChat ≥ 0.3.6)_
* _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 supprimé par un appel à
  <<_string_free_split,string_free_split>> après utilisation)

Exemples en C :

[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);

argv = weechat_string_split ("abc de  fghi ", " ", 2, 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);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_split_shell

_WeeChat ≥ 1.0._

Découper une chaîne comme le shell le fait pour une commande avec ses
paramètres.

Cette fonction est une conversion en C de la classe Python "shlex" (fichier :
Lib/shlex.py dans le dépôt Python), voir :
http://docs.python.org/3/library/shlex.html.

Prototype :

[source,C]
----
char **weechat_string_split_shell (const char *string, int *num_items);
----

Paramètres :

* _string_ : chaîne à découper
* _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 supprimé par un appel à
  <<_string_free_split,string_free_split>> après utilisation)

Exemple en C :

[source,C]
----
char **argv;
int argc;
argv = weechat_string_split_shell ("test 'first arg'  \"second arg\"", &argc);
/* résultat : argv[0] == "test"
              argv[1] == "first arg"
              argv[2] == "second arg"
              argv[3] == NULL
              argc == 3
*/
weechat_string_free_split (argv);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_free_split

Supprimer une chaîne découpée.

Prototype :

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

Paramètres :

* _split_string_ : chaîne découpée par <<_string_split,string_split>>

Exemple en C :

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

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_build_with_split_string

Construire 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 <<_string_split,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 supprimée par un appel à
  "free" après utilisation)

Exemple en C :

[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);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_split_command

Découper 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 à découper
* _separator_ : séparateur

Valeur de retour :

* tableau de chaînes, NULL en cas de problème (doit être supprimé par un appel à
  <<_free_split_command,free_split_command>> après utilisation)

Exemple en C :

[source,C]
----
char **argv = weechat_string_split_command ("/commande1 arg;/commande2", ';');
/* résultat : argv[0] == "/commande1 arg"
              argv[1] == "/commande2"
              argv[2] == NULL
*/
weechat_free_split_command (argv);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_free_split_command

Supprimer une commande découpée.

Prototype :

[source,C]
----
void weechat_string_free_split_command (char **split_command);
----

Paramètres :

* _split_command_ : commande découpée par
  <<_string_split_command,string_split_command>>

Exemple en C :

[source,C]
----
char **argv = weechat_string_split_command ("/commande1 arg;/commande2", ';');
/* ... */
weechat_free_split_command (argv);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_format_size

Construire 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 long size);
----

Paramètres :

* _size_ : taille (en octets)

Valeur de retour :

* chaîne formatée (doit être supprimée par un appel à "free" après utilisation)

Exemples en C :

[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 (1);  /* str == "1 octet" */
/* ... */
free (str);

char *str = weechat_string_format_size (200);  /* str == "200 octets" */
/* ... */
free (str);

char *str = weechat_string_format_size (15200);  /* str == "15.2 Ko" */
/* ... */
free (str);

char *str = weechat_string_format_size (2097152);  /* str == "2.10 Mo" */
/* ... */
free (str);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_remove_color

Supprimer 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 chaîne, 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 supprimée par un appel à "free" après
  utilisation)

Exemples en C :

[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);
----

Script (Python) :

[source,python]
----
# prototype
str = weechat.string_remove_color(string, replacement)

# exemple
str = weechat.string_remove_color(ma_chaine, "?")
----

==== string_encode_base64

_WeeChat ≥ 0.3.2._

Encoder une chaîne en base64.

Prototype :

[source,C]
----
void weechat_string_encode_base64 (const char *from, int length, char *to);
----

Paramètres :

* _from_ : chaîne à encoder
* _length_ : longueur de chaîne à encoder (par exemple `strlen(from)`)
* _to_ : pointeur vers la chaîne pour stocker le résultat (doit être
  suffisamment long, le résultat est plus long que la chaîne initiale)

Exemple en C :

[source,C]
----
char *string = "abcdefgh", result[128];
weechat_string_encode_base64 (string, strlen (string), result);
/* result == "YWJjZGVmZ2g=" */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_decode_base64

_WeeChat ≥ 0.3.2._

Décoder une chaîne base64.

Prototype :

[source,C]
----
int weechat_string_decode_base64 (const char *from, char *to);
----

Paramètres :

* _from_ : chaîne à décoder
* _to_ : pointeur vers la chaîne pour stocker le résultat (doit être
  suffisamment long, le résultat est plus court que la chaîne initiale)

Valeur de retour :

* longueur de la chaîne stockée dans _*to_ (ne compte pas le _\0_ final)

Exemple en C :

[source,C]
----
char *string = "YWJjZGVmZ2g=", result[128];
int length;
length = weechat_string_decode_base64 (string, result);
/* length == 8, result == "abcdefgh" */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_hex_dump

_WeeChat ≥ 1.4._

Afficher les données sous forme d'octets en hexadécimal et ascii.

Prototype :

[source,C]
----
char *string_hex_dump (const char *data, int data_size, int bytes_per_line,
                       const char *prefix, const char *suffix);
----

Paramètres :

* _data_ : les données à afficher
* _data_size_ : nombre d'octets à afficher dans _data_
* _bytes_per_line_ : nombre d'octets à afficher sur chaque ligne
* _prefix_ : le préfixe à afficher au début de chaque ligne
  (optionnel, peut être NULL)
* _suffix_ : le suffixe à afficher à la fin de chaque ligne
  (optionnel, peut être NULL)

Valeur de retour :

* chaîne avec les données (doit être supprimée par un appel à "free" après
  utilisation)

Exemple en C :

[source,C]
----
char *string = "abc def-ghi";
char *dump = weechat_string_hex_dump (string, strlen (string), 8, " >> ", NULL);
/* dump == " >> 61 62 63 20 64 65 66 2D   a b c   d e f - \n"
           " >> 67 68 69                  g h i           "  */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== string_is_command_char

_WeeChat ≥ 0.3.2._

Vérifier si le premier caractère de la chaîne est un caractère de commande (le
caractère par défaut de commande est `+/+`).

Prototype :

[source,C]
----
int weechat_string_is_command_char (const char *string);
----

Paramètres :

* _string_ : chaîne

Valeur de retour :

* 1 si le premier caractère de la chaîne est un caractère de commande, sinon 0

Exemples en C :

[source,C]
----
int command_char1 = weechat_string_is_command_char ("/test");  /* == 1 */
int command_char2 = weechat_string_is_command_char ("test");   /* == 0 */
----

Script (Python) :

[source,python]
----
# prototype
is_cmdchar = weechat.string_is_command_char(string)

# exemples
command_char1 = weechat.string_is_command_char("/test")  # == 1
command_char2 = weechat.string_is_command_char("test")   # == 0
----

==== string_input_for_buffer

_WeeChat ≥ 0.3.2._

Retourner un pointeur vers le texte envoyé vers le tampon (pointeur à
l'intérieur du paramètre "string"), ou NULL si c'est une commande.

Prototype :

[source,C]
----
const char *weechat_string_input_for_buffer (const char *string);
----

Paramètres :

* _string_ : chaîne

Valeur de retour :

* pointeur vers "string", ou NULL

Exemples en C :

[source,C]
----
const char *str1 = weechat_string_input_for_buffer ("test");    /* "test"  */
const char *str2 = weechat_string_input_for_buffer ("/test");   /* NULL    */
const char *str3 = weechat_string_input_for_buffer ("//test");  /* "/test" */
----

Script (Python) :

[source,python]
----
# prototype
str = weechat.string_input_for_buffer(string)

# exemples
str1 = weechat.string_input_for_buffer("test")    # "test"
str2 = weechat.string_input_for_buffer("/test")   # ""
str3 = weechat.string_input_for_buffer("//test")  # "/test"
----

==== string_eval_expression

_WeeChat ≥ 0.4.0, mis à jour dans la 0.4.2, 1.0, 1.1, 1.2 et 1.3._

Évaluer l'expression et retourner le résultat sous forme de chaîne.
Les variables spéciales avec le format `+${variable}+` sont étendues (voir le
tableau ci-dessous).

[NOTE]
Depuis la version 1.0, les variables imbriquées sont supportées, par exemple :
`+${color:${variable}}+`.

Prototype :

[source,C]
----
char *weechat_string_eval_expression (const char *expr,
                                      struct t_hashtable *pointers,
                                      struct t_hashtable *extra_vars,
                                      struct t_hashtable *options);
----

Paramètres :

* _expr_ : l'expression à évaluer (voir le tableau ci-dessous)
* _pointers_ : table de hachage avec les pointeurs (les clés doivent être des
  chaînes, les valeurs doivent être des pointeurs); les pointeurs "window" et
  "buffer" sont automatiquement ajoutés s'ils ne sont pas dans la table de
  hachage (avec le pointer vers fenêtre/tampon courants) (peut être NULL) :
** _regex_ : pointeur vers une expression régulière (structure _regex_t_)
   compilée avec la fonction WeeChat
   <<_string_regcomp,string_regcomp>> ou regcomp (voir `man regcomp`) ;
   cette option est similaire à _regex_ dans la table de
   hachage _options_ (ci-dessous), mais est utilisée pour de meilleures
   performances
* _extra_vars_ : variables additionnelles qui seront étendues (peut être NULL)
* _options_ : table de hachage avec des options (les clés et valeurs doivent
  être des chaînes) (peut être NULL) :
** _type_ : le comportement par défaut est de juste remplacer les valeurs dans
   l'expression, d'autres types peuvent être choisis :
*** _condition_ : l'expression est évaluée comme une condition : les opérateurs
    et parenthèses sont utilisés, le résultat est un booléen ("0" ou "1")
** _prefix_ : préfixe avant les variables à remplacer (par défaut : `+${+`)
** _suffix_ : suffixe après les variables à remplacer (par défaut : `+}+`)
** _extra_ : le comportement par défaut est juste de remplacer les variables
   additionnelles (_extra_vars_), un autre comportement peut être sélectionné :
*** _eval_ : les variables additionnelles (_extra_vars_) sont évaluées
    elles-mêmes avant remplacement
** _regex_ : une expression regulière pour remplacer du texte dans _expr_ (qui
   n'est alors pas évalué)
** _regex_replace_ : le texte de remplacement à utiliser avec _regex_, pour
   remplacer du texte dans _expr_ (_regex_replace_ est évalué sur chaque
   correspondance de _regex_ sur _expr_, jusqu'à ce que plus aucune
   correspondance ne soit trouvée)

Valeur de retour :

* expression évaluée (doit être supprimée après un appel à "free" après
  utilisation), ou NULL si problème (expression invalide ou pas assez de
  mémoire)

Liste des variables étendues dans l'expression (par ordre de priorité, de la
première étendue à la dernière) :

[width="100%",cols="2,8,4,4",options="header"]
|===
| Format | Description | Exemples | Résultats

| `+${nom}+` |
  Variable `nom` de la table de hachage _extra_vars_ |
  `+${nom}+` |
  `+valeur+`

| `+${eval:xxx}+` +
  (_WeeChat ≥ 1.3_) |
  Chaîne à évaluer |
  `+${eval:${date:${weechat.look.buffer_time_format}}}+` |
  `+19:02:45+` (avec des couleurs s'il y a des codes couleur dans l'option
  weechat.look.buffer_time_format)

| `+${esc:xxx}+` +
  `+${\xxx}+` |
  Chaîne avec caractères échappés |
  `+${esc:préfixe\tmessage}+` +
  `+${\ua9}+` |
  `+préfixe<TAB>message+` +
  `+©+`

| `+${hide:x,valeur}+` |
  Chaîne avec les caractères masqués (tous les caractères dans `valeur`
  remplacés par `x` |
  `+${hide:*,mot_de_passe}+` |
  `+************+`

| `+${re:N}+` |
  Groupe regex capturé : `0` = toute la chaîne correspondante,
  `1` à `99` = groupe capturé, `+++` = dernier groupe capturé |
  `+${re:1}+` |
  `+test+`

| `+${color:nom}+` |
  Code couleur WeeChat (le nom de couleur a des attributs facultatifs),
  voir la fonction <<_color,color>> pour les formats supportés |
  `+${color:red}texte rouge+` +
  `+${color:*214}texte orange gras+` |
  `+texte rouge+` (en rouge) +
  `+texte orange gras+` (en orange gras)

| `+${info:nom}+` +
  `+${info:nom,paramètres}+` |
  Info de WeeChat ou d'une extension, voir la fonction <<_info_get,info_get>> |
  `+${info:version}+` +
  `+${info:irc_nick_color_name,foo}+` |
  `+1.0+` +
  `+lightblue+`

| `+${date}+` +
  `+${date:xxx}+` +
  (_WeeChat ≥ 1.3_) |
  La date/heure courante, avec un format personnalisé (voir `man strftime`),
  le format par défaut est `%F %T` |
  `+${date}+` +
  `+${date:%H:%M:%S}+` |
  `+2015-06-30 19:02:45+` +
  `+19:02:45+`

| `+${env:NOM}+` +
  (_WeeChat ≥ 1.2_) |
  Valeur de la variable d'environnement `NOM` |
  `+${env:HOME}+` |
  `+/home/user+`

| `+${sec.data.nom}+` |
  Valeur de la donnée sécurisée `nom` |
  `+${sec.data.freenode_pass}+` |
  `+mon_mot_de_passe+`

| `+${fichier.section.option}+` |
  Valeur de l'option |
  `+${weechat.look.buffer_time_format}+` |
  `+%H:%M:%S+`

| `+${nom}+` |
  Valeur de la variable locale `nom` dans le tampon |
  `+${nick}+` |
  `+FlashCode+`

| `+${hdata.var1.var2...}+` +
  `+${hdata[list].var1.var2...}+` |
  Valeur d'un hdata (les pointeurs `window` et `buffer` sont définis par défaut
  avec la fenêtre et tampon courants) |
  `+${buffer[gui_buffers].full_name}+` +
  `+${window.buffer.number}+` |
  `+core.weechat+` +
  `+1+`
|===

Exemples en C :

[source,C]
----
/* conditions */
struct t_hashtable *options1 = weechat_hashtable_new (8,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      NULL,
                                                      NULL);
weechat_hashtable_set (options1, "type", "condition");
char *str1 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options1);  /* "1" */
char *str2 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options1);                 /* "0" */

/* expression simple */
char *str3 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);  /* "core.weechat" */

/* remplacement avec regex */
struct t_hashtable *options2 = weechat_hashtable_new (8,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      NULL,
                                                      NULL);
/* ajout de crochets autour des URLs */
weechat_hashtable_set (options2, "regex", "\\w+://\\S+");
weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]");
char *str4 = weechat_string_eval_expression ("test : https://weechat.org", NULL, NULL, NULL);  /* "test : [ https://weechat.org ]" */

/* masquage des mots de passe */
weechat_hashtable_set (options2, "regex", "(password=)(\\S+)");
weechat_hashtable_set (options2, "regex_replace", "${re:1}${hide:*,${re:2}}");
char *str5 = weechat_string_eval_expression ("password=abc password=def", NULL, NULL, NULL);  /* "password=*** password=***" */
----

Script (Python) :

[source,python]
----
# prototype
str = weechat.string_eval_expression(expr, pointers, extra_vars, options)

# exemples

# conditions
str1 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
str2 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"

# expression simple
str3 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat"

# remplacement avec regex : ajout de crochets autour des URLs
options = {
    "regex": "\\w+://\\S+",
    "regex_replace": "[ ${re:0} ]",
}
str4 = weechat.string_eval_expression("test : https://weechat.org", {}, {}, options)  # "test : [ https://weechat.org ]"

# replace with regex : masquage des mots de passe
options = {
    "regex": "(password=)(\\S+)",
    "regex_replace": "${re:1}${hide:*,${re:2}}",
}
str5 = weechat.string_eval_expression("password=abc password=def", {}, {}, options)  # "password=*** password=***"
----

[[utf-8]]
=== UTF-8

Fonctions pour les chaînes UTF-8.

==== utf8_has_8bits

Vérifier 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 en C :

[source,C]
----
if (weechat_utf8_has_8bits (string))
{
    /* ... */
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_is_valid

_Mis à jour dans la 1.4._

Vérifier si une chaîne est valide UTF-8.

Prototype :

[source,C]
----
int weechat_utf8_is_valid (const char *string, int length, char **error);
----

Paramètres :

* _string_ : chaîne
* _length_ : nombre maximum de caractères UTF-8 à vérifier ; si ≤ 0, la chaîne
  complète est vérifiée _(WeeChat ≥ 1.4)_
* _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 en C :

[source,C]
----
char *error;
if (weechat_utf8_is_valid (string, -1, &error))
{
    /* ... */
}
else
{
    /* "error" pointe vers le premier caractère invalide */
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_normalize

Normaliser une chaîne UTF-8 : supprimer tous les caractères non valides UTF-8
en les remplaçant par un caractère.

Prototype :

[source,C]
----
void weechat_utf8_normalize (char *string, char replacement);
----

Paramètres :

* _string_ : chaîne
* _replacement_ : caractère de remplacement pour les caractères non valides

Exemple en C :

[source,C]
----
weechat_utf8_normalize (string, '?');
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_prev_char

_Mis à jour dans la 1.3._

Retourner un pointeur vers le caractère UTF-8 précédent dans une chaîne.

Prototype :

[source,C]
----
const 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)
  (_WeeChat ≥ 1.3_ : le pointeur retourné est un _const char *_ au lieu d'un
  _char *_)

Exemple en C :

[source,C]
----
const char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_next_char

_Mis à jour dans la 1.3._

Retourner un pointeur vers le caractère UTF-8 suivant dans une chaîne.

Prototype :

[source,C]
----
const 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)
  (_WeeChat ≥ 1.3_ : le pointeur retourné est un _const char *_ au lieu d'un
  _char *_)

Exemple en C :

[source,C]
----
const char *next_char = weechat_utf8_next_char (string);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_char_int

Retourner un caractère UTF-8 sous forme d'entier.

Prototype :

[source,C]
----
int weechat_utf8_char_int (const char *string);
----

Paramètres :

* _string_ : chaîne

Valeur de retour :

* caractère UTF-8 sous forme d'entier

Exemple en C :

[source,C]
----
int char_int = weechat_utf8_char_int ("être");  /* "ê" comme entier */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_char_size

Retourner 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 en C :

[source,C]
----
int char_size = weechat_utf8_char_size ("être");  /* == 2 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_strlen

Retourner 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 en C :

[source,C]
----
int length = weechat_utf8_strlen ("chêne");  /* == 5 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_strnlen

Retourner 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 en C :

[source,C]
----
int length = weechat_utf8_strnlen ("chêne", 4);  /* == 3 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_strlen_screen

Retourner 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 en C :

[source,C]
----
int length_on_screen = weechat_utf8_strlen_screen ("é");  /* == 1 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_charcmp

_Mis à jour dans la 1.0._

Comparer deux caractères UTF-8.

Prototype :

[source,C]
----
int weechat_utf8_charcmp (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 :

* -1 si string1 < string2
* 0 si string1 == string2
* 1 si string1 > string2

Exemple en C :

[source,C]
----
int diff = weechat_utf8_charcmp ("aaa", "ccc");  /* == -2 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_charcasecmp

_Mis à jour dans la 1.0._

Comparer 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 :

* -1 si string1 < string2
* 0 si string1 == string2
* 1 si string1 > string2

Exemple en C :

[source,C]
----
int diff = weechat_utf8_charcasecmp ("aaa", "CCC");  /* == -2 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_char_size_screen

Retourner 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 en C :

[source,C]
----
int length_on_screen = weechat_utf8_char_size_screen ("é");  /* == 1 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_add_offset

_Mis à jour dans la 1.3._

Avancer de N caractères dans une chaîne UTF-8.

Prototype :

[source,C]
----
const 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)
  (_WeeChat ≥ 1.3_ : le pointeur retourné est un _const char *_ au lieu d'un
  _char *_)

Exemple en C :

[source,C]
----
const char *str = "chêne";
const char *str2 = weechat_utf8_add_offset (str, 3);  /* pointe vers "ne" */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_real_pos

Retourner 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 en C :

[source,C]
----
int pos = weechat_utf8_real_pos ("chêne", 3);  /* == 4 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_pos

Retourner 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 en C :

[source,C]
----
int pos = weechat_utf8_pos ("chêne", 4);  /* == 3 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== utf8_strndup

Retourner 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 supprimée avec un appel à "free" après
  utilisation)

Exemple en C :

[source,C]
----
char *string = weechat_utf8_strndup ("chêne", 3);  /* retourne "chê" */
/* ... */
free (str);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

[[directories]]
=== Répertoires

Fonctions liées aux répertoires.

==== mkdir_home

Créer 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 en C :

[source,C]
----
if (!weechat_mkdir_home ("temp", 0755))
{
    /* erreur */
}
----

Script (Python) :

[source,python]
----
# prototype
weechat.mkdir_home(directory, mode)

# exemple
weechat.mkdir_home("temp", 0755)
----

==== mkdir

Créer 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 en C :

[source,C]
----
if (!weechat_mkdir ("/tmp/mydir", 0755))
{
    /* erreur */
}
----

Script (Python) :

[source,python]
----
# prototype
weechat.mkdir(directory, mode)

# exemple
weechat.mkdir("/tmp/mydir", 0755)
----

==== mkdir_parents

Créer 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 en C :

[source,C]
----
if (!weechat_mkdir_parents ("/tmp/my/dir", 0755))
{
    /* erreur */
}
----

Script (Python) :

[source,python]
----
# prototype
weechat.mkdir_parents(directory, mode)

# exemple
weechat.mkdir_parents("/tmp/my/dir", 0755)
----

==== exec_on_files

_Mis à jour dans la 1.5._

Balayer les fichiers dans un répertoire et exécuter un "callback" pour chaque
fichier.

Prototype :

[source,C]
----
void weechat_exec_on_files (const char *directory,
                            int hidden_files,
                            void (*callback)(void *data,
                                             const char *filename),
                            void *callback_data);
----

Paramètres :

* _directory_ : répertoire où chercher les fichiers
* _hidden_files_ : 1 pour inclure les fichiers cachés, sinon 0
* _callback_ : fonction appelée pour chaque fichier trouvé, paramètres :
** _void *data_ : pointeur
** _const char *filename_ : nom de fichier trouvé
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat

Exemple en C :

[source,C]
----
void callback (void *data, const char *filename)
{
    /* ... */
}
...
weechat_exec_on_files ("/tmp", 0, &callback, NULL);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== file_get_content

_WeeChat ≥ 0.3.1._

Lire le contenu d'un fichier texte dans une chaîne de caractères.

Prototype :

[source,C]
----
char *weechat_file_get_content (const char *filename);
----

Paramètres :

* _filename_ : chemin et nom du fichier

Valeur de retour :

* contenu du fichier sous forme de chaîne (doit être supprimé par un appel à
  "free" après utilisation)

Exemple en C :

[source,C]
----
char *contenu;

contenu = weechat_file_get_content ("/tmp/test.txt");
/* ... */
free (contenu);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

[[util]]
=== Util

Quelques fonctions utiles.

==== util_timeval_cmp

Comparer deux structures "timeval".

Prototype :

[source,C]
----
int weechat_util_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 en C :

[source,C]
----
if (weechat_util_timeval_cmp (&tv1, &tv2) > 0)
{
    /* tv1 > tv2 */
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== util_timeval_diff

_Mis à jour dans la 1.1._

Retourner la différence (en microsecondes) entre deux structures "timeval".

Prototype :

[source,C]
----
long long weechat_util_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 microsecondes

[NOTE]
Avec WeeChat ≤ 1.0, la valeur retournée était en millisecondes.

Exemple en C :

[source,C]
----
long long diff = weechat_util_timeval_diff (&tv1, &tv2);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== util_timeval_add

_Mis à jour dans la 1.1._

Ajouter un intervalle (en microsecondes) à une structure "timeval".

Prototype :

[source,C]
----
void weechat_util_timeval_add (struct timeval *tv, long long interval);
----

Paramètres :

* _tv_ : structure "timeval"
* _interval_ : intervalle (en microsecondes)

[NOTE]
Avec WeeChat ≤ 1.0, l'intervalle était exprimé en millisecondes.

Exemple en C :

[source,C]
----
weechat_util_timeval_add (&tv, 2000000);  /* ajouter 2 secondes */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== util_get_time_string

_WeeChat ≥ 0.3.2, mise à jour dans la 1.3._

Retourner la date/heure sous forme de chaîne construite avec "strftime" et le
format défini dans l'option _weechat.look.time_format_.

Prototype :

[source,C]
----
const char *weechat_util_get_time_string (const time_t *date);
----

Paramètres :

* _date_ : pointeur vers la date

Valeur de retour :

* pointeur vers une chaîne contenant la date/heure

Exemple en C :

[source,C]
----
time_t date = time (NULL);
weechat_printf (NULL, "date : %s",
                weechat_util_get_time_string (&date));
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== util_version_number

_WeeChat ≥ 0.3.9._

Convertir une chaîne avec la version WeeChat en nombre.

Prototype :

[source,C]
----
int weechat_util_version_number (const char *version);
----

Paramètres :

* _version_ : version WeeChat sous forme de chaîne (exemple : "0.3.9" ou
  "0.3.9-dev")

Exemple en C :

[source,C]
----
version_number = weechat_util_version_number ("0.3.8");      /* == 0x00030800 */
version_number = weechat_util_version_number ("0.3.9-dev");  /* == 0x00030900 */
version_number = weechat_util_version_number ("0.3.9-rc1");  /* == 0x00030900 */
version_number = weechat_util_version_number ("0.3.9");      /* == 0x00030900 */
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

[[sorted_lists]]
=== Listes triées

Fonctions pour les listes triées.

==== list_new

Créer une nouvelle liste.

Prototype :

[source,C]
----
struct t_weelist *weechat_list_new ();
----

Valeur de retour :

* pointeur vers la nouvelle liste

Exemple en C :

[source,C]
----
struct t_weelist *list = weechat_list_new ();
----

Script (Python) :

[source,python]
----
# prototype
list = weechat.list_new()

# exemple
list = weechat.list_new()
----

==== list_add

Ajouter 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 en C :

[source,C]
----
struct t_weelist_item *my_item =
    weechat_list_add (list, "ma donnée", WEECHAT_LIST_POS_SORT, NULL);
----

Script (Python) :

[source,python]
----
# prototype
item = weechat.list_add(list, data, where, user_data)

# exemple
item = weechat.list_add(list, "ma donnée", weechat.WEECHAT_LIST_POS_SORT, "")
----

==== list_search

Rechercher 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 en C :

[source,C]
----
struct t_weelist_item *item = weechat_list_search (list, "ma donnée");
----

Script (Python) :

[source,python]
----
# prototype
item = weechat.list_search(list, data)

# exemple
item = weechat.list_search(list, "ma donnée")
----

==== list_search_pos

_WeeChat ≥ 0.3.4._

Rechercher la position d'un élément dans une liste.

Prototype :

[source,C]
----
int weechat_list_search_pos (struct t_weelist *weelist,
                             const char *data);
----

Paramètres :

* _weelist_ : pointeur vers la liste
* _data_ : donnée à chercher dans la liste

Valeur de retour :

* position de l'élément trouvé, -1 si aucun élément n'a été trouvé

Exemple en C :

[source,C]
----
int pos_item = weechat_list_search_pos (list, "ma donnée");
----

Script (Python) :

[source,python]
----
# prototype
pos_item = weechat.list_search_pos(list, data)

# exemple
pos_item = weechat.list_search_pos(list, "ma donnée")
----

==== list_casesearch

Rechercher 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 en C :

[source,C]
----
struct t_weelist_item *item = weechat_list_casesearch (list, "ma donnée");
----

Script (Python) :

[source,python]
----
# prototype
item = weechat.list_casesearch(list, data)

# exemple
item = weechat.list_casesearch(list, "ma donnée")
----

==== list_casesearch_pos

_WeeChat ≥ 0.3.4._

Rechercher la position d'un élément dans la liste, sans tenir compte de la
casse.

Prototype :

[source,C]
----
int weechat_list_casesearch_pos (struct t_weelist *weelist,
                                 const char *data);
----

Paramètres :

* _weelist_ : pointeur vers la liste
* _data_ : données à chercher dans la liste

Valeur de retour :

* position l'élément trouvé, -1 si aucun élément n'a été trouvé

Exemple en C :

[source,C]
----
int pos_item = weechat_list_casesearch_pos (list, "ma donnée");
----

Script (Python) :

[source,python]
----
# prototype
pos_item = weechat.list_casesearch_pos(list, data)

# exemple
pos_item = weechat.list_casesearch_pos(list, "ma donnée")
----

==== list_get

Retourner 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 en C :

[source,C]
----
struct t_weelist_item *item = weechat_list_get (list, 0);  /* premier élément */
----

Script (Python) :

[source,python]
----
# prototype
item = weechat.list_get(list, position)

# exemple
item = weechat.list_get(list, 0)
----

==== list_set

Affecter 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 en C :

[source,C]
----
weechat_list_set (item, "nouvelle donnée");
----

Script (Python) :

[source,python]
----
# prototype
weechat.list_set(item, value)

# exemple
weechat.list_set(item, "nouvelle donnée")
----

==== list_next

Retourner l'élément 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 en C :

[source,C]
----
struct t_weelist_item *next_item = weechat_list_next (item);
----

Script (Python) :

[source,python]
----
# prototype
item = weechat.list_next(item)

# exemple
item = weechat.list_next(item)
----

==== list_prev

Retourner 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 en C :

[source,C]
----
struct t_weelist_item *prev_item = weechat_list_prev (item);
----

Script (Python) :

[source,python]
----
# prototype
item = weechat.list_prev(item)

# exemple
item = weechat.list_prev(item)
----

==== list_string

Retourner 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 en C :

[source,C]
----
weechat_printf (NULL, "valeur de l'item : %s", weechat_list_string (item));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.list_string(item)

# exemple
weechat.prnt("", "valeur de l'item : %s" % weechat.list_string(item))
----

==== list_size

Retourner 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 en C :

[source,C]
----
weechat_printf (NULL, "taille de la liste : %d", weechat_list_size (list));
----

Script (Python) :

[source,python]
----
# prototype
size = weechat.list_size(list)

# exemple
weechat.prnt("", "taille de la liste : %d" % weechat.list_size(list))
----

==== list_remove

Supprimer 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 en C :

[source,C]
----
weechat_list_remove (list, item);
----

Script (Python) :

[source,python]
----
# prototype
weechat.list_remove(list, item)

# exemple
weechat.list_remove(list, item)
----

==== list_remove_all

Supprimer 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 en C :

[source,C]
----
weechat_list_remove_all (list);
----

Script (Python) :

[source,python]
----
# prototype
weechat.list_remove_all(list)

# exemple
weechat.list_remove_all(list)
----

==== list_free

Supprimer une liste.

Prototype :

[source,C]
----
void weechat_list_free (struct t_weelist *weelist);
----

Paramètres :

* _weelist_ : pointeur vers la liste

Exemple en C :

[source,C]
----
weechat_list_free (list);
----

Script (Python) :

[source,python]
----
# prototype
weechat.list_free(list)

# exemple
weechat.list_free(list)
----

[[hashtables]]
=== Tables de hachage

Fonctions pour les tables de hachage.

==== hashtable_new

_WeeChat ≥ 0.3.3._

Créer une nouvelle table de hachage.

Prototype :

[source,C]
----
struct t_hashtable *weechat_hashtable_new (int size,
                                           const char *type_keys,
                                           const char *type_values,
                                           unsigned long long (*callback_hash_key)(struct t_hashtable *hashtable,
                                                                                   const void *key),
                                           int (*callback_keycmp)(struct t_hashtable *hashtable,
                                                                  const void *key1,
                                                                  const void *key2));
----

Paramètres :

* _size_ : taille du tableau interne pour stocker les clés sous forme de
  hachage, une grande valeur utilise plus de mémoire mais présente une meilleure
  performance (cela n'est *pas* une limite sur le nombre d'entrées de la table
  de hachage)
* _type_keys_ : type pour les clés dans la table de hachage :
** _WEECHAT_HASHTABLE_INTEGER_
** _WEECHAT_HASHTABLE_STRING_
** _WEECHAT_HASHTABLE_POINTER_
** _WEECHAT_HASHTABLE_BUFFER_
** _WEECHAT_HASHTABLE_TIME_
* _type_values_ : type pour les valeurs dans la table de hachage :
** _WEECHAT_HASHTABLE_INTEGER_
** _WEECHAT_HASHTABLE_STRING_
** _WEECHAT_HASHTABLE_POINTER_
** _WEECHAT_HASHTABLE_BUFFER_
** _WEECHAT_HASHTABLE_TIME_
* _callback_hash_key_ : fonction appelée pour rendre le hachage d'une clé (la
  clé sous forme de nombre entier), peut être NULL si le type de clé n'est pas
  "buffer" (une fonction de hachage par défaut est utilisée), paramètres et
  valeur de retour :
** _struct t_hashtable *hashtable_ : pointeur vers la table de hachage
** _const void *key_ : clé
** valeur de retour : hachage de la clé
* _callback_keycmp_ : fonction appelée pour comparer deux clés, peut être NULL
  si le type de clé n'est pas "buffer" (une fonction de comparaison par défaut
  est utilisée), paramètres et valeur de retour :
** _struct t_hashtable *hashtable_ : pointeur vers la table de hachage
** _const void *key1_ : première clé
** _const void *key2_ : seconde clé
** valeur de retour :
*** nombre négatif si _key1_ est inférieur à _key2_
*** 0 si _key1_ est égal à _key2_
*** nombre positif si _key1_ est supérieur à _key2_

Valeur de retour :

* pointeur vers la nouvelle table de hachage, NULL en cas d'erreur

Exemple en C :

[source,C]
----
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_set_with_size

_WeeChat ≥ 0.3.3, mis à jour dans la 0.4.2._

Ajouter ou mettre à jour une entrée dans une table de hachage avec une taille
pour la clé et la valeur.

Prototype :

[source,C]
----
struct t_hashtable_item *weechat_hashtable_set_with_size (struct t_hashtable *hashtable,
                                                          const void *key, int key_size,
                                                          const void *value, int value_size);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _key_ : pointeur vers la clé
* _key_size_ : taille de la clé (en octets), utilisée seulement si le type de
  clés dans la table de hachage est "buffer"
* _value_ : pointeur vers la valeur
* _value_size_ : taille de la valeur (en octets), utilisée seulement si le type
  de valeurs dans la table de hachage est "buffer"

Valeur de retour :

* pointeur vers l'item créé/mis à jour, NULL en cas d'erreur

Exemple en C :

[source,C]
----
weechat_hashtable_set_with_size (hashtable, "ma_cle", 0,
                                 my_buffer, sizeof (my_buffer_struct));
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_set

_WeeChat ≥ 0.3.3, mis à jour dans la 0.4.2._

Ajouter ou mettre à jour une entrée dans la table de hachage.

Prototype :

[source,C]
----
struct t_hashtable_item *weechat_hashtable_set (struct t_hashtable *hashtable,
                                                const void *key, const void *value);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _key_ : pointeur vers la clé
* _value_ : pointeur vers la valeur

Valeur de retour :

* pointeur vers l'item créé/mis à jour, NULL en cas d'erreur

Exemple en C :

[source,C]
----
weechat_hashtable_set (hashtable, "ma_cle", "ma_valeur");
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_get

_WeeChat ≥ 0.3.3._

Retourner la valeur associée à une clé dans une table de hachage.

Prototype :

[source,C]
----
void *weechat_hashtable_get (struct t_hashtable *hashtable, void *key);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _key_ : pointeur vers la clé

Valeur de retour :

* valeur pour la clé, NULL si la clé n'est pas trouvée

Exemple en C :

[source,C]
----
void *value = weechat_hashtable_get (hashtable, "ma_cle");
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_has_key

_WeeChat ≥ 0.3.4._

Vérifier si une clé est présente dans la table de hachage.

Prototype :

[source,C]
----
int weechat_hashtable_has_key (struct t_hashtable *hashtable, void *key);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _key_ : pointeur vers la clé

Valeur de retour :

* 1 si la clé est dans la table de hachage, 0 si la clé n'est pas dans la table
  de hachage

Exemple en C :

[source,C]
----
if (weechat_hashtable_has_key (hashtable, "ma_cle"))
{
    /* la clé est dans la table de hachage */
    /* ... */
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_map

_WeeChat ≥ 0.3.3._

Appeller une fonction pour chaque entrée d'une table de hachage.

Prototype :

[source,C]
----
void weechat_hashtable_map (struct t_hashtable *hashtable,
                            void (*callback_map)(void *data,
                                                 struct t_hashtable *hashtable,
                                                 const void *key,
                                                 const void *value),
                            void *callback_map_data);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _callback_map_ : fonction appelée pour chaque entrée de la table de hachage
* _callback_map_data_ : pointeur donné au "callback" lorsqu'il est appelé

Exemple en C :

[source,C]
----
void
map_cb (void *data, struct t_hashtable *hashtable,
        const void *key, const void *value)
{
    /* afficher la clé et la valeur (elles sont des chaînes ici) */
    weechat_printf (NULL, "clé : '%s', valeur : '%s'",
                    (const char *)key,
                    (const char *)value);
}
/* ... */
weechat_hashtable_map (hashtable, &map_cb, NULL);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_map_string

_WeeChat ≥ 0.3.7._

Appeller une fonction pour chaque entrée d'une table de hachage, en envoyant les
clés et valeurs sous forme de chaînes.

Prototype :

[source,C]
----
void weechat_hashtable_map_string (struct t_hashtable *hashtable,
                                   void (*callback_map)(void *data,
                                                        struct t_hashtable *hashtable,
                                                        const char *key,
                                                        const char *value),
                                   void *callback_map_data);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _callback_map_ : fonction appelée pour chaque entrée de la table de hachage
* _callback_map_data_ : pointeur donné au "callback" lorsqu'il est appelé

[NOTE]
Les chaînes _key_ et _value_ envoyées au "callback" sont des chaînes
temporaires, elles sont supprimées après l'appel au "callback".

Exemple en C :

[source,C]
----
void
map_cb (void *data, struct t_hashtable *hashtable,
        const char *key, const char *value)
{
    /* afficher la clé et la valeur */
    weechat_printf (NULL, "clé : '%s', valeur : '%s'",
                    key, value);
}
/* ... */
weechat_hashtable_map_string (hashtable, &map_cb, NULL);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_dup

_WeeChat ≥ 1.0._

Dupliquer une table de hachage.

Prototype :

[source,C]
----
struct t_hashtable *weechat_hashtable_dup (struct t_hashtable *hashtable);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage

Valeur de retour :

* table de hachage dupliquée

Exemple en C :

[source,C]
----
struct t_hashtable *new_hashtable = weechat_hashtable_dup (hashtable);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_get_integer

_WeeChat ≥ 0.3.3._

Retourner une valeur entière pour une propriété d'une table de hachage.

Prototype :

[source,C]
----
int weechat_hashtable_get_integer (struct t_hashtable *hashtable,
                                   void *property);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _property_ : nom de propriété :
** _size_ : taille du tableau interne "htable" dans la table de hachage
** _items_count_ : nombre d'éléments dans la table de hachage

Valeur de retour :

* valeur de la propriété sous forme d'entier

Exemple en C :

[source,C]
----
int items_count = weechat_hashtable_get_integer (hashtable, "items_count");
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_get_string

_WeeChat ≥ 0.3.4._

Retourner une valeur pour une propriété d'une table de hachage sous forme de
chaîne.

Prototype :

[source,C]
----
const char *weechat_hashtable_get_string (struct t_hashtable *hashtable,
                                          const char *property);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _property_ : nom de la propriété :
** _type_keys_ : type pour les clés :
*** _integer_ : entier
*** _string_ : chaîne
*** _pointer_ : pointeur
*** _buffer_ : buffer
*** _time_ : heure
** _type_values_ : type pour les valeurs :
*** _integer_ : entier
*** _string_ : chaîne
*** _pointer_ : pointeur
*** _buffer_ : buffer
*** _time_ : heure
** _keys_ : chaîne avec la liste des clés (format : "clé1,clé2,clé3")
** _keys_sorted_ : chaîne avec la liste triée des clés (format :
   "clé1,clé2,clé3")
** _values_ : chaîne avec la liste des valeurs (format :
   "valeur1,valeur2,valeur3")
** _keys_values_ : chaîne avec la liste des clés et valeurs
   (format : "clé1:valeur1,clé2:valeur2,clé3:valeur3")
** _keys_values_sorted_ : chaîne avec la liste des clés et valeurs (triée sur
   les clés) (format : "clé1:valeur1,clé2:valeur2,clé3:valeur3")

Valeur de retour :

* valeur de la propriété sous forme de chaîne

Exemples en C :

[source,C]
----
weechat_printf (NULL, "les clés sont de type : %s",
                weechat_hashtable_get_string (hashtable, "type_keys"));
weechat_printf (NULL, "liste des clés : %s",
                weechat_hashtable_get_string (hashtable, "keys"));
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_set_pointer

_WeeChat ≥ 0.3.4._

Affecter un pointeur à une propriété d'une table de hachage.

Prototype :

[source,C]
----
void weechat_hashtable_set_pointer (struct t_hashtable *hashtable,
                                    const char *property, void *pointer);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _property_ : nom de la propriété :
** _callback_free_key_ : définit la fonction "callback" pour supprimer les clés
   de la table de hachage _(WeeChat ≥ 0.4.2)_
** _callback_free_value_ : définit la fonction "callback" pour supprimer les
   valeurs de la table de hachage
* _pointer_ : nouvelle valeur de pointeur pour la propriété

Exemple en C :

[source,C]
----
void
my_free_value_cb (struct t_hashtable *hashtable, const void *key, void *value)
{
    /* ... */
}

void
my_free_key_cb (struct t_hashtable *hashtable, void *key)
{
    /* ... */
}

weechat_hashtable_set_pointer (hashtable, "callback_free_value", &my_free_value_cb);
weechat_hashtable_set_pointer (hashtable, "callback_free_key", &my_free_key_cb);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_add_to_infolist

_WeeChat ≥ 0.3.3._

Ajouter les éléments d'une table de hachage dans un objet infolist.

Prototype :

[source,C]
----
int weechat_hashtable_add_to_infolist (struct t_hashtable *hashtable,
                                       struct t_infolist_item *infolist_item,
                                       const char *prefix);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _infolist_item_ : pointeur vers l'objet de l'infolist
* _prefix_ : chaîne utilisée comme préfixe pour les noms dans l'infolist

Valeur de retour :

* 1 si ok, 0 en cas d'erreur

Exemple en C :

[source,C]
----
weechat_hashtable_add_to_infolist (hashtable, infolist_item, "testhash");

/* si la table de hachage contient :
     "cle1" => "valeur 1"
     "cle2" => "valeur 2"
   alors les variables suivantes seront ajoutées dans l'objet de l'infolist :
     "testhash_name_00000"  = "cle1"
     "testhash_value_00000" = "valeur 1"
     "testhash_name_00001"  = "cle2"
     "testhash_value_00001" = "valeur 2"
*/
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_remove

_WeeChat ≥ 0.3.3._

Supprimer un élément d'une table de hachage.

Prototype :

[source,C]
----
void weechat_hashtable_remove (struct t_hashtable *hashtable, const void *key);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage
* _key_ : pointeur vers la clé

Exemple en C :

[source,C]
----
weechat_hashtable_remove (hashtable, "ma_cle");
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_remove_all

_WeeChat ≥ 0.3.3._

Supprimer tous les éléments d'une table de hachage.

Prototype :

[source,C]
----
void weechat_hashtable_remove_all (struct t_hashtable *hashtable);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage

Exemple en C :

[source,C]
----
weechat_hashtable_remove_all (hashtable);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hashtable_free

_WeeChat ≥ 0.3.3._

Supprimer une table de hachage.

Prototype :

[source,C]
----
void weechat_hashtable_free (struct t_hashtable *hashtable);
----

Paramètres :

* _hashtable_ : pointeur vers la table de hachage

Exemple en C :

[source,C]
----
weechat_hashtable_free (hashtable);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

[[configuration_files]]
=== Fichiers de configuration

Fonctions pour les fichiers de configuration.

==== config_new

_Mis à jour dans la 1.5._

Créer un nouveau fichier de configuration.

Prototype :

[source,C]
----
struct t_config_file *weechat_config_new (const char *name,
                                          int (*callback_reload)(const void *pointer,
                                                                 void *data,
                                                                 struct t_config_file *config_file),
                                          const void *callback_reload_pointer,
                                          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 et valeur de
  retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_config_file *config_file_ : pointeur vers le fichier de
   configuration
** valeur de retour :
*** _WEECHAT_CONFIG_READ_OK_
*** _WEECHAT_CONFIG_READ_MEMORY_ERROR_
*** _WEECHAT_CONFIG_READ_FILE_NOT_FOUND_
* _callback_reload_pointer_ : pointeur donné au "callback" de rechargement
  lorsqu'il est appelé par WeeChat
* _callback_reload_data_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le fichier de
  configuration est libéré

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 <<_config_write,config_write>>.
Vous ne devriez appeler cette fonction qu'après avoir créé les sections (avec
<<_config_new_section,config_new_section>>) et les options (avec
<<_config_new_option,config_new_option>>).

Exemple en C :

[source,C]
----
int
my_config_reload_cb (const void *pointer, 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, NULL);
----

Script (Python) :

[source,python]
----
# prototype
config_file = weechat.config_new(name, callback_reload, callback_reload_data)

# exemple
def my_config_reload_cb(data, config_file):
    # ...
    return weechat.WEECHAT_RC_OK

config_file = weechat.config_new("test", "my_config_reload_cb", "")
----

==== config_new_section

_Mis à jour dans la 1.5._

Créer 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)(const void *pointer,
                         void *data,
                         struct t_config_file *config_file,
                         struct t_config_section *section,
                         const char *option_name,
                         const char *value),
    const void *callback_read_pointer,
    void *callback_read_data,
    int (*callback_write)(const void *pointer,
                          void *data,
                          struct t_config_file *config_file,
                          const char *section_name),
    const void *callback_write_pointer,
    void *callback_write_data,
    int (*callback_write_default)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  const char *section_name),
    const void *callback_write_default_pointer,
    void *callback_write_default_data,
    int (*callback_create_option)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  const char *option_name,
                                  const char *value),
    const void *callback_create_option_pointer,
    void *callback_create_option_data,
    int (*callback_delete_option)(const void *pointer,
                                  void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  struct t_config_option *option),
    const void *callback_delete_option_pointer,
    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 et
  valeur de retour :
** _const void *pointer_ : pointeur
** _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
** valeur de retour :
*** _WEECHAT_CONFIG_READ_OK_
*** _WEECHAT_CONFIG_READ_MEMORY_ERROR_
*** _WEECHAT_CONFIG_READ_FILE_NOT_FOUND_
* _callback_read_pointer_ : pointeur donné au "callback" quand il est appelé
   par WeeChat
* _callback_read_data_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque la section est
  libérée
* _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 et valeur
  de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_config_file *config_file_ : pointeur vers le fichier de
   configuration
** _const char *section_name_ : nom de la section
** valeur de retour :
*** _WEECHAT_CONFIG_WRITE_OK_
*** _WEECHAT_CONFIG_WRITE_ERROR_
*** _WEECHAT_CONFIG_WRITE_MEMORY_ERROR_
* _callback_write_pointer_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat
* _callback_write_data_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque la section est
  libérée
* _callback_write_default_ : fonction appelée lorsque les valeurs par défaut
  doivent être écrites dans le fichier, paramètres et valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_config_file *config_file_ : pointeur vers le fichier de
   configuration
** _const char *section_name_ : nom de la section
** valeur de retour :
*** _WEECHAT_CONFIG_WRITE_OK_
*** _WEECHAT_CONFIG_WRITE_ERROR_
*** _WEECHAT_CONFIG_WRITE_MEMORY_ERROR_
* _callback_write_default_pointer_ : pointeur donné au "callback" lorsqu'il est
  appelé par WeeChat
* _callback_write_default_data_ : pointeur donné au "callback" lorsqu'il est
  appelé par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une
  fonction similaire) et est automatiquement libéré (par free) lorsque la
  section est libérée
* _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 et valeur de retour :
** _const void *pointer_ : pointeur
** _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_pointer_ : pointeur donné au "callback" lorsqu'il est
  appelé par WeeChat
* _callback_create_option_data_ : pointeur donné au "callback" lorsqu'il est
  appelé par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une
  fonction similaire) et est automatiquement libéré (par free) lorsque la
  section est libérée
* _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 et valeur de retour :
** _const void *pointer_ : pointeur
** _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
** valeur de retour :
*** _WEECHAT_CONFIG_OPTION_SET_OK_CHANGED_
*** _WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE_
*** _WEECHAT_CONFIG_OPTION_SET_ERROR_
*** _WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND_
* _callback_delete_option_pointer_ : pointeur donné au "callback" lorsqu'il est
  appelé par WeeChat
* _callback_delete_option_data_ : pointeur donné au "callback" lorsqu'il est
  appelé par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une
  fonction similaire) et est automatiquement libéré (par free) lorsque la
  section est libérée

Valeur de retour :

* pointeur vers la nouvelle section du fichier de configuration, NULL en cas
  d'erreur

Exemple en C :

[source,C]
----
int
my_section_read_cb (const void *pointer, void *data,
                    struct t_config_file *config_file,
                    struct t_config_section *section,
                    const char *option_name,
                    const char *value)
{
    /* ... */

    return WEECHAT_CONFIG_READ_OK;
    /* return WEECHAT_CONFIG_READ_MEMORY_ERROR; */
    /* return WEECHAT_CONFIG_READ_FILE_NOT_FOUND; */
}

int
my_section_write_cb (const void *pointer, void *data,
                     struct t_config_file *config_file,
                     const char *section_name)
{
    /* ... */

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
    /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */
}

int
my_section_write_default_cb (const void *pointer, void *data,
                             struct t_config_file *config_file,
                             const char *section_name)
{
    /* ... */

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
    /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */
}

int
my_section_create_option_cb (const void *pointer, void *data,
                             struct t_config_file *config_file,
                             struct t_config_section *section,
                             const char *option_name,
                             const char *value)
{
    /* ... */

    return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED;
    /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
    /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
}

int
my_section_delete_option_cb (const void *pointer, void *data,
                             struct t_config_file *config_file,
                             struct t_config_section *section,
                             struct t_config_option *option)
{
    /* ... */

    return WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED;
    /* return WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET; */
    /* return WEECHAT_CONFIG_OPTION_UNSET_OK_RESET; */
    /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */
}

/* 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, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL,
                                NULL, NULL, NULL);

/* 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,
                                &my_section_read_cb, NULL, NULL,
                                &my_section_write_cb, NULL, NULL,
                                &my_section_write_default_cb, NULL, NULL,
                                &my_section_create_option_cb, NULL, NULL,
                                &my_section_delete_option_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
section = weechat.config_new_section(config_file, name,
    user_can_add_options, user_can_delete_options,
    callback_read, callback_read_data,
    callback_write, callback_write_data,
    callback_create_option, callback_create_option_data,
    callback_delete_option, callback_delete_option_data)

# exemple
def my_section_read_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR

def my_section_write_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK

def my_section_write_default_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK

def my_section_create_option_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

def my_section_delete_option_cb(data, config_file, section, option):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED

section = weechat.config_new_section(config_file, "section1", 1, 1,
    "my_section_read_cb", "",
    "my_section_write_cb", "",
    "my_section_write_default_cb", "",
    "my_section_create_option_cb", "",
    "my_section_delete_option_cb", "")
----

==== config_search_section

Rechercher 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 en C :

[source,C]
----
struct t_config_section *section = weechat_config_search_section (config_file,
                                                                  "section");
----

Script (Python) :

[source,python]
----
# prototype
section = weechat.config_search_section(config_file, section_name)

# exemple
section = weechat.config_search_section(config_file, "section")
----

==== config_new_option

_Mis à jour dans la 1.5._

Créer 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)(const void *pointer,
                                void *data,
                                struct t_config_option *option,
                                const char *value),
    const void *callback_check_value_pointer,
    void *callback_check_value_data,
    void (*callback_change)(const void *pointer,
                            void *data,
                            struct t_config_option *option),
    const void *callback_change_pointer,
    void *callback_change_data,
    void (*callback_delete)(const void *pointer,
                            void *data,
                            struct t_config_option *option),
    const void *callback_delete_pointer,
    void *callback_delete_data);
----

Paramètres :

* _config_file_ : pointeur vers le fichier de configuration
* _section_ : pointeur vers la section
* _name_ : nom de l'option ; avec WeeChat ≥ 1.4, le nom peut inclure le nom
  d'une option parente (la valeur de l'option parente sera affichée dans la
  sortie de `/set` si cette option est "null"), la syntaxe est alors :
  "name << file.section.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 et valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_config_option *option_ : pointeur vers l'option
** _const char *value_ : nouvelle valeur pour l'option
** valeur de retour :
*** 1 si la valeur est ok
*** 0 si la valeur est invalide
* _callback_check_value_pointer_ : pointeur donné au "callback" lorsqu'il est
  appelé par WeeChat
* _callback_check_value_data_ : pointeur donné au "callback" lorsqu'il est
  appelé par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une
  fonction similaire) et est automatiquement libéré (par free) lorsque
  l'option est libérée
* _callback_change_ : fonction appelée lorsque la valeur de l'option a changé
  (optionnel), paramètres :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_config_option *option_ : pointeur vers l'option
* _callback_change_pointer_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat
* _callback_change_data_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque l'option est
  libérée
* _callback_delete_ : fonction appelée lorsque l'option est supprimée
  (optionnel), paramètres :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_config_option *option_ : pointeur vers l'option
* _callback_delete_pointer_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat
* _callback_delete_data_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque l'option est
  libérée

Valeur de retour :

* pointeur vers la nouvelle option de la section, NULL en cas d'erreur

Exemple en C :

[source,C]
----
/* booléen */
struct t_config_option *option1 =
    weechat_config_new_option (config_file, section, "option1", "boolean",
                               "Mon option, type booléen",
                               NULL,
                               0, 0,
                               "on",
                               "on",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* entier */
struct t_config_option *option2 =
    weechat_config_new_option (config_file, section, "option2", "integer",
                               "Mon option, type entier",
                               NULL,
                               0, 100,
                               "15",
                               "15",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* entier (avec valeurs sous forme de chaînes) */
struct t_config_option *option3 =
    weechat_config_new_option (config_file, section, "option3", "integer",
                               "Mon option, type entier "
                               "(avec valeurs sous forme de chaînes)",
                               "top|bottom|left|right",
                               0, 0,
                               "bottom",
                               "bottom",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* chaîne */
struct t_config_option *option4 =
    weechat_config_new_option (config_file, section, "option4", "string",
                               "Mon option, type chaîne",
                               NULL,
                               0, 0,
                               "test",
                               "test",
                               1,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* couleur */
struct t_config_option *option5 =
    weechat_config_new_option (config_file, section, "option5", "color",
                               "Mon option, type couleur",
                               NULL,
                               0, 0,
                               "lightblue",
                               "lightblue",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
option = weechat.config_new_option(config_file, section, name, type, description,
    string_values, min, max, default_value, value, null_value_allowed,
    callback_check_value, callback_check_value_data,
    callback_change, callback_change_data,
    callback_delete, callback_delete_data)

# exemple
def option4_check_value_cb(data, option, value):
    # ...
    return 1
    # return 0

def option4_change_cb(data, option):
    # ...

def option4_delete_cb(data, option):
    # ...

option1 = weechat.config_new_option(config_file, section, "option1", "boolean",
    "Mon option, type booléen",
    "", 0, 0, "on", "on", 0,
    "", "",
    "", "",
    "", "")

option2 = weechat.config_new_option(config_file, section, "option2", "integer",
    "Mon option, type entier",
    "", 0, 100, "15", "15", 0,
    "", "",
    "", "",
    "", "")

option3 = weechat.config_new_option(config_file, section, "option3", "integer",
    "Mon option, type entier (avec valeurs sous forme de chaînes)",
    "top|bottom|left|right",
    0, 0, "bottom", "bottom", 0,
    "", "",
    "", "",
    "", "")

option4 = weechat.config_new_option(config_file, section, "option4", "string",
    "Mon option, type chaîne",
    "", 0, 0, "test", "test", 1,
    "option4_check_value_cb", ""
    "option4_change_cb", "",
    "option4_delete_cb", "")

option5 = weechat.config_new_option(config_file, section, "option5", "color",
    "Mon option, type couleur",
    "", 0, 0, "lightblue", "lightblue", 0,
    "", "",
    "", "",
    "", "")
----

[NOTE]
En Ruby, les 3 "callbacks" + "data" (6 chaînes) doivent être données dans un
tableau de 6 chaînes de caractères (en raison d'une limitation de Ruby à 15
paramètres par fonction), voir le _Guide pour Scripts WeeChat_ pour plus d'infos
_(corrigé dans la version 0.4.1)_.

==== config_search_option

Rechercher 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 en C :

[source,C]
----
struct t_config_option *option =
    weechat_config_search_option (config_file, section, "option");
----

Script (Python) :

[source,python]
----
# prototype
option = weechat.config_search_option(config_file, section, option_name)

# exemple
option = weechat.config_search_option(config_file, section, "option")
----

==== config_search_section_option

Rechercher une section et une option dans un fichier de configuration ou une
section.

Prototype :

[source,C]
----
void weechat_config_search_section_option (struct t_config_file *config_file,
                                           struct t_config_section *section,
                                           const char *option_name,
                                           struct t_config_section **section_found,
                                           struct t_config_option **option_found);
----

Paramètres :

* _config_file_ : pointeur vers le fichier de configuration
* _section_ : pointeur vers la section
* _option_name_ : nom de l'option
* _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 en C :

[source,C]
----
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;

weechat_config_search_section_option (config_file,
                                      section,
                                      "option",
                                      &ptr_section,
                                      &ptr_option);
if (ptr_option)
{
    /* option trouvée */
}
else
{
    /* option non trouvée */
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== config_search_with_string

Retourner des infos sur fichier/section/option pour 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,
                                        char **pos_option_name);
----

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
* _pos_option_name_ : pointeur vers un pointeur sur une chaîne, sera alimenté
  avec le pointeur vers le nom de l'option trouvée

Exemple en C :

[source,C]
----
struct t_config_file *ptr_config_file;
struct t_config_section *ptr_section;
struct t_config_option *ptr_option;
char *option_name;

weechat_config_search_with_string ("fichier.section.option",
                                   &ptr_config_file,
                                   &ptr_section,
                                   &ptr_option,
                                   &option_name);
if (ptr_option)
{
    /* option trouvée */
}
else
{
    /* option non trouvée */
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== config_string_to_boolean

Vérifier 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 en C :

[source,C]
----
if (weechat_config_string_to_boolean (option_value))
{
    /* la valeur est "vrai" */
}
else
{
    /* la valeur est "faux" */
}
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_string_to_boolean(text)

# exemple
if weechat.config_string_to_boolean(text):
    # ...
----

==== config_option_reset

Réinitialiser 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 en C :

[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;
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.config_option_reset(option, run_callback)

# exemple
rc = weechat.config_option_reset(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----

==== 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 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 en C :

[source,C]
----
switch (weechat_config_option_set (option, "nouvelle_valeur", 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;
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.config_option_set(option, value, run_callback)

# exemple
rc = weechat.config_option_set(option, "nouvelle_valeur", 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----

==== 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 <<_config_new_option,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 en C :

[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;
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.config_option_set_null(option, run_callback)

# exemple
rc = weechat.config_option_set_null(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----

==== 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 en C :

[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;
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.config_option_unset(option)

# exemple
rc = weechat.config_option_unset(option)
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...
----

==== config_option_rename

Renommer 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 en C :

[source,C]
----
weechat_config_option_rename (option, "nouveau_nom");
----

Script (Python) :

[source,python]
----
# prototype
weechat.config_option_rename(option, new_name)

# exemple
weechat.config_option_rename(option, "nouveau_nom")
----

==== config_option_get_pointer

Retourner 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 *_)
** _parent_name_ : nom de l'option parente (_char *_) _(WeeChat ≥ 1.4)_
** _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 en C :

[source,C]
----
char *description = weechat_config_option_get_pointer (option, "description");
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== config_option_is_null

Vérifier 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 en C :

[source,C]
----
if (weechat_config_option_is_null (option))
{
    /* la valeur est "null" */
}
else
{
    /* la valeur n'est pas "null" */
}
----

Script (Python) :

[source,python]
----
# prototype
is_null = weechat.config_option_is_null(option)

# exemple
if weechat.config_option_is_null(option):
    # ...
----

==== config_option_default_is_null

Vérifier si la valeur par défaut d'une option est "null" (valeur non définie).

Prototype :

[source,C]
----
int weechat_config_option_default_is_null (struct t_config_option *option);
----

Paramètres :

* _option_ : pointeur vers l'option

Valeur de retour :

* 1 si la valeur par défaut de l'option est "null"
* 0 si la valeur par défaut de l'option n'est pas "null"

Exemple en C :

[source,C]
----
if (weechat_config_option_default_is_null (option))
{
    /* la valeur par défaut est "null" */
}
else
{
    /* la valeur par défaut n'est pas "null" */
}
----

Script (Python) :

[source,python]
----
# prototype
is_null = weechat.config_option_default_is_null(option)

# exemple
if weechat.config_option_default_is_null(option):
    # ...
----

==== config_boolean

Retourner 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, selon le type de l'option :

* _boolean_ : valeur booléenne de l'option (0 ou 1)
* _integer_ : 0
* _string_ : 0
* _color_ : 0

Exemple en C :

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean (option))
{
    /* la valeur est "vrai" */
}
else
{
    /* la valeur est "faux" */
}
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_boolean(option)

# exemple
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean(option):
    # ...
----

==== config_boolean_default

Retourner 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, selon le type de l'option :

* _boolean_ : valeur booléenne par défaut de l'option (0 ou 1)
* _integer_ : 0
* _string_ : 0
* _color_ : 0

Exemple en C :

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
if (weechat_config_boolean_default (option))
{
    /* la valeur est "vrai" */
}
else
{
    /* la valeur est "faux" */
}
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_boolean_default(option)

# exemple
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean_default(option):
    # ...
----

==== config_integer

Retourner 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, selon le type de l'option :

* _boolean_ : valeur booléenne de l'option (0 ou 1)
* _integer_ : valeur entière de l'option
* _string_ : 0
* _color_ : index de la couleur

Exemple en C :

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer (option);
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_integer(option)

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer(option)
----

==== config_integer_default

Retourner 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, selon le type de l'option :

* _boolean_ : valeur booléenne par défaut de l'option (0 ou 1)
* _integer_ : valeur entière par défaut de l'option
* _string_ : 0
* _color_ : index de la couleur par défaut

Exemple en C :

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer_default (option);
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_integer_default(option)

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer_default(option)
----

==== config_string

Retourner 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, selon le type de l'option :

* _boolean_ : "on" si la valeur est vraie, sinon "off"
* _integer_ : valeur de l'option sous forme de chaîne si l'option est un entier
  avec des valeurs sous forme de chaînes, sinon NULL
* _string_ : valeur de l'option sous forme de chaîne
* _color_ : nom de la couleur

Exemple en C :

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string (option);
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_string(option)

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_string(option)
----

==== config_string_default

Retourner la valeur par défaut de l'option, sous forme de chaîne.

Prototype :

[source,C]
----
const char *weechat_config_string_default (struct t_config_option *option);
----

Paramètres :

* _option_ : pointeur vers l'option

Valeur de retour, selon le type de l'option :

* _boolean_ : "on" si la valeur par défaut est vraie, sinon "off"
* _integer_ : valeur par défaut de l'option sous forme de chaîne si l'option
  est un entier avec des valeurs sous forme de chaînes, sinon NULL
* _string_ : valeur par défaut de l'option sous forme de chaîne
* _color_ : nom de la couleur par défaut

Exemple en C :

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string_default (option);
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_string_default(option)

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_string_default(option)
----

==== config_color

Retourner 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, selon le type de l'option :

* _boolean_ : NULL
* _integer_ : NULL
* _string_ : NULL
* _color_ : nom de la couleur

Exemple en C :

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color (option);
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_color(option)

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_color(option)
----

==== config_color_default

Retourner 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, selon le type de l'option :

* _boolean_ : NULL
* _integer_ : NULL
* _string_ : NULL
* _color_ : nom de la couleur par défaut

Exemple en C :

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color_default (option);
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_color_default(option)

# exemple
option = weechat.config_get("plugin.section.option")
value = weechat.config_color_default(option)
----

==== config_write_option

Écrire 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 en C :

[source,C]
----
int
my_section_write_cb (const void *pointer, 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;
}
----

Script (Python) :

[source,python]
----
# prototype
weechat.config_write_option(config_file, option)

# exemple
def my_section_write_cb(data, config_file, section_name):
    weechat.config_write_line(config_file, "ma_section", "")
    weechat.config_write_option(config_file, option)
    return weechat.WEECHAT_RC_OK
----

==== config_write_line

Écrire 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 exemple : "[section]")

Exemple en C :

[source,C]
----
int
my_section_write_cb (const void *pointer, 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",
                               "valeur", 123);

    return WEECHAT_RC_OK;
}
----

Script (Python) :

[source,python]
----
# prototype
weechat.config_write_line(config_file, option_name, value)

# exemple
def my_section_write_cb(data, config_file, section_name):
    weechat.config_write_line(config_file, "ma_section", "")
    weechat.config_write_line(config_file, "option", "valeur")
    return weechat.WEECHAT_RC_OK
----

==== config_write

Écrire 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 en C :

[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;
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.config_write(config_file)

# exemple
rc = weechat.config_write(config_file)
if rc == weechat.WEECHAT_CONFIG_WRITE_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_ERROR:
    # ...
----

==== config_read

Lire 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 en C :

[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;
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.config_read(config_file)

# exemple
rc = weechat.config_read(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...
----

==== config_reload

Relire 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 en C :

[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;
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.config_reload(config_file)

# exemple
rc = weechat.config_reload(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...
----

==== config_option_free

Supprimer une option.

Prototype :

[source,C]
----
void weechat_config_option_free (struct t_config_option *option);
----

Paramètres :

* _option_ : pointeur vers l'option

Exemple en C :

[source,C]
----
weechat_config_option_free (option);
----

Script (Python) :

[source,python]
----
# prototype
weechat.config_option_free(option)

# exemple
weechat.config_option_free(option)
----

==== config_section_free_options

Supprimer 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 en C :

[source,C]
----
weechat_config_section_free_options (section);
----

Script (Python) :

[source,python]
----
# prototype
weechat.config_section_free_options(section)

# exemple
weechat.config_section_free_options(section)
----

==== config_section_free

Supprimer une section.

Prototype :

[source,C]
----
void weechat_config_section_free (struct t_config_section *section);
----

Paramètres :

* _section_ : pointeur vers la section

Exemple en C :

[source,C]
----
weechat_config_section_free (section);
----

Script (Python) :

[source,python]
----
# prototype
weechat.config_section_free(section)

# exemple
weechat.config_section_free(section)
----

==== config_free

Supprimer 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 en C :

[source,C]
----
weechat_config_free (config_file);
----

Script (Python) :

[source,python]
----
# prototype
weechat.config_free(config_file)

# exemple
weechat.config_free(config_file)
----

==== config_get

Rechercher 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 en C :

[source,C]
----
struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");
----

Script (Python) :

[source,python]
----
# prototype
option = weechat.config_get(option_name)

# exemple
option = weechat.config_get("weechat.look.item_time_format")
----

==== config_get_plugin

Rechercher 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 en C :

[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");
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_get_plugin(option_name)

# exemple
value = weechat.config_get_plugin("option")
----

==== config_is_set_plugin

Vérifier 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 en C :

[source,C]
----
if (weechat_config_is_set_plugin ("option"))
{
    /* l'option existe */
}
else
{
    /* l'option n'existe pas */
}
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.config_is_set_plugin(option_name)

# exemple
if weechat.config_is_set_plugin("option"):
    # l'option existe
    # ...
else:
    # l'option n'existe pas
    # ...
----

==== 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 en C :

[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;
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.config_set_plugin(option_name, value)

# exemple
rc = weechat.config_set_plugin("option", "valeur_test")
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----

==== config_set_desc_plugin

_WeeChat ≥ 0.3.5._

Affecter une description pour une option dans le fichier de configuration des
extensions (plugins.conf).

Prototype :

[source,C]
----
void weechat_config_set_desc_plugin (const char *option_name,
                                     const char *description);
----

Paramètres :

* _option_name_ : nom de l'option, WeeChat ajoutera le préfixe
  "plugins.desc.xxx." (où "xxx" est le nom de l'extension courante)
* _description_ : description pour l'option

[NOTE]
Ce n'est pas un problème si l'option (plugins.var.xxx.option_name) n'existe pas.
Une création future de cette option utilisera cette description.

Exemple en C :

[source,C]
----
weechat_config_set_desc_plugin ("option", "description de l'option");
----

Script (Python) :

[source,python]
----
# prototype
weechat.config_set_desc_plugin(option_name, description)

# exemple
version = weechat.info_get("version_number", "") or 0
if int(version) >= 0x00030500:
    weechat.config_set_desc_plugin("option", "description de l'option")
----

==== config_unset_plugin

Supprimer 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 en C :

[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;
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.config_unset_plugin(option_name)

# exemple
rc = weechat.config_unset_plugin("option")
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...
----

[[key_bindings]]
=== Associations de touches

Fonctions pour les associations de touches.

==== key_bind

_WeeChat ≥ 0.3.6._

Ajouter de nouvelles associations de touches.

[NOTE]
Contrairement à la commande `/key bind`, cette fonction ne changera jamais
une association de touche existante, seulement des nouvelles touches seront
créées. Pour supprimer une association de touche, utilisez <<_key_unbind,key_unbind>>.

Prototype :

[source,C]
----
int weechat_key_bind (const char *context, struct t_hashtable *keys);
----

Paramètres :

* _context_ : contexte pour les touches :
** _default_ : contexte par défaut (actions courantes)
** _search_ : contexte de recherche (lors de la recherche de texte dans le
   tampon)
** _cursor_ : mouvement libre du curseur à l'écran
** _mouse_ : touches pour les évènements de souris
* _keys_ : table de hachage avec les associations de touches

Valeur de retour :

* nombre d'associations de touches ajoutées

Exemple en C :

[source,C]
----
struct t_hashtable *keys = weechat_hashtable_new (8,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  WEECHAT_HASHTABLE_STRING,
                                                  NULL,
                                                  NULL);
if (keys)
{
    weechat_hashtable_set (keys, "@chat(plugin.buffer):button1", "hsignal:test_mouse");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheelup", "/mycommand up");
    weechat_hashtable_set (keys, "@chat(plugin.buffer):wheeldown", "/mycommand down");
    weechat_key_bind ("mouse", keys);
    weechat_hashtable_free (keys);
}
----

Script (Python) :

[source,python]
----
# prototype
num_keys = weechat.key_bind(context, keys)

# exemple
keys = {"@chat(python.test):button1": "hsignal:test_mouse",
        "@chat(python.test):wheelup": "/mycommand up",
        "@chat(python.test):wheeldown": "/mycommand down"}
weechat.key_bind("mouse", keys)
----

==== key_unbind

_WeeChat ≥ 0.3.6._

Supprimer une/des association(s) de touche(s).

[WARNING]
Lors de l'appel à cette fonction, assurez-vous que vous n'allez pas supprimer
une touche définie par l'utilisateur.

Prototype :

[source,C]
----
int weechat_key_unbind (const char *context, const char *key);
----

Paramètres :

* _context_ : contexte pour les touches (voir <<_key_bind,key_bind>>)
* _key_ : touche à supprimer ou la valeur spéciale "area:XXX" pour supprimer
  toutes les touches ayant _XXX_ comme première ou deuxième zone

Valeur de retour :

* nombre d'associations de touches supprimées

Exemples en C :

[source,C]
----
/* supprimer une seule touche */
weechat_key_unbind ("mouse", "@chat(plugin.buffer):button1");

/* supprimer toutes les touches avec la zone "chat(plugin.buffer)" */
weechat_key_unbind ("mouse", "area:chat(plugin.buffer)");
----

Script (Python) :

[source,python]
----
# prototype
num_keys = weechat.key_unbind(context, key)

# exemples

# supprimer une seule touche
weechat.key_unbind("mouse", "@chat(plugin.buffer):button1")

# supprimer toutes les touches avec la zone "chat(python.test)"
weechat.key_unbind("mouse", "area:chat(python.test)")
----

[[display]]
=== Affichage

Fonctions pour afficher du texte dans les tampons.

==== prefix

Retourner un préfixe.

Prototype :

[source,C]
----
const char *weechat_prefix (const char *prefix);
----

Paramètres :

* _prefix_ : nom du préfixe (voir le tableau ci-dessous)

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é

Liste des préfixes :

[width="70%",cols="^2m,^1,^3,5",options="header"]
|===
| Préfixe | Valeur   | Couleur                   | Description
| error   | `+=!=+`  | jaune ("yellow")          | Message d'erreur
| network | `+--+`   | violet ("magenta")        | Message du réseau
| action  | `+*+`    | blanc ("white")           | Action personnelle
| join    | `+-->+`  | vert clair ("lightgreen") | Quelqu'un a rejoint la discussion
| quit    | `+<--+`  | rouge clair ("lightred")  | Quelqu'un a quitté la discussion
|===

[NOTE]
Les valeurs et couleurs peuvent être configurées avec la commande `/set`.

Exemple en C :

[source,C]
----
weechat_printf (NULL, "%sCeci est une erreur...", weechat_prefix ("error"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.prefix(prefix)

# exemple
weechat.prnt("", "%sCeci est une erreur..." % weechat.prefix("error"))
----

==== color

Retourner 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 :
** le nom d'une option de couleur WeeChat (de weechat.color.xxx), par exemple
  _chat_delimiters_
** le nom d'une option (format : fichier.section.option), par exemple
   _irc.color.message_quit_ (_WeeChat ≥ 1.2_)
** une couleur avec des attributs/fond optionnels (voir ci-dessous)
** 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é
*** _emphasis_ : activer/désactiver la mise en valeur du texte (note : cela ne
    devrait être utilisé que dans les barres, car WeeChat utilise la mise en
    valeur du texte lors de la recherche de texte dans le tampon)
    _(WeeChat ≥ 0.4.2)_
** 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
** réinitialisation :
*** _reset_ : réinitialiser la couleur et les attributs
*** _resetcolor_ : réinitialiser la couleur (garder les attributs)
    _(WeeChat ≥ 0.3.6)_

Le format de la couleur est : attributs (optionnel) + nom de couleur + ",fond"
(optionnel). Les attributs possibles sont :

* `+*+` : texte gras
* `+!+` : mode vidéo inverse
* `+/+` : italique
* `+_+` : texte souligné
* `+|+` : garder les attributs : ne pas réinitialiser
  gras/inverse/italique/souligné lors du changement de couleur
  _(WeeChat ≥ 0.3.6)_

Exemples :

* `+yellow+` : jaune
* `+_green+` : vert souligné
* `+*214+` : orange gras
* `+yellow,red+` : jaune sur rouge
* `+|cyan+` : cyan (et garder tout attribut définit précédemment)

Valeur de retour :

* chaîne avec le code couleur, ou une chaîne vide si la couleur n'a pas été
  trouvée

Exemple en C :

[source,C]
----
weechat_printf (NULL, "Couleur : %sbleu %scouleur par défaut %sjaune sur rouge",
                weechat_color ("blue"),
                weechat_color ("chat"),
                weechat_color ("yellow,red"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.color(color_name)

# exemple
weechat.prnt("", "Couleur : %sbleu %scouleur par défaut %sjaune sur rouge"
    % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))
----

==== printf

Afficher un message sur un tampon.

Prototype :

[source,C]
----
void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);
----

Cette fonction est un raccourci vers la fonction printf_date_tags. Ces deux appels
donnent exactement le même résultat :

[source,C]
----
weechat_printf (buffer, "message");
weechat_printf_date_tags (buffer, 0, NULL, "message");
----

Paramètres :

* _buffer_ : pointeur vers le tampon, si NULL, le message est affiché sur le
  tampon WeeChat
* _message_ : message à afficher

[NOTE]
La première tabulation dans le message ("\t") est utilisée pour séparer le
préfixe du message. +
Si votre message contient des tabulations et si vous ne voulez pas de préfixe,
utilisez un espace, une tabulation, puis le message : cela désactivera le
préfixe (l'espace avant la tabulation ne sera pas affiché).

[NOTE]
Avec deux tabulations ("\t") au début du message, l'heure ne sera pas affichée
et le message n'aura pas d'alignement. De plus, la date dans le message sera
positionnée à 0.

Exemple en C :

[source,C]
----
weechat_printf (NULL, "Bonjour sur le tampon WeeChat");
weechat_printf (buffer, "Bonjour sur ce tampon");
weechat_printf (buffer, "%sCeci est une erreur !", weechat_prefix ("error"));
weechat_printf (buffer, " \tMessage sans préfixe mais avec \t quelques \t tabulations");
weechat_printf (buffer, "\t\tMessage sans heure/alignement");
weechat_printf (buffer, "\t\t");  /* ligne vide (sans heure) */
----

Script (Python) :

[source,python]
----
# prototype
weechat.prnt(buffer, message)

# exemple
weechat.prnt("", "Bonjour sur le tampon WeeChat")
weechat.prnt(buffer, "Bonjour sur ce tampon")
weechat.prnt(buffer, "%sCeci est une erreur !" % weechat.prefix("error"))
weechat.prnt(buffer, " \tMessage sans préfixe mais avec \t quelques \t tabulations")
weechat.prnt(buffer, "\t\tMessage sans heure/alignement")
weechat.prnt(buffer, "\t\t")  # ligne vide (sans heure)
----

[NOTE]
La fonction s'appelle "print" dans les scripts ("prnt" en Python).

==== printf_date_tags

Afficher un message sur un tampon, en utilisant une date et des étiquettes
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 (0 signifie la date/heure courante)
* _tags_ : liste d'étiquettes séparées par des virgules (NULL signifie aucune
  étiquette)
* _message_ : message à afficher

Tags couramment utilisés (liste non exhaustive) :

[width="70%",cols="^1,4",options="header"]
|===
| Tag              | Description
| no_filter        | La ligne ne peut pas être filtrée
| no_highlight     | Aucun highlight n'est possible sur cette ligne
| no_log           | La ligne n'est pas écrite dans le fichier de log
| log0 ... log9    | Niveau de log pour la ligne (voir `/help logger`)
| notify_none      | Le tampon avec la ligne ne sera pas ajouté à la "hotlist"
| notify_message   | Le tampon avec la ligne sera ajouté à la "hotlist" avec le niveau "message"
| notify_private   | Le tampon avec la ligne sera ajouté à la "hotlist" avec le niveau "private"
| notify_highlight | Le tampon avec la ligne sera ajouté à la "hotlist" avec le niveau "highlight"
| nick_xxx         | Le message vient du pseudo "xxx"
| prefix_nick_ccc  | Le préfixe est un pseudo avec la couleur "ccc"
| host_xxx         | Nom d'utilisateur et hôte dans le message
| irc_xxx          | Message IRC "xxx" (peut-être une commande ou un numérique sur 3 chiffres)
| irc_numeric      | Message IRC numérique
| irc_error        | Erreur du serveur IRC
| irc_action       | Action d'un pseudo (commande `/me`)
| irc_ctcp         | Message CTCP
| irc_ctcp_reply   | Réponse à un message CTCP
| irc_smart_filter | Message IRC qui peut être filtré avec le "smart filter" (filtre intelligent)
| away_info        | Message avec une info d'absence
|===

Exemple en C :

[source,C]
----
weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
                          "Message il y a 2 minutes avec une étiquette 'notify_message'");
----

Script (Python) :

[source,python]
----
# prototype
weechat.prnt_date_tags(buffer, date, tags, message)

# exemple
time = int(time.time())
weechat.prnt_date_tags("", time - 120, "notify_message",
    "Message il y a 2 minutes avec une étiquette 'notify_message'")
----

[NOTE]
La fonction s'appelle "print_date_tags" dans les scripts ("prnt_date_tags" en
Python).

==== printf_y

Afficher 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); une valeur négative affiche
  une ligne après la dernière ligne affichée : la valeur absolue de _y_ est le
  nombre de lignes après la dernière ligne (par exemple -1 est immédiatement
  après la dernière ligne, -2 est 2 lignes après la dernière ligne)
  _(WeeChat ≥ 1.0)_
* _message_ : message à afficher

Exemple en C :

[source,C]
----
weechat_printf_y (buffer, 2, "Mon message sur la 3ème ligne");
----

Script (Python) :

[source,python]
----
# prototype
weechat.prnt_y(buffer, y, message)

# exemple
weechat.prnt_y("", 2, "Mon message sur la 3ème ligne")
----

[NOTE]
La fonction s'appelle "print_y" dans les scripts ("prnt_y" en Python).

==== log_printf

Écrire 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 en C :

[source,C]
----
weechat_log_printf ("Mon message dans le fichier log");
----

Script (Python) :

[source,python]
----
# prototype
weechat.log_print(message)

# exemple
weechat.log_print("Mon message dans le fichier log")
----

[NOTE]
La fonction s'appelle "log_print" dans les scripts.

[[hooks]]
=== Hooks

[[hook_priority]]
[float]
==== Priorité de hook

_WeeChat ≥ 0.3.4._

Pour certains "hooks", vous pouvez définir une priorité. Un "hook" avec une
priorité plus élevée sera au début de la liste des "hooks", et donc il sera
trouvé et exécuté avant les autres "hooks". Cela est pratique pour les
modificateurs, car l'ordre d'exécution est important.

Pour définir une priorité, vous devez utiliser cette syntaxe, pour un paramètre
où la priorité est autorisée : "nnn|nom" où "nnn" est un entier positif ou nul
avec la priorité et "nom" le nom pour le paramètre (la priorité n'apparaît pas
dans le nom, elle est automatiquement retirée de la chaîne).

La priorité par défaut est 1000.

Exemple en C :

[source,C]
----
/* accroche un modificateur avec priorité = 2000 */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL, NULL);
----

Les types de "hooks" suivants autorisent une priorité : command, command_run,
signal, hsignal, config, completion, modifier, info, info_hashtable, infolist,
hdata, focus.

==== hook_command

_Mis à jour dans la 1.5._

Accrocher 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)(const void *pointer,
                                                     void *data,
                                                     struct t_gui_buffer *buffer,
                                                     int argc,
                                                     char **argv,
                                                     char **argv_eol),
                                     const void *callback_pointer,
                                     void *callback_data);
----

Paramètres :

* _command_ : nom de la commande
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
* _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èle 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
  `+||+`.
* _callback_ : fonction appelée lorsque la commande est utilisée, paramètres et
  valeur de retour :
** _const void *pointer_ : pointeur
** _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)
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Les codes complétions par défaut sont :

include::autogen/plugin_api/completions.adoc[]

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

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
int
my_command_cb (const void *pointer, 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 ("monfiltre",
                          "description de monfiltre",
                          "[list] | [enable|disable|toggle [nom]] | "
                          "[add nom extension.tampon tags regex] | "
                          "[del nom|-all]",
                          "description des paramètres...",
                          "list"
                          " || enable %(filters_names)"
                          " || disable %(filters_names)"
                          " || toggle %(filters_names)"
                          " || add %(filters_names) %(buffers_plugins_names)|*"
                          " || del %(filters_names)|-all",
                          &my_command_cb, NULL, NULL);
----

Par exemple, si la commande appelée est `/command abc def ghi`, alors _argv_ et
_argv_eol_ ont les valeurs suivantes :

* _argv_ :
** _argv[0]_ == "/command"
** _argv[1]_ == "abc"
** _argv[2]_ == "def"
** _argv[3]_ == "ghi"
* _argv_eol_ :
** _argv_eol[0]_ == "/command abc def ghi"
** _argv_eol[1]_ == "abc def ghi"
** _argv_eol[2]_ == "def ghi"
** _argv_eol[3]_ == "ghi"

Pour les scripts, _args_ a la valeur "abc def ghi".

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_command(command, description, args, args_description,
    completion, callback, callback_data)

# exemple
def my_command_cb(data, buffer, args):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_command("monfiltre", "description de monfiltre",
    "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]",
    "description des paramètres...",
    "list"
    " || enable %(filters_names)"
    " || disable %(filters_names)"
    " || toggle %(filters_names)"
    " || add %(filters_names) %(buffers_plugins_names)|*"
    " || del %(filters_names)|-all",
    "my_command_cb", "")
----

==== hook_command_run

_Mis à jour dans la 1.5._

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)(const void *pointer,
                                                         void *data,
                                                         struct t_gui_buffer *buffer,
                                                         const char *command),
                                         const void *callback_pointer,
                                         void *callback_data);
----

Paramètres :

* _command_ : commande à intercepter (le caractère joker `+*+` est autorisé)
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
* _callback_ : fonction appelée lorsque la commande est exécutée, paramètres et
  valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_gui_buffer *buffer_ : tampon où la commande est exécutée
** _const char *command_ : la commande exécutée, avec ses paramètres
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_OK_EAT_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

[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 en C :

[source,C]
----
int
my_command_run_cb (const void *pointer, void *data,
                   struct t_gui_buffer *buffer, const char *command)
{
    weechat_printf (NULL, "Je mange la complétion !");
    return WEECHAT_RC_OK_EAT;
}

struct t_hook *my_command_run_hook =
    weechat_hook_command_run ("/input complete*",
                              &my_command_run_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_command_run(command, callback, callback_data)

# exemple
def my_command_run_cb(data, buffer, command):
    weechat.prnt("", "Je mange la complétion !")
    return weechat.WEECHAT_RC_OK_EAT

hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")
----

==== hook_timer

_Mis à jour dans la 1.5._

Accrocher un minuteur (fonction appelée à intervalles réguliers).

Prototype :

[source,C]
----
struct t_hook *weechat_hook_timer (long interval,
                                   int align_second,
                                   int max_calls,
                                   int (*callback)(const void *pointer,
                                                   void *data,
                                                   int remaining_calls),
                                   const void *callback_pointer,
                                   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 minuteur sera appelé chaque minute quand la seconde sera 0
* _max_calls_ : nombre maximum d'appels au minuteur (si 0, le minuteur n'a pas
  de fin)
* _callback_ : fonction appelée quand le délai est atteint, paramètres et valeur
  de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _int remaining_calls_ : nombre d'appels restants (-1 si le minuteur n'a pas
   de fin)
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
int
my_timer_cb (const void *pointer, void *data, int remaining_calls)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* minuteur appelé toutes les 20 secondes */
struct t_hook *my_timer_hook =
    weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_timer(interval, align_second, max_calls, callback, callback_data)

# exemple
def my_timer_cb(data, remaining_calls):
    # ...
    return weechat.WEECHAT_RC_OK

# minuteur appelé toutes les 20 secondes
hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")
----

==== hook_fd

_Mis à jour dans la 1.3, 1.5._

Accrocher 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)(const void *pointer,
                                                void *data,
                                                int fd),
                                const void *callback_pointer,
                                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'écriture, 0 = ignorer
* _flag_exception_ : 1 = intercepter un évènement d'exception, 0 = ignorer
  (_WeeChat ≥ 1.3_ : ce paramètre est ignoré et n'est plus utilisé)
* _callback_ : fonction appelée lorsqu'un des évènements sélectionnés se
  produit pour le fichier (ou le socket), paramètres et valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _int fd_ : descripteur de fichier
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
int
my_fd_cb (const void *pointer, void *data, int fd)
{
    /* ... */
    return WEECHAT_RC_OK;
}

int sock = socket (AF_INET, SOCK_STREAM, 0);
/* définir les options du socket */
/* ... */
struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_fd(fd, flag_read, flag_write, flag_exception, callback, callback_data)

# exemple
def my_fd_cb(data, fd):
    # ...
    return weechat.WEECHAT_RC_OK

sock = ...
hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")
----

==== hook_process

_Mis à jour dans la 1.5._

Accrocher un processus (lancé par un fork), et intercepter sa sortie.

[NOTE]
Depuis la version 0.3.9.2, le shell n'est plus utilisé pour exécuter la
commande. WeeChat effectue un découpage automatique de la commande et de ses
paramètres (comme le fait le shell). +
Si le découpage n'est pas correct (selon les guillemets utilisés dans votre
commande), ou si vous souhaitez utiliser le shell, vous pouvez utiliser la
fonction <<_hook_process_hashtable,hook_process_hashtable>> avec
les paramètres dans la table de hachage _options_ _(WeeChat ≥ 0.4.0)_.

Prototype :

[source,C]
----
struct t_hook *weechat_hook_process (const char *command,
                                     int timeout,
                                     int (*callback)(const void *pointer,
                                                     void *data,
                                                     const char *command,
                                                     int return_code,
                                                     const char *out,
                                                     const char *err),
                                     const void *callback_pointer,
                                     void *callback_data);
----


Paramètres :

* _command_ : commande à lancer dans le processus fils, URL _(WeeChat ≥ 0.3.7)_
  ou fonction _(WeeChat ≥ 1.5)_ (voir ci-dessous)
* _timeout_ : timeout pour la commande (en millisecondes) : après ce délai, le
  processus fils est tué (0 signifie pas de limite)
* _callback_ : fonction appelée quand des données du fils sont disponibles, or
  ou quand le fils s'est terminé, paramètres et valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _const char *command_ : commande exécutée par le fils
** _int return_code_ : code retour :
*** _>= 0_ : code retour du fils pour une commande, et pour l'URL, les valeurs
    possibles sont :
**** _0_ : transfert ok
**** _1_ : URL invalide
**** _2_ : erreur de transfert
**** _3_ : pas assez de mémoire
**** _4_ : erreur avec un fichier
*** _< 0_ :
**** _WEECHAT_HOOK_PROCESS_RUNNING_ : données disponibles, mais le fils tourne
     toujours
**** _WEECHAT_HOOK_PROCESS_ERROR_ : erreur en lançant la commande
**** _WEECHAT_HOOK_PROCESS_CHILD_: le "callback" est appelé dans le processus
     fils
** _out_ : sortie standard de la commande (stdout)
** _err_ : erreurs de la commande (stderr)
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
*** code retour du processus fils (dans le cas d'une fonction avec "func:" dans
    la commande)
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Lorsque la commande est terminée, ou si le timeout est atteint, WeeChat
supprimera automatiquement le "hook" (et tuera le processus s'il tourne
toujours).

La commande peut être une URL avec le format : "url:http://www.example.com",
pour télécharger le contenu de l'URL _(WeeChat ≥ 0.3.7)_.
Des options pour l'URL sont possibles avec la fonction
<<_hook_process_hashtable,hook_process_hashtable>>.

La commande peut aussi être le nom d'une fonction avec le format : "func:nom",
pour exécuter la fonction "nom" _(WeeChat ≥ 1.5)_. Cette fonction reçoit un
paramètre (_data_) et doit retourner une chaîne de caractères, qui sera envoyée
au "callback". +
Dans l'API C, le "callback" est appelé avec le code retour qui vaut
_WEECHAT_HOOK_PROCESS_CHILD_, cela signifie que le "callback" tourne dans le
processus fils (après le fork). +
Dans l'API script, la fonction _nom_ est appelée directement et le résultat
(chaîne de caractères) est envoyé au "callback" (comme la sortie d'une commande
externe).

[TIP]
Si vous souhaitez récupérer des infos à propos de WeeChat (comme la version
stable actuelle, le dernier commit git, etc...), vous pouvez utiliser les URLs
sur la page https://weechat.org/dev/info

[NOTE]
La taille du tampon pour l'envoi des données au "callback" est de 64 Ko (il y a
2 tampons : un pour stdout et un pour stderr).
Si la sortie du processus fils (stdout ou stderr) est plus longue que 64 Ko, le
"callback" sera appelé plusieurs fois.

[IMPORTANT]
Même si la plupart du temps le "callback" n'est appelé qu'une seule fois, vous
devez vous assurer que plusieurs appels au "callback" sont ok dans votre code :
vous devez concaténer les données issues de plusieurs appels et n'utiliser les
données que lorsque le code retour est positif ou nul.

Exemple en C :

[source,C]
----
/* exemple avec une commande externe */
int
my_process_cb (const void *pointer, 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 WEECHAT_RC_OK;
    }

    if (return_code >= 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 *my_process_hook = weechat_hook_process ("ls", 5000,
                                                       &my_process_cb, NULL, NULL);

/* exemple avec le "callback" appelé dans le processus fils */
int
my_process_cb (const void *pointer, void *data, const char *command,
               int return_code, const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_CHILD)
    {
        /* faire quelque chose de bloquant... */
        /* ... */

        /* la sortie "stdout" sera envoyée comme "out" au "callback" parent */
        printf ("ceci est le résultat");

        /* code retour du processus */
        return 0;
    }
    else
    {
        if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
        {
            weechat_printf (NULL, "Erreur avec la commande '%s'", command);
            return WEECHAT_RC_OK;
        }

        if (return_code >= 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 *my_process_hook = weechat_hook_process ("func:get_status", 5000,
                                                       &my_process_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_process(command, timeout, callback, callback_data)

# exemple avec une commande externe
def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Erreur avec la commande '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out != "":
        weechat.prnt("", "stdout : %s" % out)
    if err != "":
        weechat.prnt("", "stderr : %s" % err)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process("ls", 5000, "my_process_cb", "")

# exemple avec une fonction du script
def get_status(data):
    # faire quelque chose de bloquant...
    # ...
    return "ceci est le résultat"

def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Erreur avec la commande '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out != "":
        weechat.prnt("", "stdout : %s" % out)
    if err != "":
        weechat.prnt("", "stderr : %s" % err)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process("func:get_status", 5000, "my_process_cb", "")
----

==== hook_process_hashtable

_WeeChat ≥ 0.3.7, mis à jour dans la 1.5._

Accrocher un processus (lancé par un fork) en utilisant des options dans une
table de hachage, et intercepter sa sortie.

Prototype :

[source,C]
----
struct t_hook *weechat_hook_process_hashtable (const char *command,
                                               struct t_hashtable *options,
                                               int timeout,
                                               int (*callback)(const void *pointer,
                                                               void *data,
                                                               const char *command,
                                                               int return_code,
                                                               const char *out,
                                                               const char *err),
                                               const void *callback_pointer,
                                               void *callback_data);
----

Les paramètres sont les mêmes que ceux de la fonction
<<_hook_process,hook_process>>, avec un paramètre supplémentaire :

* _options_ : options pour la commande exécutée; la table de hachage est
  dupliquée dans la fonction, donc il est possible de la supprimer après cet
  appel

Pour une commande standard (ne commençant pas par "url:"), les options suivantes
sont disponibles :

[width="100%",cols="^1,1,3",options="header"]
|===
| Option | Valeur | Description

| argN (N ≥ 1) +
  _(WeeChat ≥ 0.4.0)_ |
  toute chaîne |
  Paramètres pour la commande ; si aucun paramètre n'est donné avec ces options,
  la commande sera automatiquement découpée comme le fait le shell (et donc les
  paramètres de la commande sont lus dans le paramètre _command_)

| stdin +
  _(WeeChat ≥ 0.4.3)_ |
  (non utilisée) |
  Créer un tuyau pour écrire sur l'entrée standard (stdin) du processus fils
  (voir la fonction <<_hook_set,hook_set>>)

| buffer_flush +
  _(WeeChat ≥ 1.0)_ |
  nombre d'octets |
  Nombre minimum d'octets pour vider stdout/stderr (pour envoyer la sortie au
  "callback"), entre 1 et 65536 (par défaut); 1 = envoyer toute sortie
  immédiatement au "callback"

| detached +
  _(WeeChat ≥ 1.0)_ |
  (non utilisée) |
  Lancer le process dans un mode détaché : stdout et stderr sont redirigés vers
  _/dev/null_
|===

Pour la commande "url:...", les options suivantes sont disponibles (voir
`man curl_easy_setopt` pour une description de chaque option) :

include::autogen/plugin_api/url_options.adoc[]

[NOTE]
^(1)^ Lorsque des constantes sont disponibles, elles doivent être utilisées
comme valeur pour l'option. Pour les options avec le type "mask", le format
est : "valeur1+valeur2+valeur3".

Pour l'URL, deux options supplémentaires (chaînes) sont autorisées, pour le
fichier en entrée/sortie :

* _file_in_ : fichier à lire pour envoyer avec l'URL (envoi de fichier "post")
* _file_out_ : écrire l'URL/fichier dans ce fichier (au lieu de la sortie
  standard)

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
int
my_process_cb (const void *pointer, 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 WEECHAT_RC_OK;
    }

    if (return_code >= 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;
}

/* exemple 1 : téléchargement d'une URL */
struct t_hashtable *options = weechat_hashtable_new (8,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     NULL,
                                                     NULL);
if (options)
{
    weechat_hashtable_set (options, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:https://weechat.org/",
                                                                     options,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options);
}

/* exemple 2 : exécution d'un programme de notification avec le message de quelqu'un */
struct t_hashtable *options_cmd1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd1)
{
    weechat_hashtable_set (options_cmd1, "arg1", "-from");
    weechat_hashtable_set (options_cmd1, "arg2", nick);
    weechat_hashtable_set (options_cmd1, "arg3", "-msg");
    weechat_hashtable_set (options_cmd1, "arg4", message);  /* paramètre non sûr */
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("my-notify-command",
                                                                     options_cmd1,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_cmd1);
}

/* exemple 3 : appeler le shell pour exécuter la commande (la commande doit être SURE) */
struct t_hashtable *options_cmd2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd2)
{
    weechat_hashtable_set (options_cmd2, "arg1", "-c");
    weechat_hashtable_set (options_cmd2, "arg2", "ls -l /tmp | grep something");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("sh",
                                                                     options_cmd2,
                                                                     20000,
                                                                     &my_process_cb, NULL, NULL);
    weechat_hashtable_free (options_cmd2);
}
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_process_hashtable(command, options, timeout, callback, callback_data)

# exemple
def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Erreur avec la commande '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out != "":
        weechat.prnt("", "stdout : %s" % out)
    if err != "":
        weechat.prnt("", "stderr : %s" % err)
    return weechat.WEECHAT_RC_OK

# exemple 1 : téléchargement d'une URL
hook1 = weechat.hook_process_hashtable("url:https://weechat.org/",
                                       {"file_out": "/tmp/weechat.org.html"},
                                       20000, "my_process_cb", "")

# exemple 2 : exécution d'un programme de notification avec le message de quelqu'un
hook2 = weechat.hook_process_hashtable("my-notify-command",
                                       {"arg1": "-from",
                                        "arg2": nick,
                                        "arg3": "-msg",
                                        "arg4": message},  # paramètre non sûr
                                       20000, "my_process_cb", "")

# exemple 3 : appeler le shell pour exécuter la commande (la commande doit être SURE)
hook3 = weechat.hook_process_hashtable("sh",
                                       {"arg1": "-c",
                                        "arg2": "ls -l /tmp | grep something"},
                                       20000, "my_process_cb", "")
----

==== hook_connect

_Mis à jour dans la 1.5._

Accrocher une connexion (connexion à une machine distante en tâche de fond).

Prototype :

[source,C]
----
struct t_hook *weechat_hook_connect (const char *proxy,
                                     const char *address,
                                     int port,
                                     int ipv6,
                                     int retry,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *gnutls_priorities,
                                     const char *local_hostname,
                                     int (*callback)(const void *pointer,
                                                     void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     int sock,
                                                     const char *error,
                                                     const char *ip_address),
                                     const void *callback_pointer,
                                     void *callback_data);
----

Paramètres :

* _proxy_ : nom du proxy à utiliser pour la connexion (optionnel, NULL signifie
  une connexion sans proxy)
* _address_ : nom ou adresse IP de la machine à laquelle se connecter
* _port_ : numéro de port
* _ipv6_ : 1 pour utiliser IPv6 (avec repli sur IPv4), 0 pour utiliser seulement
  IPv4
* _retry_ : numéro de nouvelle tentative, utilisé pour se rabattre sur les
  adresses IPv4 si la connexion IPv6 échoue
* _gnutls_sess_ : session GnuTLS (optionnel)
* _gnutls_cb_ : callback pour GnuTLS (optionnel)
* _gnutls_dhkey_size_ : taille de clé utilisée pour l'échange de clé
  Diffie-Hellman (GnuTLS)
* _gnutls_priorities_ : priorités pour gnutls (pour la syntaxe, voir la
  documentation de la fonction _gnutls_priority_init_ dans le manuel gnutls),
  les valeurs de base sont :
** _PERFORMANCE_
** _NORMAL_ (défaut)
** _SECURE128_
** _SECURE256_
** _EXPORT_
** _NONE_
* _local_hostname_ : nom de machine local à utiliser pour la connexion
  (optionnel)
* _callback_ : fonction appelée lorsque la connexion est ok ou a échoué,
  paramètres et valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _int status_ : statut de connexion :
*** _WEECHAT_HOOK_CONNECT_OK_ : connexion 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
*** _WEECHAT_HOOK_CONNECT_TIMEOUT_ : temps maximum dépassé
*** _WEECHAT_HOOK_CONNECT_SOCKET_ERROR_ : erreur de création socket
** _gnutls_rc_ : valeur retour de _gnutls_handshake()_
** _sock_ : socket utilisé pour la connexion
** _const char *error_ : valeur retour de _gnutls_strerror(gnutls_rc)_
** _const char *ip_address_ : adresse IP trouvée
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
int
my_connect_cb (const void *pointer, void *data, int status, int gnutls_rc,
               int sock, const char *error, 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;
        case WEECHAT_HOOK_CONNECT_TIMEOUT:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
            /* ... */
            break;
    }
    return WEECHAT_RC_OK;
}

struct t_hook *my_connect_hook = weechat_hook_connect (NULL,
                                                       "my.server.org", 1234,
                                                       1, 0,
                                                       NULL, NULL, 0,  /* GnuTLS */
                                                       NULL,
                                                       &my_connect_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_connect(proxy, address, port, ipv6, retry, local_hostname,
    callback, callback_data)

# exemple
def my_connect_cb(data, status, gnutls_rc, sock, error, ip_address):
    if status == WEECHAT_HOOK_CONNECT_OK:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_TIMEOUT:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
        # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_connect("", "my.server.org", 1234, 1, 0, "",
                            "my_connect_cb", "")
----

==== hook_print

_Mis à jour dans la 0.4.3, 1.0, 1.5._

Intercepter 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)(const void *pointer,
                                                   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),
                                   const void *callback_pointer,
                                   void *callback_data);
----

Paramètres :

* _buffer_ : pointeur vers le tampon, si NULL, les messages de tous les tampons
  sont interceptés
* _tags_ : intercepter seulement les messages avec ces étiquettes (optionnel) :
** avec WeeChat ≥ 0.4.3 : liste d'étiquettes (séparées par des virgules) qui
   doivent être dans le message ("ou" logique); il est possible de combiner
   plusieurs étiquettes sous forme d'un "et" logique avec le séparateur `+++`;
   le caractère joker `+*+` est autorisé dans les étiquettes
** avec WeeChat ≤ 0.4.2 : liste d'étiquettes (séparées par des virgules) qui
   doivent toutes être dans le message ("et" logique)
* _message_ : seulement les messages contenant cette chaîne seront interceptés
  (optionnel, insensible à la casse)
* _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 et
  valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_gui_buffer *buffer_ : pointeur vers le tampon
** _time_t date_ : date
** _int tags_count_ : nombre d'étiquettes de la ligne
** _const char **tags_ : tableau avec les étiquettes 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
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

[IMPORTANT]
Dans les scripts, avec WeeChat ≥ 1.0, les paramètres du callback _displayed_ et
_highlight_ sont des entiers (avec WeeChat ≤ 0.4.3, ils étaient des chaînes). +
Pour être compatible avec toutes les versions, il est recommandé de convertir
le paramètre en entier avant de le tester, par exemple en Python :
`if int(highlight):`.

Exemple en C :

[source,C]
----
int
my_print_cb (const void *pointer, 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 *my_print_hook =
    weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_print(buffer, tags, message, strip_colors, callback, callback_data)

# exemple
def my_print_cb(data, buffer, date, tags, displayed, highlight, prefix, message):
    if int(highlight):
        # ...
    return weechat.WEECHAT_RC_OK

# intercepter tous les messages, de tous les tampons, sans couleur
hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")
----

==== hook_signal

_Mis à jour dans la 1.5._

S'accrocher à un signal.

Prototype :

[source,C]
----
struct t_hook *weechat_hook_signal (const char *signal,
                                    int (*callback)(const void *pointer,
                                                    void *data,
                                                    const char *signal,
                                                    const char *type_data,
                                                    void *signal_data),
                                    const void *callback_pointer,
                                    void *callback_data);
----

Paramètres :

* _signal_ : signal à intercepter, le caractère joker `+*+` est autorisé
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
  (voir le tableau ci-dessous)
* _callback_ : fonction appelée quand le signal est reçu, paramètres et valeur
  de retour :
** _const void *pointer_ : pointeur
** _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
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_OK_EAT_ (arrêter l'envoi du signal immédiatement)
    _(WeeChat ≥ 0.4.0)_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Liste des signaux envoyés par WeeChat et les extensions :

[width="100%",cols="^1,^3,^4,5",options="header"]
|===
| Extension | Signal | Paramètres | Description

| aspell | aspell_suggest +
  _(WeeChat ≥ 0.4.0)_ |
  Pointeur : tampon |
  Nouvelles suggestions pour un mot mal orthographié

| guile | guile_script_loaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script scheme chargé

| guile | guile_script_unloaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script scheme déchargé

| guile | guile_script_installed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de chemins vers scripts installés (séparés par des virgules) |
  Script(s) scheme installé(s)

| guile | guile_script_removed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de scripts supprimés (séparés par des virgules) |
  Script(s) scheme supprimé(s)

| irc | xxx,irc_in_yyy ^(1)^ |
  Chaîne : message |
  Message IRC du serveur (avant utilisation par l'extension irc,
  signal envoyé uniquement si le message n'est *pas* ignoré)

| irc | xxx,irc_in2_yyy ^(1)^ |
  Chaîne : message |
  Message IRC du serveur (après utilisation par l'extension irc,
  signal envoyé uniquement si le message n'est *pas* ignoré)

| irc | xxx,irc_raw_in_yyy ^(1)^ +
  _(WeeChat ≥ 0.3.2)_ |
  Chaîne : message |
  Message IRC du serveur (avant utilisation par l'extension irc,
  signal envoyé même si le message est ignoré)

| irc | xxx,irc_raw_in2_yyy ^(1)^ +
  _(WeeChat ≥ 0.3.2)_ |
  Chaîne : message |
  Message IRC du serveur (après utilisation par l'extension irc,
  signal envoyé même si le message est ignoré)

| irc | xxx,irc_out1_yyy ^(1)^ +
  _(WeeChat ≥ 0.3.7)_ |
  Chaîne : message |
  Message IRC envoyé au serveur (avant découpage automatique pour tenir dans les
  512 octets)

| irc | xxx,irc_out_yyy ^(1)^ |
  Chaîne : message |
  Message IRC envoyé au serveur (après découpage automatique pour tenir dans les
  512 octets)

| irc | xxx,irc_outtags_yyy ^(1)^ +
  _(WeeChat ≥ 0.3.4)_ |
  Chaîne : étiquettes + ";" + message |
  Étiquettes + 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_opened +
  _(WeeChat ≥ 0.3.7)_ |
  Pointeur : tampon |
  Tampon du serveur ouvert

| 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é

| irc | irc_notify_join +
  _(WeeChat ≥ 0.3.8)_ |
  Chaîne : nom du serveur + "," + pseudo |
  Un pseudo dans la liste de notifications a rejoint le serveur

| irc | irc_notify_quit +
  _(WeeChat ≥ 0.3.8)_ |
  Chaîne : nom du serveur + "," + pseudo |
  Un pseudo dans la liste de notifications a quitté le serveur

| irc | irc_notify_away +
  _(WeeChat ≥ 0.3.8)_ |
  Chaîne : nom du serveur + "," + pseudo + "," + message d'absence |
  Un pseudo dans la liste de notifications est maintenant absent sur le serveur

| irc | irc_notify_still_away +
  _(WeeChat ≥ 0.3.8)_ |
  Chaîne : nom du serveur + "," + pseudo + "," + message d'absence |
  Un pseudo dans la liste de notifications est toujours absent sur le serveur
  (le message d'absence a changé)

| irc | irc_notify_back +
  _(WeeChat ≥ 0.3.8)_ |
  Chaîne : nom du serveur + "," + pseudo |
  Un pseudo dans la liste de notifications est de retour (statut d'absence
  supprimé)

| javascript | javascript_script_loaded +
  _(WeeChat ≥ 1.2)_ |
  Chaîne : chemin vers le script |
  Script javascript chargé

| javascript | javascript_script_unloaded +
  _(WeeChat ≥ 1.2)_ |
  Chaîne : chemin vers le script |
  Script javascript déchargé

| javascript | javascript_script_installed +
  _(WeeChat ≥ 1.2)_ |
  Chaîne : liste de chemins vers scripts installés (séparés par des virgules) |
  Script(s) javascript installé(s)

| javascript | javascript_script_removed +
  _(WeeChat ≥ 1.2)_ |
  Chaîne : liste de scripts supprimés (séparés par des virgules) |
  Script(s) javascript supprimé(s)

| 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

| lua | lua_script_loaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script lua chargé

| lua | lua_script_unloaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script lua déchargé

| lua | lua_script_installed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de chemins vers scripts installés (séparés par des virgules) |
  Script(s) lua installé(s)

| lua | lua_script_removed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de scripts supprimés (séparés par des virgules) |
  Script(s) lua supprimé(s)

| perl | perl_script_loaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script perl chargé

| perl | perl_script_unloaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script perl déchargé

| perl | perl_script_installed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de chemins vers scripts installés (séparés par des virgules) |
  Script(s) perl installé(s)

| perl | perl_script_removed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de scripts supprimés (séparés par des virgules) |
  Script(s) perl supprimé(s)

| python | python_script_loaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script python chargé

| python | python_script_unloaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script python déchargé

| python | python_script_installed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de chemins vers scripts installés (séparés par des virgules) |
  Script(s) python installé(s)

| python | python_script_removed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de scripts supprimés (séparés par des virgules) |
  Script(s) python supprimé(s)

| relay | relay_client_connecting +
  _(WeeChat ≥ 1.0)_ |
  Pointeur : client relay |
  Un client relay est en train de se connecter

| relay | relay_client_waiting_auth +
  _(WeeChat ≥ 1.0)_ |
  Pointeur : client relay |
  Attente de l'authentification d'un client relay

| relay | relay_client_auth_ok +
  _(WeeChat ≥ 1.0)_ |
  Pointeur : client relay |
  Authentification réussie d'un client relay

| relay | relay_client_connected +
  _(WeeChat ≥ 1.0)_ |
  Pointeur : client relay |
  Un client relay est connecté

| relay | relay_client_auth_failed +
  _(WeeChat ≥ 1.0)_ |
  Pointeur : client relay |
  L'authentification d'un client relay a échoué

| relay | relay_client_disconnected +
  _(WeeChat ≥ 1.0)_ |
  Pointeur : client relay |
  Un client relay est déconnecté

| ruby | ruby_script_loaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script ruby chargé

| ruby | ruby_script_unloaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script ruby déchargé

| ruby | ruby_script_installed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de chemins vers scripts installés (séparés par des virgules) |
  Script(s) ruby installé(s)

| ruby | ruby_script_removed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de scripts supprimés (séparés par des virgules) |
  Script(s) ruby supprimé(s)

| tcl | tcl_script_loaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script tcl chargé

| tcl | tcl_script_unloaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers le script |
  Script tcl déchargé

| tcl | tcl_script_installed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de chemins vers scripts installés (séparés par des virgules) |
  Script(s) tcl installé(s)

| tcl | tcl_script_removed +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : liste de scripts supprimés (séparés par des virgules) |
  Script(s) tcl supprimé(s)

| weechat | buffer_opened |
  Pointeur : tampon |
  Tampon ouvert

| weechat | buffer_closing |
  Pointeur : tampon |
  Fermeture du tampon en cours

| weechat | buffer_closed |
  Pointeur : tampon |
  Tampon fermé

| weechat | buffer_cleared |
  Pointeur : tampon |
  Tampon vidé

| weechat | buffer_hidden |
  Pointeur : tampon |
  Tampon masqué

| weechat | buffer_unhidden |
  Pointeur : tampon |
  Tampon démasqué

| weechat | buffer_line_added +
  _(WeeChat ≥ 0.3.7)_ |
  Pointeur : ligne |
  Ligne ajoutée dans un tampon

| 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_merged |
  Pointeur : tampon |
  Tampon mélangé

| weechat | buffer_unmerged |
  Pointeur : tampon |
  Le tampon n'est plus mélangé

| weechat | buffer_moved |
  Pointeur : tampon |
  Tampon déplacé

| 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 | buffer_zoomed +
  _(WeeChat ≥ 0.4.3)_ |
  Pointeur : tampon |
  Zoom sur un tampon mélangé

| weechat | buffer_unzoomed +
  _(WeeChat ≥ 0.4.3)_ |
  Pointeur : tampon |
  Fin du zoom sur un tampon mélangé

| weechat | day_changed +
  _(WeeChat ≥ 0.3.2)_ |
  Chaîne : nouvelle date, format : "2010-01-31" |
  Le jour de la date système a changé

| weechat | debug_dump |
  Chaîne : nom d'extension |
  Requête de "dump"

| weechat | debug_libs |
  - |
  Affichage des bibliothèques externes utilisées

| weechat | filter_added |
  Pointeur : filtre |
  Filtre ajouté

| weechat | filter_removing |
  Pointeur : filtre |
  Suppression de filtre en cours

| weechat | filter_removed |
  - |
  Filtre supprimé

| weechat | filters_enabled |
  - |
  Filtres activés

| weechat | filters_disabled |
  - |
  Filtres désactivés

| weechat | hotlist_changed |
  - |
  La hotlist a changé

| weechat | input_paste_pending |
  - |
  Coller de lignes en cours

| weechat | input_search |
  Pointeur : tampon |
  Recherche de texte dans le tampon

| weechat | input_text_changed |
  Pointeur : tampon |
  Texte modifié dans la barre "input"

| weechat | input_text_cursor_moved |
  Pointeur : tampon |
  Curseur déplacé dans la barre "input"

| weechat | key_bind |
  Chaîne : touche |
  Touche ajoutée

| weechat | key_unbind |
  Chaîne : touche |
  Touche supprimée

| weechat | key_pressed |
  Chaîne : touche appuyée |
  Touche appuyée

| weechat | key_combo_default +
  _(WeeChat ≥ 1.0)_ |
  Chaîne : combinaison de touches |
  Combinaison de touches dans le contexte _default_

| weechat | key_combo_search +
  _(WeeChat ≥ 1.0)_ |
  Chaîne : combinaison de touches |
  Combinaison de touches dans le contexte _search_

| weechat | key_combo_cursor +
  _(WeeChat ≥ 1.0)_ |
  Chaîne : combinaison de touches |
  Combinaison de touches dans le contexte _cursor_

| weechat | mouse_enabled +
  _(WeeChat ≥ 1.1)_ |
  - |
  Souris activée

| weechat | mouse_disabled +
  _(WeeChat ≥ 1.1)_ |
  - |
  Souris désactivée

| weechat | nicklist_group_added +
  _(WeeChat ≥ 0.3.2)_ |
  Chaîne : pointeur tampon + "," + nom du groupe |
  Groupe ajouté dans la liste des pseudos

| weechat | nicklist_group_changed +
  _(WeeChat ≥ 0.3.4)_ |
  Chaîne : pointeur tampon + "," + nom du groupe |
  Groupe modifié dans la liste des pseudos

| weechat | nicklist_group_removing +
  _(WeeChat ≥ 0.4.1)_ |
  Chaîne : pointeur tampon + "," + nom du groupe |
  Suppression du groupe de la liste des pseudos

| weechat | nicklist_group_removed +
  _(WeeChat ≥ 0.3.2)_ |
  Chaîne : pointeur tampon + "," + nom du groupe |
  Groupe supprimé de la liste des pseudos

| weechat | nicklist_nick_added +
  _(WeeChat ≥ 0.3.2)_ |
  Chaîne : pointeur tampon + "," + pseudo |
  Pseudo ajouté dans la liste des pseudos

| weechat | nicklist_nick_changed +
  _(WeeChat ≥ 0.3.4)_ |
  Chaîne : pointeur tampon + "," + pseudo |
  Pseudo modifié dans la liste des pseudos

| weechat | nicklist_nick_removing +
  _(WeeChat ≥ 0.4.1)_ |
  Chaîne : pointeur tampon + "," + pseudo |
  Suppression du pseudo de la liste des pseudos

| weechat | nicklist_nick_removed +
  _(WeeChat ≥ 0.3.2)_ |
  Chaîne : pointeur tampon + "," + pseudo |
  Pseudo supprimé de la liste des pseudos

| weechat | partial_completion |
  - |
  Une complétion partielle a été faite

| weechat | plugin_loaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : chemin vers l'extension chargée |
  Extension chargée

| weechat | plugin_unloaded +
  _(WeeChat ≥ 0.3.9)_ |
  Chaîne : nom de l'extension déchargée (exemple : "irc") |
  Extension déchargée

| weechat | quit |
  Chaîne : paramètres pour le /quit |
  La commande `/quit` a été exécutée par l'utilisateur

| weechat | signal_sighup +
  _(WeeChat ≥ 1.3)_ |
  - |
  Signal SIGHUP reçu

| weechat | signal_sigquit +
  _(WeeChat ≥ 1.2)_ |
  - |
  Signal SIGQUIT reçu (requête pour quitter avec une copie de la mémoire)

| weechat | signal_sigterm +
  _(WeeChat ≥ 1.2)_ |
  - |
  Signal SIGTERM reçu (arrêt propre du processus WeeChat)

| weechat | signal_sigwinch +
  _(WeeChat ≥ 0.4.3)_ |
  - |
  Signal SIGWINCH reçu (le terminal a été redimensionné)

| weechat | upgrade |
  Chaîne : "quit" si le paramètre "-quit" a été donné pour /upgrade, sinon NULL |
  La commande `/upgrade` a été exécutée par l'utilisateur

| weechat | upgrade_ended +
  _(WeeChat ≥ 0.3.4)_ |
  - |
  Fin du processus de mise à jour (commande `/upgrade`)

| 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_closing +
  _(WeeChat ≥ 0.3.6)_ |
  Pointeur : fenêtre |
  Fermeture de la fenêtre en cours

| weechat | window_closed +
  _(WeeChat ≥ 0.3.6)_ |
  Pointeur : fenêtre |
  Fenêtre fermée

| weechat | window_opened +
  _(WeeChat ≥ 0.4.1)_ |
  Pointeur : fenêtre |
  Fenêtre ouverte

| weechat | window_scrolled |
  Pointeur : fenêtre |
  Défilement dans la fenêtre

| weechat | window_switch +
  _(WeeChat ≥ 0.3.7)_ |
  Pointeur : fenêtre |
  Basculement vers une autre fenêtre

| weechat | window_zoom |
  Pointeur : fenêtre courante |
  Zoom en cours sur la fenêtre

| weechat | window_zoomed |
  Pointeur : fenêtre courante |
  Zoom effectué sur la fenêtre

| weechat | window_unzoom |
  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

| xfer | xfer_add |
  Pointeur : infolist avec l'info xfer |
  Nouveau xfer

| xfer | xfer_send_ready |
  Pointeur : infolist avec l'info xfer |
  Xfer prêt

| xfer | xfer_accept_resume |
  Pointeur : infolist avec l'info xfer |
  Accepter la reprise xfer

| xfer | xfer_send_accept_resume |
  Pointeur : infolist avec l'info xfer |
  Reprise xfer acceptée

| 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

| xfer | xfer_ended +
  _(WeeChat ≥ 0.3.2)_ |
  Pointer : infolist avec l'info xfer |
  Le xfer s'est terminé
|===

[NOTE]
^(1)^ _xxx_ est le nom du serveur IRC, _yyy_ est le nom d'une commande IRC.

Exemple en C :

[source,C]
----
int
my_signal_cb (const void *pointer, void *data, const char *signal,
              const char *type_data, void *signal_data)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* intercepter le signal "quit" */
struct t_hook *my_signal_hook = weechat_hook_signal ("quit",
                                                     &my_signal_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_signal(signal, callback, callback_data)

# exemple
def my_signal_cb(data, signal, signal_data):
    # ...
    return weechat.WEECHAT_RC_OK

# intercepter le signal "quit"
hook = weechat.hook_signal("quit", "my_signal_cb", "")
----

==== hook_signal_send

_Mis à jour dans la 1.0._

Envoyer un signal.

Prototype :

[source,C]
----
int 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
  <<_hook_signal,hook_signal>>)
* _signal_data_ : données envoyées avec le signal

Valeur de retour _(WeeChat ≥ 1.0)_ :

* code retour du dernier "callback" exécuté (_WEECHAT_RC_OK_ si aucun "callback"
  n'a été exécuté) :
** _WEECHAT_RC_OK_
** _WEECHAT_RC_OK_EAT_
** _WEECHAT_RC_ERROR_

Exemple en C :

[source,C]
----
int rc = weechat_hook_signal_send ("mon_signal", WEECHAT_HOOK_SIGNAL_STRING, ma_chaine);
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.hook_signal_send(signal, type_data, signal_data)

# exemple
rc = weechat.hook_signal_send("mon_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, ma_chaine)
----

[[signal_logger_backlog]]
===== Signal logger_backlog

Le signal "logger_backlog" peut être envoyé pour afficher l'historique de
discussion dans le tampon (par exemple si vous ouvrez votre propre tampon dans
votre extension/script).

Le paramètre est un pointeur vers le tampon.

Exemple en C :

[source,C]
----
weechat_hook_signal_send ("logger_backlog", WEECHAT_HOOK_SIGNAL_POINTER, buffer);
----

Script (Python) :

[source,python]
----
weechat.hook_signal_send("logger_backlog", weechat.WEECHAT_HOOK_SIGNAL_POINTER, buffer)
----

[[signals_xxx_script_install]]
===== Signaux xxx_script_install

Cinq signaux peuvent être envoyés pour installer un script, selon le langage :

* _perl_script_install_
* _python_script_install_
* _ruby_script_install_
* _lua_script_install_
* _tcl_script_install_
* _guile_script_install_
* _javascript_script_install_

Le "callback" effectuera les actions suivantes lorsqu'il recevra le signal :

. déchargement et suppression du script installé
. déplacement du nouveau script vers le répertoire _~/.weechat/xxx/_ (où _xxx_
  est le langage)
. création d'un lien vers le nouveau script dans le répertoire
  _~/.weechat/xxx/autoload/_
. chargement du nouveau script

Ces signaux sont utilisés par l'extension _script_ pour installer des scripts.

Le paramètre est une chaîne avec le chemin vers le script à installer.

Exemple en C :

[source,C]
----
weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                          "/home/xxx/.weechat/test.py");
----

Script (Python) :

[source,python]
----
weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                         "/home/xxx/.weechat/test.py")
----

[[signals_xxx_script_remove]]
===== Signaux xxx_script_remove

Cinq signaux peuvent être envoyés pour supprimer une liste de scripts, selon le
langage :

* _perl_script_remove_
* _python_script_remove_
* _ruby_script_remove_
* _lua_script_remove_
* _tcl_script_remove_
* _guile_script_remove_
* _javascript_script_remove_

Pour chaque script dans la liste, le "callback" déchargera et supprimera le
script.

Ces signaux sont utilisés par l'extension _script_ pour supprimer des scripts.

Le paramètre est une chaîne avec une liste de scripts à supprimer (séparés par
des virgules, nom du script sans le chemin, par exemple _script.py_).

Exemple en C :

[source,C]
----
/* décharge et supprime les scripts test.py et script.py */
weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                          "test.py,script.py");
----

Script (Python) :

[source,python]
----
# décharge et supprime les scripts test.py et script.py
weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                         "test.py,script.py")
----

[[signal_irc_input_send]]
===== Signal irc_input_send

_WeeChat ≥ 0.3.4, mis à jour dans la 1.5._

Le signal "irc_input_send" peut être envoyé pour simuler une entrée de texte
dans un tampon irc (serveur, canal ou privé).

Le paramètre est une chaîne avec le format suivant :

* nom interne du serveur (requis)
* point-virgule
* nom de canal (optionnel)
* point-virgule
* liste d'options séparées par des virgules (optionnel) :
** _priority_high_ : file d'attente avec haute priorité (comme les messages
   utilisateur) ; c'est la priorité par défaut
** _priority_low_ : file d'attente avec basse priorité (comme les messages
   envoyés automatiquement par WeeChat)
** _user_message_ : forcer un message utilisateur (ne pas exécuter de commande)
* point-virgule
* liste d'étiquettes (séparées par des virgules) utilisées lors de l'envoi du
  message (optionnel)
* point-virgule
* texte ou commande (requis)

Exemples en C :

[source,C]
----
/* dis "Bonjour !" sur le serveur freenode, canal #weechat */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;#weechat;priority_high,user_message;;Bonjour !");

/* envoie la commande "/whois FlashCode" sur le canal freenode, en basse priorité */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;;priority_low;;/whois FlashCode");
----

Script (Python) :

[source,python]
----
# dis "Bonjour !" sur le serveur freenode, canal #weechat
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;#weechat;priority_high,user_message;;Bonjour !")

# envoie la commande "/whois FlashCode" sur le canal freenode, en basse priorité
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;priority_low;;/whois FlashCode")
----

==== hook_hsignal

_WeeChat ≥ 0.3.4, mis à jour dans la 1.5._

S'accrocher à un hsignal (signal avec une table de hachage).

Prototype :

[source,C]
----
struct t_hook *weechat_hook_hsignal (const char *signal,
                                     int (*callback)(const void *pointer,
                                                     void *data,
                                                     const char *signal,
                                                     struct t_hashtable *hashtable),
                                     const void *callback_pointer,
                                     void *callback_data);
----

Paramètres :

* _signal_ : signal à intercepter, le caractère joker `+*+` est autorisé
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
  (voir le tableau ci-dessous)
* _callback_ : fonction appelée quand le signal est reçu, paramètres et valeur
  de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _const char *signal_ : signal reçu
** _struct t_hashtable *hashtable_ : table de hachage
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_OK_EAT_ (arrêter l'envoi du signal immédiatement)
    _(WeeChat ≥ 0.4.0)_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Liste des hsignaux envoyés par WeeChat et les extensions :

[width="100%",cols="^1,^3,5,5",options="header"]
|===
| Extension | Signal | Paramètres | Description

| irc | irc_redirection_xxx_yyy ^(1)^ +
  _(WeeChat ≥ 0.3.4)_ |
  Voir <<hsignal_irc_redirect_command,hsignal_irc_redirect_command>> |
  Sortie de la redirection

| weechat | nicklist_group_added +
  _(WeeChat ≥ 0.4.1)_ |
  _buffer_ (_struct t_gui_buffer *_) : tampon +
  _parent_group_ (_struct t_gui_nick_group *_) : groupe parent +
  _group_ (_struct t_gui_nick_group *_) : groupe |
  Groupe ajouté dans la liste de pseudos

| weechat | nicklist_nick_added +
  _(WeeChat ≥ 0.4.1)_ |
  _buffer_ (_struct t_gui_buffer *_) : tampon +
  _parent_group_ (_struct t_gui_nick_group *_) : groupe parent +
  _nick_ (_struct t_gui_nick *_) : pseudo |
  Pseudo ajouté dans la liste de pseudos

| weechat | nicklist_group_removing +
  _(WeeChat ≥ 0.4.1)_ |
  _buffer_ (_struct t_gui_buffer *_) : tampon +
  _parent_group_ (_struct t_gui_nick_group *_) : groupe parent +
  _group_ (_struct t_gui_nick_group *_) : groupe |
  Suppression d'un groupe de la liste de pseudos

| weechat | nicklist_nick_removing +
  _(WeeChat ≥ 0.4.1)_ |
  _buffer_ (_struct t_gui_buffer *_) : tampon +
  _parent_group_ (_struct t_gui_nick_group *_) : groupe parent +
  _nick_ (_struct t_gui_nick *_) : pseudo |
  Suppression d'un pseudo de la liste de pseudos

| weechat | nicklist_group_changed +
  _(WeeChat ≥ 0.4.1)_ |
  _buffer_ (_struct t_gui_buffer *_) : tampon +
  _parent_group_ (_struct t_gui_nick_group *_) : groupe parent +
  _group_ (_struct t_gui_nick_group *_) : groupe |
  Groupe changé dans la liste de pseudos

| weechat | nicklist_nick_changed +
  _(WeeChat ≥ 0.4.1)_ |
  _buffer_ (_struct t_gui_buffer *_) : tampon +
  _parent_group_ (_struct t_gui_nick_group *_) : parent +
  _nick_ (_struct t_gui_nick *_) : pseudo |
  Pseudo changé dans la liste de pseudos
|===

[NOTE]
^(1)^ _xxx_ est l'argument "signal" utilisé dans la redirection, _yyy_ est le
modèle de redirection ("pattern").

Exemple en C :

[source,C]
----
int
my_hsignal_cb (const void *pointer, void *data, const char *signal,
               struct t_hashtable *hashtable)
{
    /* ... */
    return WEECHAT_RC_OK;
}

struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test",
                                                       &my_hsignal_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_hsignal(signal, callback, callback_data)

# exemple
def my_hsignal_cb(data, signal, hashtable):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_hsignal("test", "my_hsignal_cb", "")
----

==== hook_hsignal_send

_WeeChat ≥ 0.3.4, mis à jour dans la 1.0._

Envoyer un hsignal (signal avec table de hachage).

Prototype :

[source,C]
----
int weechat_hook_hsignal_send (const char *signal, struct t_hashtable *hashtable);
----

Paramètres :

* _signal_ : signal à envoyer
* _hashtable_ : table de hachage

Valeur de retour _(WeeChat ≥ 1.0)_ :

* code retour du dernier "callback" exécuté (_WEECHAT_RC_OK_ si aucun "callback"
  n'a été exécuté) :
** _WEECHAT_RC_OK_
** _WEECHAT_RC_OK_EAT_
** _WEECHAT_RC_ERROR_

Exemple en C :

[source,C]
----
int rc;
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "clé", "valeur");
    rc = weechat_hook_hsignal_send ("my_hsignal", hashtable);
    weechat_hashtable_free (hashtable);
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.hook_hsignal_send(signal, hashtable)

# exemple
rc = weechat.hook_hsignal_send("my_hsignal", {"clé": "valeur"})
----

[[hsignal_irc_redirect_command]]
===== Hsignal irc_redirect_command

_WeeChat ≥ 0.3.4._

Le hsignal "irc_redirect_command" peut être envoyé pour rediriger la sortie
d'une commande irc vers un "callback".

Le paramètre est une table de hachage avec les entrées suivantes (les clés et
valeurs sont des chaînes) :

* _server_ : nom interne du serveur (requis)
* _pattern_ : modèle de redirection à utiliser (requis), soit un par défaut
  (défini par l'extension irc), ou un modèle utilisateur (voir
  <<hsignal_irc_redirect_pattern>>), les modèles par défaut sont :
** _ison_
** _list_
** _mode_channel_
** _mode_channel_ban_ ("mode #channel b")
** _mode_channel_ban_exception_ ("mode #channel e")
** _mode_channel_invite_ ("mode #channel I")
** _mode_user_
** _monitor_
** _names_
** _ping_
** _time_
** _topic_
** _userhost_
** _who_
** _whois_
** _whowas_
* _signal_ : nom du signal (requis)
* _count_ : nombre de fois que la redirection sera exécutée (optionnel, 1 par
  défaut)
* _string_ : chaîne qui doit être dans les messages irc reçus (optionnel, mais
  recommandé, si une chaîne peut être utilisée pour identifier les messages)
* _timeout_ : temps d'attente maximum pour la redirection, en secondes
  (optionnel, 60 par défaut)
* _cmd_filter_ : liste de commandes irc (séparées par des virgules) à filtrer
  (seules ces commandes seront transmises au "callback", les autres seront
  ignorées) (optionnel)

Immédiatement après l'envoi de ce hsignal, vous devez envoyer la commande au
serveur irc, et la redirection sera utilisée pour cette commande.

Lorsque la réponse complète à votre commande a été reçue, un hsignal est envoyé.
Ce hsignal a le nom _irc_redirection_xxx_yyy_ où _xxx_ est le _signal_ et _yyy_
le _pattern_ utilisé.

La table de hachage envoyée dans le hsignal a le contenu suivant (les clés et
valeurs sont des chaînes) :

* _output_ : sortie de la commande (les messages sont séparés par "\n")
* _output_size_ : nombre d'octets dans _output_ (sous forme de chaîne)
* _error_ : chaîne d'erreur (si une erreur s'est produite) :
** _timeout_ : redirection stoppée après le délai maximum dépassé
* _server_ : nom interne du serveur
* _pattern_ : modèle de redirection
* _signal_ : nom du signal
* _command_ : commande redirigée

Exemple en C :

[source,C]
----
int
test_whois_cb (const void *pointer, void *data, const char *signal,
               struct t_hashtable *hashtable)
{
    weechat_printf (NULL, "erreur = %s", weechat_hashtable_get (hashtable, "error"));
    weechat_printf (NULL, "sortie = %s", weechat_hashtable_get (hashtable, "output"));
    return WEECHAT_RC_OK;
}

weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL, NULL);
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "server", "freenode");
    weechat_hashtable_set (hashtable, "pattern", "whois");
    weechat_hashtable_set (hashtable, "signal", "test");
    weechat_hashtable_set (hashtable, "string", "FlashCode");
    weechat_hook_hsignal_send ("irc_redirect_command", hashtable);
    weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                              "freenode;;2;;/whois FlashCode");
    weechat_hashtable_free (hashtable);
}
----

Script (Python) :

[source,python]
----
def test_whois_cb(data, signal, hashtable):
    weechat.prnt("", "erreur = %s" % hashtable["error"])
    weechat.prnt("", "sortie = %s" % hashtable["output"])
    return weechat.WEECHAT_RC_OK

weechat.hook_hsignal ("irc_redirection_test_whois", "test_whois_cb", "")
weechat.hook_hsignal_send("irc_redirect_command",
                          {"server": "freenode", "pattern": "whois", "signal": "test",
                           "string": "FlashCode"})
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")
----

[[hsignal_irc_redirect_pattern]]
===== Hsignal irc_redirect_pattern

_WeeChat ≥ 0.3.4._

Le hsignal "irc_redirect_pattern" peut être envoyé pour créer un modèle de
redirection irc (voir <<hsignal_irc_redirect_command>>).

Le paramètre est une table de hachage avec les entrées suivantes (les clés et
valeurs sont des chaînes) :

* _pattern_ : nom du modèle (requis)
* _timeout_ : temps d'attente maximum pour le modèle, en secondes (optionnel, 60
  par défaut)
* _cmd_start_ : liste de commandes (séparées par des virgules) démarrant la
  redirection (optionnel)
* _cmd_stop_ : liste de commandes (séparées par des virgules) stoppant la
  redirection (requis)
* _cmd_extra_ : liste de commandes (séparées par des virgules) pouvant être
  reçues après les commandes de stop (optionnel)

Pour chaque commande dans _cmd_start_, _cmd_stop_ et _cmd_extra_, il est
possible de donner un entier avec la position de la chaîne "string" qui doit
être trouvée dans le message reçu, par exemple :

----
352:1,354,401:1
----

Pour les commandes 352 et 401, la chaîne "string" doit être trouvée dans le
message reçu, comme premier paramètre.

[IMPORTANT]
Le modèle est détruit dès qu'il est utilisé dans une redirection. Si vous avez
besoin du modèle pour plusieurs redirections, vous devez créer un modèle pour
chaque redirection.

Exemple en C :

[source,C]
----
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "pattern", "my_whois");
    weechat_hashtable_set (hashtable, "timeout", "30");
    weechat_hashtable_set (hashtable, "cmd_start", "311:1");
    weechat_hashtable_set (hashtable, "cmd_stop", "318:1,401:1,402:1,431:1,461");
    weechat_hashtable_set (hashtable, "cmd_extra", "318:1");
    weechat_hook_hsignal_send ("irc_redirect_pattern", hashtable);
    /*
     * rediriger maintenant la commande irc whois avec le hsignal irc_redirect_command,
     * en utilisant le modèle "my_whois"
     */
    /* ... */
    weechat_hashtable_free (hashtable);
}
----

Script (Python) :

[source,python]
----
weechat.hook_hsignal_send("irc_redirect_pattern",
                          {"pattern": "my_whois", "timeout": "30",
                           "cmd_start": "311:1",
                           "cmd_stop": "318:1,401:1,402:1,431:1,461",
                           "cmd_extra": "318:1"})
# rediriger maintenant la commande irc whois avec le hsignal irc_redirect_command,
# en utilisant le modèle "my_whois"
# ...
----

==== hook_config

_Mis à jour dans la 1.5._

S'accrocher à une option de configuration.

Prototype :

[source,C]
----
struct t_hook *weechat_hook_config (const char *option,
                                    int (*callback)(const void *pointer,
                                                    void *data,
                                                    const char *option,
                                                    const char *value),
                                    const void *callback_pointer,
                                    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`), le caractère
  joker `+*+` est autorisé (priorité autorisée, voir la note sur la
  <<hook_priority,priorité>>)
* _callback_ : fonction appelée lorsque l'option de configuration est modifiée,
  paramètres et valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _const char *option_ : nom de l'option
** _const char *value_ : nouvelle valeur pour l'option
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
int
my_config_cb (const void *pointer, void *data, const char *option,
              const char *value)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* intercepter les changements de l'option "weechat.look.item_time_format" */
struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format",
                                                     &my_config_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_config(option, callback, callback_data)

# exemple
def my_config_cb(data, option, value):
    # ...
    return weechat.WEECHAT_RC_OK

# intercepter les changements de l'option "weechat.look.item_time_format"
hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")
----

==== hook_completion

_Mis à jour dans la 1.5._

Accrocher une complétion.

Prototype :

[source,C]
----
struct t_hook *weechat_hook_completion (const char *completion_item,
                                        const char *description,
                                        int (*callback)(const void *pointer,
                                                        void *data,
                                                        const char *completion_item,
                                                        struct t_gui_buffer *buffer,
                                                        struct t_gui_completion *completion),
                                        const void *callback_pointer,
                                        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_)
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
* _description_ : description de la complétion
* _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 et valeur de retour :
** _const void *pointer_ : pointeur
** _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
   <<_hook_completion_list_add,hook_completion_list_add>>)
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

[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).

[IMPORTANT]
Le "callback" doit seulement appeler la fonction
<<_hook_completion_list_add,hook_completion_list_add>>
et ne doit *PAS* mettre à jour la ligne de commande. +
Pour mettre à jour la ligne de commande quand key[Tab] est pressé, vous pouvez
utiliser la fonction <<_hook_command_run,hook_command_run>>
avec la commande : "/input complete_next" (et vous devez retourner
_WEECHAT_RC_OK_EAT_ si votre "callback" a mis à jour la ligne de commande, de
sorte que WeeChat n'exécute pas la complétion).

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
int
my_completion_cb (const void *pointer, void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    weechat_hook_completion_list_add (completion, "mot1",
                                      0, WEECHAT_LIST_POS_SORT);
    weechat_hook_completion_list_add (completion, "test_mot2",
                                      0, WEECHAT_LIST_POS_SORT);
    return WEECHAT_RC_OK;
}

struct t_hook *my_completion_hook = weechat_hook_completion ("extension_item",
                                                             "ma complétion !",
                                                             &my_completion_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_completion(completion_item, description, callback, callback_data)

# exemple
def my_completion_cb(data, completion_item, buffer, completion):
    weechat.hook_completion_list_add(completion, "mot1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.hook_completion_list_add(completion, "test_mot2", 0, weechat.WEECHAT_LIST_POS_SORT)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_completion("extension_item", "ma complétion !",
                               "my_completion_cb", "")
----

==== hook_completion_get_string

_WeeChat ≥ 0.3.4._

Retourner la valeur d'une propriété de la complétion sous forme de chaîne.

Prototype :

[source,C]
----
const char *weechat_hook_completion_get_string (struct t_gui_completion *completion,
                                                const char *property);
----

Paramètres :

* _completion_ : pointeur vers la complétion
* _property_ : nom de la propriété :
** _base_command_ : commande utilisée pour la complétion
** _base_word_ : le mot qui va être complété
** _args_ : paramètres de la commande (incluant le mot de base "base_word")

Exemple en C :

[source,C]
----
int
my_completion_cb (const void *pointer, void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    /* récupère les paramètres de la commande */
    const char *args = weechat_hook_completion_get_string (completion, "args");

    /* complétion selon les paramètres */
    /* ... */

    return WEECHAT_RC_OK;
}
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.hook_completion_get_string(completion, property)

# exemple
def my_completion_cb(data, completion_item, buffer, completion):
    # récupère les paramètres de la commande
    args = weechat.hook_completion_get_string(completion, "args")
    # complétion selon les paramètres
    # ...
    return weechat.WEECHAT_RC_OK
----

==== hook_completion_list_add

Ajouter 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_ : position 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 en C : voir <<_hook_completion,hook_completion>>.

Script (Python) :

[source,python]
----
# prototype
weechat.hook_completion_list_add(completion, word, nick_completion, where)

# exemple : voir la fonction hook_completion ci-dessus
----

==== hook_modifier

_Mis à jour dans la 1.5._

Accrocher un modificateur.

Prototype :

[source,C]
----
struct t_hook *weechat_hook_modifier (const char *modifier,
                                      char *(*callback)(const void *pointer,
                                                        void *data,
                                                        const char *modifier,
                                                        const char *modifier_data,
                                                        const char *string),
                                      const void *callback_pointer,
                                      void *callback_data);
----

Paramètres :

* _modifier_ : nom du modificateur, liste des modificateurs utilisés par WeeChat
  ou des extensions
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
  (voir le tableau ci-dessous)
* _callback_ : fonction appelée lorsque le modificateur est utilisé, paramètres
  et valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _const char *modifier_ : nom du modificateur
** _const char *modifier_data_ : données pour le modificateur
** _const char *string_ : chaîne à modifier
** valeur de retour : nouvelle chaîne
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Liste des modificateurs utilisés par WeeChat et les extensions :

[width="100%",cols="^2,3,4,4",options="header"]
|===
| Modificateur | Données du modificateur | Chaîne | Sortie

| 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_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_color_decode |
  "1" pour garder les couleurs, "0" pour les supprimer |
  Toute chaîne |
  Chaîne avec les couleurs IRC converties en couleurs WeeChat (ou avec les
  couleurs IRC supprimées)

| irc_color_encode |
  "1" pour garder les couleurs, "0" pour les supprimer |
  Toute chaîne |
  Chaîne avec les couleurs IRC (ou avec les couleurs IRC supprimées)

| irc_color_decode_ansi +
  _(WeeChat ≥ 1.0)_ |
  "1" pour garder les couleurs, "0" pour les supprimer |
  Toute chaîne |
  Chaîne avec les couleurs ANSI converties en couleurs IRC (ou avec les couleurs
  ANSI supprimées)

| irc_command_auth +
  _(WeeChat ≥ 0.4.1)_ |
  Nom du serveur |
  Commande d'authentification (par exemple : `+/msg nickserv identify password+`) |
  Commande avec le mot de passe caché (par exemple : `+/msg nickserv identify ********+`)

| irc_message_auth +
  _(WeeChat ≥ 0.4.1)_ |
  Nom du serveur |
  Message affiché après `msg` envoyé à nickserv |
  Message avec le mot de passe caché

| irc_in_xxx ^(1)^ |
  Nom de serveur |
  Contenu du message reçu du serveur IRC (avant décodage du jeu de caractères) |
  Nouveau contenu du message

| irc_in2_xxx ^(1)^ +
  _(WeeChat ≥ 0.3.5)_ |
  Nom de serveur |
  Contenu du message reçu du serveur IRC (après décodage du jeu de caractères) |
  Nouveau contenu du message

| irc_out1_xxx ^(1)^ +
  _(WeeChat ≥ 0.3.7)_ |
  Nom de serveur |
  Contenu du message qui va être envoyé au serveur IRC (avant découpage
  automatique pour tenir dans les 512 octets) |
  Nouveau contenu du message

| irc_out_xxx ^(1)^ |
  Nom de serveur |
  Contenu du message qui va être envoyé au serveur IRC (après découpage
  automatique pour tenir dans les 512 octets) |
  Nouveau contenu du message

| color_decode_ansi +
  _(WeeChat ≥ 1.0)_ |
  "1" pour garder les couleurs, "0" pour les supprimer |
  Toute chaîne |
  Chaîne avec les couleurs ANSI converties en couleurs WeeChat (ou avec les
  couleurs ANSI supprimées)

| 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

| history_add +
  _(WeeChat ≥ 0.3.2)_ |
  Chaîne avec un pointeur vers le tampon ("0x123..") |
  Contenu de la ligne de commande à ajouter à l'historique des commandes
  (tampon et global) |
  Chaîne ajoutée à l'historique des commandes

| input_text_content |
  Chaîne avec un pointeur vers le tampon ("0x123..") |
  Contenu de la ligne de commande |
  Nouvelle chaîne pour la ligne de commande

| input_text_display |
  Chaîne avec un pointeur vers le tampon ("0x123..") |
  Contenu de la ligne de commande, sans le code du curseur dedans |
  Nouvelle chaîne, pour affichage seulement (la ligne de commande n'est pas
  modifiée)

| input_text_display_with_cursor |
  Chaîne avec un pointeur vers le tampon ("0x123..") |
  Contenu de la ligne de commande, avec le code du curseur dedans |
  Nouvelle chaîne, pour affichage seulement (la ligne de commande n'est pas
  modifiée)

| input_text_for_buffer +
  _(WeeChat ≥ 0.3.7)_ |
  Chaîne avec un pointeur vers le tampon ("0x123..") |
  Contenu de la ligne de commande envoyée au tampon (texte ou commande) |
  Nouveau contenu de la ligne de commande envoyée au tampon

| 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.

Exemple en C :

[source,C]
----
char *
my_modifier_cb (const void *pointer, 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 *my_modifier_hook = weechat_hook_modifier ("weechat_print",
                                                         &my_modifier_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_modifier(modifier, callback, callback_data)

# exemple
def my_modifier_cb(data, modifier, modifier_data, string):
    return "%s xxx" % string

hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")
----

==== hook_modifier_exec

Exécuter un ou plusieurs modificateurs.

Prototype :

[source,C]
----
char *weechat_hook_modifier_exec (const char *modifier,
                                  const char *modifier_data,
                                  const char *string);
----

Paramètres :

* _modifier_ : nom du modificateur
* _modifier_data_ : données du modificateur
* _string_ : chaîne à modifier

Valeur de retour :

* chaîne modifiée, NULL en cas d'erreur

Exemple en C :

[source,C]
----
char *new_string = weechat_hook_modifier_exec ("mon_modifier",
                                               mes_donnees, ma_chaine);
----

Script (Python) :

[source,python]
----
# prototype
weechat.hook_modifier_exec(modifier, modifier_data, string)

# exemple
weechat.hook_modifier_exec("mon_modifier", mes_donnees, ma_chaine)
----

==== hook_info

_Mis à jour dans la 1.5._

Accrocher une information (le "callback" prend et retourne une chaîne).

Prototype :

[source,C]
----
struct t_hook *weechat_hook_info (const char *info_name,
                                  const char *description,
                                  const char *args_description,
                                  const char *(*callback)(const void *pointer,
                                                          void *data,
                                                          const char *info_name,
                                                          const char *arguments),
                                  const void *callback_pointer,
                                  void *callback_data);
----

Paramètres :

* _info_name_ : nom de l'information
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
* _description_ : description
* _args_description_ : description des paramètres (optionnel, peut être NULL)
* _callback_ : fonction appelée quand l'information est demandée, paramètres et
  valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _const char *info_name_ : nom de l'information
** _const char *arguments_ : paramètres additionnels, dépendant de
   l'information
** valeur de retour : valeur de l'information demandée
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
const char *
my_info_cb (const void *pointer, void *data, const char *info_name,
            const char *arguments)
{
    /* ... */
    return pointeur_vers_chaine;
}

/* ajoute l'information "mon_info" */
struct t_hook *my_info_hook = weechat_hook_info ("mon_info",
                                                 "Une information",
                                                 "Info sur les paramètres",
                                                 &my_info_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_info(info_name, description, args_description,
                         callback, callback_data)

# exemple
def my_info_cb(data, info_name, arguments):
    return "some_info"

hook = weechat.hook_info("mon_info", "Une information", "Info sur les paramètres",
                         "my_info_cb", "")
----

==== hook_info_hashtable

_WeeChat ≥ 0.3.4, mis à jour dans la 1.5._

Accrocher une information (le "callback" prend et retourne une table de
hachage).

Prototype :

[source,C]
----
struct t_hook *weechat_hook_info_hashtable (const char *info_name,
                                            const char *description,
                                            const char *args_description,
                                            const char *output_description,
                                            struct t_hashtable *(*callback)(const void *pointer,
                                                                            void *data,
                                                                            const char *info_name,
                                                                            struct t_hashtable *hashtable),
                                            const void *callback_pointer,
                                            void *callback_data);
----

Paramètres :

* _info_name_ : nom de l'information
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
* _description_ : description
* _args_description_ : description de la table de hachage attendue
  (optionnel, peut être NULL)
* _output_description_ : description de la table de hachage retournée par le
  "callback" (optionnel, peut être NULL)
* _callback_ : fonction appelée quand l'information est demandée, paramètres et
  valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _const char *info_name_ : nom de l'information
** _struct t_hashtable *hashtable_ : table de hachage, dépendant de
   l'information
** valeur de retour : table de hachage demandée
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
struct t_hashtable *
my_info_hashtable_cb (const void *pointer, void *data, const char *info_name,
                      struct t_hashtable *hashtable)
{
    /* ... */
    return pointer_vers_nouvelle_table_de_hachage;
}

/* ajoute l'information "mon_info_hashtable" */
struct t_hook *my_info_hook = weechat_hook_info_hashtable ("mon_info_hashtable",
                                                           "Une information",
                                                           "Info sur la table de hachage en entrée",
                                                           "Info sur la table de hachage en sortie",
                                                           &my_info_hashtable_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_info_hashtable(info_name, description, args_description,
                                   output_description, callback, callback_data)

# exemple
def my_info_hashtable_cb(data, info_name, hashtable):
    return {"test_cle": "test_valeur"}

hook = weechat.hook_info_hashtable("mon_info_hashtable", "Une information",
                                   "Info sur la table de hachage en entrée",
                                   "Info sur la table de hachage en sortie",
                                   "my_info_hashtable_cb", "")
----

==== hook_infolist

_Mis à jour dans la 1.5._

Accrocher une infolist : le "callback" retournera un pointeur vers l'infolist
demandée.

Prototype :

[source,C]
----
struct t_hook *weechat_hook_infolist (const char *infolist_name,
                                      const char *description,
                                      const char *pointer_description,
                                      const char *args_description,
                                      struct t_infolist *(*callback)(const void *pointer,
                                                                     void *data,
                                                                     const char *infolist_name,
                                                                     void *obj_pointer,
                                                                     const char *arguments),
                                      const void *callback_pointer,
                                      void *callback_data);
----

Paramètres :

* _infolist_name_ : nom de l'infolist
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
* _description_ : description
* _pointer_description_ : description du pointeur (optionnel, peut être NULL)
* _args_description_ : description des paramètres (optionnel, peut être NULL)
* _callback_ : fonction appelée quand l'infolist est demandée, paramètres et
  valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _const char *infolist_name_ : nom de l'infolist
** _void *pointer_ : pointeur vers un objet que l'infolist doit retourner (pour
   obtenir uniquement cet objet dans l'infolist)
** _const char *arguments_ : paramètres additionnels, dépendant de l'infolist
** valeur de retour : infolist demandée
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
struct t_infolist *
my_infolist_cb (const void *pointer, void *data, const char *infolist_name,
                void *obj_pointer, const char *arguments)
{
    struct t_infolist *mon_infolist;

    /* construction de l'infolist */
    /* ... */

    return mon_infolist;
}

/* ajoute l'infolist "mon_infolist" */
struct t_hook *my_infolist = weechat_hook_infolist ("mon_infolist",
                                                    "Mon infolist",
                                                    "Info sur le pointeur",
                                                    "Info sur les paramètres",
                                                    &my_infolist_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_infolist(infolist_name, description, pointer_description,
                             args_description, callback, callback_data)

# exemple
def my_infolist_cb(data, infolist_name, pointer, arguments):
    # construction de l'infolist
    # ...
    return my_infolist

hook = weechat.hook_infolist("mon_infolist", "Mon infolist",
                             "Info sur le pointeur", "Info sur les paramètres",
                             "my_infolist_cb", "")
----

==== hook_hdata

_Mis à jour dans la 1.5._

Accrocher un hdata : le "callback" retournera un pointeur vers le hdata demandé.

Prototype :

[source,C]
----
struct t_hook *weechat_hook_hdata (const char *hdata_name,
                                   const char *description,
                                   struct t_hdata *(*callback)(const void *pointer,
                                                               void *data,
                                                               const char *hdata_name),
                                   const void *callback_pointer,
                                   void *callback_data);
----

Paramètres :

* _hdata_name_ : nom du hdata
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
* _description_ : description
* _callback_ : fonction appelée quand le hdata est demandé, paramètres et valeur
  de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _const char *hdata_name_ : nom du hdata
** valeur de retour : hdata demandé
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
struct t_hdata *
my_hdata_cb (const void *pointer, void *data, const char *hdata_name)
{
    struct t_hdata *mon_hdata;

    /* construction du hdata */
    /* ... */

    return mon_hdata;
}

/* ajoute le hdata "mon_hdata" */
struct t_hook *my_hdata = weechat_hook_hdata ("mon_hdata",
                                              "Hdata pour ma structure",
                                              &my_hdata_cb, NULL, NULL);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hook_focus

_Mis à jour dans la 1.5._

Accrocher un focus : évènement souris ou touche du clavier pressée dans le mode
"curseur" (mouvement libre du curseur).

Prototype :

[source,C]
----
struct t_hook *weechat_hook_focus (const char *area,
                                   struct t_hashtable *(*callback)(const void *pointer,
                                                                   void *data,
                                                                   struct t_hashtable *info),
                                   const void *callback_pointer,
                                   void *callback_data);
----

Paramètres :

* _area_ : "chat" pour la zone de discussion, ou un nom d'objet de barre
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
* _callback_ : fonction appelée quand le focus est fait, paramètres et valeur de
  retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_hashtable *info_ : table de hachage avec les informations sur le
   focus et les chaînes retournées par les autres appels aux "callbacks" de
   focus (avec plus haute priorité) (voir le tableau ci-dessous)
** valeur de retour : soit le pointeur vers la table de hachage "info" (avec la
   table de hachage complétée), ou un pointeur vers une nouvelle table de
   hachage (créée par le "callback", avec clés et valeurs de type "string"), le
   contenu de cette nouvelle table de hachage sera ajouté à _info_ pour les
   autres appels aux "callbacks" focus
* _callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat
* _callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

[IMPORTANT]
Pour un geste de souris, votre "callback" sera appelé deux fois : la première
lorsque le bouton est pressé (ici la zone correspond à vôtre zone), la seconde
fois lorsque le bouton est relâché, et la zone peut ne pas correspondre à la
vôtre : donc vous devez *toujours* tester dans le "callback" si la zone
correspond avant d'utiliser les informations de la table de hachage.

Contenu de la table de hachage envoyée au "callback" (les clés et valeurs sont
de type "string") :

[width="100%",cols="5,5,8,3",options="header"]
|===
| Clé ^(1)^ | Description | Exemples de valeur | Valeur si non applicable

| _x | Colonne sur l'écran |
  "0" ... "n" |

| _y | Ligne sur l'écran |
  "0" ... "n" |

| _key | Touche ou évènement souris |
  "button1", "button2-gesture-left", ... |

| _window | Pointeur vers la fenêtre |
  "0x12345678" | ""

| _window_number | Numéro de la fenêtre |
  "1" ... "n" | "*"

| _buffer | Pointeur vers le tampon |
  "0x12345678" | ""

| _buffer_number | Numéro du tampon |
  "1" ... "n" | "-1"

| _buffer_plugin | Nom d'extension du tampon |
  "core", "irc", ... | ""

| _buffer_name | Nom du tampon |
  "weechat", "freenode.#weechat", ... | ""

| _buffer_full_name | Nom complet du tampon |
  "core.weechat", "irc.freenode.#weechat", ... | ""

| _buffer_localvar_XXX ^(2)^ | Variables locales du tampon |
  toute chaîne | non défini

| _chat | Indicateur zone "chat" |
  "0" ou "1" | "0"

| _chat_line | Pointeur vers la ligne +
  _(WeeChat ≥ 1.2)_ |
  "0x12345678" | ""

| _chat_line_x | Colonne de la ligne ^(3)^ |
  "0" ... "n" | "-1"

| _chat_line_y | Numéro de ligne ^(3)^ |
  "0" ... "n" | "-1"

| _chat_line_date | Date/heure de la ligne |
  "1313237175" | "0"

| _chat_line_date_printed | Date/heure de la ligne ^(4)^ |
  "1313237175" | "0"

| _chat_line_time | Heure affichée |
  "14:06:15" | ""

| _chat_line_tags | Étiquettes de la ligne |
  "irc_privmsg,nick_flashy,log1" | ""

| _chat_line_nick | Pseudo de la ligne |
  "FlashCode" | ""

| _chat_line_prefix | Préfixe de la ligne |
  "@FlashCode" | ""

| _chat_line_message | Message de la ligne |
  "Hello world!" | ""

| _chat_word | Mot à la position (x,y) |
  "Hello" | ""

| _chat_bol | Début de ligne ⇒ (x-1,y) |
  "He" | ""

| _chat_eol | (x,y) ⇒ fin de ligne |
  "llo world!" | ""

| _bar_name | Nom de la barre |
  "title", "nicklist", ... | ""

| _bar_filling | Remplissage de la barre |
  "horizontal", "vertical", ... | ""

| _bar_item_name | Nom de l'objet de barre |
  "buffer_nicklist", "hotlist", ... | ""

| _bar_item_line | Ligne dans l'objet de barre |
  "0" ... "n" | "-1"

| _bar_item_col | Colonne dans l'objet de barre |
  "0" ... "n" | "-1"
|===

[NOTE]
^(1)^ Il y a les mêmes clés suffixées par "2" (c'est-à-dire : "_x2", "_y2",
"_window2", ...) avec l'information sur le second point (pratique seulement
pour les gestes de souris, pour savoir où le bouton de la souris a été
relâché). +
^(2)^ `XXX` est le nom d'une variable locale du tampon. +
^(3)^ Renseigné seulement pour les tampons avec contenu libre. +
^(4)^ Il s'agit de la date lorsque WeeChat ajoute la ligne dans le tampon
(supérieure ou égale à "_chat_line_date").

Informations additionnelles pour l'objet de barre "buffer_nicklist" :

[width="60%",cols="1,1,5",options="header"]
|===
| Clé      | Extension ^(1)^ | Description
| nick     | core            | Pseudonyme
| prefix   | core            | Préfixe du pseudonyme
| group    | core            | Nom du groupe
| irc_host | irc             | Nom d'hôte pour le pseudonyme (si connu)
|===

[NOTE]
^(1)^ Le nom de l'extension qui définit un hook_focus pour retourner des infos
pour cet objet de barre (donc par exemple si l'extension est "irc", ces infos
ne seront disponibles que sur les tampons irc).

Valeur de retour :

* pointeur vers le nouveau "hook", NULL en cas d'erreur

Exemple en C :

[source,C]
----
struct t_hashtable *
my_focus_nicklist_cb (const void *pointer, void *data, struct t_hashtable *info)
{
    /* ajout de chaînes dans la table de hachage */
    /* ... */

    return info;
}

/* ajoute le focus sur la liste des pseudos */
struct t_hook *my_focus = weechat_hook_focus ("buffer_nicklist",
                                              &my_focus_nicklist_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
hook = weechat.hook_focus(area, callback, callback_data)

# exemple
def my_focus_nicklist_cb(data, info):
    # construction du dict
    # ...
    return my_dict

hook = weechat.hook_focus("buffer_nicklist", "my_focus_nicklist_cb", "")
----

==== hook_set

_WeeChat ≥ 0.3.9 (script : WeeChat ≥ 0.4.3)._

Affecter une valeur à une propriété d'un hook.

Prototype :

[source,C]
----
void weechat_hook_set (struct t_hook *hook, const char *property,
                       const char *value);
----

Paramètres :

* _hook_ : quelque chose d'accroché avec "weechat_hook_xxx()"
* _property_ : nom de la propriété (voir le tableau ci-dessous)
* _value_ : nouvelle valeur pour la propriété

Propriétés :

[width="100%",cols="^2,2,2,5",options="header"]
|===
| Nom | Type de hook | Valeur | Description

| subplugin | tout type | toute chaîne |
  Nom de la sous-extension (couramment un nom de script, qui est affiché dans
  `/help commande` pour un hook de type _command_)

| stdin +
  _(WeeChat ≥ 0.4.3)_ |
  _process_, _process_hashtable_ | toute chaîne |
  Envoyer les données sur l'entrée standard (_stdin_) du processus fils

| stdin_close +
  _(WeeChat ≥ 0.4.3)_ |
  _process_, _process_hashtable_ | (non utilisée) |
  Fermer le tuyau utilisé pour envoyer les données sur l'entrée standard
  (_stdin_) du processus fils

| signal +
  _(WeeChat ≥ 1.0)_ |
  _process_, _process_hashtable_ |
  numéro de signal ou un de ces noms : `hup`, `int`, `quit`, `kill`, `term`,
  `usr1`, `usr2` |
  Envoyer un signal au processus fils
|===

Exemple en C :

[source,C]
----
struct t_hook *my_command_hook =
    weechat_hook_command ("abcd", "description",
                          "args", "description args",
                          "", &my_command_cb, NULL, NULL);
weechat_hook_set (my_command_hook, "subplugin", "test");
----

Script (Python) :

[source,python]
----
# prototype
weechat.hook_set(hook, property, value)

# exemple
def my_process_cb(data, command, return_code, out, err):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process_hashtable("/chemin/vers/commande", {"stdin": "1"},
                                      20000, "my_process_cb", "")
weechat.hook_set(hook, "stdin", "données envoyées sur le stdin du processus fils")
weechat.hook_set(hook, "stdin_close", "")  # facultatif
----

==== unhook

Décrocher quelque chose qui est a été accroché.

Prototype :

[source,C]
----
void weechat_unhook (struct t_hook *hook);
----

Paramètres :

* _hook_ : quelque chose accroché avec "weechat_hook_xxx()"

Exemple en C :

[source,C]
----
struct t_hook *my_hook = weechat_hook_command ( /* ... */ );
/* ... */
weechat_unhook (my_hook);
----

Script (Python) :

[source,python]
----
# prototype
weechat.unhook(hook)

# exemple
weechat.unhook(my_hook)
----

==== unhook_all

_Mis à jour dans la 1.5._

Décrocher tout ce qui a été accroché par l'extension courante.

Prototype :

[source,C]
----
void weechat_unhook_all (const char *subplugin);
----

Paramètres :

* _subplugin_ : si non NULL, décrocher uniquement les "hooks" qui ont ce
  "subplugin" défini (ce paramètre n'est pas disponible dans l'API script)

Exemple en C :

[source,C]
----
weechat_unhook_all (NULL);
----

Script (Python) :

[source,python]
----
# prototype
weechat.unhook_all()

# exemple
weechat.unhook_all()
----

[[buffers]]
=== Tampons

Fonctions pour créer/interroger/fermer les tampons.

==== buffer_new

_Mis à jour dans la 1.5._

Ouvrir un nouveau tampon.

Prototype :

[source,C]
----
struct t_gui_buffer *weechat_buffer_new (const char *name,
                                         int (*input_callback)(const void *pointer,
                                                               void *data,
                                                               struct t_gui_buffer *buffer,
                                                               const char *input_data),
                                         const void *input_callback_pointer,
                                         void *input_callback_data,
                                         int (*close_callback)(const void *pointer,
                                                               void *data,
                                                               struct t_gui_buffer *buffer),
                                         const void *close_callback_pointer,
                                         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 et valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_gui_buffer *buffer_ : pointeur vers le tampon
** _const char *input_data_ : données en entrée
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _input_callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat
* _input_callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le tampon est
  fermé
* _close_callback_ : fonction appelée lorsque le tampon est fermé, paramètres et
  valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_gui_buffer *buffer_ : pointeur vers le tampon
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _close_callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat
* _close_callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le tampon est
  fermé

Valeur de retour :

* pointeur vers le nouveau tampon, NULL en cas d'erreur

Exemple en C :

[source,C]
----
int
my_input_cb (const void *pointer, void *data,
             struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Texte : %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (const void *pointer, 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",
                                                     &my_input_cb, NULL, NULL,
                                                     &my_close_cb, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
buffer = weechat.buffer_new(name, input_callback, input_callback_data,
    close_callback, close_callback_data)

# exemple
def my_input_cb(data, buffer, input_data):
    weechat.prnt(buffer, "Texte : %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data, buffer):
    weechat.prnt("", "Le tampon '%s' va être fermé !" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

buffer = weechat.buffer_new("mon_buffer", "my_input_cb", "", "my_close_cb", "")
----

==== current_buffer

Retourner 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 en C :

[source,C]
----
weechat_printf (weechat_current_buffer (), "Texte sur le tampon courant");
----

Script (Python) :

[source,python]
----
# prototype
buffer = weechat.current_buffer()

# exemple
weechat.prnt(weechat.current_buffer(), "Texte sur le tampon courant")
----

==== buffer_search

_Mis à jour dans la 1.0._

Rechercher 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, la valeur spéciale suivante est autorisée :
** `+==+` : le nom utilisé est le nom complet du tampon (par exemple :
   `irc.freenode.#weechat` au lieu de `freenode.#weechat`)
   _(WeeChat ≥ 1.0)_
* _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); si le nom commence par
  `(?i)`, la recherche est insensible à la casse _(WeeChat ≥ 1.0)_

Valeur de retour :

* pointeur vers le tampon trouvé, NULL s'il n'a pas été trouvé

Exemples en C :

[source,C]
----
struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "freenode.#weechat");
struct t_gui_buffer *buffer2 = weechat_buffer_search ("==", "irc.freenode.#test");  /* WeeChat ≥ 1.0 */
----

Script (Python) :

[source,python]
----
# prototype
buffer = weechat.buffer_search(plugin, name)

# exemple
buffer = weechat.buffer_search("mon_extension", "mon_tampon")
----

==== buffer_search_main

Rechercher 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 en C :

[source,C]
----
struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();
----

Script (Python) :

[source,python]
----
# prototype
buffer = weechat.buffer_search_main()

# exemple
buffer = weechat.buffer_search_main()
----

==== buffer_clear

Effacer 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 en C :

[source,C]
----
struct t_gui_buffer *my_buffer = weechat_buffer_search ("mon_extension",
                                                        "mon_tampon");
if (my_buffer)
{
    weechat_buffer_clear (my_buffer);
}
----

Script (Python) :

[source,python]
----
# prototype
weechat.buffer_clear(buffer)

# exemple
buffer = weechat.buffer_search("mon_extension", "mon_tampon")
if buffer != "":
    weechat.buffer_clear(buffer)
----

==== buffer_close

Fermer un tampon.

Prototype :

[source,C]
----
void weechat_buffer_close (struct t_gui_buffer *buffer);
----

Paramètres :

* _buffer_ : pointeur vers le tampon

Exemple en C :

[source,C]
----
struct t_gui_buffer *my_buffer = weechat_buffer_new ("mon_tampon",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
/* ... */
weechat_buffer_close (my_buffer);
----

Script (Python) :

[source,python]
----
# prototype
weechat.buffer_close(buffer)

# exemple
buffer = weechat.buffer_new("mon_tampon", "my_input_cb", "", "my_close_cb", "")
# ...
weechat.buffer_close(buffer)
----

==== buffer_merge

Mélanger 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 en C :

[source,C]
----
/* mélanger le tampon courant avec le tampon "core" */
weechat_buffer_merge (weechat_current_buffer (),
                      weechat_buffer_search_main ());
----

Script (Python) :

[source,python]
----
# prototype
weechat.buffer_merge(buffer, target_buffer)

# exemple
# mélanger le tampon courant avec le tampon "core"
weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())
----

==== buffer_unmerge

Supprimer 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 en C :

[source,C]
----
weechat_buffer_unmerge (weechat_current_buffer (), 1);
----

Script (Python) :

[source,python]
----
# prototype
weechat.buffer_unmerge(buffer, number)

# exemple
weechat.buffer_unmerge(weechat.current_buffer(), 1)
----

==== buffer_get_integer

Retourner 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)
** _layout_number_ : numéro du tampon sauvegardé dans le "layout"
** _layout_number_merge_order_ : ordre du tampon mélangé pour le "layout"
** _short_name_is_set_ : 1 si le nom court est défini, 0 si non défini
** _type_ : type de tampon (0 : formaté, 1 : contenu libre)
** _notify_ : niveau de notification du tampon
** _num_displayed_ : nombre de fenêtres affichant ce tampon
** _active_ : 2 si le tampon est le seul actif (mélangé), 1 si le tampon est
   actif, 0 si le tampon est mélangé et n'est pas sélectionné
** _hidden_ : 1 si le tampon est caché, sinon 0
   _(WeeChat ≥ 1.0)_
** _zoomed_ : 1 si le tampon est mélangé et zoomé, sinon 0
   _(WeeChat ≥ 1.0)_
** _print_hooks_enabled_ : 1 si les hooks "print" sont activés, sinon 0
** _day_change_ : 1 si les messages de changement de jour sont affichés, sinon 0
   _(WeeChat ≥ 0.4.3)_
** _clear_ : 1 si le tampon peut être effacé avec la commande `/buffer clear`,
   sinon 0 _(WeeChat ≥ 1.0)_
** _filter_ : 1 si les filtres sont activés sur le tampon, sinon 0
   _(WeeChat ≥ 1.0)_
** _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
** _nicklist_ : 1 si la liste de pseudos est activée, sinon 0
** _nicklist_case_sensitive_ : 1 si les pseudos sont sensibles à la casse,
   sinon 0
** _nicklist_max_length_ : longueur maximale d'un pseudo
** _nicklist_display_groups_ : 1 si les groupes sont affichés, sinon 0
** _nicklist_count_ : nombre de pseudos et groupes dans la liste de pseudos
** _nicklist_groups_count_ : nombre de groupes dans la liste de pseudos
** _nicklist_nicks_count_ : nombre de pseudos dans la liste de pseudos
** _nicklist_visible_count_ : nombre de pseudos/groupes affichés
** _input_ : 1 si la zone de saisie est activée, sinon 0
** _input_get_unknown_commands_ : 1 si les commandes inconnues sont envoyées
   au "callback input", sinon 0
** _input_size_ : taille de la zone de saisie (en octets)
** _input_length_ : longueur de la zone de saisie (nombre de caractères)
** _input_pos_ : position du curseur dans la zone de saisie
** _input_1st_display_ : premier caractère affiché à l'écran
** _num_history_ : nombre de commandes dans l'historique
** _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 en C :

[source,C]
----
weechat_printf (NULL, "mon numéro de tampon est : %d",
                weechat_buffer_get_integer (mon_tampon, "number"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.buffer_get_integer(buffer, property)

# exemple
weechat.prnt("", "mon numéro de tampon est : %d" % weechat.buffer_get_integer(my_buffer, "number"))
----

==== buffer_get_string

Retourner la valeur d'une propriété du tampon 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
** _full_name_ : nom complet du tampon ("extension.nom") _(WeeChat ≥ 0.3.7)_
** _short_name_ : nom court du tampon (note : utilisé pour l'affichage
   seulement et peut être changé par l'utilisateur, il ne doit pas être utilisé
   pour trouver le nom du tampon, utilisez à la place _name_, _full_name_ ou
   bien la variable locale _channel_)
** _title_ : titre du tampon
** _input_ : texte saisi
** _text_search_input_ : texte saisi sauvegardé avant la recherche de texte
** _highlight_words_ : liste des mots pour le highlight
** _highlight_regex_ : expression régulière POSIX étendue pour le highlight
** _highlight_tags_restrict_ : restreindre les highlights aux messages
   comportant ces étiquettes
** _highlight_tags_ : forcer le highlight pour les messages avec ces étiquettes
** _hotlist_max_level_nicks_ : niveau maximum pour la hotlist pour certains
   pseudos
** _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 en C :

[source,C]
----
weechat_printf (NULL, "nom / nom court du tampon sont : %s / %s",
                weechat_buffer_get_string (my_buffer, "name"),
                weechat_buffer_get_string (my_buffer, "short_name"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.buffer_get_string(buffer, property)

# exemple
weechat.prnt("", "nom / nom court du tampon sont : %s / %s"
    % (weechat.buffer_get_string(my_buffer, "name"),
    weechat.buffer_get_string(my_buffer, "short_name")))
----

==== buffer_get_pointer

Retourner la valeur d'une propriété sous forme d'un pointeur.

Prototype :

[source,C]
----
void *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)
** _highlight_regex_compiled_ : expression régulière _highlight_regex_ compilée

Valeur de retour :

* valeur de la propriété, sous forme de pointeur

Exemple en C :

[source,C]
----
weechat_printf (NULL, "pointeur vers l'extension de mon tampon : %lx",
                weechat_buffer_get_pointer (mon_tampon, "plugin"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.buffer_get_pointer(buffer, property)

# exemple
weechat.prnt("", "pointeur vers l'extension de mon tampon : %s" % weechat.buffer_get_pointer(my_buffer, "plugin"))
----

==== buffer_set

Affecter 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_ : nom de la propriété (voir le tableau ci-dessous)
* _value_ : nouvelle valeur pour la propriété

Propriétés :

[width="100%",cols="^2,4,8",options="header"]
|===
| Nom | Valeur | Description

| hotlist | "+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE,
  WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT, "-1" |
  "+" : 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é +
  "-1" : supprimer ce tampon de la hotlist _(WeeChat ≥ 1.0)_

| completion_freeze | "0" ou "1" |
  "0" : pas de gel de la complétion (valeur par défaut)
  (option globale, le pointeur vers le tampon n'est pas utilisé) +
  "1" : ne pas arrêter la complétion lorsque la ligne de commande est mise à
  jour (option globale, le pointeur vers le tampon n'est pas utilisé)

| unread | - |
  Définit le marqueur de données non lues après la dernière ligne du tampon

| display | "1" ou "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é

| hidden +
  _(WeeChat ≥ 1.0)_ | "0" ou "1" |
  "0" : démasquer le tampon +
  "1" : masquer le tampon

| 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); lorsque la valeur est "free",
  la propriété _clear_ est forcée à "0" _(WeeChat ≥ 1.0)_

| 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

| print_hooks_enabled | "0" ou "1" |
  "0" pour désactiver les hooks "print", "1" pour les activer
  (par défaut pour un nouveau tampon)

| day_change +
  _(WeeChat ≥ 0.4.3)_ | "0" ou "1" |
  "0" pour cacher les messages de changement de jour, "1" pour les voir
  (par défaut pour un nouveau tampon)

| clear +
  _(WeeChat ≥ 1.0)_ | "0" ou "1" |
  "0" pour empêcher l'utilisateur d'effacer le tampon avec la commande
  `/buffer clear`, "1" pour autoriser l'utilisateur à effacer le tampon (par
   défaut pour un nouveau tampon) (note : même lorsque la valeur est "0", le
   tampon peut toujours être effacé avec la fonction <<_buffer_clear,buffer_clear>>)

| filter +
  _(WeeChat ≥ 1.0)_ | "0" or "1" |
  "0" : désactiver les filtres sur le tampon +
  "1" : activer les filtres sur le tampon

| 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éciale 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_words_add | liste de mots séparés par des virgules |
  Liste de mots à mettre en valeur dans ce tampon, ces mots sont ajoutés aux
  mots existants pour le tampon

| highlight_words_del | liste de mots séparés par des virgules |
  Liste de mots à supprimer de la liste des mots à mettre en valeur dans ce
  tampon

| highlight_regex | toute chaîne |
  Expression régulière POSIX étendue pour le highlight

| highlight_tags_restrict | liste d'étiquettes séparées par des virgules |
  Restreindre les highlights aux messages avec ces étiquettes dans ce tampon
  (il est possible de combiner plusieurs étiquettes sous forme d'un "et" logique
  avec le séparateur "+", par exemple : "nick_toto+irc_action")

| highlight_tags | liste d'étiquettes séparées par des virgules |
  Forcer le highlight pour les messages avec ces étiquettes dans ce tampon
  (il est possible de combiner plusieurs étiquettes sous forme d'un "et" logique
  avec le séparateur "+", par exemple : "nick_toto+irc_action")

| hotlist_max_level_nicks | liste de "pseudo:niveau" séparés par des virgules |
  Liste de pseudos avec niveau max pour la hotlist sur ce tampon (le niveau peut
  être : -1 : jamais dans la hotlist, 0 : faible, 1 : message, 2 : privé,
  3 : highlight), par exemple : "joe:2,mike:-1,robert:-1" (joe ne produira
  jamais de highlight sur le tampon, mike et robert ne changeront jamais la
  hotlist)

| hotlist_max_level_nicks_add | liste de "pseudo:niveau" séparés par des virgules" |
  Liste de pseudos avec niveau pour la hotlist, ces pseudos sont ajoutés aux
  pseudos existant dans le tampon

| hotlist_max_level_nicks_del | liste de pseudos séparés par des virgules |
  Liste de pseudos à supprimer des niveaux max de hotlist

| 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 | - |
  Supprime la touche _xxx_ pour ce tampon

| input | toute chaîne |
  Change le contenu de la zone de saisie

| input_pos | position |
  Change la position du curseur dans 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 | - |
  Supprime la variable locale _xxx_
|===

Exemple en C :

[source,C]
----
/* désactiver la hotlist (pour tous les tampons) */
weechat_buffer_set (NULL, "hotlist", "-");

/* activer à nouveau la hotlist */
weechat_buffer_set (NULL, "hotlist", "+");

/* changer le nom du tampon */
weechat_buffer_set (mon_tampon, "name", "nouveau_nom");

/* ajouter une variable locale "toto" avec la valeur "abc" */
weechat_buffer_set (mon_tampon, "localvar_set_toto", "abc");

/* supprimer la variable locale "toto" */
weechat_buffer_set (mon_tampon, "localvar_del_toto", NULL);
----

Script (Python) :

[source,python]
----
# prototype
weechat.buffer_set(buffer, property, value)

# exemples

# désactiver la hotlist (pour tous les tampons)
weechat.buffer_set("", "hotlist", "-")

# activer à nouveau la hotlist
weechat.buffer_set("", "hotlist", "+")

# changer le nom du tampon
weechat.buffer_set(my_buffer, "name", "my_new_name")

# ajouter une variable locale "toto" avec la valeur "abc"
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")

# supprimer la variable locale "toto"
weechat.buffer_set(my_buffer, "localvar_del_toto", "")
----

==== buffer_set_pointer

Affecter 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_ : nom de la propriété :
** _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
** _nickcmp_callback_ : définit la fonction "callback" de comparaison de pseudos
   (ce "callback" est appelé lors de la recherche d'un pseudo dans la liste des
   pseudos) _(WeeChat ≥ 0.3.9)_
** _nickcmp_callback_data_ : définit les données pour le "callback" de
   comparaison de pseudos _(WeeChat ≥ 0.3.9)_
* _pointer_ : nouvelle valeur de pointeur pour la propriété

Prototypes pour les "callbacks" :

[source,C]
----
int close_callback (const void *pointer, void *data,
                    struct t_gui_buffer *buffer);

int input_callback (const void *pointer, void *data,
                    struct t_gui_buffer *buffer, const char *input_data);

int nickcmp_callback (const void *pointer, void *data,
                      struct t_gui_buffer *buffer,
                      const char *nick1, const char *nick2);
----

Exemple en C :

[source,C]
----
int
my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
{
    /* ... */
    return WEECHAT_RC_OK;
}

weechat_buffer_set_pointer (mon_tampon, "close_callback", &my_close_cb);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== buffer_string_replace_local_var

Remplacer 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 en C :

[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" */
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.buffer_string_replace_local_var(buffer, string)

# exemple
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")
str = weechat.buffer_string_replace_local_var(my_buffer, "test avec $toto")
# str contient "test avec abc"
----

==== buffer_match_list

_WeeChat ≥ 0.3.5._

Vérifier si le tampon correspond à la liste de tampons.

Prototype :

[source,C]
----
int weechat_buffer_match_list (struct t_gui_buffer *buffer, const char *string);
----

Paramètres :

* _buffer_ : pointeur vers le tampon
* _string_ : liste de tampons, séparés par des virgules :
** `+*+` signifie tous les tampons
** un nom commençant par `+!+` est exclu
** le caractère joker `+*+` est autorisé dans le nom

Valeur de retour :

* 1 si le tampon correspond à la liste de tampons, 0 sinon

Exemple en C :

[source,C]
----
struct t_gui_buffer *buffer = weechat_buffer_search ("irc", "freenode.#weechat");
if (buffer)
{
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*"));                    /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*,!*#weechat*"));        /* 0 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.freenode.*"));       /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.oftc.*,python.*"));  /* 0 */
}
----

Script (Python) :

[source,python]
----
# prototype
match = weechat.buffer_match_list(buffer, string)

# exemple
buffer = weechat.buffer_search("irc", "freenode.#weechat")
if buffer:
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*"))                    # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*,!*#weechat*"))        # 0
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.freenode.*"))       # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.oftc.*,python.*"))  # 0
----

[[windows]]
=== Fenêtres

Fonctions pour interroger les fenêtres.

==== current_window

Retourner 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 en C :

[source,C]
----
struct t_gui_window *current_window = weechat_current_window ();
----

Script (Python) :

[source,python]
----
# prototype
window = weechat.current_window()

# exemple
current_window = weechat.current_window()
----

==== window_search_with_buffer

_WeeChat ≥ 0.3.5._

Retourner le pointeur vers la fenêtre affichant un tampon.

Prototype :

[source,C]
----
struct t_gui_window *weechat_window_search_with_buffer (struct t_gui_buffer *buffer);
----

Paramètre :

* _buffer_ : pointeur vers le tampon

Valeur de retour :

* pointeur vers la fenêtre affichant un tampon (NULL si aucune fenêtre n'affiche
  ce tampon)

Exemple en C :

[source,C]
----
weechat_printf (NULL,
                "fenêtre affichant le tampon core : %lx",
                weechat_window_search_with_buffer (weechat_buffer_search_main ()));
----

Script (Python) :

[source,python]
----
# prototype
window = weechat.window_search_with_buffer(buffer)

# exemple
weechat.prnt("", "fenêtre affichant le tampon core : %s"
    % weechat.window_search_with_buffer(weechat.buffer_search_main()))
----

==== window_get_integer

Retourner 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é :
** _number_ : numéro de la fenêtre (commence à 1)
** _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
** _scrolling_ : 1 s'il y a un défilement en cours dans la fenêtre (la dernière
   ligne n'est pas affichée)
** _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 en C :

[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"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.window_get_integer(window, property)

# exemple
weechat.prnt("", "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")))
----

==== window_get_string

Retourner 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

==== window_get_pointer

Retourner 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 en C :

[source,C]
----
weechat_printf (NULL,
                "tampon affiché dans la fenêtre courante : %lx",
                weechat_window_get_pointer (weechat_current_window (), "buffer"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.window_get_pointer(window, property)

# exemple
weechat.prnt("", "tampon affiché dans la fenêtre courante : %s"
    % weechat.window_get_pointer(weechat.current_window(), "buffer"))
----

==== window_set_title

Définir le titre du terminal.

Prototype :

[source,C]
----
void weechat_window_set_title (const char *title);
----

Paramètres :

* _title_ : nouveau titre pour le terminal (NULL pour réinitialiser le titre) ;
  la chaîne est évaluée, donc les variables comme `${info:version}` peuvent
  être utilisées (voir <<_string_eval_expression,string_eval_expression>>)

Exemple en C :

[source,C]
----
weechat_window_set_title ("nouveau titre ici");
----

Script (Python) :

[source,python]
----
# prototype
weechat.window_set_title(window, title)

# exemple
weechat.window_set_title("nouveau titre ici")
----

[[nicklist]]
=== Nicklist

Fonctions pour la liste des pseudos.

==== nicklist_add_group

Ajouter 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
* _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
* _visible_ :
** _1_ : le groupe et ses sous-groupes/pseudos sont visibles
** _0_ : le groupe et ses sous-groupes/pseudos sont cachés

[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 en C :

[source,C]
----
struct t_gui_nick_group *my_group =
    weechat_nicklist_add_group (my_buffer,
                                my_parent_group,
                                "groupe_test",
                                "weechat.color.nicklist_group",
                                1);
----

Script (Python) :

[source,python]
----
# prototype
group = weechat.nicklist_add_group(buffer, parent_group, name, color, visible)

# exemple
group = weechat.nicklist_add_group(my_buffer, my_parent_group, "groupe_test",
    "weechat.color.nicklist_group", 1)
----

==== nicklist_search_group

Rechercher 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 en C :

[source,C]
----
struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer,
                                                                    NULL, "groupe_test");
----

Script (Python) :

[source,python]
----
# prototype
group = weechat.nicklist_search_group(buffer, from_group, name)

# exemple
group = weechat.nicklist_search_group(my_buffer, "", "groupe_test")
----

==== nicklist_add_nick

Ajouter 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 en C :

[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);
----

Script (Python) :

[source,python]
----
# prototype
nick = weechat.nicklist_add_nick(buffer, group, name, color, prefix, prefix_color, visible)

# exemple
if nick_away:
    color = "weechat.color.nicklist_away"
else:
    color = "bar_fg"
nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)
----

==== nicklist_search_nick

Rechercher 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 en C :

[source,C]
----
struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer,
                                                            NULL, "test_nick");
----

Script (Python) :

[source,python]
----
# prototype
nick = weechat.nicklist_search_nick(buffer, from_group, name)

# exemple
nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick")
----

==== nicklist_remove_group

Supprimer 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 en C :

[source,C]
----
weechat_nicklist_remove_group (my_buffer, my_group);
----

Script (Python) :

[source,python]
----
# prototype
weechat.nicklist_remove_group(buffer, group)

# exemple
weechat.nicklist_remove_group(my_buffer, my_group)
----

==== nicklist_remove_nick

Supprimer 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 en C :

[source,C]
----
weechat_nicklist_remove_nick (my_buffer, my_nick);
----

Script (Python) :

[source,python]
----
# prototype
weechat.nicklist_remove_nick(buffer, nick)

# exemple
weechat.nicklist_remove_nick(my_buffer, my_nick)
----

==== nicklist_remove_all

Supprimer 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 en C :

[source,C]
----
weechat_nicklist_remove_all (my_buffer);
----

Script (Python) :

[source,python]
----
# prototype
weechat.nicklist_remove_all(buffer)

# exemple
weechat.nicklist_remove_all(my_buffer)
----

==== nicklist_get_next_item

_WeeChat ≥ 0.3.7._

Retourner le prochain groupe ou pseudo de la liste des pseudos (utilisé
principalement pour afficher la liste des pseudos).

Prototype :

[source,C]
----
void weechat_nicklist_get_next_item (struct t_gui_buffer *buffer,
                                     struct t_gui_nick_group **group,
                                     struct t_gui_nick **nick);
----

Paramètres :

* _buffer_ : pointeur vers le tampon
* _group_ : pointeur vers un pointeur sur le groupe
* _nick_ : pointeur vers un pointeur sur le pseudo

Exemple en C :

[source,C]
----
struct t_gui_nick_group *ptr_group;
struct t_gui_nick *ptr_nick;

ptr_group = NULL;
ptr_nick = NULL;
weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
while (ptr_group || ptr_nick)
{
    if (ptr_nick)
    {
        /* pseudo */
        /* ... */
    }
    else
    {
        /* groupe */
        /* ... */
    }
    weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== nicklist_group_get_integer

_WeeChat ≥ 0.3.4._

Retourner une valeur entière pour une propriété du groupe.

Prototype :

[source,C]
----
int weechat_nicklist_group_get_integer (struct t_gui_buffer *buffer,
                                        struct t_gui_nick_group *group,
                                        const char *property);
----

Paramètres :

* _buffer_ : pointeur vers le tampon
* _group_ : pointeur vers le groupe
* _property_ : nom de la propriété :
** _visible_ : 1 si le groupe est visible, sinon 0
** _level_ : niveau du groupe (la racine est 0)

Valeur de retour :

* valeur entière de la propriété

Exemple en C :

[source,C]
----
int visible = weechat_nicklist_group_get_integer (buffer, group, "visible");
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.nicklist_group_get_integer(buffer, group, property)

# exemple
visible = weechat.nicklist_group_get_integer(buffer, group, "visible")
----

==== nicklist_group_get_string

_WeeChat ≥ 0.3.4._

Retourner la valeur d'une propriété du groupe sous forme de chaîne.

Prototype :

[source,C]
----
const char *weechat_nicklist_group_get_string (struct t_gui_buffer *buffer,
                                               struct t_gui_nick_group *group,
                                               const char *property);
----

Paramètres :

* _buffer_ : pointeur vers le tampon
* _group_ : pointeur vers le groupe
* _property_ : nom de la propriété :
** _name_ : nom du groupe
** _color_ : couleur du groupe dans la liste des pseudos

Valeur de retour :

* valeur de la propriété, sous forme de chaîne

Exemple en C :

[source,C]
----
const char *color = weechat_nicklist_group_get_string (buffer, group, "color");
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.nicklist_group_get_string(buffer, group, property)

# exemple
color = weechat.nicklist_group_get_string(buffer, group, "color")
----

==== nicklist_group_get_pointer

_WeeChat ≥ 0.3.4._

Retourner la valeur d'une propriété du groupe sous forme d'un pointeur.

Prototype :

[source,C]
----
void *weechat_nicklist_group_get_pointer (struct t_gui_buffer *buffer,
                                          struct t_gui_nick_group *group,
                                          const char *property);
----

Paramètres :

* _buffer_ : pointeur vers le tampon
* _group_ : pointeur vers le groupe
* _property_ : nom de la propriété :
** _parent_ : pointeur vers le groupe parent

Valeur de retour :

* valeur de la propriété, sous forme de pointeur

Exemple en C :

[source,C]
----
struct t_gui_nick_group *parent = weechat_nicklist_group_get_pointer (buffer, group, "parent");
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.nicklist_group_get_pointer(buffer, group, property)

# exemple
parent = weechat.nicklist_group_get_pointer(buffer, group, "parent")
----

==== nicklist_group_set

_WeeChat ≥ 0.3.4._

Affecter une valeur à une propriété d'un groupe.

Prototype :

[source,C]
----
void weechat_nicklist_group_set (struct t_gui_buffer *buffer,
                                 struct t_gui_nick_group *group,
                                 const char *property,
                                 const char *value);
----

Paramètres :

* _buffer_ : pointeur vers le tampon
* _group_ : pointeur vers le groupe
* _property_ : nom de la propriété (voir le tableau ci-dessous)
* _value_ : nouvelle valeur pour la propriété

Propriétés :

[width="100%",cols="^2,4,8",options="header"]
|===
| Nom | Valeur | Description

| color | nom d'option de couleur WeeChat |
  Voir le paramètre "color" de la fonction
  <<_nicklist_add_group,nicklist_add_group>>

| visible | "0", "1" |
  "0" = groupe caché, "1" = groupe visible
|===

Exemples en C :

[source,C]
----
/* changer la couleur du groupe en "bar_fg" */
weechat_nicklist_group_set (buffer, group, "color", "bar_fg");

/* changer la couleur du groupe en jaune */
weechat_nicklist_group_set (buffer, group, "color", "yellow");

/* cacher le groupe dans la liste des pseudos */
weechat_nicklist_group_set (buffer, group, "visible", "0");
----

Script (Python) :

[source,python]
----
# prototype
weechat.nicklist_group_set(buffer, group, property, value)

# exemples

# changer la couleur du groupe en "bar_fg"
weechat.nicklist_group_set(buffer, group, "color", "bar_fg")

# changer la couleur du groupe en jaune
weechat.nicklist_group_set(buffer, group, "color", "yellow")

# cacher le groupe dans la liste des pseudos
weechat.nicklist_group_set(buffer, group, "visible", "0")
----

==== nicklist_nick_get_integer

_WeeChat ≥ 0.3.4._

Retourner une valeur entière pour une propriété du pseudo.

Prototype :

[source,C]
----
int weechat_nicklist_nick_get_integer (struct t_gui_buffer *buffer,
                                       struct t_gui_nick *nick,
                                       const char *property);
----

Paramètres :

* _buffer_ : pointeur vers le tampon
* _nick_ : pointeur vers le pseudo
* _property_ : nom de la propriété :
** _visible_ : 1 si le pseudo est visible, sinon 0

Valeur de retour :

* valeur entière de la propriété

Exemple en C :

[source,C]
----
int visible = weechat_nicklist_nick_get_integer (buffer, nick, "visible");
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.nicklist_nick_get_integer(buffer, nick, property)

# exemple
visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible")
----

==== nicklist_nick_get_string

_WeeChat ≥ 0.3.4._

Retourner la valeur d'une propriété du pseudo sous forme de chaîne.

Prototype :

[source,C]
----
const char *weechat_nicklist_nick_get_string (struct t_gui_buffer *buffer,
                                              struct t_gui_nick *nick,
                                              const char *property);
----

Paramètres :

* _buffer_ : pointeur vers le tampon
* _nick_ : pointeur vers le pseudo
* _property_ : nom de la propriété :
** _name_ : nom du pseudo
** _color_ : couleur du pseudo dans la liste des pseudos
** _prefix_ : préfixe du pseudo
** _prefix_color_ : couleur du préfixe dans la liste des pseudos

Valeur de retour :

* valeur de la propriété, sous forme de chaîne

Exemple en C :

[source,C]
----
const char *color = weechat_nicklist_nick_get_string (buffer, nick, "color");
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.nicklist_nick_get_string(buffer, nick, property)

# exemple
color = weechat.nicklist_nick_get_string(buffer, nick, "color")
----

==== nicklist_nick_get_pointer

_WeeChat ≥ 0.3.4._

Retourner la valeur d'une propriété du pseudo sous forme d'un pointeur.

Prototype :

[source,C]
----
void *weechat_nicklist_nick_get_pointer (struct t_gui_buffer *buffer,
                                         struct t_gui_nick *nick,
                                         const char *property);
----

Paramètres :

* _buffer_ : pointeur vers le tampon
* _nick_ : pointeur vers le pseudo
* _property_ : nom de la propriété :
** _group_ : pointeur vers le groupe contenant ce pseudo

Valeur de retour :

* valeur de la propriété, sous forme de pointeur

Exemple en C :

[source,C]
----
struct t_gui_nick_group *group = weechat_nicklist_nick_get_pointer (buffer, nick, "group");
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.nicklist_nick_get_pointer(buffer, nick, property)

# exemple
group = weechat.nicklist_nick_get_pointer(buffer, nick, "group")
----

==== nicklist_nick_set

_WeeChat ≥ 0.3.4._

Affecter une valeur à une propriété d'un pseudo.

Prototype :

[source,C]
----
void weechat_nicklist_nick_set (struct t_gui_buffer *buffer,
                                struct t_gui_nick *nick,
                                const char *property,
                                const char *value);
----

Paramètres :

* _buffer_ : pointeur vers le tampon
* _nick_ : pointeur vers le pseudo
* _property_ : nom de la propriété (voir le tableau ci-dessous)
* _value_ : nouvelle valeur pour la propriété

Propriétés :

[width="100%",cols="^2,4,8",options="header"]
|===
| Nom | Valeur | Description

| color | nom d'option de couleur WeeChat |
  Voir le paramètre "color" de la fonction
  <<_nicklist_add_nick,nicklist_add_nick>>

| prefix | toute chaîne |
  Préfixe du pseudo

| prefix_color | nom d'option de couleur WeeChat |
  Voir le paramètre "prefix_color" de la fonction
  <<_nicklist_add_nick,nicklist_add_nick>>

| visible | "0", "1" |
  "0" = pseudo caché, "1" = pseudo visible
|===

Exemples en C :

[source,C]
----
/* changer la couleur du pseudo en cyan */
weechat_nicklist_nick_set (buffer, nick, "color", "cyan");

/* changer le préfixe en "+" */
weechat_nicklist_nick_set (buffer, nick, "prefix", "+");

/* changer la couleur du préfixe en jaune */
weechat_nicklist_nick_set (buffer, nick, "prefix_color", "yellow");

/* cacher le pseudo dans la liste des pseudos */
weechat_nicklist_nick_set (buffer, nick, "visible", "0");
----

Script (Python) :

[source,python]
----
# prototype
weechat.nicklist_nick_set(buffer, nick, property, value)

# exemples

# changer la couleur du pseudo en cyan
weechat.nicklist_nick_set(buffer, nick, "color", "cyan")

# changer le préfixe en "+"
weechat.nicklist_nick_set(buffer, nick, "prefix", "+")

# changer la couleur du préfixe en jaune
weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow")

# cacher le pseudo dans la liste des pseudos
weechat.nicklist_nick_set(buffer, nick, "visible", "0")
----

[[bars]]
=== Barres

Fonctions pour les barres.

==== bar_item_search

Rechercher 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 en C :

[source,C]
----
struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");
----

Script (Python) :

[source,python]
----
# prototype
bar_item = weechat.bar_item_search(name)

# exemple
bar_item = weechat.bar_item_search("myitem")
----

==== bar_item_new

_Mis à jour dans la 0.4.2, 1.5._

Créer un nouvel objet de barre.

Prototype :

[source,C]
----
struct t_gui_bar_item *weechat_bar_item_new (const char *name,
                                             char *(*build_callback)(const void *pointer,
                                                                     void *data,
                                                                     struct t_gui_bar_item *item,
                                                                     struct t_gui_window *window,
                                                                     struct t_gui_buffer *buffer,
                                                                     struct t_hashtable *extra_info),
                                             const void *build_callback_pointer,
                                             void *build_callback_data);
----

Paramètres :

* _name_ : nom de l'objet de barre
* _build_callback_ : fonction appelée lorsque l'objet est construit, paramètres
  et valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_gui_bar_item *item_ : pointeur vers l'objet de barre
** _struct t_gui_window *window_ : pointeur vers la fenêtre (NULL lors d'un
   appel pour une barre "root")
** _struct t_gui_buffer *buffer_ : tampon affiché dans la fenêtre (si la fenêtre
   est NULL alors c'est le tampon courant) ou tampon passé dans l'objet de
   barre avec la syntaxe : "@buffer:item" _(WeeChat ≥ 0.4.2)_
** _struct t_hashtable *extra_info_ : toujours NULL (le paramètre est réservé
   pour une version future) _(WeeChat ≥ 0.4.2)_
** valeur de retour : contenu de l'objet de barre
* _build_callback_pointer_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat
* _build_callback_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque l'objet de barre
  est supprimé

Valeur de retour :

* pointeur vers le nouvel objet de barre, NULL en cas d'erreur

Exemple en C :

[source,C]
----
char *
my_build_callback (const void *pointer, void *data,
                   struct t_gui_bar_item *item,
                   struct t_gui_window *window,
                   struct t_gui_buffer *buffer,
                   struct t_hashtable *extra_info)
{
    return strdup ("mon contenu");
}

struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                       &my_build_callback,
                                                       NULL, NULL);
----

Script (Python) :

[IMPORTANT]
Pour la compatibilité avec les versions ≤ 0.4.1, le "callback" par défaut a
seulement 3 paramètres : _data_, _item_ et _window_ (pas de _buffer_ et
_extra_info_). +
Pour utiliser le callback avec tous les paramètres, vous devez ajouter "(extra)"
avant le nom, voir l'exemple ci-dessous (supporté seulement dans
WeeChat ≥ 0.4.2).

[source,python]
----
# prototype
bar_item = weechat.bar_item_new(name, build_callback, build_callback_data)

# exemple (callback sans "buffer" et "extra_info")
def my_build_callback(data, item, window):
    return "mon contenu"

bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")

# example (callback avec tous les paramètres, pour WeeChat ≥ 0.4.2)
def my_build_callback2(data, item, window, buffer, extra_info):
    return "mon contenu"

bar_item2 = weechat.bar_item_new("(extra)myitem2", "my_build_callback2", "")  # WeeChat ≥ 0.4.2
----

==== bar_item_update

Mettre à 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 en C :

[source,C]
----
weechat_bar_item_update ("myobjet");
----

Script (Python) :

[source,python]
----
# prototype
weechat.bar_item_update(name)

# exemple
weechat.bar_item_update("myitem")
----

==== bar_item_remove

Supprimer 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 en C :

[source,C]
----
weechat_bar_item_remove (&my_item);
----

Script (Python) :

[source,python]
----
# prototype
weechat.bar_item_remove(item)

# exemple
weechat.bar_item_remove(myitem)
----

==== bar_search

Rechercher une barre.

Prototype :

[source,C]
----
struct t_gui_bar *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 en C :

[source,C]
----
struct t_gui_bar *bar = weechat_bar_search ("my_barre");
----

Script (Python) :

[source,python]
----
# prototype
bar = weechat.bar_search(name)

# exemple
bar = weechat.bar_search("mybar")
----

==== bar_new

Créer 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
** expression évaluée : voir le chapitre sur les barres dans le
   _Guide utilisateur WeeChat_
* _position_ : _top_ (en haut), _bottom_ (en bas), _left_ (à gauche) ou _right_
  (à droite)
* _filling_top_bottom_ :
** _horizontal_ : les objets sont remplis horizontalement (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 horizontalement, 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 horizontalement (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 horizontalement, 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 virgule (espace
  entre les objets), ou "+" (objets collés)

Valeur de retour :

* pointeur vers la nouvelle barre, NULL en cas d'erreur

Exemple en C :

[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");
----

Script (Python) :

[source,python]
----
# prototype
bar = weechat.bar_new(name, hidden, priority, type, condition, position,
    filling_top_bottom, filling_left_right, size, size_max,
    color_fg, color_delim, color_bg, separator, items)

# exemple
bar = weechat.bar_new("mybar", "off", "100", "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "off", "time,buffer_number+buffer_name")
----

==== bar_set

Affecter 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 :

* _bar_ : pointeur vers 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 <<_bar_new,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 en C :

[source,C]
----
weechat_bar_set (my_bar, "position", "bottom");
----

Script (Python) :

[source,python]
----
# prototype
weechat.bar_set(bar, property, value)

# exemple
weechat.bar_set(my_bar, "position", "bottom")
----

==== bar_update

Mettre à 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 en C :

[source,C]
----
weechat_bar_update ("mybar");
----

Script (Python) :

[source,python]
----
# prototype
weechat.bar_update(name)

# exemple
weechat.bar_update("mybar")
----

==== bar_remove

Supprimer une barre.

Prototype :

[source,C]
----
void weechat_bar_remove (struct t_gui_bar *bar);
----

Paramètres :

* _bar_ : pointeur vers la barre

Exemple en C :

[source,C]
----
weechat_bar_remove (my_bar);
----

Script (Python) :

[source,python]
----
# prototype
weechat.bar_remove(bar)

# exemple
weechat.bar_remove(my_bar)
----

[[commands]]
=== Commandes

Fonctions pour exécuter des commandes WeeChat.

==== command

_Mis à jour dans la 1.1._

Exécuter une commande ou envoyer du texte au tampon.

Prototype :

[source,C]
----
int 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 courant)
* _command_ : commande à exécuter (si elle commence par "/"), ou texte à
  envoyer au tampon

Valeur de retour : (_WeeChat ≥ 1.1_)

* _WEECHAT_RC_OK_ si ok
* _WEECHAT_RC_ERROR_ si erreur

Exemple en C :

[source,C]
----
int rc;
rc = weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"),
                      "/whois FlashCode");
----

Script (Python) :

[source,python]
----
# prototype
weechat.command(buffer, command)

# exemple
rc = weechat.command(weechat.buffer_search("irc", "freenode.#weechat"), "/whois FlashCode")
----

[[network]]
=== Réseau

Fonctions pour le réseau.

==== network_pass_proxy

Établir une connexion/authentification avec un proxy.

[IMPORTANT]
Cette fonction est bloquante sur l'appel à connect(), donc elle doit être
appelée sans un processus issu d'un "fork", pour ne pas bloquer WeeChat.

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_ : adresse (nom de machine ou adresse IP)
* _port_ : port

Valeur de retour :

* 1 si la connexion est ok, 0 en cas d'erreur

Exemple en C :

[source,C]
----
if (weechat_network_pass_proxy ("mon_proxy", sock, "chat.freenode.net", 6667))
{
    /* OK */
}
else
{
    /* erreur */
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== network_connect_to

_Mis à jour dans la 0.4.3._

Établir une connexion à une machine distante.

[IMPORTANT]
Cette fonction est bloquante sur l'appel à connect(), donc elle doit être
appelée sans un processus issu d'un "fork", pour ne pas bloquer WeeChat.

Prototype :

[source,C]
----
int weechat_network_connect_to (const char *proxy,
                                struct sockaddr *address,
                                socklen_t address_length);
----

Paramètres :

* _proxy_ : nom du proxy à utiliser
* _address_ : adresse où se connecter (avec le port)
* _address_length_ : longueur du paramètre _address_

Valeur de retour :

* numéro de socket (>= 0) si la connexion est OK, -1 en cas d'erreur

Exemple en C :

[source,C]
----
struct sockaddr *addr;
socklen_t length;
int sock;

/* allouer/définir l'adresse et le port dans 'addr', définir 'length' */
/* ... */

sock = weechat_network_connect_to (NULL, addr, length);
if (sock >= 0)
{
    /* OK */
}
else
{
    /* erreur */
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

[[infos]]
=== Infos

Fonctions pour obtenir des informations.

==== info_get

Retourner une information, sous forme de chaîne, 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 (voir le tableau ci-dessous)
* _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

Infos :

include::autogen/plugin_api/infos.adoc[]

Exemple en C :

[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", NULL));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.info_get(info_name, arguments)

# exemple
weechat.prnt("", "La version de WeeChat est : %s (compilée le %s)"
    % (weechat.info_get("version", ""), weechat.info_get("date", ""))
weechat.prnt("", "Le répertoire de WeeChat est : %s" % weechat.info_get("weechat_dir", ""))
----

==== info_get_hashtable

_WeeChat ≥ 0.3.4._

Retourner une information, sous forme de table de hachage, de WeeChat ou d'une
extension.

Prototype :

[source,C]
----
struct t_hashtable *weechat_info_get_hashtable (const char *info_name,
                                                struct t_hashtable *hashtable);
----

Paramètres :

* _info_name_ : nom de l'information à lire (voir le tableau ci-dessous)
* _hashtable_ : table de hachage avec les paramètres (dépendant de l'information
  demandée) (optionnel, NULL si aucun paramètre n'est nécessaire)

Valeur de retour :

* table de hachage avec l'information demandée, NULL en cas d'erreur

Infos :

include::autogen/plugin_api/infos_hashtable.adoc[]

Exemple en C :

[source,C]
----
struct t_hashtable *hashtable_in, *hashtable_out;

hashtable_in = weechat_hashtable_new (8,
                                      WEECHAT_HASHTABLE_STRING,
                                      WEECHAT_HASHTABLE_STRING,
                                      NULL,
                                      NULL);
if (hashtable_in)
{
    weechat_hashtable_set (
        hashtable_in,
        "message",
        "@time=2015-06-27T16:40:35.000Z :nick!user@host PRIVMSG #weechat :hello!");
    hashtable_out = weechat_info_get_hashtable ("irc_message_parse",
                                                hashtable_in);
    /*
     * maintenant hashtable_out a les clés/valeurs suivantes :
     *   "tags"                : "time=2015-06-27T16:40:35.000Z"
     *   "message_without_tags": ":nick!user@host PRIVMSG #weechat :hello!"
     *   "nick"                : "nick"
     *   "host"                : "nick!user@host"
     *   "command"             : "PRIVMSG"
     *   "channel"             : "#weechat"
     *   "arguments"           : "#weechat :hello!"
     *   "text"                : "hello!"
     *   "pos_command"         : "47"
     *   "pos_arguments"       : "55"
     *   "pos_channel"         : "55"
     *   "pos_text"            : "65"
     */
    weechat_hashtable_free (hashtable_in);
    weechat_hashtable_free (hashtable_out);
}
----

[NOTE]
Voir le _Guide pour Scripts WeeChat_ pour plus d'infos sur la sortie de
"irc_message_parse".

Script (Python) :

[source,python]
----
# prototype
dict = weechat.info_get_hashtable(info_name, dict_in)

# exemple
dict_in = {"message": ":nick!user@host PRIVMSG #weechat :message ici"}
weechat.prnt("", "message analysé : %s"
             % weechat.info_get_hashtable("irc_message_parse", dict_in))
----

[[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 contenir n'importe quel type de
  données
* _time_ : date/heure

==== infolist_new

Créer une "infolist".

Prototype :

[source,C]
----
struct t_infolist *weechat_infolist_new ();
----

Valeur de retour :

* pointeur vers la nouvelle "infolist"

Exemple en C :

[source,C]
----
struct t_infolist *infolist = weechat_infolist_new ();
----

Script (Python) :

[source,python]
----
# prototype
infolist = weechat.infolist_new()

# exemple
infolist = weechat.infolist_new()
----

==== infolist_new_item

Ajouter 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 en C :

[source,C]
----
struct t_infolist_item *item = weechat_infolist_new_item (infolist);
----

Script (Python) :

[source,python]
----
# prototype
item = weechat.infolist_new_item(infolist)

# exemple
item = weechat.infolist_new_item(infolist)
----

==== infolist_new_var_integer

Ajouter 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 en C :

[source,C]
----
struct t_infolist_var *var = weechat_infolist_new_var_integer (item,
                                                               "mon_entier",
                                                               123);
----

Script (Python) :

[source,python]
----
# prototype
var = weechat.infolist_new_var_integer(item, name, value)

# exemple
var = weechat.infolist_new_var_integer(item, "mon_entier", 123)
----

==== infolist_new_var_string

Ajouter 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 en C :

[source,C]
----
struct t_infolist_var *var = weechat_infolist_new_var_string (item,
                                                              "ma_chaine",
                                                              "valeur");
----

Script (Python) :

[source,python]
----
# prototype
var = weechat.infolist_new_var_string(item, name, value)

# exemple
var = weechat.infolist_new_var_string(item, "ma_chaine", "valeur")
----

==== infolist_new_var_pointer

Ajouter 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 en C :

[source,C]
----
struct t_infolist_var *var = weechat_infolist_new_var_pointer (item,
                                                               "mon_pointeur",
                                                               &pointer);
----

Script (Python) :

[source,python]
----
# prototype
var = weechat.infolist_new_var_pointer(item, name, pointer)

# exemple
var = weechat.infolist_new_var_pointer(item, "mon_pointeur", pointer)
----

==== infolist_new_var_buffer

Ajouter 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 en C :

[source,C]
----
char buffer[256];
/* ... */
struct t_infolist_var *var = weechat_infolist_new_var_buffer (item,
                                                              "mon_buffer",
                                                              buffer,
                                                              sizeof (buffer));
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== infolist_new_var_time

Ajouter 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 en C :

[source,C]
----
struct t_infolist_var *var = weechat_infolist_new_var_time (item,
                                                            "mon_time",
                                                            time (NULL));
----

Script (Python) :

[source,python]
----
# prototype
var = weechat.infolist_new_var_time(item, name, time)

# exemple
var = weechat.infolist_new_var_time(item, "mon_time", int(time.time()))
----

==== infolist_get

Retourner une "infolist" de WeeChat ou d'une extension.

[IMPORTANT]
Le contenu d'une infolist est une duplication des données réelles. Donc si vous
demandez une infolist avec beaucoup de données (comme "buffer_lines"), WeeChat
allouera de la mémoire pour dupliquer toutes les données, et cela peut prendre
du temps. +
Au lieu d'utiliser une grosse infolist, il est préférable d'utiliser un hdata
(mais l'infolist peut contenir plus de données que le hdata, qui contient des
données brutes), voir <<hdata,hdata>>.

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 (voir le tableau ci-dessous)
* _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

Infolists :

include::autogen/plugin_api/infolists.adoc[]

Exemple en C :

[source,C]
----
struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
infolist = weechat.infolist_get(infolist_name, pointer, arguments)

# exemple
infolist = weechat.infolist_get("irc_server", "", "")
----

==== infolist_next

Déplacer 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 en C :

[source,C]
----
if (weechat_infolist_next (infolist))
{
    /* lecture des variables dans l'objet... */
}
else
{
    /* pas d'autre objet disponible */
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.infolist_next(infolist)

# exemple
rc = weechat.infolist_next(infolist)
if rc:
    # lecture des variables dans l'objet...
else:
    # pas d'autre objet disponible
----

==== infolist_prev

Déplacer 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 en C :

[source,C]
----
if (weechat_infolist_prev (infolist))
{
    /* lecture des variables dans l'objet... */
}
else
{
    /* pas d'autre objet disponible */
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.infolist_prev(infolist)

# exemple
rc = weechat.infolist_prev(infolist)
if rc:
    # lecture des variables dans l'objet
else:
    # pas d'autre objet disponible
----

==== infolist_reset_item_cursor

Réinitialiser 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 en C :

[source,C]
----
weechat_infolist_reset_item_cursor (infolist);
----

Script (Python) :

[source,python]
----
# prototype
weechat.infolist_reset_item_cursor(infolist)

# exemple
weechat.infolist_reset_item_cursor(infolist)
----

==== infolist_search_var

_WeeChat ≥ 0.4.3._

Chercher une variable dans l'objet courant de l'infolist.

Prototype :

[source,C]
----
struct t_infolist_var *weechat_infolist_search_var (struct t_infolist *infolist,
                                                    const char *name);
----

Paramètres :

* _infolist_ : pointeur vers l'infolist
* _name_ : nom de la variable

Valeur de retour :

* pointeur vers la variable trouvée, NULL si la variable n'est pas trouvée

Exemple en C :

[source,C]
----
if (weechat_infolist_search_var (infolist, "name"))
{
    /* la variable "name" existe */
    /* ... */
}
----

Script (Python) :

[source,python]
----
# prototype
var = weechat.infolist_search_var(infolist, name)

# exemple
if weechat.infolist_search_var(infolist, "name"):
    # la variable "name" existe
    # ...
----

==== infolist_fields

Retourner 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 en C :

[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" */
----

Script (Python) :

[source,python]
----
# prototype
fields = weechat.infolist_fields(infolist)

# exemple
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"
----

==== infolist_integer

Retourner 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 en C :

[source,C]
----
weechat_printf (NULL, "entier = %d",
                weechat_infolist_integer (infolist, "mon_entier"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.infolist_integer(infolist, var)

# exemple
weechat.prnt("", "entier = %d" % weechat.infolist_integer(infolist, "mon_entier"))
----

==== infolist_string

Retourner 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 en C :

[source,C]
----
weechat_printf (NULL, "chaîne = %s",
                weechat_infolist_string (infolist, "ma_chaine"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.infolist_string(infolist, var)

# exemple
weechat.prnt("", "chaîne = %s" % weechat.infolist_string(infolist, "ma_chaine"))
----

==== infolist_pointer

Retourner 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 en C :

[source,C]
----
weechat_printf (NULL, "pointeur = 0x%lx",
                weechat_infolist_pointer (infolist, "mon_pointeur"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.infolist_pointer(infolist, var)

# exemple
weechat.prnt("", "pointeur = 0x%s" % weechat.infolist_pointer(infolist, "mon_pointeur"))
----

==== infolist_buffer

Retourner la valeur de la variable de l'objet courant de l'infolist, sous forme
de tampon de données.

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 tampon de données

Exemple en C :

[source,C]
----
int size;
void *pointer = weechat_infolist_buffer (infolist, "mon_buffer", &size);
weechat_printf (NULL, "buffer = 0x%lx, taille = %d",
                pointer, size);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== infolist_time

Retourner 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 en C :

[source,C]
----
weechat_printf (NULL, "date/heure = %ld",
                weechat_infolist_time (infolist, "mon_time"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.infolist_time(infolist, var)

# exemple
weechat.prnt("", "date/heure = %ld" % weechat.infolist_time(infolist, "mon_time"))
----

==== infolist_free

Supprimer une infolist.

Prototype :

[source,C]
----
void weechat_infolist_free (struct t_infolist *infolist);
----

Paramètres :

* _infolist_ : pointeur vers l'infolist

Exemple en C :

[source,C]
----
weechat_infolist_free (infolist);
----

Script (Python) :

[source,python]
----
# prototype
weechat.infolist_free(infolist)

# exemple
weechat.infolist_free(infolist)
----

[[hdata]]
=== Hdata

Fonctions pour les hdata (accès brut aux données de WeeChat ou des extensions).

[IMPORTANT]
Le "hdata" fournit seulement un accès en lecture seule aux données. Il est
*STRICTEMENT INTERDIT* d'écrire quelque chose dans une zone mémoire pointée par
les variables du hdata. +
Le seul moyen pour mettre à jour des données est d'appeler la fonction
<<_hdata_update,hdata_update>>.

==== hdata_new

_WeeChat ≥ 0.3.6, mis à jour dans la 0.3.9 et 0.4.0._

Créer un "hdata".

[NOTE]
.hdata vs infolist
====
Le "hdata" est un moyen rapide de lire des données de WeeChat ou des extensions.
Il est similaire à l'infolist, mais il y a quelques différences :

* il est plus rapide et utilise moins de mémoire : accès direct aux données sans
  duplication
* il peut contenir des informations différentes de l'infolist : il contient
  seulement les données brutes des structures (l'infolist peut ajouter des
  données supplémentaires pour plus de commodité)
====

Prototype :

[source,C]
----
struct t_hdata *weechat_hdata_new (const char *hdata_name, const char *var_prev, const char *var_next,
                                   int create_allowed, int delete_allowed,
                                   int (*callback_update)(void *data,
                                                          struct t_hdata *hdata,
                                                          void *pointer,
                                                          struct t_hashtable *hashtable),
                                   void *callback_update_data);
----

Paramètres :

* _hdata_name_ : nom du hdata
* _var_prev_ : nom de la variable dans la structure qui est un pointeur vers
  l'élément précédent dans la liste (peut être NULL si une telle variable
  n'existe pas)
* _var_next_ : nom de la variable dans la structure qui est un pointeur vers
  l'élément suivant dans la liste (peut être NULL si une telle variable
  n'existe pas)
* _create_allowed_ : 1 si la création de structure est autorisée, sinon 0
  _(WeeChat ≥ 0.4.0)_
* _delete_allowed_ : 1 si la suppression de structure est autorisée, sinon 0
  _(WeeChat ≥ 0.3.9)_
* _callback_update_ : fonction appelée pour mettre à jour des données dans le
  hdata, peut être NULL si aucune mise à jour n'est autorisée
  _(WeeChat ≥ 0.3.9)_, paramètres et valeur de retour :
** _void *data_ : pointeur
** _struct t_hdata *hdata_ : pointeur vers le hdata
** _struct t_hashtable *hashtable_ : table de hachage avec les variables à
   mettre à jour (voir <<_hdata_update,hdata_update>>)
** valeur de retour : nombre de variables mises à jour
* _callback_update_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat _(WeeChat ≥ 0.3.9)_

Valeur de retour :

* pointeur vers le nouveau "hdata"

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next", 0, 0, &callback_update, NULL);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hdata_new_var

_WeeChat ≥ 0.3.6._

Créer une nouvelle variable dans le hdata.

Prototype :

[source,C]
----
void weechat_hdata_new_var (struct t_hdata *hdata, const char *name, int offset, int type,
                            int update_allowed, const char *array_size, const char *hdata_name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _name_ : nom de la variable
* _offset_ : position (offset) de la variable dans la structure
* _type_ : type de la variable, un parmi ceux-ci :
** WEECHAT_HDATA_CHAR
** WEECHAT_HDATA_INTEGER
** WEECHAT_HDATA_LONG
** WEECHAT_HDATA_STRING
** WEECHAT_HDATA_SHARED_STRING
** WEECHAT_HDATA_POINTER
** WEECHAT_HDATA_TIME
** WEECHAT_HDATA_HASHTABLE
** WEECHAT_HDATA_OTHER
* _update_allowed_ : 1 si la mise à jour de la variable est autorisée, sinon 0
  _(WeeChat ≥ 0.3.9)_
* _array_size_ : non NULL seulement si la variable est un tableau, et peut
  être : _(WeeChat ≥ 0.3.9)_
** nom d'une variable du hdata : cette variable sera utilisée comme taille de
   tableau (taille dynamique pour le tableau)
** entier (sous forme de chaîne) : taille fixe pour le tableau
** _*_ : taille automatique : la taille est calculée en examinant les valeurs,
   lorsque le premier NULL est trouvé (seulement pour le type string, pointer ou
   hashtable)
* _hdata_name_ : nom d'un hdata (si c'est un pointeur vers une structure qui a
  un hdata)

Exemple en C :

[source,C]
----
struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, 0, "tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, 0, "*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");
----

La macro "WEECHAT_HDATA_VAR" peut être utilisée pour raccourcir le code :

[source,C]
----
WEECHAT_HDATA_VAR(struct t_myplugin_list, name, STRING, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, buffer, POINTER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_count, INTEGER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_array, STRING, 0, "tags_count", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, string_split, STRING, 0, "*", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, prev, POINTER, 0, NULL, "myplugin_list");
WEECHAT_HDATA_VAR(struct t_myplugin_list, next, POINTER, 0, NULL, "myplugin_list");
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hdata_new_list

_WeeChat ≥ 0.3.6, mis à jour dans la 1.0._

Créer un nouveau pointer vers une liste dans le hdata.

Prototype :

[source,C]
----
void weechat_hdata_new_list (struct t_hdata *hdata, const char *name, void *pointer, int flags);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _name_ : nom de la variable
* _pointer_ : pointeur vers la liste
* _flags_ : combinaison des valeurs suivantes : _(WeeChat ≥ 1.0)_
** _WEECHAT_HDATA_LIST_CHECK_POINTERS_ : liste utilisée pour vérifier les
   pointeurs

Exemple en C :

[source,C]
----
struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, "tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, "*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");

weechat_hdata_new_list (hdata, "buffers", &buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
weechat_hdata_new_list (hdata, "last_buffer", &last_buffer, 0);
----

La macro "WEECHAT_HDATA_LIST" peut être utilisée pour raccourcir le code :

[source,C]
----
WEECHAT_HDATA_LIST(buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
WEECHAT_HDATA_LIST(last_buffer, 0);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hdata_get

_WeeChat ≥ 0.3.6._

Retourner un "hdata" pour une structure de WeeChat ou d'une extension.

[NOTE]
Le "hdata" ne contient aucune donnée, il s'agit seulement d'une table de hachage
avec la position (offset) des variables dans la structure. Cela signifie que
vous aurez besoin de ce hdata et d'un pointeur vers un objet WeeChat ou d'une
extension pour lire des données.

Prototype :

[source,C]
----
struct t_hdata *weechat_hdata_get (const char *hdata_name);
----

Paramètres :

* _hdata_name_ : nom du hdata (voir la liste ci-dessous)

Valeur de retour :

* pointeur vers le hdata, NULL en cas d'erreur

Liste des hdata :

include::autogen/plugin_api/hdata.adoc[]

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("irc_server");
----

Script (Python) :

[source,python]
----
# prototype
hdata = weechat.hdata_get(hdata_name)

# exemple
hdata = weechat.hdata_get("irc_server")
----

==== hdata_get_var_offset

_WeeChat ≥ 0.3.6._

Retourner la position (offset) de la variable dans le hdata.

Prototype :

[source,C]
----
int weechat_hdata_get_var_offset (struct t_hdata *hdata, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _name_ : nom de la variable

Valeur de retour :

* position (offset) de la variable, 0 en cas d'erreur

Exemple en C :

[source,C]
----
int offset = weechat_hdata_get_var_offset (hdata, "name");
----

Script (Python) :

[source,python]
----
# prototype
offset = weechat.hdata_get_var_offset(hdata, name)

# exemple
offset = weechat.hdata_get_var_offset(hdata, "name")
----

==== hdata_get_var_type

_WeeChat ≥ 0.3.6._

Retourner le type de la variable dans le hdata (sous forme d'entier).

Prototype :

[source,C]
----
int weechat_hdata_get_var_type (struct t_hdata *hdata, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _name_ : nom de la variable

Valeur de retour :

* type de la variable, -1 en cas d'erreur

Exemple en C :

[source,C]
----
int type = weechat_hdata_get_var_type (hdata, "name");
switch (type)
{
    case WEECHAT_HDATA_CHAR:
        /* ... */
        break;
    case WEECHAT_HDATA_INTEGER:
        /* ... */
        break;
    case WEECHAT_HDATA_LONG:
        /* ... */
        break;
    case WEECHAT_HDATA_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_SHARED_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_POINTER:
        /* ... */
        break;
    case WEECHAT_HDATA_TIME:
        /* ... */
        break;
    case WEECHAT_HDATA_HASHTABLE:
        /* ... */
        break;
    case WEECHAT_HDATA_OTHER:
        /* ... */
        break;
    default:
        /* variable non trouvée */
        break;
}
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hdata_get_var_type_string

_WeeChat ≥ 0.3.6._

Retourner le type de la variable dans le hdata (sous forme de chaîne).

Prototype :

[source,C]
----
const char *weechat_hdata_get_var_type_string (struct t_hdata *hdata, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _name_ : nom de la variable

Valeur de retour :

* type de la variable, NULL en cas d'erreur

Exemple en C :

[source,C]
----
weechat_printf (NULL, "type = %s", weechat_hdata_get_var_type_string (hdata, "name"));
----

Script (Python) :

[source,python]
----
# prototype
type = weechat.hdata_get_var_type_string(hdata, name)

# exemple
weechat.prnt("", "type = %s" % weechat.hdata_get_var_type_string(hdata, "name"))
----

==== hdata_get_var_array_size

_WeeChat ≥ 0.3.9._

Retourner la taille du tableau pour la variable dans le hdata.

Prototype :

[source,C]
----
int weechat_hdata_get_var_array_size (struct t_hdata *hdata, void *pointer, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable

Valeur de retour :

* taille du tableau pour la variable, -1 si la variable n'est pas un tableau ou
  en cas d'erreur

Exemple en C :

[source,C]
----
int array_size = weechat_hdata_get_var_array_size (hdata, pointer, "name");
----

Script (Python) :

[source,python]
----
# prototype
array_size = weechat.hdata_get_var_array_size(hdata, pointer, name)

# exemple
array_size = weechat.hdata_get_var_array_size(hdata, pointer, "name")
----

==== hdata_get_var_array_size_string

_WeeChat ≥ 0.3.9._

Retourner la taille du tableau pour la variable dans le hdata (sous forme de
chaîne).

Prototype :

[source,C]
----
const char *weechat_hdata_get_var_count_array_size (struct t_hdata *hdata, void *pointer,
                                                    const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable

Valeur de retour :

* taille du tableau pour la variable sous forme de chaîne, -1 si la variable
  n'est pas un tableau ou en cas d'erreur

Exemple en C :

[source,C]
----
const char *array_size = weechat_hdata_get_var_array_size_string (hdata, pointer, "name");
----

Script (Python) :

[source,python]
----
# prototype
array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, name)

# exemple
array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, "name")
----

==== hdata_get_var_hdata

_WeeChat ≥ 0.3.6._

Retourner le hdata pour la variable dans le hdata.

Prototype :

[source,C]
----
const char *weechat_hdata_get_var_hdata (struct t_hdata *hdata, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _name_ : nom de la variable

Valeur de retour :

* hdata pour la variable, NULL si pas de hdata ou en cas d'erreur

Exemple en C :

[source,C]
----
weechat_printf (NULL, "hdata = %s", weechat_hdata_get_var_hdata (hdata, "name"));
----

Script (Python) :

[source,python]
----
# prototype
hdata_name = weechat.hdata_get_var_hdata(hdata, name)

# exemple
weechat.prnt("", "hdata = %s" % weechat.hdata_get_var_hdata(hdata, "name"))
----

==== hdata_get_var

_WeeChat ≥ 0.3.6._

Retourner un pointeur vers le contenu de la variable dans le hdata.

Prototype :

[source,C]
----
void *weechat_hdata_get_var (struct t_hdata *hdata, void *pointer, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable

Valeur de retour :

* pointeur vers le contenu de la variable, NULL en cas d'erreur

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
void *pointer = weechat_hdata_get_var (hdata, buffer, "name");
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hdata_get_var_at_offset

_WeeChat ≥ 0.3.6._

Retourner un pointeur vers le contenu de la variable dans le hdata, en utilisant
une position (offset).

Prototype :

[source,C]
----
void *weechat_hdata_get_var_at_offset (struct t_hdata *hdata, void *pointer, int offset);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _offset_ : position (offset) de la variable

Valeur de retour :

* pointeur vers le contenu de la variable, NULL en cas d'erreur

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
int offset = weechat_hdata_get_var_offset (hdata, "name");
void *pointer = weechat_hdata_get_var_at_offset (hdata, buffer, offset);
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hdata_get_list

_WeeChat ≥ 0.3.6._

Retourner un pointeur de liste du hdata.

Prototype :

[source,C]
----
void *weechat_hdata_get_list (struct t_hdata *hdata, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _name_ : nom de la liste

Valeur de retour :

* pointeur vers la liste, NULL en cas d'erreur

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffers = weechat_hdata_get_list (hdata, "gui_buffers");
----

Script (Python) :

[source,python]
----
# prototype
list = weechat.hdata_get_list(hdata, name)

# exemple
hdata = weechat.hdata_get("buffer")
buffers = weechat.hdata_get_list(hdata, "gui_buffers")
----

==== hdata_check_pointer

_WeeChat ≥ 0.3.7, mis à jour dans la 1.0._

Vérifier si un pointeur est valide pour un hdata et un pointeur de liste.

Prototype :

[source,C]
----
int weechat_hdata_check_pointer (struct t_hdata *hdata, void *list, void *pointer);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _list_ : pointeur vers une liste; si NULL _(WeeChat ≥ 1.0)_, le pointeur est
  vérifié avec les listes dans le hdata qui ont le drapeau
  "vérifier les pointeurs" (voir
  <<_hdata_new_list,hdata_new_list>>), et s'il n'y a pas de telle liste,
  le pointeur est considéré comme valide
* _pointer_ : pointeur à vérifier

Valeur de retour :

* 1 si le pointeur est dans la liste, 0 si non trouvé

Exemple en C :

[source,C]
----
/* vérifie si le pointeur vers le tampon est valide */
struct t_hdata *hdata = weechat_hdata_get ("buffer");
if (weechat_hdata_check_pointer (hdata,
                                 weechat_hdata_get_list (hdata, "gui_buffers"),
                                 ptr_buffer))
{
    /* pointeur valide */
}
else
{
    /* pointeur invalide */
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.hdata_check_pointer(hdata, list, pointer)

# exemple
hdata = weechat.hdata_get("buffer")
if weechat.hdata_check_pointer(hdata, weechat.hdata_get_list(hdata, "gui_buffers"), ptr_buffer):
    # pointeur valide
    # ...
else:
    # pointeur invalide
    # ...
----

==== hdata_move

_WeeChat ≥ 0.3.6._

Déplacer le pointeur vers un autre élément dans la liste.

Prototype :

[source,C]
----
void *weechat_hdata_move (struct t_hdata *hdata, void *pointer, int count);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _count_ : nombre de saut(s) à exécuter (entier négatif ou positif, différent
  de 0)

Valeur de retour :

* pointeur vers l'élément atteint, NULL en cas d'erreur

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();

/* se déplacer au tampon suivant, 2 fois */
buffer = weechat_hdata_move (hdata, buffer, 2);

/* se déplacer au tampon précédent */
if (buffer)
    buffer = weechat_hdata_move (hdata, buffer, -1);
----

Script (Python) :

[source,python]
----
# prototype
pointer = weechat.hdata_move(hdata, pointer, count)

# exemple
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()

# se déplacer au tampon suivant, 2 fois
buffer = weechat.hdata_move(hdata, buffer, 2)

# se déplacer au tampon précédent
if buffer:
    buffer = weechat.hdata_move(hdata, buffer, -1)
----

==== hdata_search

_WeeChat ≥ 0.4.1._

Chercher un élément dans la liste : l'expression _search_ est évaluée pour
chaque élément dans la liste, jusqu'à trouver l'élément (ou la fin de la liste).

Prototype :

[source,C]
----
void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search, int move);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _search_ : expression à évaluer, le pointeur par défaut dans l'expression est
  le nom du hdata (et ce pointeur change pour chaque élément dans la liste);
  pour l'aide sur l'expression, voir la commande `/eval` dans le
  _Guide utilisateur WeeChat_
* _move_ : nombre de saut(s) à exécuter après une recherche infructueuse (entier
  négatif ou positif, différent de 0)

Valeur de retour :

* pointeur vers l'élément trouvé, ou NULL si non trouvé

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("irc_server");
void *servers = weechat_hdata_get_list (hdata, "irc_servers");

/* cherche un serveur irc avec le nom "freenode" */
void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == freenode", 1);
if (server)
{
    /* ... */
}
----

Script (Python) :

[source,python]
----
# prototype
pointer = weechat.hdata_search(hdata, pointer, search, count)

# exemple
hdata = weechat.hdata_get("irc_server")
servers = weechat.hdata_get_list(hdata, "irc_servers")

# cherche un serveur irc avec le nom "freenode"
server = weechat.hdata_search(hdata, servers, "${irc_server.name} == freenode", 1)
if server:
    # ...
----

==== hdata_char

_WeeChat ≥ 0.3.7._

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous
forme de caractère.

Prototype :

[source,C]
----
char weechat_hdata_char (struct t_hdata *hdata, void *pointer, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable (doit être de type "char"); pour les tableaux,
  le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0),
  par exemple : "2|name"

Valeur de retour :

* valeur de la variable, sous forme de caractère

Exemple en C :

[source,C]
----
weechat_printf (NULL, "letter = %c", weechat_hdata_char (hdata, pointer, "letter"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.hdata_char(hdata, pointer, name)

# exemple
weechat.prnt("", "letter = %c" % weechat.hdata_char(hdata, pointer, "letter"))
----

==== hdata_integer

_WeeChat ≥ 0.3.6._

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous
forme d'entier.

Prototype :

[source,C]
----
int weechat_hdata_integer (struct t_hdata *hdata, void *pointer, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable (doit être de type "integer"); pour les tableaux,
  le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0),
  par exemple : "2|name"

Valeur de retour :

* valeur de la variable, sous forme d'entier

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "number = %d", weechat_hdata_integer (hdata, buffer, "number"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.hdata_integer(hdata, pointer, name)

# exemple
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "number = %d" % weechat.hdata_integer(hdata, buffer, "number"))
----

==== hdata_long

_WeeChat ≥ 0.3.6._

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous
forme d'entier long.

Prototype :

[source,C]
----
long weechat_hdata_long (struct t_hdata *hdata, void *pointer, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable (doit être de type "long"); pour les tableaux,
  le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0),
  par exemple : "2|name"

Valeur de retour :

* valeur de la variable, sous forme d'entier long

Exemple en C :

[source,C]
----
weechat_printf (NULL, "longvar = %ld", weechat_hdata_long (hdata, pointer, "longvar"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.hdata_long(hdata, pointer, name)

# exemple
weechat.prnt("", "longvar = %ld" % weechat.hdata_long(hdata, pointer, "longvar"))
----

==== hdata_string

_WeeChat ≥ 0.3.6._

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous
forme de chaîne.

Prototype :

[source,C]
----
const char *weechat_hdata_string (struct t_hdata *hdata, void *pointer, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable (doit être de type "string"); pour les tableaux,
  le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0),
  par exemple : "2|name"

Valeur de retour :

* valeur de la variable, sous forme de chaîne

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "name = %s", weechat_hdata_string (hdata, buffer, "name"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.hdata_string(hdata, pointer, name)

# exemple
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "name = %s" % weechat.hdata_string(hdata, buffer, "name"))
----

==== hdata_pointer

_WeeChat ≥ 0.3.6._

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous
forme de pointeur.

Prototype :

[source,C]
----
void *weechat_hdata_pointer (struct t_hdata *hdata, void *pointer, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable (doit être de type "pointeur"); pour les tableaux,
  le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0),
  par exemple : "2|name"

Valeur de retour :

* valeur de la variable, sous forme de pointeur

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "lines = %lx", weechat_hdata_pointer (hdata, buffer, "lines"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.hdata_pointer(hdata, pointer, name)

# exemple
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "lines = %lx" % weechat.hdata_pointer(hdata, buffer, "lines"))
----

==== hdata_time

_WeeChat ≥ 0.3.6._

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous
forme de date/heure.

Prototype :

[source,C]
----
time_t weechat_hdata_time (struct t_hdata *hdata, void *pointer, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable (doit être de type "time"); pour les tableaux,
  le nom peut être "N|name" où N est un index dans le tableau (démarrant à 0),
  par exemple : "2|name"

Valeur de retour :

* valeur de la variable, sous forme de date/heure

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *ptr = weechat_buffer_search_main ();
ptr = weechat_hdata_pointer (hdata, ptr, "lines");
if (ptr)
{
    hdata = weechat_hdata_get ("lines");
    ptr = weechat_hdata_pointer (hdata, ptr, "first_line");
    if (ptr)
    {
        hdata = weechat_hdata_get ("line");
        ptr = weechat_hdata_pointer (hdata, ptr, "data");
        if (ptr)
        {
            hdata = weechat_hdata_get ("line_data");
            time_t date = weechat_hdata_time (hdata, hdata, "date");
            weechat_printf (NULL, "heure de la première ligne affichée = %s", ctime (&date));
        }
    }
}
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.hdata_time(hdata, pointer, name)

# exemple
buf = weechat.buffer_search_main()
ptr = weechat.hdata_pointer(weechat.hdata_get("buffer"), buf, "lines")
if ptr:
    ptr = weechat.hdata_pointer(weechat.hdata_get("lines"), ptr, "first_line")
    if ptr:
        ptr = weechat.hdata_pointer(weechat.hdata_get("line"), ptr, "data")
        if ptr:
            date = weechat.hdata_time(weechat.hdata_get("line_data"), ptr, "date")
            weechat.prnt("", "heure de la première ligne affichée = %s" % time.strftime("%F %T", time.localtime(int(date))))
----

==== hdata_hashtable

_WeeChat ≥ 0.3.7._

Retourner la valeur de la variable dans la structure en utilisant le hdata, sous
forme de table de hachage.

Prototype :

[source,C]
----
struct t_hashtable *weechat_hdata_hashtable (struct t_hdata *hdata, void *pointer, const char *name);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable (doit être de type "hashtable"); pour les
  tableaux, le nom peut être "N|name" où N est un index dans le tableau
  (démarrant à 0), par exemple : "2|name"

Valeur de retour :

* valeur de la variable, sous forme de pointeur vers la table de hachage

Exemple en C :

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
struct t_hashtable *hashtable = weechat_hdata_hashtable (hdata, buffer, "local_variables");
weechat_printf (NULL, "%d variables locales dans le tampon principal",
                weechat_hashtable_get_integer (hashtable, "items_count"));
----

Script (Python) :

[source,python]
----
# prototype
hashtable = weechat.hdata_hashtable(hdata, pointer, name)

# exemple
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
hash = weechat.hdata_hashtable(hdata, buffer, "local_variables")
weechat.prnt("", "variables locales dans le tampon principal :")
for key in hash:
    weechat.prnt("", "  %s == %s" % (key, hash[key]))
----

==== hdata_set

_WeeChat ≥ 0.3.9._

Définir une nouvelle valeur pour une variable dans un hdata.

[NOTE]
Cette fonction ne peut être appelée que dans un "callback" de mise à jour
(voir <<_hdata_new,hdata_new>> et <<_hdata_update,hdata_update>>), si la variable
peut être mise à jour.

Prototype :

[source,C]
----
int weechat_hdata_set (struct t_hdata *hdata, void *pointer, const char *name, const char *value);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _name_ : nom de la variable (types autorisés : char, integer, long, string,
  pointer, time)
* _value_ : nouvelle valeur pour la variable

Valeur de retour :

* 1 si ok, 0 en cas d'erreur

Exemple en C :

[source,C]
----
weechat_hdata_set (hdata, pointer, "message", "test");
----

[NOTE]
Cette fonction n'est pas disponible dans l'API script.

==== hdata_update

_WeeChat ≥ 0.3.9._

Mettre à jour des données dans le hdata.

Prototype :

[source,C]
----
int weechat_hdata_update (struct t_hdata *hdata, void *pointer, struct t_hashtable *hashtable);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _pointer_ : pointeur vers un objet WeeChat ou d'une extension
* _hashtable_ : variables à mettre à jour : les clés sont les noms des
  variables, les valeurs sont les nouvelles valeurs pour les variables (clés et
  valeurs sont des chaînes de caractères), quelques clés spéciales sont
  acceptées :
** clé `__create_allowed` (avec n'importe quelle valeur) : retourne 1 si la
   création est autorisée pour la structure, sinon 0
   _(WeeChat ≥ 0.4.0)_
** clé `__delete_allowed` (avec n'importe quelle valeur) : retourne 1 si la
   suppression est autorisée pour la structure, sinon 0
** clé `__update_allowed`, la valeur est le nom d'une variable : retourne 1 si
   la mise à jour est autorisée pour la variable, sinon 0
** clé `__delete` (avec n'importe quelle valeur) : supprime la structure
   (si autorisé)

Valeur de retour :

* nombre de variables mises à jour

Exemple en C :

[source,C]
----
/* soustrait une heure sur le dernier message affiché dans le tampon courant */

struct t_gui_lines *own_lines;
struct t_gui_line *line;
struct t_gui_line_data  *line_data;
struct t_hdata *hdata;
struct t_hashtable *hashtable;
char str_date[64];

own_lines = weechat_hdata_pointer (weechat_hdata_get ("buffer"), weechat_current_buffer (), "own_lines");
if (own_lines)
{
    line = weechat_hdata_pointer (weechat_hdata_get ("lines"), own_lines, "last_line");
    if (line)
    {
        line_data = weechat_hdata_pointer (weechat_hdata_get ("line"), line, "data");
        hdata = weechat_hdata_get ("line_data");
        hashtable = weechat_hashtable_new (8,
                                           WEECHAT_HASHTABLE_STRING,
                                           WEECHAT_HASHTABLE_STRING,
                                           NULL,
                                           NULL);
        if (hashtable)
        {
            snprintf (str_date, sizeof (str_date), "%ld", ((long int)weechat_hdata_time (hdata, line_data, "date")) - 3600);
            weechat_hashtable_set (hashtable, "date", str_date);
            weechat_hdata_update (hdata, line_data, hashtable);
            weechat_hashtable_free (hashtable);
        }
    }
}
----

Script (Python) :

[source,python]
----
# prototype
count = weechat.hdata_update(hdata, pointer, hashtable)

# exemple : soustrait une heure sur le dernier message affiché dans le tampon courant
own_lines = weechat.hdata_pointer(weechat.hdata_get("buffer"), weechat.current_buffer(), "own_lines")
if own_lines:
    line = weechat.hdata_pointer(weechat.hdata_get("lines"), own_lines, "last_line")
    if line:
        line_data = weechat.hdata_pointer(weechat.hdata_get("line"), line, "data")
        hdata = weechat.hdata_get("line_data")
        weechat.hdata_update(hdata, line_data, {"date": str(weechat.hdata_time(hdata, line_data, "date") - 3600)})
----

==== hdata_get_string

_WeeChat ≥ 0.3.6._

Retourner une valeur pour une propriété d'un hdata sous forme de chaîne.

Prototype :

[source,C]
----
const char *weechat_hdata_get_string (struct t_hdata *hdata, const char *property);
----

Paramètres :

* _hdata_ : pointeur vers le hdata
* _property_ : nom de la propriété :
** _var_keys_ : chaîne avec la liste des clés pour les variables du hdata
   (format : "key1,key2,key3")
** _var_values_ : chaîne avec la liste des valeurs pour les variables du hdata
   (format : "value1,value2,value3")
** _var_keys_values_ : chaîne avec la liste des clés et valeurs pour les
   variables du hdata (format : "key1:value1,key2:value2,key3:value3")
** _var_prev_ : nom de la variable dans la structure qui est un pointeur vers
   l'élément précédent dans la liste
** _var_next_ : nom de la variable dans la structure qui est un pointeur vers
   l'élément suivant dans la liste
** _list_keys_ : chaîne avec la liste des clés pour les listes du hdata
   (format : "key1,key2,key3")
** _list_values_ : chaîne avec la liste des valeurs pour les listes du hdata
   (format : "value1,value2,value3")
** _list_keys_values_ : chaîne avec la liste des clés et valeurs pour les listes
   du hdata (format : "key1:value1,key2:value2,key3:value3")

Valeur de retour :

* valeur de la propriété sous forme de chaîne

Exemple en C :

[source,C]
----
weechat_printf (NULL, "variables dans le hdata : %s", weechat_hdata_get_string (hdata, "var_keys"));
weechat_printf (NULL, "listes dans le hdata : %s", weechat_hdata_get_string (hdata, "list_keys"));
----

Script (Python) :

[source,python]
----
# prototype
value = weechat.hdata_get_string(hdata, property)

# exemple
weechat.prnt("", "variables dans le hdata : %s" % weechat.hdata_get_string(hdata, "var_keys"))
weechat.prnt("", "listes dans le hdata : %s" % weechat.hdata_get_string(hdata, "list_keys"))
----

[[upgrade]]
=== Mise à jour

Fonctions pour la mise à jour de WeeChat (commande "/upgrade").

==== upgrade_new

_Mis à jour dans la 1.5._

Créer ou lire un fichier pour la mise à jour.

Prototype :

[source,C]
----
struct t_upgrade_file *upgrade_file_new (const char *filename,
                                         int (*callback_read)(const void *pointer,
                                                              void *data,
                                                              struct t_upgrade_file *upgrade_file,
                                                              int object_id,
                                                              struct t_infolist *infolist),
                                         const void *callback_read_pointer,
                                         void *callback_read_data);
----

Paramètres :

* _filename_ : nom du fichier (l'extension ".upgrade" est ajoutée
  automatiquement par WeeChat)
* _callback_read_ : fonction appelée pour chaque objet lu dans le fichier de
  mise à jour (si NULL, le fichier pour la mise à jour est ouvert en
  écriture), paramètres et valeur de retour :
** _const void *pointer_ : pointeur
** _void *data_ : pointeur
** _struct t_upgrade_file *upgrade_file_ : pointeur vers le fichier de mise à
   jour
** _int object_id_ : identifiant de l'objet
** _struct t_infolist *infolist_ : infolist avec le contenu de l'objet
** valeur de retour :
*** _WEECHAT_RC_OK_
*** _WEECHAT_RC_ERROR_
* _callback_read_pointer_ : pointeur donné au "callback" lorsqu'il est appelé
  par WeeChat
* _callback_read_data_ : pointeur donné au "callback" lorsqu'il est appelé par
  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
  similaire) et est automatiquement libéré (par free) lorsque le fichier de
  mise à jour est fermé

Valeur de retour :

* pointeur vers le fichier de mise à jour

Exemple en C :

[source,C]
----
struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("mon_fichier",
                                                           NULL, NULL, NULL);
----

Script (Python) :

[source,python]
----
# prototype
upgrade_file = weechat.upgrade_new(filename, callback_read, callback_read_data)

# exemple
upgrade_file = weechat.upgrade_new("mon_fichier", "", "")
----

==== upgrade_write_object

Écrire un objet dans le fichier de mise à jour.

Prototype :

[source,C]
----
int 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 en C :

[source,C]
----
if (weechat_upgrade_write_object (upgrade_file, 1, &infolist))
{
    /* ok */
}
else
{
    /* erreur */
}
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.upgrade_write_object(upgrade_file, object_id, infolist)

# exemple
weechat.upgrade_write_object(upgrade_file, 1, infolist)
----

==== upgrade_read

_Mis à jour dans la 1.5._

Lire un fichier de mise à jour.

Prototype :

[source,C]
----
int weechat_upgrade_read (struct t_upgrade_file *upgrade_file);
----

Paramètres :

* _upgrade_file_ : pointeur vers le fichier de mise à jour

Valeur de retour :

* 1 si ok, 0 en cas d'erreur

Exemple en C :

[source,C]
----
weechat_upgrade_read (upgrade_file);
----

Script (Python) :

[source,python]
----
# prototype
rc = weechat.upgrade_read(upgrade_file)

# exemple
weechat.upgrade_read(upgrade_file)
----

==== upgrade_close

Fermer 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 en C :

[source,C]
----
weechat_upgrade_close (upgrade_file);
----

Script (Python) :

[source,python]
----
# prototype
weechat.upgrade_close(upgrade_file)

# exemple
weechat.upgrade_close(upgrade_file)
----
