Module: socket

The default options for socket connections from the client side.

The default options for socket servers.

A Socket object for the server side of a new connection. This is created by the _socketCreated function above whenever a new connection is established at the request of a client. It should not normally be called by the JavaScript programmer. The returned Socket is an event emitter that emits the following events:

• data: Emitted when data is received on any socket handled by this server. This will be passed the data.
• close: Emitted when a socket is closed. This is not passed any arguments.
• error: Emitted when an error occurs. This will be passed an error message.

Construct an instance of a socket client that can send or receive messages to a server at the specified host and port. The returned object subclasses EventEmitter and emits the following events:

• open: Emitted with no arguments when the socket has been successfully opened.
• data: Emitted with the data as an argument when data arrives on the socket.
• close: Emitted with no arguments when the socket is closed.

• error: Emitted with an error message when an error occurs.

  You can invoke the this.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();

  }); socket.open();

  The options argument is a JSON object that can include:

• connectTimeout: The time to wait (in milliseconds) before declaring a connection attempt to have failed. This defaults to 6000.
• idleTimeout: The amount of idle time in seconds that will cause a disconnection of a socket. This defaults to 0, which means no timeout.
• discardMessagesBeforeOpen: If true, then discard any messages passed to SocketClient.send() before the socket is opened. If false, then queue the messages to be sent when the socket opens. This defaults to false.
• emitBatchDataAsAvailable: Whether to emit all data available when the TCP stream is received and when rawBytes is true. This parameter is intended for socket.js module, and will not be exposed to TCP socket accessors. Set this true only when the TCP stream is going to be handled by upper layer protocols.
• keepAlive: Whether to keep a connection alive and reuse it. This defaults to true.
• maxUnsentMessages: The maximum number of unsent messages to queue before further calls to this.send() will fail. A value of 0 means no limit. This defaults to 100.
• noDelay: If true, data as sent as soon as it is available (the default). If false, data may be accumulated until a reasonable packet size is formed in order to make more efficient use of the network (using Nagle's algorithm).
• rawBytes: If true (the default), then transmit only the data bytes provided to this.send() without any header. If false, then prepend sent data with length information and assume receive data starts with length information. Setting this false on both ends will ensure that each data item passed to this.send() is emitted once in its entirety at the receiving end, as a single message. When this is false, the receiving end can emit a partially received message or could concatenate two messages and emit them together.
• receiveBufferSize: The size of the receive buffer. Defaults to 65536.
• receiveType: See below.
• reconnectAttempts: The number of times to try to reconnect. If this is greater than 0, then a failure to attempt will trigger additional attempts. This defaults to 10.
• reconnectInterval: The time between reconnect attempts, in milliseconds. This defaults to 1000 (1 second).
• sendBufferSize: The size of the receive buffer. Defaults to 65536.
• sendType: See below.
• sslTls: Whether SSL/TLS is enabled. This defaults to false.

• trustAll: Whether to trust servers. This defaults to false. Setting it to true means that if sslTls is set to true, then any certificate provided by the server will be trusted. FIXME: Need to provide a trusted list if this is false.

  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, as specified here: https://docs.oracle.com/javase/specs/jls/se8/html/jls-5.html#jls-5.1.3 .

  For numeric types, you can also send an array with a single call to this.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 this.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.

  The meaning of the options is (partially) defined here: http://vertx.io/docs/vertx-core/java/

  After this SocketClient is constructed, it will have properties 'port' and 'host' equal to the port and host options passed to the constructor.

Construct an instance of a socket client that can send or receive messages to a server at the specified host and port. The returned object subclasses EventEmitter and emits the following events:

• open: Emitted with no arguments when the socket has been successfully opened.
• data: Emitted with the data as an argument when data arrives on the socket.
• close: Emitted with no arguments when the socket is closed.

• error: Emitted with an error message when an error occurs.

  You can invoke the this.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).

  FIXME: No options (including discardMessagesBeforeOpen) have been implemented for this Cordova module!!!

  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();

  }); socket.open();

Construct an instance of a socket server that listens for connection requests and opens sockets when it receives them. After invoking this constructor (using new), the user can set up listeners for the following events:

• listening: Emitted when the server is listening. This will be passed the port number that the server is listening on (this is useful if the port is specified to be 0).
• connection: Emitted when a new connection is established after a request from (possibly remote) client. This will be passed an instance of a Socket class that can be used to send data or to close the socket. The instance of Socket is also an event emitter that emits 'close', 'data', and 'error' events.

• error: Emitted if the server fails to start listening. This will be passed an error message.

  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);
   });

  }); server.start();

  When the 'connection' event is emitted, it will be passed a Socket object, which has a this.send() function. For example, to send a reply to each incoming message, replace the above 'data' handler as follows:

  serverSocket.on('data', function(data) {

  serverSocket.send('Reply message');

  });

  The Socket object also has a close() function that allows the server to close the connection. The ServerSocket object has a close() 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:

• clientAuth: One of 'none', 'request', or 'required', meaning whether it requires that a certificate be presented.

