WebSocket

Availability

BlackBerry Device Software 7.0 or later

Implements

EventTarget

The WebSocket object represents a bi-directional communication channel between a web server and a browser. A web socket allows messages to be sent back and forth without requiring an HTTP request and response each time.

Web sockets are an efficient solution for a web application that requires regular communication with a server. Because a web socket is established once and can be used repeatedly without the need for communication over HTTP, it greatly reduces the overhead of sending multiple HTTP headers back and forth. In addition, web sockets eliminate the need for inefficient communication practices such as polling, in which the browser checks repeatedly for new data on the server. Because a web socket is an open communication channel, the browser only needs to wait quietly and listen for incoming messages. When the server has new data, it sends a new message and the browser receives it as it arrives.

The Web Socket API is designed to hide much of the complexity of socket communication. A socket is opened when a new WebSocket object is constructed. Once the socket connection has been established, the browser and server can send data back and forth. When the socket is closed, it cannot be reopened; a new WebSocket objected must be constructed.

Web sockets are not subject to same-origin policy, meaning that the browser can open a socket with a server different from the server that originally served the web page.

By default, support for web sockets is disabled in the BlackBerry Browser. To establish a web socket between the browser and a server, the user must first select the Enable Web Sockets setting in the BlackBerry Browser options.

Constructor

WebSocket( DOMString URL, [ DOMString protocol ] )

Argument

Type

Description

URL

DOMString

The URL to which the web socket connection will be made. Since the web socket connection need not be of the same origin, the URL must be an absolute URL.

protocol

DOMString

The sub-protocol that the server must support for it to successfully establish a connection. This argument is optional.

Properties

Property name

Type

Description

Status

Support level

Availability

bufferedAmount

long

Returns the number of bytes that have been queued but not yet sent. The value does not reset to zero when the connection closes.

read only

Web Sockets

7.0+

readyState

short

Represents the state of the connection, represented using a WebSocket constant.

read only

Web Sockets

7.0+

URL

DOMString

Returns the result of resolving the URL that was passed to the WebSocket constructor.

read only

Web Sockets

7.0+

Methods

Method name

Description

Support level

Availability

close()

Closes the web socket.

Web Sockets

7.0+

send()

Transmits data using the web socket connection. This method takes a single argument, data, a DOMString containing the message that is to be sent to the server.

Web Sockets

7.0+

WebSocket constants

Constants returned by WebSocket.readyState.

Constant

Value type

Description

Support level

Availability

0

CONNECTING

The web socket connection is in the process of being established.

Web Sockets

7.0+

1

OPEN

The web socket connection is established.

Web Sockets

7.0+

2

CLOSED

The web socket connection is closed or cannot be established.

Web Sockets

7.0+

Event handlers

Event handler

Description

Status

Support level

onopen

Specifies the function to perform when the web socket connection has been established with the server.

writable

Web Sockets

7.0+

1.0+

onmessage

Specifies the function to perform when the browser receives a message from the server over the web socket connection.

writable

Web Sockets

7.0+

1.0+

onclose

Specifies the function to perform when the web socket connection has been established with the server.

writable

Web Sockets

7.0+

1.0+

Last modified: 2014-03-10



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus