Fonctions de l'interface (API)

ascii_strcasecmp
ascii_strncasecmp
explode_string
free_exploded_string
exec_on_files
printf
printf_server
printf_infobar
msg_handler_add
cmd_handler_add
handler_remove
handler_remove_all
exec_command
get_info
get_dcc_info
free_dcc_info
get_config
set_config
get_plugin_config
set_plugin_config

ascii_strcasecmp

Prototype : int ascii_strcasecmp (t_weechat_plugin *plugin, char *chaine1, char *chaine2)

Effectue une comparaison entre deux chaînes, sans tenir compte des majuscules/minuscules ni de la locale.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • chaine1 : la première chaîne à comparer

  • chaine2 : la deuxième chaîne à comparer

Valeur renvoyée : la différence entre les deux chaînes : négatif si chaine1 < chaine2, zéro si chaine1 == chaine2, positif si chaine1 > chaine2

Exemple :

if (plugin->ascii_strcasecmp (plugin, "abc", "def") != 0) ...

ascii_strncasecmp

Prototype : int ascii_strncasecmp (t_weechat_plugin *plugin, char *chaine1, char *chaine2, int max)

Effectue une comparaison entre deux chaînes, sans tenir compte des majuscules/minuscules ni de la locale, en comparant au plus "max" caractères.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • chaine1 : la première chaîne à comparer

  • chaine2 : la deuxième chaîne à comparer

  • max : nombre de caractères max à comparer

Valeur renvoyée : la différence entre les deux chaînes : négatif si chaine1 < chaine2, zéro si chaine1 == chaine 2, positif si chaine1 > chaine2

Exemple :

if (plugin->ascii_strncasecmp (plugin, "abc", "def", 2) != 0) ...

explode_string

Prototype : char **explode_string (t_weechat_plugin *plugin, char *chaine, char *separateurs, int num_items_max, int *num_items)

Explose une chaîne en plusieurs selon un/des délimiteur(s).

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • chaine : la chaîne à exploser

  • separateurs : les délimiteurs utilisés pour exploser la chaîne

  • num_items_max : nombre maximum de sous-chaînes créées (0 = pas de limite)

  • num_items : pointeur vers un entier qui contiendra le nombre de sous-chaînes créées en retour

Valeur renvoyée : un tableau de chaînes, ou NULL si un problème a été rencontré.

Note : le résultat doit être libéré par un appel à la fonction "free_exploded_string" après utilisation.

Exemple :

char **argv;
int argc;
argv = plugin->explode_string (plugin, chaine, " ", 0, &argc);
...
if (argv != NULL)
    plugin->free_exploded_string (plugin, argv);

free_exploded_string

Prototype : char **free_exploded_string (t_weechat_plugin *plugin, char **chaine)

Libère la mémoire utilisée pour une explosion de chaîne.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • chaine : la chaîne explosée par la fonction "explode_string"

Valeur renvoyée : aucune.

Exemple :

char *argv;
int argc;
argv = plugin->explode_string (plugin, chaine, " ", 0, &argc);
...
if (argv != NULL)
    plugin->free_exploded_string (plugin, argv);

exec_on_files

Prototype : void exec_on_files (t_weechat_plugin *plugin, char *repertoire, int (*callback)(t_weechat_plugin *, char *))

Exécute une fonction sur tous les fichiers d'un répertoire.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • repertoire : le répertoire où les fichiers sont recherchés

  • callback : une fonction appelée pour chaque fichier trouvé

Valeur renvoyée : aucune.

Exemple :

int callback (t_weechat_plugin *plugin, char *fichier)
{
    plugin->printf_server (plugin, "fichier: %s", fichier);
    return 1;
}
...
plugin->exec_on_files (plugin, "/tmp", &callback);

printf

Prototype : void printf (t_weechat_plugin *plugin, char *serveur, char *canal, char *message, ...)

