Interface aux greffons XChat 2.0
plugin20-fr.html révision 2.86
Les versions plus récentes de ce document sont disponibles sur : https://xchat.trollab.org/Docs/plugin20-fr.html
1. Documentation :
1.0 Introduction
1.1 Exemple de greffon
1.2 Que sont word et word_eol?
1.3 Listes et Champs
1.4 Greffons sur Windows (Win32)
1.5 Controller la GUI
1.5.1 Contrôles de base
1.5.2 Eléments de menu personalisés
1.5.3 System Tray
1.6 Support pour les chaînes UTF-8/Unicode
2. Référence des Fonctions :
xchat_hook_command
xchat_hook_fd
xchat_hook_print
xchat_hook_server
xchat_hook_timer
xchat_unhook
xchat_command
xchat_commandf
xchat_print
xchat_printf
xchat_emit_print
xchat_send_modes
xchat_find_context
xchat_get_context
xchat_get_info
xchat_get_prefs
xchat_set_context
xchat_nickcmp
xchat_strip
xchat_free
xchat_list_get
xchat_list_free
xchat_list_fields (non encore documenté)
xchat_list_next
xchat_list_str
xchat_list_int
xchat_list_time
xchat_plugingui_add (non encore documenté)
xchat_plugingui_remove (non encore documenté)
Les greffons pour XChat sont écrits en C. Lʼinterface devrait rester 100%
compatible au niveau binaire. Ceci signifie que vous devriez pouvoir mettre
à jour XChat sans avoir besoin de recompiler les greffons, ils devraient
continuer à fonctionner. Cette structure ne dépend dʼaucune autre structure
ni dʼoffset et donc la version du compilateur ne devrait pas avoir le moindre
impact non plus. La seule chose nécessaire à un greffon XChat, est la présence
du symbole « xchat_plugin_init ». Cʼest son point dʼentrée, voir lʼexemple plus
bas. Vous devriez rendre vos variables globales
statiques, de manière à
ce que les symboles ne soient pas exportés. Rien de gênant à ce quʼils le soit,
mais ce nʼest absolument pas nécessaire et ne ferait que polluer le name-space.
Les greffons sont compilés en tant que bibliothèques dynamiques (fichiers .so
ou .dll), par exemple :
Sur la plupart des systèmes UNIX :
gcc -Wl,--export-dynamic -Wall -O1 -shared -fPIC myplugin.c -o myplugin.so
MacOSX:
gcc -no-cpp-precomp -g -O2 -Wall -bundle -flat_namespace -undefined suppress -o myplugin.so myplugin.c
Voir la
Section Windows pour comprendre comment compiler
avec visual studio.
Toutes les chaînes passées au et par le greffon sont encodées en UTF-8, quelle
que soit la locale. Quʼest-ce que ça signifie?
Ce greffon simple « autoOps » tout ceux qui joignent un salon dans lequel vous
vous trouvez. Il ajoute aussi la nouvelle commande « /AUTOOPTOGGLE », qui va
permettre de contrôler la mise en fonction ou lʼarrêt de cette fonctionnalité.
Tout greffon XChat doit définir la fonction « xchat_plugin_init », cʼest son
point dʼentrée normal. « xchat_plugin_deinit », elle, est optionnelle.
#include "xchat-plugin.h"
#define PNAME "AutoOp"
#define PDESC "Auto Ops anyone that joins";
#define PVERSION "0.1"
static xchat_plugin *ph; /* handle du greffon */
static int enable = 1;
static int join_cb(char *word[], void *userdata)
{
if (enable)
/* Rends Op QUICONQUE rejoint le salon */
xchat_commandf(ph, "OP %s", word[1]);
/* word[1] est le pseudo, comme dans paramétres->Avancé->Fenêtre des événements texte de xchat */
return XCHAT_EAT_NONE; /* ne pas avaller cet événement, xchat a besoin de le voir! */
}
static int autooptoggle_cb(char *word[], char *word_eol[], void *userdata)
{
if (!enable)
{
enable = 1;
xchat_print(ph, "AutoOping now enabled!\n");
} else
{
enable = 0;
xchat_print(ph, "AutoOping now disabled!\n");
}
return XCHAT_EAT_ALL; /* avaler cette commande de manière à ce que xchat et les autres greffons ne puissent pas la traiter */
}
void xchat_plugin_get_info(char **name, char **desc, char **version, void **reserved)
{
*name = PNAME;
*desc = PDESC;
*version = PVERSION;
}
int xchat_plugin_init(xchat_plugin *plugin_handle,
char **plugin_name,
char **plugin_desc,
char **plugin_version,
char *arg)
{
/* nous avons besoin de le sauvegarder pour lʼutiliser avec les fonctions « xchat_* » */
ph = plugin_handle;
/* informer xchat de nos infos */
*plugin_name = PNAME;
*plugin_desc = PDESC;
*plugin_version = PVERSION;
xchat_hook_command(ph, "AutoOpToggle", XCHAT_PRI_NORM, autooptoggle_cb, "Usage: AUTOOPTOGGLE, Turns OFF/ON Auto Oping", 0);
xchat_hook_print(ph, "Join", XCHAT_PRI_NORM, join_cb, 0);
xchat_print(ph, "AutoOpPlugin loaded successfully!\n");
return 1; /* return 1 en cas de succès */
}
Ce sont des tables de chaînes. Elles contiennent les paramètres entrés par
lʼutilisateur pour une commande donnée. Par exemple, si vous exécutez :
/command NICK salut a vous
word[1] is command
word[2] is NICK
word[3] is salut
word[4] is a
word[5] is vous
word_eol[1] is command NICK salut à vous
word_eol[2] is NICK salut à vous
word_eol[3] is salut à vous
word_eol[4] is à vous
word_eol[4] is vous
Ces tables ne sont fournies que pour simplicité. Vous nʼêtes pas autorisé à les
modifier. Ces deux tables sont limitées à 32 élements (index 31). Les entrées
word[0] et word_eol[0] sont réservées et ne devrait pas être lues.
Les listes dʼinformations (DCCs, Salons, Liste des utilisateurs, etc…) peuvent
être retrouvées grâce à la fonction « xchat_list_get ». Tous les champs sont
en LECTURE SEULE et doivent être recopiés si ils sont nécessaire longtemps
après lʼappel de « xchat_list_str ». Les types de listes et les champs
disponibles sont :
"channels" - liste des salons, queries et leurs serveurs.
Nom | Description | Type |
channel | Nom du salon ou du query | string |
chantypes | Types des salons ex. : "#!&" (Ajouté depuis la version 2.0.9. Les anciennes versions retourneront NULL) | string |
context | (xchat_context *) pointer. A utiliser avec xchat_set_context | string |
flags | Bits dʼétat Serveur/Salon :
Bit # | Valeur | Description |
0 | 1 | Connecté |
1 | 2 | Connection en cours |
2 | 4 | Vous êtes away |
3 | 8 | Fin de MOTD (Login effectué) |
4 | 16 | Possède WHOX (ircu) |
5 | 32 | Possède IDMSG (FreeNode) |
6 | 64 | Messages Join/Part cachés |
7 | 128 | Inutilisé (représentait « Color Paste » dans les anciennes versions) |
8 | 256 | Beep sur Message reçu |
9 | 512 | Fait clignoter la barre dʼétat |
10 | 1024 | Fait clignoter la barre des tâches |
(Bits 0-5 ajoutés depuis 2.0.9. Bits 6-8 ajoutés depuis 2.6.6. Bit 9 ajouté depuis 2.8.0. Bit 10 ajouté depuis 2.8.6) | int |
id | ID unique du serveur (Ajouté depuis la version 2.0.8. Les anciennes versions retourneront -1) | int |
lag | Lag en millisecondes (Ajouté depuis la version 2.6.8. Les anciennes versions retourneront -1) | int |
maxmodes | Nombre maximum de nœuds par ligne (Ajouté depuis la version 2.0.9. Les anciennes versions retourneront -1) | int |
network | Nom du réseau auquel le salon appartient (Ajouté depuis la version 2.0.2. Les anciennes versions retourneront NULL) | string |
nickprefixes | Préfixes des Pseudos ex : « @+ » (Ajouté depuis la version 2.0.9. Les anciennes versions retourneront NULL) | string |
nickmodes | Caractères des modes des Pseudos ex. : « ov » (Ajouté depuis la version 2.0.9. Les anciennes versions retourneront NULL) | string |
queue | Nombre dʼoctets dans le tampon dʼenvoi (Ajouté depuis la version 2.6.8. Les anciennes versions retourneront -1) | int |
server | Nom du serveur auquel ce salon appartient | string |
type | Type de contexte : 1-Serveur 2-Salon 3-Dialogue (Ajouté depuis la 2.0.2. Les anciennes versions retourneront -1) | int |
users | Nombre dʼutilisateurs dans le salon (Ajouté depuis la version 2.0.8. Les anciennes versions retourneront -1) | int |
"dcc" - liste des transferts de fichiers DCC. Champs :
Nom | Description | Type |
address32 | Adresse de lʼutilisateur distant (adresse ipv4) | int |
cps | Octets par seconde (vitesse) | int |
destfile | Chemin complet de destination | string |
file | Nom du fichier | string |
nick | Pseudo de la personne à laquelle le fichier est destiné / de laquelle ce fichier provient | string |
port | numéro du port TCP | int |
pos | Octets émis/reçus | int |
resume | Pointe au début de la reprise du transfert (ou zéro si aucune reprise) | int |
size | Taille du fichier en octets, 32 bits bas (caste vers unsigned) | int |
sizehigh | Taille du fichier en octets, 32 bits hauts | int |
status | Statut DCC : 0-Mis en tampon 1-Actif 2-Echec 3-Terminé 4-Connection en cours 5-Abandonné | int |
type | Type de DCC : 0-Envoi 1-Réception 2-Chat Reçu 3-Chat Emis | int |
"ignore" - liste des ignorés actifs.
Nome | Description | Type |
mask | Masque dʼignorance. ex. : *!*@*.aol.com | string |
flags | Champ de bits. 0=Privé 1=Notice 2=Salon 3=Ctcp
4=Invite 5=Dés-Ignore 6=Pas-De-Sauve 7=DCC | int |
"notify" - liste des personnes a notifier.
Nom | Description | Type |
networks | Réseaux sur lesquels le pseudo se situe. Séparés par virgules. Peut être NULL.
(Ajouté dans la version 2.6.8) | string |
nick | Pseudo | string |
flags | Champ de bits. 0=En ligne. | int |
on | Heure dʼarrivée de lʼutilisateur. | time_t |
off | Heure de départ de lʼutilisateur. | time_t |
seen | Heure de la dernière vérification de présence. | time_t |
La liste complète « notify » a été ajoutée dans xchat 2.0.8. Ses champs ne
sont valables dans le contexte que lorsque « xchat_list_get() » a été
appelée (ex. : vous nʼobtenez des informations concernant un utilisateur que
POUR CE SERVEUR UNIQUEMENT). Vous pouvez boucler sur la liste « channels » pour
trouver les informations de notification pour tout le serveur.
"users" - liste des utilisateurs dans le salon courant.
Nom | Description | Type |
away | Statut Away (booléen) (Ajouté depuis la version 2.0.6. Les anciennes versions retourneront -1) | int |
lasttalk | Dernière fois que lʼutilisateur à parlé (Ajouté depuis la version 2.4.2. Les anciennes versions retourneront -1) | time_t |
nick | Pseudo | string |
host | Nom de lʼhôte suivant la forme : user@host (ou NULL si inconnu). | string |
prefix | Caractère de préfixe, es. : @ ou + ou ~. Pointeur vers un seul caractère. | string |
realname | Nom réel ou NULL (Ajouté depuis la version 2.8.6) | string |
selected | Statut sélectionné dans la liste dʼutilisateurs, ne fonctionne que pour retrouver quel est lʼutilisateur dans lʼonglet ayant le focus (Ajouté depuis la version 2.6.1. Les anciennes versions retourneront -1) | int |
Exemple :
list = xchat_list_get(ph, "dcc");
if(list)
{
xchat_print(ph, "--- DCC LIST ------------------\n"
"File To/From KB/s Position\n");
while(xchat_list_next(ph, list))
{
xchat_printf(ph, "%6s %10s %.2f %d\n",
xchat_list_str(ph, list, "file"),
xchat_list_str(ph, list, "nick"),
xchat_list_int(ph, list, "cps") / 1024,
xchat_list_int(ph, list, "pos"));
}
xchat_list_free(ph, list);
}
Oui, c'est possible… Tout ce dont vous avez besoin est
MSVC (Visual Studio) ou
MINGW, ces deux compilateurs sont libres a télécharger.
Compilez simplement votre greffon en tant que DLL. Vous devez avoir les fichiers suivants :
- xchat-plugin.h - Lʼentête principale des greffons
- plugin.c - Votre greffon, il est nécessaire que vous lʼécriviez celui là :)
- plugin.def - Un simple fichier texte contenant ceci :
EXPORTS
xchat_plugin_init
xchat_plugin_deinit
xchat_plugin_get_info
Laissez tomber
xchat_plugin_deinit si vous nʼavez pas lʼintention dʼécrire
cette fonction. Puis pour compiler, tapez ceci en ligne de commande :
MSVC
cl -O1 -MD -G5 -DWIN32 -c plugin.c
link /DLL /out:plugin.dll /SUBSYSTEM:WINDOWS plugin.obj /def:plugin.def /base:0x00d40000
GCC (MINGW)
gcc -Wall -Os -DWIN32 -c plugin.c
dllwrap --def plugin.def --dllname plugin.dll plugin.o
Pour un exemple complet, regardez le code source de
DNS Plugin, qui contient aussi un Makefile.
MERDOUILLE : Les greffons compilés sur Win32 DOIVENT posséder une variable
globale nommée
ph, qui sera le plugin_handle, un peu comme dans lʼ
exemple de greffon ci-dessus.
La manière la plus simple dʼexécuter les fonctions de base de la GUI est dʼutiliser
la commande « /GUI ».
Vous pouvez exécuter cette commande au travers de la boite de saisie ou par un
appel à la fonction « xchat_command(ph, "GUI …"); ».
GUI ATTACH | Même fonction que « Attacher la fenêtre » du menu de XChat menu (nouveau dans 2.6.2). |
GUI DETACH | Même fonction que « Détacher lʼonglet » du menu de XChat (nouveau dans 2.6.2). |
GUI APPLY | Identique à un clic sur « OK » dans le fenêtre Paramètres. Exécutez la après un « /SET » pour activer les modifications apportées à la GUI (nouveau dans 2.8.0) |
GUI COLOR n | Modifier la couleur de lʼonglet correspondant au contexte courant, avec n compris entre 0 et 3 inclus. |
GUI FOCUS | Donne le focus à la fenêtre ou à lʼonglet courant. |
GUI FLASH | Faire clignoter le bouton de la barre des tâches. Ne clignotera que si la fenêtre nʼa pas le focus et sʼarrêtera dès que le focus lui sera donné par lʼutilsateur. |
GUI HIDE | Cacher la fenêtre principale de xchat (utilisé par le greffon Systray). |
GUI ICONIFY | Icônifier (minimiser sur la barre des tâches) la fenêtre courante de xchat. |
GUI MSGBOX texte | Affiche une boite de message asynchrone contenant votre texte (nouveau dans 2.4.5). |
GUI SHOW | Afficher la fenêtre principale de xchat (si elle est cachée). |
Note : les arguments pour FLASH, ICONIFY et COLOR ont été ajoutés dans xchat 2.0.8, ils
ne fonctionneront pas avec les versions précédentes.
A partir de la version 2.4.5 il est possible dʼajouter vos propres éléments à la barre de menu. La commande « menu » suit cette syntaxe :
MENU [-eX] [-i<ICONFILE>] [-k<mod>,<key>] [-m] [-pX] [-rX,group] [-tX] {ADD|DEL} <path> [commande] [commande de désélection]
Par exemple :
MENU -p5 ADD FServe
MENU ADD "FServe/Voir Liste des fichiers" "fs list"
MENU ADD FServe/-
MENU -k4,101 -t1 ADD "FServe/Activer" "fs on" "fs off"
MENU -e0 ADD "FServe/Fait un truc" "fs action"
Dans lʼexemple ci-dessus, il est recommandé dʼexécuter « MENU DEL FServe » dans vorez fonction « xchat_plugin_deinit ». Lʼélément spécial nommé « - » ajoutera une ligne de séparation.
Paramètres et Drapeaux :
-eX | Positionne le drapeau « enable » à X. -e0 pour désactivé, -e1 pour activé. Vous permet de créer un élément désactivé (grisé). |
-iFILE | Utiliser lʼicône dont le nom de fichier est FILE (nouveau dans 2.8.0). Non supporté pour les éléments commutables ou radio. |
-k<mod>,<key> | Spécifier un raccourci clavier. « mod » est le modificateur, un champ de bits (faire un OU logique) : 1-MAJ 4-CTRL 8-ALT en décimal. « key » est la valeur décimale de la touche, ex. : -k5,101 va spécifier MAJ-CTRL-E. |
-m | Spécifie que ce label doit être traité comme écrit en langage Pango Markup. Comme la barre de fraction (« / ») est toujours utilisée dans les chemins du menu, vous devez remplacer les fin de tags par un caractère ASCII 003 ex. : xchat_command(ph, "MENU -m ADD \"<b>Bold Menu<\003b>\""); (nouveau dans 2.6.6). |
-pX | Spécifie un numéro dʼélément dans le menu. ex : -p5 causera lʼinsertion de lʼélément en 5ème ligne. Nouveau dans 2.8.0: Si la position est négative, ce sera un offset à partir de lʼélément en bas à droite. |
-rX,group | Spécifie un élément de menu radio, dont lʼétat initial est X et un nom de groupe (nouveau dans 2.8.0). Le nom du groupe doit être le label exact dʼun autre élément (sans le chemin) avec lequel cet élément est regroupé. Pour les éléments radios, seule la commande « select » sera exécutée (pas de commande « unselect »). |
-tX | Spécifie un élément de menu sélectionnable ainsi que son état initial. -t0 pour un élément « non coché » et -t1 pour un élément « coché ». |
Si vous voulez modifier lʼétat dʼun élément ou dʼun drapeau, ajoutez simplement
un élément ayant exactement le même nom et la même commande en spécifiant les paramètres -tX -eX désirés.
Il est aussi possible dʼajouter des éléments au menus préexistants de XChat, par exemple :
MENU ADD "Settings/Sub Menu"
MENU -t0 ADD "Settings/Sub Menu/My Setting" myseton mysetoff
Toutefois, les noms internes et la disposition des menus XChat peuvent changer dans le futur, donc à utiliser à vos risques et périls…
Voici un exemple dʼéléments Radio :
MENU ADD "Language"
MENU -r1,"English" ADD "Language/English" cmd1
MENU -r0,"English" ADD "Language/Spanish" cmd2
MENU -r0,"English" ADD "Language/German" cmd3
Depuis 2.8.0, il est aussi possible de modifier les menus autres que le menu principal (ex. : les menus popup). Actuellement ce sont :
Nom initial | Menu |
$TAB | Menu Onglet (clic droit sur lʼonglet salon/query ou une ligne du treeview) |
$TRAY | Menu de la barre dʼétat |
$URL | Menu des liens URL |
$NICK | Menu popup de la liste des pseudos |
$CHAN | Menu lors dʼun clic dans la zone texte dʼun salon (depuis 2.8.4) |
Exemple : MENU -p0 ADD "$TAB/Cycle Channel" cycle
Depuis 2.8.0 vous pouvez manipuler les icônes de la barre dʼétat en utilisant la commande « /TRAY » :
Usage:
TRAY -f <timeout> <file1> [<file2>] Faire clignoter la barre dʼétat en alternant deux icônes. Laisser off file2 pour utiliser celle par défaut de xchat.
TRAY -f <filename> Affecter une icône spécifique à la barre dʼétat.
TRAY -i <number> Faire clignoter la barre dʼétat avec une icône interne.
2=Message 5=Surligné 8=Privé 11=Fichier
TRAY -t <text> Affecter au tooltip de la barre dʼétat.
TRAY -b <title> <text> Affecter au ballon de la barre dʼétat.
Supporté sous Windows depuis 2.8.1 et 2.8.2 sous Linux (libnotify nécessaire sous Linux).
Les noms peuvent être au format ICO ou PNG. PNG est supporté sous Linux/BSD et Windows XP (mais nécessite lʼinstallation de GDI+ sous Windows 2000). Mettez un timeout de -1 pour utiliser celui par défaut de XChat.
LʼAPI des greffons de XChat stipule que les chaînes passées depuis ou vers xchat doivent être encodées en UTF-8.
Quʼest-ce que cela implique pour le programmeur? Que vous devez juste faire attention lorsque
vous transférez des chaînes venant dʼIRC vers les appels systèmes. Par exemple, si vous écrivez un robot serveur de fichiers,
où quelquʼun peut vous envoyer un nom de fichier; est-il possible de le passer directement à « open() »? Peut-être!
Si vous êtes laxiste… La manière correcte de faire est de convertir la chaîne en utilisant lʼ« encodage de la locale système »,
sans quoi votre greffon peut échouer avec les caractères non ASCII.
Voici quelques exemples de comment effectuer cette conversion sous Unix et Windows. Dans cet exemple, quelquʼun va
vous CTCP le message « SHOWFILE <filename> ».
static int ctcp_cb(char *word[], char *word_eol[], void *userdata)
{
if(strcmp(word[1], "SHOWFILE") == 0)
{
get_file_name(nick, word[2]);
}
return XCHAT_EAT_XCHAT;
}
static void get_file_name(char *nick, char *fname)
{
char buf[256];
FILE *fp;
/* fname est en UTF-8, puisquʼil vient de lʼAPI xchat */
#ifdef _WIN32
wchar_t wide_name[MAX_PATH];
/* Conversion de UTF-8 vers WIDECHARs (aka UTF-16LE) */
if (MultiByteToWideChar(CP_UTF8, 0, fname, -1, wide_name, MAX_PATH) < 1)
return;
/* maintenant nous avons des WIDECHARs, donc on peut _wopen() ou CreateFileW(). */
/* _wfopen nécessite NT4, Win2000, XP ou plus récent. */
fp = _wfopen(wide_name, "r");
#else
char *loc_name;
/* conversion de UTF-8 vers lʼencodage système */
loc_name = g_filename_from_utf8(fname, -1, 0, 0, 0);
if(!loc_name)
return;
/* maintenant ouvrir en utilisant lʼencodage système */
fp = fopen(loc_name, "r");
g_free(loc_name);
#endif
if (fp)
{
while (fgets (buf, sizeof(buf), fp))
{
/* envoyer chacune des lignes à lʼutilisateur qui les a demandé */
xchat_commandf (ph, "QUOTE NOTICE %s :%s", nick, buf);
}
fclose (fp);
}
}
Fonctions
Prototype : xchat_hook *xchat_hook_command(xchat_plugin *ph, const char *name, int pri, xchat_cmd_cb *callb, const char *help_text, void *userdata);
Description : Ajoute une nouvelle «/command ». Permet à votre greffon
gérer les commandes depuis la boite de saisies. Pour capturer du texte sans « / » initial
(non-commandes), vous pouver greffer le nom spécial "". ex. : xchat_hook_command(ph, "", …);.
Depuis la version 2.6.8, les commandes greffées débutant par un point ('.') seront cachées dans « /HELP » et « /HELP -l ».
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
name : Nom de la commande (sans la barre de fraction initiale).
pri : Priorité de cette commande. Utiliser XCHAT_PRI_NORM.
callb : Fonction callback. Celle qui sera appelée quand lʼutilisateur exécutera une certaine commande.
help_text : Chaîne de texte à afficher lorsque lʼutilisateur exécute « /help » pour cette commande. Peut être NULL si vous êtes fainéant.
userdata : Pointeur passé à la fonction callback.
Retourne : Pointeur vers la greffe. Peut être passé à « xchat_unhook ».
Exemple :
static int onotice_cb(char *word[], char *word_eol[], void *userdata)
{
if(word_eol[2][0] == 0)
{
xchat_printf(ph, "Second arg must be the message!\n");
return XCHAT_EAT_ALL;
}
xchat_commandf(ph, "NOTICE @%s :%s", xchat_get_info(ph, "channel"), word_eol[2]);
return XCHAT_EAT_ALL;
}
xchat_hook_command(ph, "ONOTICE", XCHAT_PRI_NORM, onotice_cb,
"Usage: ONOTICE <message> Sends a notice to all ops", NULL);
Prototype : xchat_hook *xchat_hook_fd(xchat_plugin *ph, int fd, int flags, xchat_fd_cb *callb, void *userdata);
Description : Greffe une socket ou un descripteur de fichier. WIN32 : Passer un tube depuis MSVCR71, MSVCR80 ou autre variations nʼest pas supporté pour lʼinstant.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
fd : Le descripteur de fichier ou la socket.
Drapeaux : Un ou plus parmi XCHAT_FD_READ, XCHAT_FD_WRITE, XCHAT_FD_EXCEPTION, XCHAT_FD_NOTSOCKET. Utiliser le ou pour les combiner.
XCHAT_FD_NOTSOCKET indique à xchat due le fd indiqué n ʼest pas une socket, mais un tube « MSVCRT.DLL ».
callb : Fonction callback. Celle qui sera appelée lorsque la socket est disponible pour la lecture/lʼécriture ou lors quʼune exception (suivant les drapeaux utilisés)
userdata : Pointer passé à la fonction callback.
Retourne : Pointeur vers la greffe. Peut être passé à « xchat_unhook ».
Prototype : xchat_hook *xchat_hook_print(
xchat_plugin *ph,
const char *name,
int pri,
xchat_print_cb *callb,
void *userdata);
Description : Enregistre une fonction pour capturer tous les évènements dʼaffichages.
Les noms de ces événements peuvent être nʼimporte lequel de ceux disponibles dans la fenêtre « Avancé > Evènements Texte ».
Il existe aussi des évènements supplémentaires « spéciaux » sur lesquels vous pouvez greffer cette fonction.
Actuellement ce sont :
"Open Context" - Appelée lorsquʼun nouveau xchat_contexte est créé.
"Close Context" - Appelée lorsquʼun pointeur xchat_context est libéré.
"Focus Tab" - Appelée lorsquʼun onglet est mis en avant.
"Focus Window" - Appelée lorsquʼune fenêtre est prends le focus ou que le fenêtre principale
des onglets prends le focus par le gestionnaire de fenêtre.
"DCC Chat Text" - Appelée lorsque du texte arrive par DCC Chat. Les éléments se trouvent dans la table word[] :word[1] Adresse
word[2] Port
word[3] Pseudo
word[4] Le Message
"Key Press" - Appelée lorsquʼune touche est pressée dans la boite de saisie (depuis 2.4.2). Les éléments se trouvent dans la table word[] :word[1] Valeur de la touche
word[2] Champ de bits dʼétat (maj, ctrl, alt …)
word[3]Version chaîne de la touche
word[4] Longueur de la chaîne (peut être de zéro pour les caractères non imprimables)
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
name : Nom de lʼévénement dʼaffichage (comme dans la fenêtre « Edition des Evènements Textes »).
pri : Priorité de cette commande. Utiliser « XCHAT_PRI_NORM ».
callb : Fonction callback. Celle qui sera appelée lors dʼun affichage de ce type dʼévénement.
userdata : Pointeur passé à la fonction callback.
Retourne : Pointeur vers la greffe. Peut être passé à « xchat_unhook ».
Exemple :
static int youpart_cb(char *word[], void *userdata)
{
xchat_printf(ph, "You have left channel %s\n", word[3]);
return XCHAT_EAT_XCHAT; /* ne pas laisser xchat effectuer son affichage normal */
}
xchat_hook_print(ph, "You Part", XCHAT_PRI_NORM, youpart_cb, NULL);
Prototype : xchat_hook *xchat_hook_server(xchat_plugin *ph, const char *name, int pri, xchat_serv_cb *callb, void *userdata);
Description : Enregistre une fonction à appeler lorsquʼun certain événement se produit sur le serveur. Vous pouvez lʼutiliser
pour capturer PRIVMSG, NOTICE, PART, une numéro de serveur etc… Si vous désirez capturer toutes
les en provenance du serveur IRC, vous pouvez utiliser le nom spécial « RAW LINE ».
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
name : Nom de lʼévénement du serveur.
pri : Priorité de cette commande. Utiliser « XCHAT_PRI_NORM ».
callb : Fonction callback. Celle qui sera appelée lorsque le type dʼévénement sera reçu depuis le serveur.
userdata : Pointeur passé à la fonction callback.
Retourne : Pointeur vers la greffe. Peut être passé à « xchat_unhook ».
Exemple :
static int kick_cb(char *word[], char *word_eol[], void *userdata)
{
xchat_printf(ph, "%s was kicked from %s (reason=%s)\n", word[4], word[3], word_eol[5]);
return XCHAT_EAT_NONE; /* ne pas avaler cet événement, laisser les autres greffons et xchat le voir aussi */
}
xchat_hook_server(ph, "KICK", XCHAT_PRI_NORM, kick_cb, NULL);
Prototype : xchat_hook *xchat_hook_timer(xchat_plugin *ph, int timeout, xchat_timer_cb *callb, void *userdata);
Description : Enregistre une fonction à appeler toutes les « timeout » millisecondes.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
timeout : Timeout en millisecondes (1000 représente 1 seconde).
callb : Fonction du callback. Sera appelée toutes les « timeout » millisecondes.
userdata : Pointeur passé à la fonction callback.
Retourne : Pointeur vers la greffe. Peut être passée à « xchat_unhook ».
Exemple :
static xchat_hook *myhook;
static int stop_cb(char *word[], char *word_eol[], void *userdata)
{
if(myhook != NULL)
{
xchat_unhook(ph, myhook);
myhook = NULL;
xchat_print(ph, "Timeout removed!\n");
}
return XCHAT_EAT_ALL;
}
static int timeout_cb(void *userdata)
{
xchat_print(ph, "Annoying message every 5 seconds! Type /STOP to stop it.\n");
return 1; /* return 1 pour laisser le timeout continuer */
}
myhook = xchat_hook_timer(ph, 5000, timeout_cb, NULL);
xchat_hook_command(ph, "STOP", XCHAT_PRI_NORM, stop_cb, NULL, NULL);
Prototype : void *xchat_unhook(xchat_plugin *ph, xchat_hook *hook);
Description : Supprime les greffes enregistrées grâce à « xchat_hook_print/server/timer/command ». Lorsquʼun greffon est déchargé, toutes ses greffes sont automatiquement
supprimées, donc inutile dʼappeler cette fonction dans votre fonction « xchat_plugin_deinit() ».
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
hook: Pointeur vers la greffe, telle que retourné par « xchat_hook_* ».
Retourne : Les données utilisateur passées à lʼorigine à « xchat_hook_* ».
Prototype : void xchat_command(xchat_plugin *ph, const char *command);
Description : Exécute une commande comme si elle avait été tapée dans la boite de saisie de xchat.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
command: Commande à exécuter, sans la barre de fraction « / » initiale.
Prototype : void xchat_commandf(xchat_plugin *ph, const char *format, ...);
Description : Exécute une commande comme si elle était tapée dans la boite de saisie de xchat en utilisant le formatage à la printf.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
format : La chaîne de format.
Prototype : void xchat_print(xchat_plugin *ph, const char *text);
Description : Affiche du texte dans la fenêtre/lʼonglet courant.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
texte : Texte à afficher. Peut contenir des codes couleur mIRC.
Prototype : void xchat_printf(xchat_plugin *ph, const char *format, ...);
Description : Affiche du texte dans la fenêtre/lʼonglet courant à la manière de printf.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
format : La chaîne de format.
Prototype : int xchat_emit_print(xchat_plugin *ph, const char *event_name, ...);
Description : Génère un évènement a afficher. Ce peut être nʼimporte
quel évènement se trouvant dans « Paramètres > Avancé > Fenêtre dʼévènements texte. La liste de paramètre
vararg DOIT toujours se terminer par NULL. Une attention particulière doit être apportée lors de lʼutilisation
cette fonction dans un callback dʼimpression (dans xchat_hook_print), pour éviter tout problème de boucle sans fin.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
event_name : Evènement texte à afficher.
Retourne : 1-Succès 0-Echec.
Exemple :
xchat_emit_print(ph, "Message Canal", "John", "Salut à tous", "@", NULL);
Prototype : void xchat_send_modes (xchat_plugin *ph, const char *targets[], int ntargets, int modes_per_line, char sign, char mode)
Description : Emmet un certain nombre de changement de mode du salon courant. Par exemple, vous pouvez Op un groupe
entier de personnes en une action. Elle peut envoyer plusieurs lignes MODE si la requête ne tient pas sur une seule. Passez 0
dans
modes_per_line pour utiliser le maximum possible. Cette fonction ne doit être appelée que depuis un contexte de salon.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
targets : Table des destinations (strings). Les noms des gens pour lesquels lʼaction sera effectuée.
ntargets : Nombre dʼéléments dans la table.
modes_per_line : Nombre maximum de nœuds à envoyer par ligne.
sign : Signe du mode, « - » ou «+ ».
mode : caractère du mode, ex. : « o » pour Ops.
Exemple : (Ops les trois noms donnés)
const char *names_to_Op[] = {"John", "Jack", "Jill"};
xchat_send_modes(ph, names_to_Op, 3, 0, '+', 'o');
Prototype : xchat_context *xchat_find_context(xchat_plugin *ph, const char *servname, const char *channel);
Description : Trouve un salon basé sur le contexte et le servername. Si servname est NULL, trouve le salon (ou query) par le nom donné. Si le salon est NULL, trouve lʼonglet ou la fenêtre le plus en avant sur le servname spécifié. Si NULL est spécifié pour les deux arguments, la fenêtre ou lʼonglet ayant le focus est retourné.
Modifié dans 2.6.1. Si servname est NULL, trouve le salon (ou query) par son le nom spécifié dans le même groupe de serveur que le contexte courant. Sʼil nʼen existe pas, trouve nʼimporte lequel ayant le nom spécifié.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
servname : Servername ou NULL.
channel : Channelname ou NULL.
Retourne : Pointeur vers le contexte (à utiliser avec « xchat_set_context ») ou NULL.
Prototype : xchat_context *xchat_get_context(xchat_plugin *ph);
Description : Retourne le contexte pour le greffon. Vous pourrez lʼutiliser plus tard avec « xchat_set_context ».
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
Retourne : Pointer vers le contexte (à ustiliser avec xchat_set_context).
Prototype : const char *xchat_get_info(xchat_plugin *ph, const char *id);
Description : Retourne les informations basées sur votre contexte actuel.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
id : ID des informations désirées. Les IDs actuellement supportés sont (sensible à la casse) :
away | raison du départ ou NULL si vous nʼêtes pas away. |
channel | nom du salon courrant. |
charset | character-set utilisé par le contexte courant (depuis 2.4.2). |
event_text <nom> | chaîne de format de lʼévénement texte pour nom (depuis 2.8.2). |
host | hostname réel du serveur auquel vous êtes connecté. |
inputbox | le contenu de la boite de saisie, ce que lʼutilisateur a tappé (depuis 2.4.1). |
libdirfs | dossier des bibliothèques ex. : /usr/lib/xchat. Le même dossier que celui utilisé pour auto-charger les greffons (depuis 2.4.0).Cette chaîne nʼest pas forcément en UTF-8, mais dans lʼencodage système. |
modes | modes du salon, sʼils sont connus ou NULL (depuis 2.8.1). |
network | nom du réseau courant ou NULL. |
nick | votre pseudo actuel. |
nickserv | mot de passe nickserv pour ce réseau ou NULL (depuis 2.4.3). |
server | nom du serveur courant (ce que le serveur dit être). NULL si vous nʼêtes pas connecté. |
topic | topique courant du salon. |
version | numéro de version de xchat. |
win_ptr | pointeur natif vers la fenêtre. Unix : (GtkWindow *) Win32 : HWND (depuis 2.6.0). |
win_status | Statut de la fenêtre : « active », « cachée » ou « normale » (depuis 2.0.9). |
xchatdir | dossier de configuration de xchat, ex. : /home/user/.xchat2 Cette chaîne est encodée en UTF-8, ce qui signifie que vous _devez_ la convertir dans lʼencodage « local » avant dʼutiliser des fonctions telles que « open() » ou « OpenFile() ». Pour un meilleur support Unicode sous Linux, convertissez cette chaîne avec g_filename_from_utf8 et sous Windows convertissez la en UTF-16LE (wide) et utilisez « OpenFileW() » etc… |
xchatdirfs | dossier de configuration de xchat, ex. : /home/user/.xchat2 (depuis 2.0.9).Cette chaîne est encodée dans au format du système de fichiers local, la rendant idéale pour une utilisation directe avec les fonctions telles que « open() » ou « OpenFile() ». Pour un support Unicode réel sous Windows, mieux vaut ne pas utiliser xchatdirfs, mais plutôt xchatdir. |
Retourne : Une chaîne contenant les information demandées ou NULL. Cette chaîne ne doit
pas être désallouée mais doit être recopiée si nécessaire après lʼappel à « xchat_get_info ».
Prototype : int xchat_get_prefs(xchat_plugin *ph, const char *name, const char **string, int *integer);
Description : Fournie les informations de configuration de xchat (celles disponibles par la commande « /set »).
Quelques information supplémentaires ne sont pas disponibles dans la liste de « /set », actuellement ce sont :
state_cursor | Position actuelle du curseur dans la boite de saisie (en charactères, pas en octets). depuis 2.4.2. |
id | ID unique du serveur. Depuis 2.6.1. |
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
name : Nom du paramètre désiré.
string : Pointeur vers le pointeur à générer.
integer : Pointeur vers lʼinteger à générer, si la configuration spécifie Boolean ou Integer.
Retourne : 0-Echec 1-Chaîne retournée 2-Integer Retourné 3-Booléen retourné.
Exemple :
{
int i;
const char *str;
if (xchat_get_prefs (ph, "irc_nick1", &str, &i) == 1)
{
xchat_printf (ph, "Current nickname setting: %s\n", str);
}
}
Prototype : int xchat_set_context(xchat_plugin *ph, xchat_context *ctx);
Description : Remplace le contexte courant pour celui spécifié.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
ctx : Contexte vers lequel changer (obtenu par « xchat_get_context » ou « xchat_find_context »).
Retourne : 1 en cas de succès, 0 en cas dʼéchec.
Prototype : int xchat_nickcmp(xchat_plugin *ph, const char *s1, const char *s2);
Description : Effectue une comparaison entre deux pseudos, basée sur la connexion serveur courante. Ce devrait être une comparaison de chaînes respectant la RFC1459 ou
ASCII (dans le cas de DALNet). A utiliser pour comparer les noms de canaux ou les pseudos. Cette fonction fonctionne de la même manière que « strcasecmp ».
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
s1 : Chaîne à comparer.
s2 : chaîne à comparer à s1.
Extrait de RFC1459 :
Du fait de lʼorigine scandinave de IRC, les caractères {}| sont considérés
comme étant les équivalents minuscules respectifs de []\. Cʼest un problème
critique (NDT : chez les anglophones, puisque ce mode de fonctionnement est
utilisé par lʼEurope sauf UK aussi bien que par lʼasie) pour la détermination de lʼidentité
de deux pseudos.
Retourne : Un integer plus petit que, égal à, ou plus grand que zéro selon que s1 doive être respectivement, plus petite que, égale à, ou plus grande que s2.
Prototype : char *xchat_strip(xchat_plugin *ph, const char *str, int len, int flags);
Description : Supprime les codes de couleurs mIRC et/ou les attributs de texte (gras, souligné,…) de la chaîne spécifiée et retourne une chaîne nouvellement allouée.
Arguments :
ph : Handle du greffon (tel que reçu par « xchat_plugin_init »).
str : Chaîne à épurer.
len : Longueur de la chaîne (ou -1 pour les NULL terminated).
flags : champ de bits : 0-Epurer les couleurs mIRC, 1-Epurer les attributs texte.
Retourne :
Une chaîne nouvellement allouée ou NULL en cas dʼéchec. Cette chaîne doit être libérée avec « xchat_free ».
Exemple :
{
char *new_text;
/* strip both colors and attributes by using the 0 and 1 bits (1 BITWISE-OR 2) */
new_text = xchat_strip(ph, "\00312Blue\003 \002Bold!\002", -1, 1 | 2);
if(new_text)
{
/* new_text should now contain only "Blue Bold!" */
xchat_printf(ph, "%s\n", new_text);
xchat_free(ph, new_text);
}
}
Prototype : void xchat_free(xchat_plugin *ph, void *ptr);
Description : Libère une chaîne retournée par les fonctions « xchat_* ». Actuellement utilisé uniquement pour les chaînes venant de « xchat_strip ».
Arguments :
ph : Handle du greffon (tel que « xchat_plugin_init » lʼa reçu).
ptr : Pointeur à libérer.