# Communiquer avec un serveur XMPP

Ce document a été déplacé vers le wiki de la communauté francophone sur lequel il a été mis à jour.
http://wiki.jabberfr.org/Introduction_au_protocole_XMPP
Ce livre a pour but de vous expliquer comment communiquer avec un serveur XMPP pour la création d'un client. Il n'a pas pour but de montrer des lignes de programmations mais seulement de vous expliquer les échanges entre le client et le serveur.
Les échanges entre le client et le serveur se font en XML et ont donc l'avantage d'être faciles à parser.
La documentation sur le sujet la plus précise est sans doute : RFC3920 et RFC3921. Nous considérons également que vous connaissez déjà XMPP, en cas de doute, vous pouvez consulter Extensible Messaging and Presence Protocol.
Les indentations ne sont ici que pour faciliter la lisibilité des exemples, elles ne sont pas obligatoires. Vous pourrez facilement tester ces exemples grâce à une session telnet sur un serveur XMPP : telnet jabber.org 5222

## Les bases

Ce chapitre regroupe les actions élémentaires permettant de se connecter à un serveur XMPP et de discuter avec ses contacts en connaissant leur statut.

### Initialisation de la connexion

Notre client va envoyer ceci :
Les échanges entre le client et le serveur se font en XML. On peut également préciser l'encodage des caractères.
On ouvre un "stream" qui sera ouvert tout au long de la connexion au serveur.
Le client devra renseigner certains paramètres obligatoirement :
* xmlns='jabber:client' : indique au serveur que notre client est effectivement un client et non un serveur.
* xmlns:stream='http://etherx.jabber.org/streams'
* to : indique l'adresse du serveur auquel on s'adresse
et il est aussi conseillé de renseigner d'autres paramètres :
* version : indique la version du protocole utilisé
* xml:lang : indique la langue utilisée par défaut
Le serveur doit nous répondre quelque chose comme ceci :
Mais s'il y a un problème, celui-ci peut aussi vous envoyer un message tel que : <stream:error>

### Identification

Maintenant que nous sommes connectés au serveur, nous devons lui dire qui on est pour pouvoir discuter avec nos contacts.
La valeur de id n'est pas obligatoirement "auth_1" mais le serveur va nous répondre en réutilisant cet id pour nous indiquer à quoi il répond et donc il faut le conserver. Le type "get" nous indique que nous demandons une information au serveur. Et en même temps, nous indiquons notre identité (balise query).
Le serveur va alors nous indiquer les informations nécessaire à la connexion.
Tous ces éléments ne sont pas obligatoires, il est inutile de préciser à la fois password et digest.
On peut alors lui envoyer les informations pour s'identifier :
Encore une fois, la valeur de id n'est pas obligatoirement "auth_2".
Le serveur doit vous répondre en cas de réussite :
Sinon vous pourriez avoir quelque chose comme ceci :

### Changer son statut

Pour le moment, on est certes identifié au serveur mais personne ne sait que vous êtes en ligne. Pour cela, vous devez simplement indiquer votre statut. C'est la balise <presence> qui permet cela.
Lorsqu'il n'y a pas les balises "show" et "status" cela veut dire qu'on se dit simplement en ligne. D'ailleurs en général, la première chose faite après l'identification est du type :
La balise priority n'est pas obligatoire, cependant, en cas d'omission, cela revient à lui donner la valeur 0 :
équivaut à :
* show possède 4 états possibles :
** away : Absent
** chat : Veut discuter
** dnd : Ne pas déranger (occupé)
** xa : Non disponible
* presence possède également la propriété type qui permet :
** de se rendre invisible :
** de se déconnecter :

### Statut de ses contacts

Il n'y a pas besoin de les demander au serveur, du moment où vous êtes en ligne, vous recevrez des messages de présence similaire à ceux que vous pourriez envoyer à la différence près que ceux-là contiennent une propriété "from" (et "to" mais qui ne vous servira pas) :

### Récupérer la liste des contacts

Pour demander la liste de ses contacts, il faut envoyer :
Encore une fois, vous pouvez mettre ce que vous voulez comme id mais celui-ci doit être unique.
Le serveur peut répondre quelque chose comme ceci :
Attention, un contact peut appartenir à différents groupes. Dans ce cas, vous aurez plusieurs balises <group> contenant les différents groupes auxquels il appartient.

### Envoyer des messages

Il existe différents types de messages :
* chat : Le plus couramment employé, c'est celui de la messagerie instantanée, il est fait pour une conversation 1 à 1.
* error : Permet au serveur de vous envoyer un message d'erreur.
* groupchat : Utile pour une conversation à plusieurs.
* headline : Permet au serveur d'envoyer des informations.
* normal : Envoi un message similaire à un e-mail (sujet et message)
Exemple d'envois de message de type chat :
Exemple de réception d'un message de type chat :

#### Envoyer une notification de frappe (XEP-0022)

Pour cela c'est très simple, il suffit d'envoyer un message qui ne contient pas <body> mais :
Il peut être souhaitable de préciser un id :
Si Roméo fait une pause, alors il suffit de renvoyer :
Ceci a pour effet d'annuler la première information indiquant que Roméo est en train d'écrire.

#### Envoyer du texte en XHTML (XEP-0071)

