WebSocket

Dies ist eine experimentelle Technologie
Da diese Technologie noch nicht definitiv implementiert wurde, sollte die Browserkompatibilit├Ąt beachtet werden. Es ist auch m├Âglich, dass die Syntax in einer sp├Ąteren Spezifikation noch ge├Ąndert wird.

Das WebSocket-Objekt bietet die API f├╝r das Erstellen und Verwalten einer WebSocket-Verbindung zu einem Server, ebenso dient es auch dem Senden und dem Empfangen von Daten auf der Verbindung.

Der WebSocket-Konstruktor akzeptiert einen ben├Âtigten und einen optionalen Parameter:

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

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString[] protocols
);
url
Die URL mit der sich das WebSocket verbinden soll; dies sollte die URL sein, auf welcher der WebSocket Server antworten wird.
protocols Optional
Entweder ein einzelnes Protokol als String oder ein Array aus Protokol-Strings. Diese Strings werden genutzt um Sub-Protokolle zu indizieren, sodass ein einzelner Server mehrere WebSocket Sub-Protokolle implementieren kann (Beispielswei├če kann ein Server abh├Ąngig vom protocol verschiedene Interaktionen mit dem Client handeln). Falls du kein Protokoll angibst, wird ein leerer String verwendet.

Der Konstruktur kann folgende Exceptions werfen:

SECURITY_ERR
Der Port auf dem man die Verbindung aufbauen will, ist blockiert worden.

Methoden ├ťbersicht

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

Attribute

Attribut Typ Beschreibung
binaryType DOMString Ein String indiziert den Typ der Bin├Ąrdaten, die von der Verbindung ├╝bertragen werden. Dies sollte entweder "blob" sein, falls DOM-Objekte Blob genutzt werden oder "arraybuffer" falls ArrayBuffer-Objekte genutzt werden.
bufferedAmount unsigned long Die Anzahl der Bytes der Daten, welche bereits durch Aufrufe von send() gebuffert wurden, allerdings noch nicht ├╝ber das Netzwerk versand wurden. Dieses Feld setzt sich nicht auf Null zur├╝ck, wenn die Verbindung beendet wurde; falls du weiterhin send() aufrufst, wird dieses Feld weiterhin ansteigen. Read only.
extensions DOMString Die Erweiterungen, die von dem Server gew├Ąhlt wurden. Aktuell ist dies nur ein leerer String oder eine Liste von Erweiterungen, die von der Verbindung verhandelt wurden.
onclose EventListener Ein Event-Listener welcher aufgerufen wird, wenn der readyState der WebSocket-Verbindung auf CLOSED wechselt. Den Listener erreicht ein CloseEvent welches "close" hei├čt.
onerror EventListener Ein Event-Listener welcher bei Fehlern aufgerufen wird. Dies ist ein einfaches Event welches "error" genannt wird.
onmessage EventListener Ein Event-Listener welcher aufgerufen wird, wenn eine Nachricht vom Server empfangen wird. Den Listener erreicht ein MessageEvent welches "message" hei├čt.
onopen EventListener Ein Event-Listener welcher aufgerufen wird, wenn der readyState der WebSocket-Verbindung auf OPEN wechselt; dies indiziert, dass die Verbindung bereit ist, dass man Daten versenden und empfangen kann. Dieses Event ist eine einfaches Event, es hei├čt "open".
protocol DOMString Ein String welcher dne Namen des Sub-Protokolls nennt, welches vom Server ausgew├Ąhlt wurde; dieses Protokoll wird eines sein, welches in den Strings des protocols-Parameter beim Erstellen des WebSocket-Objekt angegeben wurde.
readyState unsigned short Der aktuelle Status der Verbindung; dies ist einer der Ready state Konstanten. Read only.
url DOMString Die URL welche beim Konstruktor angegeben wurde. Dies ist immer die absolute URL. Read only.

Konstanten

Ready state Konstanten

Diese Konstanten werden vom readyState Attribut genutzt, um den Status der WebSocket-Verbindung zu beschreiben.

