Accessor: net/TCPSocketServer


This accessor establishes a server that can accept connection requests for a TCP socket and can send and/or receives messages from the client that makes the request.

When the server is listening and accepting connections, the port on which it is listening is emitted on the listening output port.

When a connection is established, this accessor outputs on the connection output an object with the following properties:

  • id: A unique ID identifying the connection (a positive integer).
  • remoteHost: The IP address of the remote host for the socket (a string).
  • remotePort: The port of the remote host for the socket (an integer).
  • status: The string 'open'.

When the connection is closed, the same object as above is produced on the connection output, except with status being 'closed'.

When data is received from the connection, two outputs are produced. The data itself is produced on the received output. The ID of the connection over which the data arrived is produced on the receivedID output.

To send data over a connection, provide the data on the toSend input port and the ID of the connection on the toSendID input port. To send to all open connections, provide an ID of 0 (zero).

The send and receive types can be any of those supported by the host. The list of supported types will be provided as options for the sendType and receiveType parameter. For the Ptolemy II host, these include at least 'string', 'number', 'image', and a variety of numeric types.

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: .

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 that arrives on toSend, 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.

When a model with an instance of this accessor stops executing, there are two mechanisms by which data in transit can be lost. In both cases, warning messages or error messages will be issued to the host to be displayed or otherwise handled as the host sees fit.

  • First, there might be queued messages that were received on toSend but have not yet been sent, either because the socket has not yet been opened or because it was closed from the other side.
  • Second, a message might be received from the server after shutdown has commenced. In particular, received messages are handled asynchronously by a handler function that can be invoked at any time, and that handler might be invoked after it is no longer possible for this accessor to produce outputs (it has entered its wrapup phase of execution).

The client might similarly lose messages by the same two mechanisms occurring on the client side. In that case, messages will presumably be displayed on the client side.

Accessors that extend this one can override the toSendInputHandler function to customize what is sent.

This accessor requires the 'socket' module.

  • $$Id$$
  • Edward A. Lee, Hokeun Kim
Name Type Description
toSend The data to be sent over the socket.
toSendID The ID of the connection over which to send the data, where 0 means to send to all open connections.
Name Type Description
listening int When the server is listening for connections, this output will produce the port number that the server is listening on (this is useful if the port is specified to be 0).
connection Output an object with the properties specified above when a connection is established.
received The data received from the web socket server.
receivedID The ID of the connection over which data produced on the received output was received. This is a positive integer, as indicated in the connection output.
Name Type Description
clientAuth string One of 'none', 'request', or 'required', meaning whether it requires that a certificate be presented.
discardSendToUnopenedSocket boolean If true, then discard any data sent to a socket that is not open. The data will be logged using console.log() instead. This defaults to false.
hostInterface string The name of the network interface to use for listening, e.g. 'localhost'. The default is '', which means to listen on all available interfaces.
idleTimeout int The amount of idle time in seconds that will cause a disconnection of a socket. This defaults to 0, which means no timeout.
keepAlive boolean Whether to keep a connection alive and reuse it. This defaults to true.
noDelay boolean 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).
pfxKeyCertPassword string If sslTls is set to true, then this option needs to specify the password for the pfx key-cert file specified by pfxKeyCertPath.
pfxKeyCertPath string If sslTls is set to true, then this option needs to specify the fully qualified filename for the file that stores the private key and 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/.
port int The default port to listen on. This defaults to 4000. a value of 0 means to choose a random ephemeral free port.
rawBytes boolean 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 int The size of the receive buffer. Defaults to 65536.
receiveType string See below.
sendBufferSize int The size of the receive buffer. Defaults to 65536.
sendType string See below.
sslTls boolean Whether SSL/TLS is enabled. This defaults to false.
trustedCACertPath string If sslTls is set to true and this server requests/requires a certificate from the client, then this option needs to specify the filename for the file that stores the certificate of a certificate authority (CA) that this server will use to verify client certificates. This path can be any of those understood by the Ptolemy host, e.g. paths beginning with $CLASSPATH/. FIXME: Need to be a list of paths for certificates rather than a single path.


(static) initialize()

Initialize the accessor by starting the server with the current parameter values specifying the options, setting up listeners to be notified when the server is is listening for connections, when a client requests and connection, and when errors occur, and setting up an input handler for data arriving on the toSend input. When a client requests a connection, the handler will open the socket, send a connection output, and and set up listeners for incoming data, errors, and closing of the socket from the remote site.


(static) setup()

Set up the accessor by defining the parameters, inputs, and outputs.


(static) toSendInputHandler()

Handle input on 'toSend' by sending to one or all of the open sockets, depending on the most recently received value on the toSendID input.


(static) wrapup()

Close all sockets, unregister event listeners, and stop the server.