Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
Called when the WebSocket closesUsually, errors happen because of bad/malformed incoming packets. The <code>path</code> specifies WebSocket connection gets closed after the path which a client is connected toerror handling.
The WebSocket is already closed when this annotation is called so there can be no return. ==%ws:close(path)==
==%wsCalled when the WebSocket closes. The <code>path</code> specifies the path which a client is connected to:error(path, message)==
Called when an error occurs. The <codepre class="brush:xquery">pathdeclare %ws:close('/') function local:connect() { };</codepre> specifies the path which a client is connected to.
Usually, errors happen because of bad/malformed incoming packets. The <code>message</code> WebSocket is the error message. The WebSocket connection gets already closed after the error handlingwhen this annotation is called so there can be no return.
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.
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.: <pre class="brush:xquery">declare %ws:connect('/') function local:connect() { };</pre>
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.
==%ws:message(path, message)==
Called when a <code>client message</code> 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 class="brush:xquery">declare %ws:message('/', '{$info}') function local:message($info) { };</pre> 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. ==%ws:error(path, message)==
Called when an error occurs. The <code>messagepath</code> specifies the path which a client is the connected to. The <code>message</code> sent by string contains the client. It will be name of type <code>xs:string</code> or <code>xs:base64Binary</code>. The client needs the variable to take care of which the message syntax, and it must not exceed the configured maximum size.will be bound:
<pre class=="brush:xquery">declare %ws:closeerror(path'/', '{$error}')==function local:error($error) { };</pre>
==%ws:header-param(name, variable[, default])==
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 is available, an optional <code>default</code> value will be bound assigned instead.: <pre class="brush:xquery">declare %ws:close('host', '{$host}') %ws:header-param('host', '{$host}')function local:close($host) { admin:write-log('Connection was closed: ' || $host)};</pre>
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.
</pre>
The <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 (estandard timeout). gIt 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 message) to the serverapplication that demonstrates how WebSockets can be used in practice. =Changelog=
