This accessor starts a server that listens for web socket connection requests on the specified hostInterface and port. The hostInterface is needed only if the host machine has more than one network interface (e.g. Ethernet and WiFi) and 'localhost' does not resolve to the desired interface.
The output connection reports when a
connection is opened or closed.
The output is an object with two fields, a 'socketID',
which is a unique ID for this client connection, and a 'status' field,
which is the string 'open' or 'closed'.
When a message arrives on a connection, a received
output is produced with that message. Note that the message may arrive in
multiple frames, but it will be produced on this port as a single message.
The output is an object with two fields,
a 'socketID', which is a unique ID for this client connection, and a 'message' field,
which is the message received from the client.
When an input arrives on toSend, then a message is
sent to one or all of the open socket connections.
If this is an object with 'socketID' field and a 'message' field,
then send the value of the message field to the socket identified
by the socketID field. If the input has any other form, then the
message is broadcast to all open socket connections.
When wrapup() is invoked, this accessor closes the
server and all connections.
The default type for both sending and receiving is 'application/json', which allows sending and receiving anything that has a string representation in JSON. The types supported by this implementation include at least:
- application/json: The this.send() function uses JSON.stringify() and sends the result with a UTF-8 encoding. An incoming byte stream will be parsed as JSON, and if the parsing fails, will be provided as a string interpretation of the byte stream.
- text/*: Any text type is sent as a string encoded in UTF-8.
image/x: Where x is one of json, png, gif, and more. In this case, the data passed to this.send() is assumed to be an image, as encoded on the host, and the image will be encoded as a byte stream in the specified format before sending. A received byte stream will be decoded as an image, if possible.
This accessor requires the module webSocket.
- Version:
- $$Id$$
- Source:
Inputs:
| Name | Type | Description |
|---|---|---|
toSend |
The data to be sent to open sockets. If this is an object with 'socketID' field and a 'message' field, then send the value of the message field to the socket identified by the socketID field. If the input has any other form, then the message is broadcast to all open socket 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 |
connection |
An output produced when a connection opens or closes. The output is an object with two fields, a 'socketID', which is a unique ID for this client connection, and a 'status' field, which is the string 'open' or 'closed'. | |
received |
A message received a client in the form of an object with two fields, a 'socketID', which is a unique ID for this client connection, and a 'message' field, which is the message received from the client. |
Parameters:
| Name | Type | Description |
|---|---|---|
hostInterface |
string | The IP address or domain name of the network interface to listen to. |
port |
int | The port to listen to for connections. |
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/. |
receiveType |
string | The MIME type for incoming messages, which defaults to 'application/json'. |
sendType |
string | The MIME type for outgoing messages, which defaults to 'application/json'. |
sslTls |
boolean | Whether SSL/TLS is enabled. This defaults to false. |
Methods
(static) filterReceived(message)
Filter the received message. This base class just returns the argument unmodified, but derived classes can override this to extract a portion of the message, for example.
Parameters:
| Name | Type | Description |
|---|---|---|
message |
The message. |
(static) initialize()
Starts the web socket and attaches functions to inputs and outputs. Adds an input handler on toSend that sends the input received to the right socket.
(static) notifyClose()
Notify that the socketID is now closed. This base class does nothing, but derived classes can override this to be notified of a closing socket, for example.
(static) onConnection()
Executes when a connection has been established.
Triggers an output on 'connection'.
Adds an event listener to the socket.
(static) setup()
Sets up the accessor by defining inputs and outputs.
(static) wrapup()
Removes all inputHandlers from sockets.
Unregisters event listeners from sockets.
Closes server.