Évènements
File d'attente des évènements
Le service COMHUB gère une liste d'événements à destination des utilisateurs Teambox. Ces événements sont stockés pendant un certain temps sur le serveur. Par exemple, lorsque le poste d'un utilisateur sonne, l'événement « ringing » est généré pour cet utilisateur; cet événement peut par exemple être exploité par un logiciel client pour déclencher une action de montée de fiche.
Il est important de bien noter que la gestion des événements est indépendante des éventuelles connexions au service COMHUB: il est tout a fait possible de récupérer un événement lorsque la connexion COMHUB est ouverte après la génération de cet événement. De même, il est tout à fait possible d'ouvrir plusieurs connexions COMHUB et de récupérer ces événements sur chacune d'elles.
Seule la durée de conservation des événements joue un rôle sur leur accessibilité, et cette durée de conservation dépend entre autre de la nature de l'événement. Par exemple, on ne conserve pas les événements « ringing » très longtemps car cela n'a pas de sens.
Format des évènements
Chaque événement est une liste de couples «champ=valeur » ; tous les événements ont en commun les champs suivants:
| Champ | Signification |
|---|---|
| type | Type de l'événement (chaîne de caractères) |
| seq | Numéro se séquence de l'événement: ce numéro identifie de manière unique l'événement sur le système COMHUB ; plus le numéro est élevé, plus l'évènement est récent. Ce champ est utile pour naviguer dans la liste des événements disponibles. Les numéros de séquence sont discontinus: on peut recevoir les événements consécutifs #1023 puis #2036 (sans rien entre les deux). |
| time | Date (format numérique EPOCH) à laquelle l'événement à été généré par le service COMHUB. Cette date est exprimée dans le timezone du serveur |
| category | Sous système associé à l'évenement (ex: « call » pour la gestion des appels) |
Requête « nextevent » - boucle événementielle
La requête « nextevent » permet de récupérer un événement à partir d'un numéro de séquence donné.
Le numéro de séquence peut être omis. Dans ce cas, on retournera une liste de tous les événements disponibles pour le user. Depuis une application cliente, la gestion des événements peut s'effectue schématiquement de cette manière:
$seq=0
boucle
récupérer les événements a partir de $seq
conserver le numéro de séquence du dernier événement récupéré dans $seq
traiter les événements reçus
fin-boucle
Notes:
-
l'obtention des événements est synchrone par défaut: si aucun événement n'est disponible, le serveur mettra la requête en attente avec une limite temporelle de quelques minutes (la requête http est maintenue pendant cette période). Il n'est donc pas nécessaire ni souhaitable de gérer la queue d'événements en POLLING depuis le client
-
la requête retourne toujours une liste d'événements (même lorsqu'il n'y en a qu'un), qui peut être vide si aucun événement n'est survenu dans le laps de temps maximum autorisé pour la requête
Avertissement
Il est possible que vous observiez des informations non documentées dans les évènements émis par un système COMHUB ; il est important de ne jamais se baser sur l'existence de ces informations sont le contenu peu varier d'une version à l'autre, ou simplement être supprimé.