Konstante Inhalt Beschreibung
CONNECTING 0 Die Verbindung ist noch nicht hergestellt.
OPEN 1 Die Verbindung ist hergestellt und bereit dar├╝ber zu kommunizieren.
CLOSING 2 Die Verbindung ist im Prozess des Schlie├čens.
CLOSED 3 Die Verbindung ist geschlossen oder konnte nicht hergestellt werden.

Methoden

close()

Schlie├čt die WebSocket-Verbindung oder den Verbindungsversuch, falls dieser gerade existiert. Falls die Verbindung bereits CLOSED ist, macht diese Methode ├╝berhaupt nichts.

void close(
  in optional unsigned short code,
  in optional DOMString reason
);
Parameter
code Optional
Eine Nummer welche den Status-Code setzt, warum die Verbindung geschlossen wird. Falls dieser Parameter nicht gesetzt wird, wird er auf 1005 (welcher bei einer normalen Verbindung "Keinen Status erhalten" bedeutet) gesetzt.
reason Optional
Ein vom Menschen lesbarer String, welcher erkl├Ąrt, warum die Verbindung geschlossen wurde. Dieser Text darf nicht l├Ąnger als 123 Bytes UTF-8-Text sein. Dabei hei├čt dies nicht unbedingt, dass es auch 123 Zeichen sind.
Exceptions thrown
INVALID_ACCESS_ERR
Ein ung├╝ltiger code wurde gesetzt.
SYNTAX_ERR
Der reason-String ist zu lang oder enth├Ąlt ung├╝ltige Zeichen.
Notizen

In Gecko vor Version Gecko 8.0 unterst├╝tzte diese Methode ├╝berhaupt keine Parameter. (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5).

send()

├ťbertr├Ągt Daten zu dem Server ├╝ber die WebSocket-Verbindung.

void send(
  in DOMString data
);

void send(
  in ArrayBuffer data
);

void send(
  in Blob data
);
Parameter
data
Ein String der zum Server geschickt wird.
Exceptions thrown
INVALID_STATE_ERR
Die Verbindung hat aktuell nicht den Status OPEN.
SYNTAX_ERR
data enth├Ąlt ung├╝ltige Zeichen.
Erl├Ąuterung

Notiz: Geckos Implementierung von der send() Methode unterscheidet sich ein wenig von der Spezifikation in Gecko 6.0; Gecko gibt einen boolean zur├╝ck, welcher dar├╝ber auskunft gibt, ob die Verbindung immer noch hergestellt ist oder nicht (und, durch Erweiterung, dass die Daten erfolgreich gesammelt oder ├╝bertragen wurden); dies wurde in Gecko 8.0 korrigiert.

In Gecko 11.0 ist die Unterst├╝tzung f├╝r  ArrayBuffer implementiert aber nicht die f├╝r Blob Datentypen.

Weiterf├╝hrendes

Browser Kompatibilit├Ąt

Wir konvertieren die Kompatibilit├Ątsdaten in ein maschinenlesbares JSON Format. Diese Kompatibilit├Ątstabelle liegt noch im alten Format vor, denn die darin enthaltenen Daten wurden noch nicht konvertiert. Finde heraus wie du helfen kannst!
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support (Ja) 4.0 (2.0) (Ja) (Ja) ?
Sub-protocol support ? 6.0 (6.0) ? ? ?
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? 7.0 (7.0) ? ? ?
Sub-protocol support ? 7.0 (7.0) ? ? ?

Gecko Notizen

In Gecko 6.0 ist der Konstruktur mit einem Prefix ausgestattet; du must MozWebSocket() benutzen:

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

Das extensions-Attribut wurde bis Gecko 8.0 nicht unterst├╝tzt.

Notiz: Vor Gecko 11.0 ausgehende Nachrichten welche mit der send() Methode versendet wurden, waren auf 16 MB begrenzt. Jetzt k├Ânnen sie bis zu 2 GB wachsen.