• emitBatchDataAsAvailable: Whether to emit all data available when the TCP stream is received and when rawBytes is true. This parameter is intended for socket.js module, and will not be exposed to TCP socket accessors. Set this true only when the TCP stream is going to be handled by upper layer protocols.
• hostInterface: The name of the network interface to use for listening, e.g. 'localhost'. The default is '0.0.0.0', which means to listen on all available interfaces.
• idleTimeout: The amount of idle time in seconds that will cause a disconnection of a socket. This defaults to 0, which means no timeout.
• keepAlive: Whether to keep a connection alive and reuse it. This defaults to true.
• keyStorePassword: If sslTls is set to true, then this option needs to specify the password for the key store specified by keyStorePath.
• keyStorePath: If sslTls is set to true, then this option needs to specify the fully qualified filename for the file that stores the certificate that this server will use to identify itself. This path can be any of those understood by the Ptolemy host, e.g. paths beginning with $CLASSPATH/.
• noDelay: If true, data as sent as soon as it is available (the default). If false, data may be accumulated until a reasonable packet size is formed in order to make more efficient use of the network (using Nagle's algorithm).
• port: The default port to listen on. This defaults to 4000. a value of 0 means to choose a random ephemeral free port.
• rawBytes: If true (the default), then transmit only the data bytes provided to this.send() without any header. If false, then prepend sent data with length information and assume receive data starts with length information. Setting this false on both ends will ensure that each data item passed to this.send() is emitted once in its entirety at the receiving end, as a single message. When this is false, the receiving end can emit a partially received message or could concatenate two messages and emit them together.
• receiveBufferSize: The size of the receive buffer. Defaults to 65536.
• receiveType: See below.
• sendBufferSize: The size of the receive buffer. Defaults to 65536.
• sendType: See below.

• sslTls: Whether SSL/TLS is enabled. This defaults to false.

  The meaning of the options is (partially)defined here: http://vertx.io/docs/vertx-core/java/

  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, as specified here: https://docs.oracle.com/javase/specs/jls/se8/html/jls-5.html#jls-5.1.3 .

  For numeric types, you can also send an array with a single call to this.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.

Return an array of the types supported by the current host for receiveType arguments.

Return an array of the types supported by the current host for sendType arguments.

cordova-plugin-chrome-apps-sockets-tcp uses an array buffer for sent and received messages. This helper function interprets the buffer as a UTF-8 string

cordova-plugin-chrome-apps-sockets-tcp uses an array buffer for sent and received messages. This helper function creates a buffer for a UTF-8 string.

The default options for socket connections from the client side.

The default options for socket servers.

A Socket object for the server side of a new connection. This is created by the _socketCreated function above whenever a new connection is established at the request of a client. It should not normally be called by the JavaScript programmer. The returned Socket is an event emitter that emits the following events:

• data: Emitted when data is received on any socket handled by this server. This will be passed the data.
• close: Emitted when a socket is closed. This is not passed any arguments.
• error: Emitted when an error occurs. This will be passed an error message.

Construct an instance of a socket client that can send or receive messages to a server at the specified host and port. The returned object subclasses EventEmitter and emits the following events:

• open: Emitted with no arguments when the socket has been successfully opened.
• data: Emitted with the data as an argument when data arrives on the socket.
• close: Emitted with no arguments when the socket is closed.

• error: Emitted with an error message when an error occurs.

  You can invoke the this.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();

  }); socket.open();

  The options argument is a JSON object that can include:

• connectTimeout: The time to wait (in milliseconds) before declaring a connection attempt to have failed. This defaults to 6000.
• idleTimeout: The amount of idle time in seconds that will cause a disconnection of a socket. This defaults to 0, which means no timeout.
• discardMessagesBeforeOpen: If true, then discard any messages passed to SocketClient.send() before the socket is opened. If false, then queue the messages to be sent when the socket opens. This defaults to false.
• emitBatchDataAsAvailable: Whether to emit all data available when the TCP stream is received and when rawBytes is true. This parameter is intended for socket.js module, and will not be exposed to TCP socket accessors. Set this true only when the TCP stream is going to be handled by upper layer protocols.
• keepAlive: Whether to keep a connection alive and reuse it. This defaults to true.
• maxUnsentMessages: The maximum number of unsent messages to queue before further calls to this.send() will fail. A value of 0 means no limit. This defaults to 100.
• noDelay: If true, data as sent as soon as it is available (the default). If false, data may be accumulated until a reasonable packet size is formed in order to make more efficient use of the network (using Nagle's algorithm).
• rawBytes: If true (the default), then transmit only the data bytes provided to this.send() without any header. If false, then prepend sent data with length information and assume receive data starts with length information. Setting this false on both ends will ensure that each data item passed to this.send() is emitted once in its entirety at the receiving end, as a single message. When this is false, the receiving end can emit a partially received message or could concatenate two messages and emit them together.
• receiveBufferSize: The size of the receive buffer. Defaults to 65536.
• receiveType: See below.
• reconnectAttempts: The number of times to try to reconnect. If this is greater than 0, then a failure to attempt will trigger additional attempts. This defaults to 10.
• reconnectInterval: The time between reconnect attempts, in milliseconds. This defaults to 1000 (1 second).
• sendBufferSize: The size of the receive buffer. Defaults to 65536.
• sendType: See below.
• sslTls: Whether SSL/TLS is enabled. This defaults to false.

• trustAll: Whether to trust servers. This defaults to false. Setting it to true means that if sslTls is set to true, then any certificate provided by the server will be trusted. FIXME: Need to provide a trusted list if this is false.

  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, as specified here: https://docs.oracle.com/javase/specs/jls/se8/html/jls-5.html#jls-5.1.3 .

  For numeric types, you can also send an array with a single call to this.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 this.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.

  The meaning of the options is (partially) defined here: http://vertx.io/docs/vertx-core/java/

  After this SocketClient is constructed, it will have properties 'port' and 'host' equal to the port and host options passed to the constructor.

Construct an instance of a socket client that can send or receive messages to a server at the specified host and port. The returned object subclasses EventEmitter and emits the following events:

• open: Emitted with no arguments when the socket has been successfully opened.
• data: Emitted with the data as an argument when data arrives on the socket.
• close: Emitted with no arguments when the socket is closed.

• error: Emitted with an error message when an error occurs.

  You can invoke the this.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).

  FIXME: No options (including discardMessagesBeforeOpen) have been implemented for this Cordova module!!!

  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();

  }); socket.open();

