JavaScript Reference

Local Navigation

Web Sockets API

Method name

Description

BlackBerry Tablet OS

WebSocket

Represents a di-directoinal connection with a web server.

7.0+

1.0+

Object: WebSocket

Availability

  • BlackBerry Device Software 7.0 or later
  • BlackBerry Tablet OS 1.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.

Back To Top

Constructor: WebSocket

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.

Back To Top

WebSocket constants

Constants returned by WebSocket.readyState.

Constant

Value type

Description

Support level

0

CONNECTING

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

Web Sockets

1.0+

7.0+

1

OPEN

The web socket connection is established.

Web Sockets

1.0+

7.0+

2

CLOSED

The web socket connection is closed or cannot be established.

Web Sockets

1.0+

7.0+

Back To Top

WebSocket 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+

Back To Top

WebSocket properties

Property name

Type

Description

Status

Support level

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+

1.0+

readyState

short

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

read only

Web Sockets

7.0+

1.0+

URL

DOMString

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

read only

Web Sockets

7.0+

1.0+

Back To Top

WebSocket methods

Method name

Description

Support level

Availability

close()

Closes the web socket.

Web Sockets

6.1 or later

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

6.1 or later

Back To Top
Next topic: Window API
Previous topic: TreeWalker methods

Was this information helpful? Send us your comments.