WebSocket : constructeur WebSocket()

Syntaxe

new WebSocket(url)
new WebSocket(url, protocols)

Paramètres

url

L'URL du serveur WebSocket cible auquel se connecter. L'URL doit utiliser l'un des schémas suivants : ws, wss, http ou https, et ne peut pas inclure un fragment d'URL. Si une URL relative est fournie, elle est relative à l'URL de base du script appelant.

protocols Facultatif

Une chaîne unique ou un tableau de chaînes représentant les sous-protocoles que le client souhaite utiliser, par ordre de préférence. Si cette valeur est omise, un tableau vide est utilisé par défaut, c'est-à-dire [].

Un serveur unique peut implémenter plusieurs sous-protocoles WebSocket, et gérer différents types d'interactions en fonction de la valeur définie. Notez toutefois qu'un seul sous-protocole peut être sélectionné par connexion.

Les valeurs autorisées sont celles pouvant être définies dans l'en-tête HTTP Sec-WebSocket-Protocol. Il s'agit de valeurs choisies dans le registre des noms de sous-protocoles WebSocket de l'IANA ^(angl.), telles que soap, wamp, ship, ou d'un nom personnalisé compris conjointement par le client et le serveur.

Note : La connexion n'est pas établie tant que le sous-protocole n'a pas été négocié avec le serveur. Le protocole sélectionné peut ensuite être lu via WebSocket.protocol : il sera la chaîne vide si une connexion ne peut être établie.

Exceptions

SyntaxError DOMException

Levée si :

• l'analyse de url échoue
• url utilise un schéma autre que ws, wss, http ou https
• url contient un fragment
• l'une des valeurs de protocols apparaît plus d'une fois, ou ne respecte pas les exigences des éléments constituant la valeur de l'en-tête Sec-WebSocket-Protocol telles que définies par la spécification du protocole WebSocket

Exemples

Les exemples ci-dessous montrent comment se connecter à un WebSocket.

Le code suivant montre comment se connecter à un socket en utilisant une URL avec le schéma wss :

const wssWebSocket = new WebSocket("wss://websocket.example.org");
console.log(wssWebSocket.url); // 'wss://websocket.example.org'

// Faire quelque chose avec le socket

wssWebSocket.close();

Le code pour se connecter à une URL HTTPS est presque identique. Sous le capot, le navigateur résout cela en une connexion « WSS », donc WebSocket.url aura le schéma wss:.

const httpsWebSocket = new WebSocket("https://websocket.example.org");
console.log(httpsWebSocket.url); // 'wss://websocket.example.org'

// Faire quelque chose avec le socket

httpsWebSocket.close();

On peut aussi résoudre des URL relatives. L'URL absolue dépendra de l'URL de base du contexte dans lequel l'appel est effectué.

relativeWebSocket = new WebSocket("/local/url");

// Faire quelque chose avec le socket

relativeWebSocket.close();

Spécifications

Compatibilité des navigateurs

Voir aussi

• RFC 6455 ^(angl.) (la spécification du protocole WebSocket)