path: root/files/fr/web/api/websocket/index.html

---
title: WebSocket
slug: Web/API/WebSocket
tags:
  - API
  - WebSocket
  - WebSockets
translation_of: Web/API/WebSocket
---
<p>{{APIRef("Web Sockets API")}}{{ SeeCompatTable() }}</p>

<p>L'objet WebSocket fournit une API permettant la création et la gestion d'une <span style="background-color: rgba(212, 221, 228, 0.14902); font-size: 14.4444446563721px; line-height: 23.3333339691162px;">connexion</span> <a href="/en/WebSockets" title="en/WebSockets">WebSocket</a> avec un serveur, ainsi que l'émission et la réception de données par l'intermédiaire de cette <span style="background-color: rgba(212, 221, 228, 0.14902); font-size: 14.4444446563721px; line-height: 23.3333339691162px;">connexion</span>.</p>

<p>Le constructeur WebSocket accepte deux paramètres, un paramètre obligatoire et un facultatif:</p>

<pre>WebSocket WebSocket(
  in DOMString url,
  in optional DOMString protocols
);

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString[] protocols
);
</pre>

<dl>
 <dt><code>url</code></dt>
 <dd>URL à laquelle se connecter; ce devrait être l'URL à laquelle le serveur WebSocket répondra.</dd>
 <dt><code>protocols</code> {{ optional_inline() }}</dt>
 <dd>Une chaîne de caractères spécifiant un protocole, ou <span style="font-size: 14.4444446563721px; line-height: 23.3333339691162px;">un tableau de chaîne de caractères (plusieurs protocoles)</span>. 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.</dd>
</dl>

<p>Le constructeur peut lancer des exceptions:</p>

<dl>
 <dt><code>SECURITY_ERR</code></dt>
 <dd>Le port vers lequel la <span style="background-color: rgba(212, 221, 228, 0.14902); font-size: 14.4444446563721px; line-height: 23.3333339691162px;">connexion</span> est tentée est actuellement bloqué.</dd>
</dl>

<dl>
</dl>

<h2 id="Method_overview" name="Method_overview">Vue d'ensemble des méthodes</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <td><code>void <a href="#close()">close</a>(in optional unsigned long code, in optional DOMString reason);</code></td>
  </tr>
  <tr>
   <td><code>void <a href="#send()">send</a>(in DOMString data);</code></td>
  </tr>
 </tbody>
</table>

<h2 id="Attributes" name="Attributes">Attributs</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <td class="header">Attribut</td>
   <td class="header">Type</td>
   <td class="header">Description</td>
  </tr>
  <tr>
   <td><code>binaryType</code></td>
   <td>{{DOMXref("DOMString")}}</td>
   <td>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 {{ domxref("Blob") }} sont utilisés ou "arraybuffer" si des objets <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a> sont utilisés.</td>
  </tr>
  <tr>
   <td><code>bufferedAmount</code></td>
   <td><code><a href="/en/unsigned_long" title="en/unsigned long">unsigned long</a></code></td>
   <td>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 à {{ manch("send") }}. Cette valeur n'est pas remise à zéro quand la connexion est fermée; elle continue d'augmenter si les appels à {{ manch("send") }} persistent. <strong>Lecture seule.</strong></td>
  </tr>
  <tr>
   <td><code>extensions</code></td>
   <td>{{DOMXref("DOMString")}}</td>
   <td>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.</td>
  </tr>
  <tr>
   <td><code>onclose</code></td>
   <td>{{DOMXref("EventListener")}}</td>
   <td>Un gestionnaire d'évènement à appeler quand la valeur de l'attribut <code>readyState</code> de la connexion WebSocket devient <code>CLOSED</code>. Le gestionnaire reçoit un évènement <a href="/en/WebSockets/WebSockets_reference/CloseEvent" title="en/WebSockets/WebSockets reference/CloseEvent"><code>CloseEvent</code></a> nommé "close".</td>
  </tr>
  <tr>
   <td><code>onerror</code></td>
   <td>{{DOMXref("EventListener")}}</td>
   <td><span style="background-color: rgba(212, 221, 228, 0.14902); font-size: 14.4444446563721px; line-height: 23.3333339691162px;">Un gestionnaire d'évènement à appeler quand une erreur survient</span>. L'évènement est un évènement de base, nommé "error".</td>
  </tr>
  <tr>
   <td><code>onmessage</code></td>
   <td>{{DOMXref("EventListener")}}</td>
   <td><span style="background-color: rgba(212, 221, 228, 0.14902); font-size: 14.4444446563721px; line-height: 23.3333339691162px;">Un gestionnaire d'évènement à appeler</span> quand un message émis par le serveur est reçu. Le gestionnaire reçoit un évènement <a href="/en/WebSockets/WebSockets_reference/MessageEvent" title="en/WebSockets/WebSockets reference/MessageEvent"><code>MessageEvent</code></a> nommé "message".</td>
  </tr>
  <tr>
   <td><code>onopen</code></td>
   <td>{{DOMXref("EventListener")}}</td>
   <td><span style="background-color: rgba(212, 221, 228, 0.14902); font-size: 14.4444446563721px; line-height: 23.3333339691162px;">Un gestionnaire d'évènement à appeler</span> quand la valeur de l'attribut <code>readyState</code> de la connexion WebSocket devient <code>OPEN</code>; 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".</td>
  </tr>
  <tr>
   <td><code>protocol</code></td>
   <td>{{DOMXref("DOMString")}}</td>
   <td>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 <code>protocols</code> lors de la création de l'objet WebSocket.</td>
  </tr>
  <tr>
   <td><code>readyState</code></td>
   <td><code><a href="/en/unsigned_short" title="en/unsigned short">unsigned short</a></code></td>
   <td>Le statut (actuel) de la connexion; c'est une  valeur de {{ anch("Constantes de statut") }}. <strong>Lecture Seule.</strong></td>
  </tr>
  <tr>
   <td><code>url</code></td>
   <td>{{DOMXref("DOMString")}}</td>
   <td>L'URL telle que déterminée par le constructeur. C'est toujours une URL absolue. <strong>Lecture Seule.</strong></td>
  </tr>
 </tbody>