Affiche un message sur un tampon WeeChat, identifié par le serveur et le canal (tous deux pouvant être NULL pour le tampon courant).

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • serveur : nom interne du serveur pour trouver le tampon dans lequel afficher (peut être NULL)

  • canal : nom du canal pour trouver le tampon dans lequel afficher (peut être NULL)

  • message : message à afficher

Valeur renvoyée : aucune.

Exemples :

plugin->printf (plugin, NULL, NULL, "hello");
plugin->printf (plugin, NULL, "#weechat", "hello");
plugin->printf (plugin, "freenode", "#weechat", "hello");

printf_server

Prototype : void printf_server (t_weechat_plugin *plugin, char *message, ...)

Affiche un message sur le tampon du serveur courant.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • message : message à afficher

Valeur renvoyée : aucune.

Exemple :

plugin->printf_server (plugin, "hello");

printf_infobar

Prototype : void printf_infobar (t_weechat_plugin *plugin, int temps, char *message, ...)

Affiche un message sur la barre d'infos pour un temps déterminé.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • temps : temps (en secondes) pendant lequel le message est affiché (0 = jamais effacé)

Valeur renvoyée : aucune.

Exemple :

plugin->printf_infobar (plugin, 5, "hello");

msg_handler_add

Prototype : t_plugin_handler *msg_handler_add (t_weechat_plugin *plugin, char *message, t_plugin_handler_func *fonction, char *handler_args, void *handler_pointer)

Ajoute un gestionnaire de messages IRC, appelé dès qu'un message IRC est reçu.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • message : nom du message IRC pour lequel la fonction est appelée. Pour connaître la liste des messages IRC disponibles, merci de consulter les RFCs 1459 et 2812

  • fonction : fonction appelée lorsque le message est reçu

  • handler_args : paramètres passés à la fonction appelée

  • handler_pointer : pointeur passé à la fonction appelée

Valeur renvoyée : le pointeur vers le nouveau gestionnaire de messages.

Note : la fonction appelée lorsque le message est reçu doit renvoyer une des valeurs suivantes :

  • PLUGIN_RC_KO : la fonction a échoué

  • PLUGIN_RC_OK : la fonction a réussi

  • PLUGIN_RC_OK_IGNORE_WEECHAT : le message ne sera pas transmis à WeeChat

  • PLUGIN_RC_OK_IGNORE_PLUGINS : le message ne sera pas transmis à d'autres extensions

  • PLUGIN_RC_OK_IGNORE_ALL : le message ne sera ni transmis à WeeChat ni à d'autres extensions

Exemple :

int msg_kick (t_weechat_plugin *plugin, char *serveur, char *commande,
              char *arguments, char *handler_args, void *handler_pointer)
{
    plugin->printf (plugin, serveur, NULL, "KICK reçu");
    return PLUGIN_RC_OK;
}
...
plugin->msg_handler_add (plugin, "KICK", &msg_kick, NULL, NULL);

cmd_handler_add

Prototype : t_plugin_handler *cmd_handler_add (t_weechat_plugin *plugin, char *commande, char *description, char *arguments, char *arguments_description, char *modele_completion, t_plugin_handler_func *fonction, char *handler_args, void *handler_pointer)

Ajoute un gestionnaire de commande WeeChat, appelé dès que l'utilisateur utilise la commande (par exemple /commande).

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • commande : nom de la nouvelle commande, qui peut être une commande déjà existante (attention la commande remplacée ne sera plus disponible jusqu'à ce que l'extension soit déchargée)

  • description : brève description de la commande (affichée par /help commande)

  • arguments : brève description des paramètres de la commande (affichée par /help commande)

  • arguments_description : longue description des paramètres de la commande (affichée par /help commande)

  • modele_completion : modèle pour la complétion sous la forme "abc|%w def|%i" qui signigie "abc" ou une commande WeeChat pour le premier paramètre, et "def" ou une commande IRC pour le deuxième. Une chaîne vide indique à WeeChat de compléter tout paramètre avec un pseudo du canal courant, une valeur NULL désactive toute complétion pour tous les paramètres de la commande.

    Les codes suivants peuvent être utilisés :

    CodeDescription
    %-aucune complétion pour le paramètre
    %aalias
    %A alias et commandes (WeeChat, IRC et extensions)
    %ccanal courant
    %Ccanaux du serveur courant
    %hcommandes définies par des extensions
    %icommandes IRC (envoyées)
    %Icommandes IRC (reçues)
    %kfonctions associées aux touches
    %npseudos du canal courant
    %ooptions de configuration
    %pmessage de "part" par défaut
    %qmessage de "quit" par défaut
    %snom du serveur courant
    %Stous les serveurs
    %ttitre du canal courant
    %vvaleur d'une option de configuration
    %wcommandes WeeChat

  • fonction : fonction appelée lorsque la commande est exécutée

  • handler_args : paramètres passés à la fonction appelée

  • handler_pointer : pointeur passé à la fonction appelée

