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

Introduction

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?


Exemple de greffon

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 */
}

Que sont word et word_eol?

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.


Listes et Champs

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.
NomDescriptionType
channelNom du salon ou du querystring
chantypesTypes 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_contextstring
flagsBits dʼétat Serveur/Salon :
Bit #ValeurDescription
01Connecté
12Connection en cours
24Vous êtes away
38Fin de MOTD (Login effectué)
416Possède WHOX (ircu)
532Possède IDMSG (FreeNode)
664Messages Join/Part cachés
7128Inutilisé (représentait « Color Paste » dans les anciennes versions)
8256Beep sur Message reçu
9512Fait clignoter la barre dʼétat
101024Fait 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
idID unique du serveur
(Ajouté depuis la version 2.0.8. Les anciennes versions retourneront -1)
int
lagLag en millisecondes
(Ajouté depuis la version 2.6.8. Les anciennes versions retourneront -1)
int
maxmodesNombre maximum de nœuds par ligne
(Ajouté depuis la version 2.0.9. Les anciennes versions retourneront -1)
int
networkNom du réseau auquel le salon appartient
(Ajouté depuis la version 2.0.2. Les anciennes versions retourneront NULL)
string
nickprefixesPréfixes des Pseudos ex : « @+ »
(Ajouté depuis la version 2.0.9. Les anciennes versions retourneront NULL)
string
nickmodesCaractères des modes des Pseudos ex. : « ov »
(Ajouté depuis la version 2.0.9. Les anciennes versions retourneront NULL)
string
queueNombre dʼoctets dans le tampon dʼenvoi
(Ajouté depuis la version 2.6.8. Les anciennes versions retourneront -1)
int
serverNom du serveur auquel ce salon appartientstring
typeType de contexte : 1-Serveur 2-Salon 3-Dialogue
(Ajouté depuis la 2.0.2. Les anciennes versions retourneront -1)
int
usersNombre 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 :
NomDescriptionType
address32Adresse de lʼutilisateur distant (adresse ipv4)int
cpsOctets par seconde (vitesse)int
destfileChemin complet de destinationstring
fileNom du fichierstring
nickPseudo de la personne à laquelle le fichier est destiné / de laquelle ce fichier provientstring
portnuméro du port TCPint
posOctets émis/reçusint
resumePointe au début de la reprise du transfert (ou zéro si aucune reprise)int
sizeTaille du fichier en octets, 32 bits bas (caste vers unsigned)int
sizehighTaille du fichier en octets, 32 bits hautsint
statusStatut DCC : 0-Mis en tampon 1-Actif 2-Echec 3-Terminé 4-Connection en cours 5-Abandonnéint
typeType de DCC : 0-Envoi 1-Réception 2-Chat Reçu 3-Chat Emisint
"ignore" - liste des ignorés actifs.
NomeDescriptionType
maskMasque dʼignorance. ex. : *!*@*.aol.comstring
flagsChamp 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.
NomDescriptionType
networksRéseaux sur lesquels le pseudo se situe. Séparés par virgules. Peut être NULL.
(Ajouté dans la version 2.6.8)
string
nickPseudostring
flagsChamp de bits. 0=En ligne.int
onHeure dʼarrivée de lʼutilisateur.time_t
offHeure de départ de lʼutilisateur.time_t
seenHeure 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.
NomDescriptionType
awayStatut Away (booléen)
(Ajouté depuis la version 2.0.6. Les anciennes versions retourneront -1)
int
lasttalkDernière fois que lʼutilisateur à parlé
(Ajouté depuis la version 2.4.2. Les anciennes versions retourneront -1)
time_t
nickPseudostring
hostNom de lʼhôte suivant la forme : user@host (ou NULL si inconnu).string
prefixCaractère de préfixe, es. : @ ou + ou ~. Pointeur vers un seul caractère.string
realnameNom réel ou NULL
(Ajouté depuis la version 2.8.6)
string
selectedStatut 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);
   }

Greffons sous Windows (Win32)

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

Contrôler la GUI

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 ATTACHMême fonction que « Attacher la fenêtre » du menu de XChat menu (nouveau dans 2.6.2).
GUI DETACHMême fonction que « Détacher lʼonglet » du menu de XChat (nouveau dans 2.6.2).
GUI APPLYIdentique à 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 nModifier la couleur de lʼonglet correspondant au contexte courant, avec n compris entre 0 et 3 inclus.
GUI FOCUSDonne le focus à la fenêtre ou à lʼonglet courant.
GUI FLASHFaire 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 HIDECacher la fenêtre principale de xchat (utilisé par le greffon Systray).
GUI ICONIFYIcônifier (minimiser sur la barre des tâches) la fenêtre courante de xchat.
GUI MSGBOX texteAffiche une boite de message asynchrone contenant votre texte (nouveau dans 2.4.5).
GUI SHOWAfficher 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 :
-eXPositionne le drapeau « enable » à X. -e0 pour désactivé, -e1 pour activé. Vous permet de créer un élément désactivé (grisé).
-iFILEUtiliser 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.
-mSpé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).
-pXSpé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,groupSpé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 »).
-tXSpé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 initialMenu
$TABMenu Onglet (clic droit sur lʼonglet salon/query ou une ligne du treeview)
$TRAYMenu de la barre dʼétat
$URLMenu des liens URL
$NICKMenu popup de la liste des pseudos
$CHANMenu 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.

Gérer les chaînes UTF-8/Unicode

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

 xchat_hook_command() 

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

 xchat_hook_fd() 

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 ».


 xchat_hook_print() 

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

 xchat_hook_server() 

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

 xchat_hook_timer() 

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

 xchat_unhook() 

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_* ».

 xchat_command() 

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.

 xchat_commandf() 

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.

 xchat_print() 

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.

 xchat_printf() 

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.

 xchat_emit_print() 

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


 xchat_send_modes() (nouveau dans 2.0.9)

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


 xchat_find_context() 

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.


 xchat_get_context() 

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


 xchat_get_info() 

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) :
awayraison du départ ou NULL si vous nʼêtes pas away.
channelnom du salon courrant.
charsetcharacter-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).
hosthostname réel du serveur auquel vous êtes connecté.
inputboxle contenu de la boite de saisie, ce que lʼutilisateur a tappé (depuis 2.4.1).
libdirfsdossier 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.
modesmodes du salon, sʼils sont connus ou NULL (depuis 2.8.1).
networknom du réseau courant ou NULL.
nickvotre pseudo actuel.
nickservmot de passe nickserv pour ce réseau ou NULL (depuis 2.4.3).
servernom du serveur courant (ce que le serveur dit être). NULL si vous nʼêtes pas connecté.
topictopique courant du salon.
versionnuméro de version de xchat.
win_ptrpointeur natif vers la fenêtre. Unix : (GtkWindow *) Win32 : HWND (depuis 2.6.0).
win_statusStatut de la fenêtre : « active », « cachée » ou « normale » (depuis 2.0.9).
xchatdirdossier 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…
xchatdirfsdossier 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 ».


 xchat_get_prefs() 

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_cursorPosition actuelle du curseur dans la boite de saisie (en charactères, pas en octets). depuis 2.4.2.
idID 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);
	}
}


 xchat_set_context() 

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.


 xchat_nickcmp() 

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.


 xchat_strip() (nouveau dans 2.4.2)

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


 xchat_free() (nouveau dans 2.4.2)

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.