Changes

Called directly after a successful WebSocket handshake. The <code>path</code> specifies the path which a client is connected to:

declare %ws:connect('/') function local:connect() { };

You can specify here how to handle your users, e. g. save a name as a WebSocket attribute. Furthermore, you can check header parameters for validity.

Called when a client message arrives at the server. The <code>path</code> specifies the path which a client is connected to. The <code>message</code> string contains the name of the variable to which the message will be bound:

declare %ws:message('/', '{$info}') function local:message($info) { };

The value will be of type <code>xs:string</code> or <code>xs:base64Binary</code>. As there is no fixed message protocol, the client needs to take care of the message syntax.

Called when an error occurs. The <code>path</code> specifies the path which a client is connected to. The <code>message</code> string contains the name of the variable to which the message will be bound:

declare %ws:error('/', '{$error}') function local:error($error) { };

Usually, errors happen because of bad/malformed incoming packets. The WebSocket connection gets closed after the error handling.

Called when the WebSocket closes. The <code>path</code> specifies the path which a client is connected to:

declare %ws:close('/') function local:connect() { };

The WebSocket is already closed when this annotation is called so there can be no return.

For accessing connection-specific properties like the HTTP version. The value will be bound to the specified <code>variable</code>. If the property has no value, an optional <code>default</code> value will be assigned instead:

declare

%ws:close('host', '{$host}')

admin:write-log('Connection was closed: ' || $host)

};

The following parameters are available:

For establishing a connection to the WebSocket server, it is necessary that the server provides at least one function annotated with a WebSocket annotation. Let’s start by using the annotation <code>%ws:connect('/')</code>. In the connect function, a bidirectional communication with the client can be initialized: attributes such as the id and name of a client can be set, or a welcome message can be emitted to other connected users, and so on.

declare

%ws:connect('/')

function example:connect() as empty-sequence() {

};

The connect function is sufficient for creating the persistent client/server connection. In order to something sensible with the connection, you should implement a function annotated with <code>%ws:message("/")</code>:

import module namespace ws = 'http://basex.org/modules/ws'

ws:emit($message)

};

In the function above, the [[WebSocket Module]] is imported, and the function <code>ws:emit</code> is used for forwarding the message to all connected clients.

The following client-side code demonstrates a basic application of the WebSocket connection:

var ws = new WebSocket("ws://localhost:8984/ws");

ws.send(message);

};

The <code>send</code> function can be called to pass on a string to the server.