Ce document est une spécification du protocole Relay de WeeChat : le protocole utilisé pour relayer les données de WeeChat aux clients, qui sont surtout des interfaces distantes.

1. Introduction

1.1. Terminologie

Les termes suivants sont utilisés dans ce document :

  • relay : il s’agit de l’extension "relay" de WeeChat, qui agit comme un "serveur" et autorise les clients à se connecter

  • client : il s’agit d’un autre logiciel, connecté au relay via une connexion réseau; dans la plupart des cas, ce client est une interface distante.

1.2. Diagramme réseau

Les clients sont connectés au relay comme dans le diagramme ci-dessous :

                                              ┌──────────┐ Station de travail
 ┌────────┐                               ┌───┤ client 1 │ (Linux, Windows,
 │  irc   │◄──┐  ╔═══════════╤═══════╗    │   └──────────┘ BSD, Mac OS X ...)
 └────────┘   └──╢           │       ║◄───┘   ┌──────────┐
   ......        ║  WeeChat  │ Relay ║◄───────┤ client 2 │ Appareil mobile
 ┌────────┐   ┌──╢           │       ║◄───┐   └──────────┘ (Android, iPhone ...)
 │ jabber │◄──┘  ╚═══════════╧═══════╝    │      ......
 └────────┘                               │   ┌──────────┐
   ......                                 └───┤ client N │ Autres appareils
                                              └──────────┘


└────────────┘   └───────────────────┘╘══════╛└────────────────────────────────┘
   serveurs        interface ncurses  protocole      interfaces distantes
                                        relay
Note
Tous les clients ici utilisent le protocole weechat dans l’extension relay. L’extension relay autorise aussi des clients IRC, et relay agit alors comme un proxy IRC (non décrit dans ce document).

2. Généralités sur le protocole

  • Les connexions du client vers relay sont faites avec des sockets TCP sur l’IP/port utilisé par relay pour écouter les nouvelles connexions.

  • Le nombre de clients est limité par l’option relay.network.max_clients.

  • Chaque client est indépendant des autres clients.

  • Les messages du client vers relay sont appelés commandes, elles sont envoyées sous forme de texte (une chaîne de caractères).

  • Les messages de relay vers le client sont appelés des messages, ils sont envoyés sous forme de données binaires.

3. Commandes (client → relay)

Les commandes ont le format : "(id) commande paramètres\n".

Les champs sont :

  • id : identifiant du message (facultatif) qui sera envoyée dans la réponse de relay; elle doit être entre parenthèses, et ne doit pas commencer par un underscore ("_") (les identifiants commençant par un underscore sont réservés pour les messages évènements de WeeChat)

  • commande : une commande (voir le tableau ci-dessous)

  • paramètres : paramètres facultatifs pour la commande (plusieurs paramètres sont séparés par des espaces).

Liste des commandes disponibles (détail dans les chapitres suivants) :

Commande Description

init

Initialiser la connexion avec relay

hdata

Demander un hdata

info

Demander une info

infolist

Demander une infolist

nicklist

Demander une nicklist (liste de pseudos)

input

Envoyer des données à un tampon (texte ou commande)

sync

Synchroniser un/des tampon(s) (recevoir les mises à jour pour le(s) tampon(s))

desync

Désynchroniser un/des tampon(s) (stopper les mises à jour pour le(s) tampon(s))

quit

Se déconnecter de relay

3.1. init

Initialiser la connexion avec relay. Il doit s’agir de la première commande envoyée à relay. Si elle n’est pas envoyée, relay coupera la connexion à la première commande reçue, sans avertissement.

Syntaxe :

init [<option>=<valeur>,[<option>=<valeur>,...]]

Paramètres :

  • option : une des options suivantes :

    • password : mot de passe utilisé pour s’authentifier avec relay (option relay.network.password dans WeeChat)

    • compression : type de compression :

      • zlib : activer la compression zlib pour les messages envoyés par relay

      • off : désactiver la compression

Note
La compression zlib est activée par défaut si relay supporte la compression zlib.

Exemples :

# initialiser et utiliser la compression zlib par défaut (si WeeChat la supporte)
init password=mypass

# initialiser et désactiver la compression
init password=mypass,compression=off

3.2. hdata

Demander un hdata.

Syntaxe :

(id) hdata <chemin> [<clés>]

