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:
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 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
toSendbut 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.
- Version:
- $$Id$$
- Source:
Inputs:
| 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. |
Outputs:
| 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. |
Parameters:
| 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 '0.0.0.0', 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. |
Methods
(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.