Web Sockets API
Object: WebSocket
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
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. |
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+ |
WebSocket event handlers
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 |
7.0+ |
1.0+ |
|
|
readyState |
short |
Represents the state of the connection, represented using a WebSocket constant. |
read only |
7.0+ |
1.0+ |
|
|
URL |
DOMString |
Returns the result of resolving the URL that was passed to the WebSocket constructor. |
read only |
7.0+ |
1.0+ |
WebSocket methods
|
Method name |
Description |
Support level |
Availability |
|---|---|---|---|
|
close() |
Closes the web socket. |
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 |