Paramètres :

  • chemin : chemin vers le hdata, avec le format : "hdata:pointeur/var/var/…/var", la dernière variable est le hdata retourné :

    • hdata : nom du hdata

    • pointeur : pointeur ("0x12345") ou nom de liste (par exemple : "gui_buffers") (nombre autorisé, voir ci-dessous)

    • var : un nom de variable dans le hdata parent (nom précédent dans le chemin) (nombre autorisé, voir ci-dessous)

  • clés : liste de clés (séparées par des virgules) à retourner dans le hdata (si non spécifié, toutes les clés sont retournées, ce qui n’est pas recommandé avec les grosses structures hdata)

Un nombre est autorisé après le pointeur et les variables, avec le format "(N)". Les valeurs possibles sont :

  • nombre positif : itérer en utilisant l'élément suivant, N fois

  • nombre négatif : itérer en utilisant l'élément précédent, N fois

  • * : itérer en utilisant l'élément suivant, jusqu'à la fin de la liste

Exemples :

# demander tous les tampons, un hdata de type "buffer" est retourné
# les clés "number" et "name" sont retournées pour chaque tampon
hdata buffer:gui_buffers(*) number,name

# demander toutes les lignes de tous les tampons, un hdata de type "line_data"
# est retourné
# toutes les clés sont retournées
hdata buffer:gui_buffers(*)/lines/first_line(*)/data

# demander le nom complet du premier tampon
hdata buffer:gui_buffers full_name

3.3. info

Demander une info.

Syntaxe :

(id) info <nom> [<paramètres>]

Paramètres :

  • nom : nom de l’info à obtenir

  • paramètres : paramètres pour l’info (facultatif)

Exemple :

info version

3.4. infolist

Demander une infolist.

Important
Le contenu de l’infolist est une duplication des données. Dans la mesure du possible, utilisez plutôt la commande hdata, qui est un accès direct aux données (cela est plus rapide, utilise moins de mémoire et retourne des objets plus petits dans le message).

Syntaxe :

(id) infolist <nom> [<pointeur> [<paramètres>]]

Paramètres :

  • nom : nom de l’infolist à obtenir

  • pointeur : pointeur (facultatif)

  • paramètres : paramètres (facultatif)

Exemple :

infolist buffer

3.5. nicklist

Demander une nicklist (liste de pseudos), pour un ou tous les tampons.

Syntaxe :

(id) nicklist [<tampon>]

Paramètres :

  • tampon : pointeur (0x12345) ou nom complet du tampon (par exemple : core.weechat ou irc.freenode.#weechat)

Exemples :

# demander la liste de pseudos pour tous les tampons
nicklist

# demander la liste de pseudos pour irc.freenode.#weechat
nicklist irc.freenode.#weechat

3.6. input

Envoyer des données à un tampon.

Syntaxe :

input <tampon> <données>

Paramètres :

  • tampon : pointeur (0x12345) ou nom complet du tampon (par exemple : core.weechat ou irc.freenode.#weechat)

  • données : données à envoyer au tampon : si elles commencent par /, cela sera exécuté comme une commande sur le tampon, sinon le texte est envoyé comme entrée sur le tampon

Exemples :

input core.weechat /help filter
input irc.freenode.#weechat bonjour !

3.7. sync

Mis à jour dans la version 0.4.1.

Synchroniser un ou plusieurs tampons, pour obtenir les mises à jour.

Important
Il est recommandé d’utiliser cette commande immédiatement après avoir demandé les données des tampons (lignes, …). Elle peut être envoyée dans le même message (après un caractère de nouvelle ligne : "\n").

Syntaxe :

sync [<tampon>[,<tampon>...] <option>[,<option>...]]

Paramètres :

  • tampon : pointeur (0x12345) ou nom complet du tampon (par exemple : core.weechat ou irc.freenode.#weechat); le nom "*" peut être utilisé pour spécifier tous les tampons

  • options : un ou plusieurs mots-clés, séparés par des virgules (par défaut buffers,upgrade,buffer,nicklist pour "*" et buffer,nicklist pour un tampon) :

    • buffers : recevoir les signaux à propos des tampons (ouverts/fermés, déplacés, renommés, mélangés, masqués/démasqués); peut être utilisé seulement avec "*" (WeeChat ≥ 0.4.1)

    • upgrade : recevoir les signaux à propos de la mise à jour de WeeChat (mise à jour, fin de mise à jour); peut être utilisé seulement avec "*" (WeeChat ≥ 0.4.1)

    • buffer : recevoir les signaux à propos du tampon (nouvelles lignes, type changé, titre changé, variable locale ajoutée/supprimée, et les même signaux que buffers pour le tampon) (mis à jour dans la version 0.4.1)

    • nicklist : recevoir la liste de pseudos après des changements

Exemples :

# synchroniser tous les tampons avec la liste de pseudos
# (les 3 commandes sont équivalentes, mais la première est recommandée pour une
# compatibilité avec les futures versions)
sync
sync *
sync * buffers,upgrade,buffer,nicklist

# synchroniser le tampon "core"
sync core.buffer

# synchroniser le canal #weechat, sans la liste de pseudos
sync irc.freenode.#weechat buffer

# obtenir les signaux généraux + tous les signaux pour le canal #weechat
sync * buffers,upgrade
sync irc.freenode.#weechat

3.8. desync

Mis à jour dans la version 0.4.1.

Désynchroniser un ou plusieurs tampons, pour stopper les mises à jour.

Note
Ceci retirera les options pour les tampons. Si des options sont toujours actives pour les tampons, le client recevra toujours les mises à jour pour ces tampons.

Syntaxe :

desync [<tampon>[,<tampon>...] <option>[,<option>...]]

Paramètres :

  • tampon : pointeur (0x12345) ou nom complet du tampon (par exemple : core.weechat ou irc.freenode.#weechat); le nom "*" peut être utilisé pour spécifier tous les tampons

  • options : un ou plusieurs mots-clés, séparés par des virgules (le défaut est buffers,upgrade,buffer,nicklist pour "*" et buffer,nicklist pour un tampon); voir la commande sync pour les valeurs

Note
En utilisant le tampon "*", les autres tampons synchronisés (en utilisant un nom) sont gardés.
Donc si vous envoyez : "sync *", puis "sync irc.freenode.#weechat", puis "desync *", les mises à jour sur le canal #weechat seront toujours envoyées par WeeChat (vous devez le retirer explicitement pour stopper les mises à jour).

Exemples :

# désynchroniser tous les tampons
# (les 3 commandes sont équivalentes, mais la première est recommandée pour une
# compatibilité avec les futures versions)
desync
desync *
desync * buffers,upgrade,buffer,nicklist

# désynchroniser la liste de pseudos pour le canal #weechat
# (garder les mises à jour du tampon)
desync irc.freenode.#weechat nicklist

# désynchroniser le canal #weechat
desync irc.freenode.#weechat

3.9. test

Commande de test : WeeChat répondra avec différents objets.

Cette commande est utile pour tester le décodage d’objets binaires retournés par WeeChat.

Important
Vous ne devez pas utiliser les pointeurs retournés par cette commande, ils ne sont pas valides. Cette commande doit être utilisée seulement pour tester le décodage d’un message envoyé par WeeChat.

Syntaxe :

test

Exemple :

test

Objets retournés (dans cet ordre) :

Type Type (dans le message) Valeur

caractère

chr

65 ("A")

entier

int

123456

entier

int

-123456

long

lon

1234567890

long

lon

-1234567890

chaîne

str

"a string"

chaîne

str

""

chaîne

str

NULL

tampon de données

buf

"buffer"

tampon de données

buf

NULL

pointeur

ptr

0x1234abcd

pointeur

ptr

NULL

date/heure

tim

1321993456

tableau de chaînes

arr str

[ "abc", "de" ]

tableau d’entiers

arr int

[ 123, 456, 789 ]

3.10. ping

WeeChat ≥ 0.4.2.

Envoyer un ping à WeeChat qui répondra avec un message "_pong" et les mêmes paramètres.

Cette commande est pratique pour tester que la connexion avec WeeChat est toujours active et mesurer le temps de réponse.

Syntaxe :

ping [<paramètres>]

Exemple :

ping 1370802127000

3.11. quit

Se déconnecter de relay.

Syntaxe :

quit

Exemple :

quit

4. Messages (relay → client)

Les messages sont envoyés sous forme de données binaires, en utilisant le format suivant (avec la taille en octets) :

┌────────╥─────────────╥────╥────────┬─────────╥───────╥────────┬─────────┐
│ taille ║ compression ║ id ║ type 1 │ objet 1 ║  ...  ║ type N │ objet N │
└────────╨─────────────╨────╨────────┴─────────╨───────╨────────┴─────────┘
 └──────┘ └───────────┘ └──┘ └──────┘ └───────┘         └──────┘ └───────┘
     4          1        ??      3       ??                 3       ??
 └────────────────────┘ └────────────────────────────────────────────────┘
      en-tête (5)                    données compressées (??)
 └───────────────────────────────────────────────────────────────────────┘
                              'taille' octets
  • taille (entier non signé) : nombre d’octets du message entier (en incluant ce champ)

  • compression (octet) : drapeau :

    • 0x00 : les données qui suivent ne sont pas compressées

    • 0x01 : les données qui suivent sont compressées avec zlib

  • id (chaîne) : l’identifiant envoyé par le client (avant le nom de la commande); il peut être vide (chaîne avec une longueur de zéro sans contenu) si l’identifiant n'était pas donné dans la commande

  • type (3 caractères) : un type : 3 lettres (voir le tableau ci-dessous)

  • objet : un objet (voir tableau ci-dessous)

4.1. Compression

Si le drapeau de compression est égal à 0x01, alors toutes les données après sont compressées avec zlib, et par conséquent doivent être décompressées avant d'être utilisées.

4.2. Identifiant

Il y a deux types d’identifiants (id) :

  • id envoyé par le client : relay répondra avec le même id dans sa réponse

  • id d’un évènement : pour certains évènements, relay enverra un message au client en utilisant un id spécifique, commençant par underscore (voir le tableau ci-dessous)

Les identifiants réservés par WeeChat :

Identifiant Reçu avec sync Données envoyées Description Action recommandée dans le client

_buffer_opened

buffers / buffer

hdata : buffer

Tampon ouvert

Ouvrir le tampon

_buffer_moved

buffers / buffer

hdata : buffer

Tampon déplacé

Déplacer le tampon

_buffer_merged

buffers / buffer

hdata : buffer

Tampon mélangé

Mélanger le tampon

_buffer_unmerged

buffers / buffer

hdata : buffer

Tampon sorti du mélange

Sortir le tampon du mélange

_buffer_hidden

buffers / buffer

hdata : buffer

Tampon masqué

Masquer le le tampon

_buffer_unmerged

buffers / buffer

hdata : buffer

Tampon démasqué

Démasquer le tampon

_buffer_renamed

buffers / buffer

hdata : buffer

Tampon renommé

Renommer le tampon

_buffer_title_changed

buffers / buffer

hdata : buffer

Titre du tampon changé

Changer le titre du tampon

_buffer_cleared

buffer

hdata : buffer

Tampon qui est vidé

Vider le tampon

_buffer_type_changed

buffer

hdata : buffer

Type de tampon changé

Changer le type de tampon

_buffer_localvar_added

buffer

hdata : buffer

Variable locale ajoutée

Ajouter la variable locale dans le tampon

_buffer_localvar_changed

buffer

hdata : buffer

Variable locale changée

Changer la variable locale dans le tampon

_buffer_localvar_removed

buffer

hdata : buffer

Variable locale supprimée

Supprimer la variable locale du tampon

_buffer_line_added

buffer

hdata : line

Ligne ajoutée dans le tampon

Afficher la ligne dans le tampon

_buffer_closing

buffers / buffer

hdata : buffer

Tampon qui se ferme

Fermer le tampon

_nicklist

nicklist

hdata : nicklist_item

Liste de pseudos pour un tampon

Remplacer la liste de pseudos

_nicklist_diff

nicklist

hdata : nicklist_item

Différence de liste de pseudos pour un tampon

Mettre à jour la liste de pseudos

_pong

(always)

chaîne : paramètres du ping

Réponse à un "ping"

Mesurer le temps de réponse

_upgrade

upgrade

(vide)

WeeChat se met à jour

Se désynchroniser de WeeChat (ou quitter)

_upgrade_ended

upgrade

(vide)

WeeChat a été mis à jour

(Re)synchroniser avec WeeChat

4.2.1. _buffer_opened

Ce message est envoyé au client lorsque le signal "buffer_opened" est envoyé par WeeChat.

Données envoyées dans le hdata :

Nom Type Description

number

entier

Numéro de tampon (≥ 1)

full_name

chaîne

Nom complet (exemple : irc.freenode.#weechat)

short_name

chaîne

Nom court (exemple : #weechat)

nicklist

entier

1 si le tampon a une liste de pseudos, sinon 0

title

chaîne

Titre du tampon

local_variables

table de hachage

Variables locales

prev_buffer

pointeur

Pointeur vers le tampon précédent

next_buffer

pointeur

Pointeur vers le tampon suivant

Exemple : canal #weechat rejoint sur freenode, nouveau tampon irc.freenode.#weechat :