|
Version0 /
webSocket moduleThe webSocket module supports web sockets. Web sockets differ from HTTP interactions by including a notion of a bidirectional connection called a "socket". It differs from a TCP socket in that the connection carries not just a byte stream, but a sequence of "messages," where each message can have an arbitrary number of bytes. It also differs from a TCP socket in that the connection is established through HTTP and is supported by most web browsers. This module defines three classes, Client, Server, and Socket. A minimal implementation of this module only provides the Client class. To make a connection, create an instance of Server, set up event listeners, and start the server. On another machine (or the same machine), create an instance of Client and set up listeners and/or invoke the send() function of the client to send a message. When a client connects to the Server, the Server will create an instance of the Socket object. This object can be used to send and receive messages to and from the client. This module also provides two utility functions that return arrays of MIME types supported for sending or receiving messages. Specifying a message type facilitates conversion between the byte streams transported over the socket and JavaScript objects that are passed to send() or emitted as a 'message' event. These functions specify what types are supported by a particular implementation of this module. Module Functions
Client ClassA Client is constructed (using new) by the Client function, which takes one (optional) argument, an options object, defined below. A Client instance represents a single web socket connection to a server and can send and receive messages to and from that server. A Client object is an EventEmitter, and you can register handlers for the following events:
The functions provided by the Client class are:
The type of data sent and received can be specified with the sendType and receiveType options. In principle, any MIME type can be specified, but the host may support only a subset of MIME types. The client and the server have to agree on the type, or the data will not get through correctly. The default type for both sending and receiving is 'application/json'. For this type, the host will use JSON.stringify() to convert any JavaScript object passed to send() into a string, and for received messages, will attempt to parse the message as a JSON string. Implementations of this module should support at least the following types:
An example usage is given below: var webSocket = require('webSocket'); var client = new webSocket.Client({'host': 'localhost', 'port': 8080}); client.send({'foo': 'bar'}); client.on('message', function(message) { console.log('Received from web socket: ' + message); }); client.open(); The above code sends a message even before the socket is opened. The module implementation is expected to queue that message to be sent later when the socket is opened (unless the option discardMessagesBeforeOpen is given with value true). The options argument to the Client constructor is a JSON object that can contain the following properties:
Server ClassA Server is constructed (using new) by the Server function, which takes one (optional) argument, an options object, defined below. A Server instance is an HTTP server that listens for web socket connection requests and creates an instance of the Socket class (defined below) for each opened web socket. After invoking this constructor (using new), the user script should set up listeners and then invoke the start() function on this Server. This will create an HTTP server on the local host. The options argument is a JSON object containing the following optional fields:
A Server object is an EventEmitter, and you can register handlers for the following events:
The functions provided by the Server class are:
A typical usage pattern looks like this: var server = new WebSocket.Server({'port':8082}); server.on('listening', onListening); server.on('connection', onConnection); server.start(); where onListening is a handler for an event that this Server emits when it is listening for connections, and onConnection is a handler for an event that this Server emits when a client requests a websocket connection and the socket has been successfully established. When the 'connection' event is emitted, it will be passed a Socket object, and the onConnection handler can register a listener for 'message' events on that Socket object, as follows: server.on('connection', function(socket) { socket.on('message', function(message) { console.log(message); socket.send('Reply message'); }); }); Socket ClassA Socket is constructed by a Server and provided as an argument to any handler registered to handle 'connection' events. An instance of Socket provides incoming messages as 'message' events and provides a send() function to send messages to the client over the socket. A user should not directly construct an instance of Socket. The Server will do that. A Socket is an EventEmitter that emits the following events:
Functions provided by the Socket are:
See Also
Remote Resources
|