Pour le moment, vous ne savez qu'envoyer des messages texte... Donc vous ne pouviez pas changer de police, de couleur d'écriture etc... Et bien c'est ce que nous allons voir maintenant grâce à la possibilité d'envoyer des messages en XHTML.
Exemple simple :
Vous retrouvez des éléments identiques à l'envoie d'un message en texte simple : <body>Salut !</body>. En effet, cela permet aux clients qui ne gèrent pas cette fonctionnalité d'afficher le message quand même. Le message est ensuite répété en XHTML.
Vous pouvez aller consulter les attributs de chaque balise directement dans la XEP. Regardez bien ceux qui sont obligatoires, recommandés et déconseillés.
À noter la possibilité d'insérer des images mais attention, des clients peuvent préférer afficher le contenu de l'attribut alt à la place de l'image.
Pour savoir si le client de votre contact supporte le XHTML, il suffit de lui demander ce qu'il supporte :
Si le client le supporte, il vous le dira :

### Enregistrement d'un nouveau compte (XEP-0077)

La connexion au serveur doit juste être initialisée mais vous n'avez pas à vous identifier (ce qui est logique).
Exemple d'enregistrement :
Ceci va créer un nouveau compte sur le serveur XMPP "server.org" avec le pseudo "Login". Ainsi le JID de ce nouveau compte sera login@server.org. L'attribut id permet de connaître la réponse du serveur, ce qui est très important ici mais il est facultatif. Tout le reste est obligatoire excepté l’e-mail. D'autres balises peuvent aussi être renseigner : nick, name, first, last, address, city, state, zip, phone, url, date, misc... (voir la XEP officielle)
Exemple d'erreur :
Exemple en cas de succés :

### Fermeture d'un compte

Si vous n'utilisez plus un compte XMPP, vous pouvez décider de le supprimer.
Pour cela, il vous faut déjà être connecté et identifié avec votre mot de passe. Ensuite il suffit d'envoyer :

### Changement de mot de passe

Pour une raison ou un autre, vous pouvez vouloir changer le mot de passe de votre compte.
Pour cela, il vous faut être déjà connecté et identifié avec votre mot de passe. Ensuite, il suffit d'envoyer :

## Gestion des contacts

XMPP permet de gérer les contacts par une liste de contact stockée sur le serveur mais à cela se rajoute un système d'autorisation permettant d'accepter que tel ou tel contact puisse voir votre statut.

### Autorisations
#### Les différents niveaux d'autorisation

* "none" -- Ni l'utilisateur ni le contact n'ont d'autorisation pour se voir.
* "to" -- L'utilisateur a l'autorisation de voir la présence du contact mais le contact lui ne l'a pas.
* "from" -- Le contact a l'autorisation de voir l'utilisateur mais l'utilisateur lui ne l'a pas.
* "both" -- L'utilisateur et le contact ont tous deux l'autorisation de connaître l'état de présence de l'autre.

#### Types pour <presence />

L'attribut type est optionnel. Une balise "presence" sans attribut est utilisé pour signaliser au serveur le statut de l'expéditeur. La balise "presence" permet aussi de gérer les autorisations.
L'attribut type peut avoir en plus ces valeurs :
* subscribe : L'expéditeur veut avoir l'autorisation de voir l'état du contact.
* subscribed : L'expéditeur a accepté de recevoir le statut de présence du contact.
* unsubscribe : L'expéditeur supprime l'autorisation de l'autre.
* unsubscribed : La demande d'autorisation a été refusé ou une précédente autorisation a été annulée.

#### Demander une autorisation

La balise "status" n'est pas obligatoire mais permet d'envoyer un message en même temps que la demande.
Toto va recevoir ceci :

#### Refuser une autorisation
### Gestion de la contact-liste
#### Ajouter un contact

L'attribut id est facultatif mais en cas d'erreur, il est bon de toujours spécifier un id pour savoir d'où vient l'erreur. D'autres informations peuvent être ajoutées :
En cas de succés, le serveur doit vous répondre quelque chose comme ceci :

#### Supprimer un contact

Notez à la différence de l'ajout d'un contact, l'attribut subscription avec la valeur "remove" qui indique la suppression du jid spécifié.

#### Modifier un contact

Pour modifier un contact, il suffit d'ajouter à nouveau ce contact mais avec les nouvelles options (groupe et nom).

### Procédure complète pour une autorisation mutuelle
#### Vous demandez en premier

Ajout du contact dans la contact-liste :
Demande d'inscription :
[Réception d'une autorisation et d'une demande d'autorisation]
Envoi d'une autorisation :

#### Vous recevez une demande d'autorisation

Ajout du contact dans la contact-liste :
Vous demandez à votre tour une autorisation :
Vous acceptez la sienne :
[reception d'une autorisation]

## Fonctionnalités Avancées
### Informations sur le client (XEP-0092)

La XEP-0092 permet de demander des informations supplémentaires sur les logiciels utilisés par vos contacts. On peut récupérer 3 informations qui sont le nom, la version et le système d'exploitation sur lequel celui ci tourne.
Pour demander, c'est très simple. Mais vous devrez spécifier la ressource.
Si le client peut lui répondre, alors vous recevrez une réponse, par exemple :
Repérez bien ici les 3 balises name, version et os qui correspondent respectivement au nom du client, de sa version et du système d'exploitation. La XEP-0092 n'en prévoit pas d'autres.