Implementations of the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]], as this specification uses that specification and terminology.

Terminology

The EventHandler interface represents a callback used for event handlers as defined in [[!HTML5]].

The concepts queue a task and fire a simple event are defined in [[!HTML5]].

The terms event handler and event handler event types are defined in [[!HTML5]].

The task source for all tasks queued in this specification is the WebSocket task source defined in [[!WEBSOCKETS-API]].

The term DOM is used to refer to the API set made available to scripts in Web applications, and does not necessarily imply the existence of an actual Document object or of any other Node objects as defined in the DOM Core specifications. [[!DOM-LEVEL-3-CORE]]

An IDL attribute is said to be getting when its value is being retrieved (e.g. by author script), and is said to be setting when a new value is assigned to it.

Security and privacy considerations

This API must be only exposed to trusted content.

Interface WebSocketServer

The WebSocketServer interface defines attributes and methods for Web Socket Server communication

      var webSocketServer = new WebSocketServer(urlToListen, serverID);
      webSocketServer.onconnect = function handleClient(event) {
          var port = event.port[0];

          // security related informations
          var origin = port.origin; // check same origin or CORS access
          var cookies = port.cookies; // initial HTTP cookies
          var authorization = port.authorization; // initial HTTP Authorization header
          var remoteURI = port.remoteURI; // ex: "tcp:194.43.12.5:80"

          // handle client messages
          port.onmessage = function handleMessage(msgEvent) {
              // send a message to a specific client
              port.postMessage(message);
          }
      };

      // send basic message to all connected clients
      webSocketServer.send(message);

      webSocketServer.onmessage = function (msgEvent) {
        // global handling of client message

        var origin = msgEvent.origin; // check same origin or CORS access
        var cookies = msgEvent.cookies; // initial HTTP cookies
        var authorization = msgEvent.authorization; // initial HTTP Authorization header
        var remoteURI = msgEvent.remoteURI; // ex: "tcp:194.43.12.5:80"
      };
      

readonly attribute DOMString url

TBD: Coming from the WebSocket interface. Used on the Server Interface to specified the listened URI

[ready state]const unsigned short CONNECTING = 0

The connection has not yet been established.

const unsigned short OPEN = 1

The WebSocket connection is established and communication is possible.

const unsigned short CLOSING = 2

The connection is going through the closing handshake, or the close() method has been invoked.

const unsigned short CLOSED = 3

The connection has been closed or could not be opened.

readonly attribute unsigned short readyState

The readyState attribute represents the state of the connection. It can have the constant defined values

readonly attribute unsigned long bufferedAmount

The bufferedAmount attribute must return the number of bytes of application data (UTF-8 text and binary data) that have been queued using send() but that, as of the last time the event loop started executing a task, had not yet been transmitted to the network. (This thus includes any text sent during the execution of the current task, regardless of whether the user agent is able to transmit text asynchronously with script execution.) This does not include framing overhead incurred by the protocol, or buffering done by the operating system or network hardware. If the connection is closed, this attribute's value will only increase with each call to the send() method (the number does not reset to zero once the connection closes).

[networking]attribute EventHandler onopen

Event handler that corresponds to the open event, which is fired when the socket is open and ready to receive connection attempts from clients. If the creation of the server socket fails the error event will be fired instead.

// networking

attribute EventHandler onconnect

Event handler that corresponds to the connect event, which is fired repeatedly and asynchronously after the WebSocketServer object has been created, every time an incoming connection attempt on the specified URI has been accepted.

attribute EventHandler onerror

Event handler that corresponds to the error event, which is fired when there is an error on the server socket. The data attribute of the event passed to the onerror handler will have a description of the kind of error.

attribute EventHandler onclose

TBD: Coming from the WebSocket interface. To be specified if required

readonly attribute DOMString extensions

TBD: Coming from the WebSocket interface. To be specified if required

readonly attribute DOMString protocol

TBD: Coming from the WebSocket interface. To be specified if required

void close()

Closes the Web socket. A closed Web socket can not be used any more.

[messaging]attribute EventHandler onmessage

TBD: Coming from the WebSocket interface. Expected to be used to handle messages from whatever connection. May be source of security issues.

attribute DOMString binaryType

When a WebSocket object is created, its binaryType IDL attribute must be set to the string "blob". On getting, it must return the last value it was set to. On setting, if the new value is either the string "blob" or the string "arraybuffer", then set the IDL attribute to this new value. Otherwise, throw a SyntaxError exception.

As WebSocketServer can be connected to multiple client, this property should also be at the port level and depend on each connection related port.onmessage event

void send(ArrayBufferView data)

Sends data on the given Web socket to all the connected clients.

(DOMString or Blob or ArrayBuffer or ArrayBufferView) data

The data to write in one of the alternative representations as stated below:

• Represented as a sequence of Unicode characters. [[!UNICODE]].
• As raw data represented by the Blob object. [[!FILE-API]]
• Represented as an ArrayBuffer object. [[!TYPED-ARRAYS]]
• Represented by the section of the buffer described by the ArrayBuffer object that the ArrayBufferView object references. [[!TYPED-ARRAYS]].

Ping and Pong frames

The WebSocket protocol specification defines Ping and Pong frames that can be used for keep-alive, heart-beats, network status probing, latency instrumentation, and so forth. These are not currently exposed in the API.

TBD: Section coming from The Web Sockets API [[!WEBSOCKETS-API]]. To be specified if required

Parsing WebSocket URLs

The steps to parse a WebSocket URL's components from a string url are as follows. These steps return either a host, a port, a resource name, and a secure flag, or they fail.

TBD: Section coming from The Web Sockets API [[!WEBSOCKETS-API]]. To be specified if required

Event definitions

TO BE DONE

Garbage collection

TBD: Section coming from The Web Sockets API [[!WEBSOCKETS-API]]. To be specified if required