WebSocket

Cette fonction est expérimentale
Puisque cette fonction est toujours en développement dans certains navigateurs, veuillez consulter le tableau de compatibilité pour les préfixes à utiliser selon les navigateurs.
Il convient de noter qu'une fonctionnalité expérimentale peut voir sa syntaxe ou son comportement modifié dans le futur en fonction des évolutions de la spécification.

L'objet WebSocket fournit une API permettant la création et la gestion d'une connexion WebSocket avec un serveur, ainsi que l'émission et la réception de données par l'intermédiaire de cette connexion.

Le constructeur WebSocket accepte deux paramètres, un paramètre obligatoire et un facultatif:

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString protocols
);

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString[] protocols
);
url
URL à laquelle se connecter; ce devrait être l'URL à laquelle le serveur WebSocket répondra.
protocols Facultatif
Une chaîne de caractères spécifiant un protocole, ou un tableau de chaîne de caractères (plusieurs protocoles). Ces chaînes sont utilisées pour indiquer les sous-protocoles, afin qu'un même serveur puisse implémenter de multiples sous-protocoles WebSocket (par exemple, vous pourriez souhaiter qu'un serveur soit capable de gérer différents types d'intéractions en fonction du protocole spécifié). Si vous ne passez aucune chaîne de caractères pour le(s) protocole(s), une chaîne vide est utilisée.

Le constructeur peut lancer des exceptions:

SECURITY_ERR
Le port vers lequel la connexion est tentée est actuellement bloqué.

Vue d'ensemble des méthodes

void close(in optional unsigned long code, in optional DOMString reason);
void send(in DOMString data);

Attributs

Attribut Type Description
binaryType DOMString Une chaîne de caractères indiquant le type de données binaires transmises par la connexion. Les valeurs possibles sont soit "blob" si des objets DOM Blob sont utilisés ou "arraybuffer" si des objets ArrayBuffer sont utilisés.
bufferedAmount unsigned long Le nombre d'octets de données mis en fil d'attente (n'étant pas encore transmis sur le réseau) en effectuant des appels à send(). Cette valeur n'est pas remise à zéro quand la connexion est fermée; elle continue d'augmenter si les appels à send() persistent. Lecture seule.
extensions DOMString Extensions sélectionnées par le serveur. Actuellement, c'est une chaîne de caractères vide ou une liste des extensions telle que décidée par la connexion.
onclose EventListener Un gestionnaire d'évènement à appeler quand la valeur de l'attribut readyState de la connexion WebSocket devient CLOSED. Le gestionnaire reçoit un évènement CloseEvent nommé "close".
onerror EventListener Un gestionnaire d'évènement à appeler quand une erreur survient. L'évènement est un évènement de base, nommé "error".
onmessage EventListener Un gestionnaire d'évènement à appeler quand un message émis par le serveur est reçu. Le gestionnaire reçoit un évènement MessageEvent nommé "message".
onopen EventListener Un gestionnaire d'évènement à appeler quand la valeur de l'attribut readyState de la connexion WebSocket devient OPEN; cela indique que la connexion est prête à recevoir et émettre des données. L'évènement est un évènement de base nommé "open".
protocol DOMString Une chaîne de caractères indiquant le nom du sous-protocole que le serveur a choisi; ce sera l'une des chaînes spécifiées dans le paramètre protocols lors de la création de l'objet WebSocket.
readyState unsigned short Le statut (actuel) de la connexion; c'est une  valeur de Constantes de statut. Lecture Seule.
url DOMString L'URL telle que déterminée par le constructeur. C'est toujours une URL absolue. Lecture Seule.

Constantes

Constantes de statut

Ces constantes sont utilisées par l'attribut readyState pour décrire le statut de la connexion WebSocket.

Constant Value Description
CONNECTING 0 La connexion n'est pas encore établie.
OPEN 1 La connexion est établie et prête pour la communication.
CLOSING 2 La connexion est en train de se fermer.
CLOSED 3 La connexion est fermée ou n'a pas pu être établie.

Méthodes

close()

Ferme la connexion Websocket ou abandonne la tentative de connexion. Si la connexion est déjà fermée (statut CLOSED), cette méthode est sans effet.

void close(
  in optional unsigned short code,
  in optional DOMString reason
);
Paramètres
code Facultatif
Une valeur numérique indiquant le code du statut décrivant pourquoi la connexion est fermée. Si ce paramètre n'est pas spécifié, une valeur par défaut de 1000 est utilisée (indiquant une fermeture standard de "transaction terminée"). Voir la liste des codes de statut sur la page de l'évènement CloseEvent pour les valeurs autorisées.
reason Facultatif
Une chaîne de caractère humainement-compréhensible expliquant pourquoi la connexion est fermée. Cette chaîne ne doit pas excéder 123 octets (et non pas caractères) de texte UTF-8.
Exceptions lancées
INVALID_ACCESS_ERR
Un code invalide a été spécifié.
SYNTAX_ERR
La chaîne de caractères (paramètre reason) est trop longue ou contient des données invalides.
Notes

Concernant Gecko: Cette méthode ne supporte aucun paramètre avant Gecko 8.0 (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5).

send()

Émet des données vers le serveur via la connexion WebSocket.

void send(
  in DOMString data
);

void send(
  in ArrayBuffer data
);

void send(
  in Blob data
); 
Paramètres
data
Une chaîne de caractères à envoyer au serveur.
Exceptions lancées
INVALID_STATE_ERR
La connexion n'est pas actuellent ouverte (valeur de l'attribut readyState OPEN).
SYNTAX_ERR
La chaîne de caractères contient des données invalides.
Remarques

Note: L'implémentation de la méthode send() dans Gecko diffère quelques peu des spécifications dans Gecko 6.0; Gecko retourne une valeur booléenne (boolean) indiquant si la connexion est toujours ouverte (et, par extension, que les données ont bien été mise en fil d'émission ou émises); cette différence est corrigée dans Gecko 8.0.

Sur Gecko 11.0, le support d'ArrayBuffer est implémenté, mais pas le type de données Blob.

Voir aussi

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari
Support basique (Oui) 4.0 (2.0) (Oui) (Oui) ?
Support des sous-protocoles ? 6.0 (6.0) ? ? ?
Fonctionnalité Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Support basique ? 7.0 (7.0) ? ? ?
Support des sous-protocoles ? 7.0 (7.0) ? ? ?

Notes pour Gecko

Avec Gecko 6.0, le constructeur est préfixé; il vous faudra utiliser MozWebSocket():

var mySocket = new MozWebSocket("http://www.example.com/socketserver");

L'attribut extensions n'est pas supporté par Gecko avant Gecko 8.0.

Note: Avant Gecko 11.0, les messages (sur le point d'être émis) envoyés avec la méthode send() étaient limités à 16 Mo. Leur taille peut maintenant atteindre 2 Go.

Étiquettes et contributeurs liés au document

Étiquettes : 
 Contributeurs à cette page : VinceOPS
 Dernière mise à jour par : VinceOPS,