WebSocket

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

Attributs

Constantes

Constantes de statut

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

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

Voir aussi

• Writing WebSocket client applications
• HTML5: WebSockets

Compatibilité des navigateurs

Notes pour Gecko

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

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

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