Valeur renvoyée : le pointeur vers le nouveau gestionnaire de commande.

Note : la fonction appelée lorsque la commande est exécutée doit renvoyer une des valeurs suivantes :

  • PLUGIN_RC_KO : la fonction a échoué

  • PLUGIN_RC_OK : la fonction a réussi

Exemple :

int cmd_test (t_weechat_plugin *plugin, char *serveur,
              char *commande, char *arguments, char *handler_args,
              void *handler_pointer)
{
    plugin->printf (plugin, serveur, NULL,
                    "commande test, pseudo: %s",
                    (arguments) ? arguments : "aucun");
    return PLUGIN_RC_OK;
}
...
plugin->cmd_handler_add (plugin, "test", "Commande test",
                         "[pesudo]", "pseudo: un pseudo du canal",
                         "%n", &cmd_test, NULL, NULL);

handler_remove

Prototype : void handler_remove (t_weechat_plugin *plugin, t_plugin_handler *handler)

Supprime un gestionnaire.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • handler : le gestionnaire à supprimer

Valeur renvoyée : aucune.

Exemple :

plugin->handler_remove (plugin, mon_handler);

handler_remove_all

Prototype : void handler_remove_all (t_weechat_plugin *plugin)

Supprime tous les gestionnaires d'une extension.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

Valeur renvoyée : aucune.

Exemple :

plugin->handler_remove_all (plugin);

exec_command

Prototype : void exec_command (t_weechat_plugin *plugin, char *serveur, char *canal, char *commande)

Execute une commande WeeChat ou envoie un message à un canal.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • serveur : nom interne du serveur où exécuter la commande (peut être NULL)

  • canal : nom du canal où exécuter la commande (peut être NULL)

  • commande : la commande à exécuter

Valeur renvoyée : aucune.

Exemples :

plugin->exec_command (plugin, NULL, NULL, "/help nick");
plugin->exec_command (plugin, "freenode", "#weechat", "bonjour");

get_info

Prototype : char *get_info (t_weechat_plugin *plugin, char *info, char *serveur)

Renvoie une information sur WeeChat ou un canal.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • info : nom de l'info à obtenir :

    InfoDescription
    versionversion de WeeChat
    nickpesudo
    channel nom du canal (NULL pour un serveur ou un privé)
    servernom du serveur
    awaydrapeau "away"
    weechat_dir répertoire maison de WeeChat (par défaut: ~/.weechat/)
    weechat_libdirrépertoire "lib" système de WeeChat
    weechat_sharedirrépertoire "share" système de WeeChat

  • serveur : nom interne du serveur où récupérer l'information (si nécessaire)

Valeur renvoyée : l'information recherchée, NULL si non trouvée.

Note : le résultat doit être libéré par un appel à la fonction "free" après utilisation.

Exemples :

char *version = plugin->get_info (plugin, "version", NULL);
char *nick = plugin->get_info (plugin, "nick", "freenode");

get_dcc_info

Prototype : t_plugin_info_dcc *get_dcc_info (t_weechat_plugin *plugin)

Renvoie la liste des DCC en cours ou terminés.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

Valeur renvoyée : la liste chaînée des DCC.