Construct an instance of a socket server that listens for connection requests and opens sockets when it receives them. After invoking this constructor (using new), the user can set up listeners for the following events:

• listening: Emitted when the server is listening. This will be passed the port number that the server is listening on (this is useful if the port is specified to be 0).
• connection: Emitted when a new connection is established after a request from (possibly remote) client. This will be passed an instance of a Socket class that can be used to send data or to close the socket. The instance of Socket is also an event emitter that emits 'close', 'data', and 'error' events.

• error: Emitted if the server fails to start listening. This will be passed an error message.

  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);
   });

  }); server.start();

  When the 'connection' event is emitted, it will be passed a Socket object, which has a this.send() function. For example, to send a reply to each incoming message, replace the above 'data' handler as follows:

  serverSocket.on('data', function(data) {

  serverSocket.send('Reply message');

  });

  The Socket object also has a close() function that allows the server to close the connection. The ServerSocket object has a close() 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:

• clientAuth: One of 'none', 'request', or 'required', meaning whether it requires that a certificate be presented.

• emitBatchDataAsAvailable: Whether to emit all data available when the TCP stream is received and when rawBytes is true. This parameter is intended for socket.js module, and will not be exposed to TCP socket accessors. Set this true only when the TCP stream is going to be handled by upper layer protocols.
• hostInterface: The name of the network interface to use for listening, e.g. 'localhost'. The default is '0.0.0.0', which means to listen on all available interfaces.
• idleTimeout: The amount of idle time in seconds that will cause a disconnection of a socket. This defaults to 0, which means no timeout.
• keepAlive: Whether to keep a connection alive and reuse it. This defaults to true.
• keyStorePassword: If sslTls is set to true, then this option needs to specify the password for the key store specified by keyStorePath.
• keyStorePath: If sslTls is set to true, then this option needs to specify the fully qualified filename for the file that stores the certificate that this server will use to identify itself. This path can be any of those understood by the Ptolemy host, e.g. paths beginning with $CLASSPATH/.
• noDelay: If true, data as sent as soon as it is available (the default). If false, data may be accumulated until a reasonable packet size is formed in order to make more efficient use of the network (using Nagle's algorithm).
• port: The default port to listen on. This defaults to 4000. a value of 0 means to choose a random ephemeral free port.
• rawBytes: If true (the default), then transmit only the data bytes provided to this.send() without any header. If false, then prepend sent data with length information and assume receive data starts with length information. Setting this false on both ends will ensure that each data item passed to this.send() is emitted once in its entirety at the receiving end, as a single message. When this is false, the receiving end can emit a partially received message or could concatenate two messages and emit them together.
• receiveBufferSize: The size of the receive buffer. Defaults to 65536.
• receiveType: See below.
• sendBufferSize: The size of the receive buffer. Defaults to 65536.
• sendType: See below.

• sslTls: Whether SSL/TLS is enabled. This defaults to false.

  The meaning of the options is (partially)defined here: http://vertx.io/docs/vertx-core/java/

  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, as specified here: https://docs.oracle.com/javase/specs/jls/se8/html/jls-5.html#jls-5.1.3 .

  For numeric types, you can also send an array with a single call to this.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.

Return an array of the types supported by the current host for receiveType arguments.

Return an array of the types supported by the current host for sendType arguments.

cordova-plugin-chrome-apps-sockets-tcp uses an array buffer for sent and received messages. This helper function interprets the buffer as a UTF-8 string

cordova-plugin-chrome-apps-sockets-tcp uses an array buffer for sent and received messages. This helper function creates a buffer for a UTF-8 string.