</table>

<h2 id="Constants" name="Constants">Constantes</h2>

<h3 id="Constantes_de_statut">Constantes de statut</h3>

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

<table class="standard-table">
 <tbody>
  <tr>
   <td class="header">Constant</td>
   <td class="header">Value</td>
   <td class="header">Description</td>
  </tr>
  <tr>
   <td><code>CONNECTING</code></td>
   <td><code>0</code></td>
   <td>La connexion n'est pas encore établie.</td>
  </tr>
  <tr>
   <td><code>OPEN</code></td>
   <td><code>1</code></td>
   <td>La connexion est établie et prête pour la communication.</td>
  </tr>
  <tr>
   <td><code>CLOSING</code></td>
   <td><code>2</code></td>
   <td>La connexion est en train de se fermer.</td>
  </tr>
  <tr>
   <td><code>CLOSED</code></td>
   <td><code>3</code></td>
   <td>La connexion est fermée ou n'a pas pu être établie.</td>
  </tr>
 </tbody>
</table>

<h2 id="Methods" name="Methods">Méthodes</h2>

<h3 id="close()" name="close()">close()</h3>

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

<pre class="eval">void close(
  in optional unsigned short code,
  in optional DOMString reason
);
</pre>

<h6 id="Parameters" name="Parameters">Paramètres</h6>

<dl>
 <dt><code>code</code> {{ optional_inline() }}</dt>
 <dd>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 <a href="/en/WebSockets/WebSockets_reference/CloseEvent#Status_codes" title="en/WebSockets/WebSockets reference/CloseEvent#Status codes">liste des codes de statut</a> sur la page de l'évènement <a href="/en/WebSockets/WebSockets_reference/CloseEvent" title="en/WebSockets/WebSockets reference/CloseEvent"><code>CloseEvent</code></a> pour les valeurs autorisées.</dd>
 <dt><code>reason</code> {{ optional_inline() }}</dt>
 <dd>Une chaîne de caractère <em>humainement-compréhensible</em> expliquant pourquoi la connexion est fermée. Cette chaîne ne doit pas excéder 123 octets <span style="font-size: 14.4444446563721px; line-height: 23.3333339691162px;">(et non </span><strong style="font-size: 14.4444446563721px; line-height: 23.3333339691162px;">pas</strong><span style="font-size: 14.4444446563721px; line-height: 23.3333339691162px;"> caractères) </span>de texte UTF-8.</dd>
</dl>

<h6 id="Exceptions_lancées">Exceptions lancées</h6>

<dl>
 <dt><code>INVALID_ACCESS_ERR</code></dt>
 <dd>Un code invalide a été spécifié.</dd>
 <dt><code>SYNTAX_ERR</code></dt>
 <dd>La chaîne de caractères (paramètre <strong>reason</strong>) est trop longue ou contient des données invalides.</dd>
</dl>

<h6 id="Notes">Notes</h6>

<p>Concernant Gecko: Cette méthode ne supporte aucun paramètre avant Gecko 8.0 {{ geckoRelease("8.0") }}.</p>

<h3 id="send()" name="send()">send()</h3>

<p>Émet des données vers le serveur via la connexion WebSocket.</p>

<pre class="eval">void send(
  in DOMString data
);

void send(
  in ArrayBuffer data
);

void send(
  in Blob data
);
</pre>

<h6 id="Parameters" name="Parameters">Paramètres</h6>