ChampDescription
serverle serveur IRC
channelle canal IRC
type le type de DCC : 0 = discussion reçue, 1 = discussion envoyée, 2 = fichier reçu, 3 = fichier envoyé
status le statut du DCC : 0 = en attente, 1 = en cours de connexion, 2 = actif, 3 = terminé, 4 = échoué, 5 = interrompu par l'utilisateur
start_timela date et heure de création du DCC
start_transferla date et heure de démarrage du transfert
addradresse IP de l'utilisateur distant
portport utilisé pour le DCC
nickpseudo de l'utilisateur distant
filenamenom de fichier
local_filenamenom de fichier local
sizetaille du fichier
posposition actuelle dans le fichier
start_resumeposition de démarrage après une interruption
bytes_per_sec nombre d'octets transmis par seconde depuis le début du transfert

Note : le résultat doit être libéré par un appel à la fonction "free_dcc_info" après utilisation.

Exemples :

t_plugin_dcc_info *dcc_info = plugin->get_dcc_info (plugin);
for (ptr_dcc = dcc_info; ptr_dcc; ptr_dcc = ptr_dcc->next_dcc)
{
    plugin->printf_server (plugin, "DCC type=%d, avec: %s",
                           ptr_dcc->type, ptr_dcc->nick);
}
if (dcc_info)
    plugin->free_dcc_info (plugin, dcc_info);

free_dcc_info

Prototype : void free_dcc_info (t_weechat_plugin *plugin, t_plugin_dcc_info *dcc_info)

Libère la mémoire utilisée par une liste de DCC.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • dcc_info : pointeur vers la liste DCC renvoyée par la fonction "get_dcc_info"

Valeur renvoyée : aucune.

Exemple :

plugin->free_dcc_info (plugin, dcc_info);

get_config

Prototype : char *get_config (t_weechat_plugin *plugin, char *option)

Renvoie la valeur d'une option de configuration WeeChat.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • option : nom de l'option à lire

Valeur renvoyée : la valeur de l'option, NULL si non trouvée.

Note : le résultat doit être libéré par un appel à la fonction "free" après utilisation.

Exemples :

char *value1 = plugin->get_config (plugin, "look_set_title");
char *value2 = plugin->get_config (plugin, "freenode.server_autojoin");

set_config

Prototype : int set_config (t_weechat_plugin *plugin, char *option, char *valeur)

Modifie la valeur d'une option de configuration WeeChat.

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • option : nom de l'option à mettre à jour

  • valeur : nouvelle valeur pour l'option

Valeur renvoyée : 1 si l'option a été modifiée avec succès, 0 si une erreur s'est produite.

Exemple :

plugin->set_config (plugin, "look_nicklist", "off");

get_plugin_config

Prototype : char *get_plugin_config (t_weechat_plugin *plugin, char *option)

Renvoie la valeur d'une option de l'extension. L'option est lue depuis le fichier "~/.weechat/plugins.rc" et est sous cette forme : "extension.option=valeur" (NB : le nom de l'extension est ajouté automatiquement).

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • option : nom de l'option à lire

Valeur renvoyée : la valeur de l'option, NULL si non trouvée.

Note : le résultat doit être libéré par un appel à la fonction "free" après utilisation.

Exemple :

char *value = plugin->get_plugin_config (plugin, "ma_variable");

set_plugin_config

Prototype : int set_plugin_config (t_weechat_plugin *plugin, char *option, char *valeur)

Modifie la valeur d'une option de l'extension. L'option est écrite dans le fichier "~/.weechat/plugins.rc" et est sous cette forme : "extension.option=valeur" (NB : le nom de l'extension est ajouté automatiquement).

Paramètres :

  • plugin : pointeur vers la structure de l'extension

  • option : nom de l'option à mettre à jour

  • valeur : nouvelle valeur pour l'option

Valeur renvoyée : 1 si l'option a été modifiée avec succès, 0 si une erreur s'est produite.

Exemple :

plugin->set_plugin_config (plugin, "ma_variable", "valeur");