Changes

Jump to navigation Jump to search
548 bytes added ,  13:18, 27 February 2020
no edit summary
==%ws:connect(path)==
Called directly after a successful WebSocket handshake. The <code>path</code> specifies the path which a client is connected to.: <syntaxhighlight lang="xquery">declare %ws:connect('/') function local:connect() { };</syntaxhighlight>
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:
<pre classsyntaxhighlight lang="brush:xquery">
declare %ws:message('/', '{$info}') function local:message($info) { };
</presyntaxhighlight>
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:
<pre classsyntaxhighlight lang="brush:xquery">
declare %ws:error('/', '{$error}') function local:error($error) { };
</presyntaxhighlight>
Usually, errors happen because of bad/malformed incoming packets. The WebSocket connection gets closed after the error handling.
==%ws:close(path)==
Called when the WebSocket closes. The <code>path</code> specifies the path which a client is connected to.: <syntaxhighlight lang="xquery">declare %ws:close('/') function local:connect() { };</syntaxhighlight>
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:
<pre classsyntaxhighlight lang="brush:xquery">
declare
%ws:close('host', '{$host}')
admin:write-log('Connection was closed: ' || $host)
};
</presyntaxhighlight>
The following parameters are available:
If you get the <code>[basex:ws] WebSocket connection required</code> error, you may be attempting to call WebSocket functions from a non-WebSocket context. If you use a proxy server, check in the configuration if WebSockets are enabled.
=Examples= ==Basic Example==
The following chapter explains how to create a simple basic web application with WebSockets. You can find another example in the BaseX source code.
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.
<pre classsyntaxhighlight lang="brush:xquery">
declare
%ws:connect('/')
function example:connect() as empty-sequence() {
};
</presyntaxhighlight>
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>:
<pre classsyntaxhighlight lang="brush:xquery">
import module namespace ws = 'http://basex.org/modules/ws'
ws:emit($message)
};
</presyntaxhighlight>
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:
<pre classsyntaxhighlight lang="brush:javajavascript">
var ws = new WebSocket("ws://localhost:8984/ws");
ws.send(message);
};
</presyntaxhighlightThe <code>send</code> function can be called to pass on a string to the server. There are no heart-beats in this example. This means that the connection is terminated if nothing happens for 5 minutes (standard timeout). It will also be closed if you send a message that exceeds the standard text size. ==Chat Application== In the full distributions of BaseX, you will find a little self-contained chat application that demonstrates how WebSockets can be used in practice.
The <code>send</code> function can be called to pass on a string (e. g. a chat message) to the server.=Changelog=
There are no heartbeats in this exampleWebSockets werre introduced with Version 9. This means that the connection is terminated if nothing happens for 5 minutes (standard timeout). It will also be closed if you send a message that exceeds the standard text size1.
Bureaucrats, editor, reviewer, Administrators
13,550

edits

Navigation menu