<dl>
 <dt><code>data</code></dt>
 <dd>Une chaîne de caractères à envoyer au serveur.</dd>
</dl>

<h6 id="Exceptions_lancées_2">Exceptions lancées</h6>

<dl>
 <dt><code>INVALID_STATE_ERR</code></dt>
 <dd>La connexion n'est pas actuellent ouverte (valeur de l'attribut <em>readyState</em> <code>OPEN)</code>.</dd>
 <dt><code>SYNTAX_ERR</code></dt>
 <dd>La chaîne de caractères contient des données invalides.</dd>
</dl>

<h6 id="Remarques">Remarques</h6>

<div class="note">
<p><strong>Note:</strong> L'implémentation de la méthode <code>send()</code> dans Gecko diffère quelques peu des spécifications dans {{Gecko("6.0")}}; Gecko retourne une valeur booléenne (<code>boolean)</code> 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")}}.</p>

<p>Sur {{Gecko("11.0")}}, le support d'<code><a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer">ArrayBuffer</a></code> est implémenté, mais pas le type de données {{ domxref("Blob") }}.</p>
</div>

<h2 id="See_also" name="See_also">Exemple</h2>

<pre class="brush: js">var socket = null;
try {
    // Connexion vers un serveur HTTP
    // prennant en charge le protocole WebSocket ("ws://").
    socket = new WebSocket("ws://localhost");

    // ----- OU -----

    // Connexion vers un serveur HTTPS
    // prennant en charge le protocole WebSocket over SSL ("wss://").
    socket = new WebSocket("wss://localhost");
} catch (exception) {
    console.error(exception);
}

// Récupération des erreurs.
// Si la connexion ne s'établie pas,
// l'erreur sera émise ici.
socket.onerror = function(error) {
    console.error(error);
};

// Lorsque la connexion est établie.
socket.onopen = function(event) {
    console.log("Connexion établie.");

    // Lorsque la connexion se termine.
    this.onclose = function(event) {
        console.log("Connexion terminé.");
    };

    // Lorsque le serveur envoi un message.
    this.onmessage = function(event) {
        console.log("Message:", event.data);
    };

    // Envoi d'un message vers le serveur.
    this.send("Hello world!");
};
</pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th>Specification</th>
   <th>Status</th>
   <th>Comment</th>
  </tr>
  <tr>
   <td>{{SpecName("Websockets", "#the-websocket-interface", "WebSocket")}}</td>
   <td>{{Spec2("Websockets")}}</td>
   <td>Definition initiale</td>
  </tr>
 </tbody>
</table>

<h2 id="See_also" name="See_also">Voir aussi</h2>

<ul>
 <li><a href="/en/WebSockets/Writing_WebSocket_client_applications" title="en/WebSockets/Writing WebSocket client applications">Writing WebSocket client applications</a></li>
 <li><a class="external" href="http://dev.w3.org/html5/websockets/" title="http://dev.w3.org/html5/websockets/">HTML5: WebSockets</a></li>
</ul>

<h2 id="Compatibilité_des_navigateurs">Compatibilité des navigateurs</h2>

<p>{{ CompatibilityTable() }}</p>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Fonctionnalité</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Support basique</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatGeckoDesktop("2.0") }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatVersionUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
  <tr>
   <td>Support des sous-protocoles</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatGeckoDesktop("6.0") }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th><span style="font-family: open sans light,sans-serif; font-size: 15.5555562973022px; line-height: 16px;">Fonctionnalité</span></th>
   <th>Android</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
  </tr>
  <tr>
   <td><span style="font-size: 12.222222328186px; line-height: 20px;">Support basique</span></td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatGeckoMobile("7.0") }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
  <tr>
   <td><span style="font-size: 12.222222328186px; line-height: 20px;">Support des sous-protocoles</span></td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatGeckoMobile("7.0") }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
   <td>{{ CompatUnknown() }}</td>
  </tr>
 </tbody>
</table>
</div>

<h3 id="Notes_pour_Gecko">Notes pour Gecko</h3>

<p>Avec Gecko 6.0, le constructeur est préfixé; il vous faudra utiliser <code>MozWebSocket()</code>:</p>

<pre class="brush: js">var socket = new MozWebSocket("ws<span class="plain">://www.example.com/socketserver</span>");
</pre>

<p>L'attribut <code>extensions</code> n'est pas supporté par Gecko avant Gecko 8.0.</p>

<div class="note"><strong>Note:</strong> Avant {{Gecko("11.0")}}, les messages (sur le point d'être émis) envoyés avec la méthode {{ manch("send") }} étaient limités à 16 Mo. Leur taille peut maintenant atteindre 2 Go.</div>

<p>{{ languages ( {"zh-tw": "zh_tw/WebSockets/WebSockets_reference/WebSocket"} ) }}</p>