Guides/Window Driver/Websocket

Jqt Websocket

Jqt provides a websocket interface for acting both as a server and a client based on the QtWebsocket (Qt 4.8) or QWebSocket (Qt 5.3) class. Communications are done using the ws (websocket) command with the format

wd 'ws cmd parameters '

where cmd is the command and parameter is an optional list of values specific for each command.

Commands

Documentation for all of the Jqt websocket commands is provided below, including the parameters available for each command. Some additional notes regarding usage for some commands is also provided. See addons/ide/qt/demo for examples.

connect

(client mode only) Connect to a websocket server.

ws connect url

url - url of a websocket server in the form of either ws://server[|port]] (tcp, unencrypted connection) or wss://server[|port]] (tls encrypted connection), without trailing slash.

return a socket number for identifying the connection.

Example:

socket=: wd 'ws connect ws://localhost:3000'

Notes:

This command will return as soon as after sending request to server without waiting for the reply. The connection is not guaranteed to be successful.

When successful connected, an onOpen event will be triggered which can be processed inside the verb wscln_handler_z_

Connection to wss:// (tls, encrypted connection) is not yet implemented.

close

Close a socket

ws close socket

socket - socket number of connection to be closed.

Example:

wd 'ws close ', socket

Notes:

An onClose event will be triggered when socket is closed.

listen

(server mode only) Start a websocket server.

ws listen port [protocol]

port - port number to listen, must be a positive integer.

protocol - 0 for tcp (unencrypted); 1 for tls (encrypted). 0 if elided.

Example:

wd 'ws listen 3000'

Notes:

Any running websocket server will be terminated and all client connections will also be closed before trying to start a websocket server.

In particular, a value of 0 for port will terminate an active websocket server.

Protocol tls (encrypted) is not yet implemented.

query

Query for socket connected.

ws query mode

mode - 0 for server mode; 1 for client mode. 0 if elided.

return LF delimited list of all sockets.

Example:

wd 'ws query 0'

Notes:

For client mode, some of sockets may not be connected to remote servers.

send

Send utf8 text data to a socket

ws send socket data

socket - socket number of connection.

data - rank-1 character array.

return the number of bytes of data written or _1 if failed.

Example:

len=. ". wd 'ws send ', socket, ' "greeting from J"'

Notes:

If socket is 0, data will be broadcasted to all clients connected to J.

If socket is 1, data will be broadcasted to all servers connected to J.

There is no recv command. When data have been received, the onMessage event will be triggered.

If data is binary, then it can encoded as plain text using an encoding system such as base64, however both ends should use the same encoding.

Use either send or sendb as what will be expected by the other end of communication.

See also command sendb.

sendb

Send binary data to a socket

ws sendb socket data

socket - socket number of connection.

data - rank-1 character array.

return the number of bytes of data written or _1 if failed.

Example:

len=. ". wd 'ws sendb ', socket, ' *Alphabet:', a.

Notes:

If socket is 0, data will be broadcasted to all clients connected to J.

If socket is 1, data will be broadcasted to all servers connected to J.

Utf8 text can also be sent but will be received as binary data by the other end of communication.

See also command send.

state

Query state of a socket

ws state socket

return NULL terminated list of name and value of some properties of a socket.

Example:

wd 'ws state ', ":sk

Notes:

This command is available for Qt 5.3

To convert the result to a rank-2 array

   _2]\ <;._2 wd 'ws state ', ":sk

+------------+--------------------------+
|errorString |Unknown error             |
+------------+--------------------------+
|isValid     |1                         |
+------------+--------------------------+
|localAddress|192.168.1.23              |
+------------+--------------------------+
|localPort   |44820                     |
+------------+--------------------------+
|origin      |                          |
+------------+--------------------------+
|peerAddress |174.129.224.73            |
+------------+--------------------------+
|peerName    |echo.websocket.org        |
+------------+--------------------------+
|peerPort    |80                        |
+------------+--------------------------+
|requestUrl  |ws://echo.websocket.org:80|
+------------+--------------------------+
|resourceName|/                         |
+------------+--------------------------+

Event handler

Websocket is event driven. Users should implement event handlers in response to various events, their names are:

(server mode) wssvr_handler_z_ (monadic verb)

(client mode) wscln_handler_z_ (monadic verb)

When events occur, the event handler is called with a right argument which is a list of 2 numbers - event and socket.

The following constants are defined in locale jqtide in qt.ijs:

jws_onOpen jws_onClose jws_onMessage jws_onError jws_onSslError jws_onStateChange

A typical event handler looks like this

'evt socket'=.y
if. evt = jws_onOpen_jqtide_ do.          NB. onOpen
....
elseif. evt = jws_onMessage_jqtide_ do.   NB. onMessage
...
endif.

Notes:

J can work as either a server or a client or both at same time therefore users need to implement wssvr_handler_z_ or wscln_handler_z_ or both depending on the mode of operation.

Typically J acts as a websocket server so that only wssvr_handler_z_ is needed.

Events

There are 6 type of events.

onOpen

(server mode) a new client connection is accepted

(client mode) connection to a remote websocket server is established

onClose

socket is closed.

onMessage

data is received.

2 nouns will be set on entry:

(server mode)

wss0_jrx_ - rank-1 array of data received

wss1_jrx_ - either 'text' or 'binary'

(client mode)

wsc0_jrx_ - rank-1 array of data received

wsc1_jrx_ - either 'text' or 'binary'

onError

Error occurred.

(server mode) wss0_jrx_ - error message

(client mode) wsc0_jrx_ - error message

onSslError

Ssl Error occurred.

(server mode) wss0_jrx_ - error message

(client mode) wsc0_jrx_ - error message

onStateChange

(client mode only) state of socket changed

wsc0_jrx_ - reason

Contributed by Bill Lam