|
Version0 /
socket ModuleModule supporting TCP sockets. This module defines three classes, SocketClient, SocketServer, and Socket. To establish a connection, create an instance of SocketServer and listen for connection events. When a connection request comes in, the listener will be passed an instance of Socket. The server can send data through that instance and listen for incoming data events. On another machine (or the same machine), create an instance of SocketClient. When the connection is established to the server, this instance will emit an 'open' event. When data arrives from the server, it will emit a 'data' event. You can invoke send() to send data to the server. The send() function can accept data in many different forms. You can send a string, an image, a number, or an array of numbers. Two utility functions supportedReceiveTypes() and supportedSendTypes() tell you exactly which data types supported by the host. Arrays of numeric types are also supported. If the rawBytes option is true (the default), then data is sent without any message framing. As a consequence, the recipient of the data may emit only a portion of any sent data, or it may even coalesce data provided in separate invocations of send(). If rawBytes is false, then messages will be framed so that each invocation of send() results in exactly one data item emitted at the other end. This will only work if both sides of the connection implement the same framing protocol, e.g. if they both are implemented with this same module. To communicate with external tools that do not support this message framing protocol, leave rawBytes set to true. The message framing protocol used here is very simple. Each message is preceded by one byte indicating the length of the message. If the message has length greater than 254, then the value of this byte will be 255 and the subsequent four bytes will represent the length of the message. The message then follows these bytes. Functions
SocketClient ClassAn instance of this class, created with new, is a socket client that can send or receive messages to a server at the host and port to the constructor. The constructor takes three arguments:
The instance of SocketClient provides the following functions:
This class subclasses EventEmitter and emits the following events:
You can invoke the send() function of this SocketClient object to send data to the server. If the socket is not opened yet, then data will be discarded or queued to be sent later, depending on the value of the discardMessagesBeforeOpen option (which defaults to false). The event close will be emitted when the socket is closed, and error if an an error occurs (with an error message as an argument). A simple example that sends a message, and closes the socket on receiving a reply:
var socket = require('socket');
var client = new socket.SocketClient();
client.on('open', function() {
client.send('hello world');
});
client.on('data', function onData(data) {
print('Received from socket: ' + data);
client.close();
});
client.open();
The options argument is a JSON object that can include:
The send and receive types can be any of those returned by supportedReceiveTypes() and supportedSendTypes(), respectively. If both ends of the socket are known to be JavaScript clients, then you should use the 'number' data type for numeric data. If one end or the other is not JavaScript, then you can use more specified types such as 'float' or 'int', if they are supported by the host. In all cases, received numeric data will be converted to JavaScript 'number' when emitted. For sent data, this will try to convert a JavaScript number to the specified type. The type 'number' is equivalent to 'double'. When type conversions are needed, e.g. when you send a double with sendType set to int, or an int with sendType set to byte, then a "primitive narrowing conversion" will be applied. For numeric types, you can also send an array with a single call to send(). The elements of the array will be sent in sequence all at once, and may be received in one batch. If both ends have rawBytes set to false (specifying message framing), then these elements will be emitted at the receiving end all at once in a single array. Otherwise, they will be emitted one at a time. For strings, you can also send an array of strings in a single call, but these will be simply be concatenated and received as a single string. If the rawBytes option is set to false, then each data item passed to send(), of any type or array of types, will be coalesced into a single message and the receiving end (if it also has rawBytes set to false) will emit the entire message, and only the message, exactly once. Otherwise, a message may get fragmented, emitted in pieces, or coalesced with subsequent messages. SocketServer ClassAn instance of this class, created with new, is a socket server that can send or receive messages from a client. The client initiates the connection. The constructor takes one argument:
The instance of SocketServer provides the following function:
An instance of a socket server that listens for connection requests and opens sockets when it receives them. This class is an event emitter that emits the following events:
A typical usage pattern looks like this:
var server = new socket.SocketServer();
server.on('listening', function(port) {
console.log('Server listening on port: ' + port);
});
var connectionCount = 0;
server.on('connection', function(serverSocket) {
var connectionNumber = connectionCount++;
console.log('Server connected on a new socket number: ' + connectionNumber);
serverSocket.on('data', function(data) {
console.log('Server received data on connection '
+ connectionNumber
+ ": "
+ data);
});
});
server.start();
When the connection event is emitted, it will be passed a Socket object, defined below, which has a send() function. For example, to send a reply to each incoming message, replace the above data handler as follows:
serverSocket.on('data', function(data) {
socket.send('Reply message');
});
The Socket object also has a close() function that allows the server to close the individual connection without stopping the server. The SocketServer object has a stop() function that will close all connections and shut down the server. An options argument can be passed to the SocketServer constructor above. This is a JSON object containing the following optional fields:
The send and receive types can be any of those returned by supportedReceiveTypes() and supportedSendTypes(), respectively, defined above. If both ends of the socket are known to be JavaScript clients, then you should use the 'number' data type for numeric data. If one end or the other is not JavaScript, then you can use more specified types such as 'float' or 'int', if they are supported by the host. In all cases, received numeric data will be converted to JavaScript 'number' when emitted. For sent data, this will try to convert a JavaScript number to the specified type. The type 'number' is equivalent to 'double'. When type conversions are needed, e.g. when you send a double with sendType set to int, or an int with sendType set to byte, then a "primitive narrowing conversion" will be applied. For numeric types, you can also send an array with a single call to send(). The elements of the array will be sent in sequence all at once, and may be received in one batch. If both ends have rawBytes set to false (specifying message framing), then these elements will be emitted at the receiving end all at once in a single array. Otherwise, they will be emitted one at a time. For strings, you can also send an array of strings in a single call, but these will be simply be concatenated and received as a single string. Socket ClassAn instance of this class is created by the SocketServer whenever a new socket connection has been established. That instance is emitted as an argument to the connection event. An instance of Socket is an event emitter that emits the following events:
An instance of this class provides the following functions:
|