Difference between revisions of "WebSocket Module"
Jump to navigation
Jump to search
Line 6: | Line 6: | ||
* All functions and errors are assigned to the <code><nowiki>http://basex.org/modules/websocket</nowiki></code> namespace. The module must be imported in the query prolog: | * All functions and errors are assigned to the <code><nowiki>http://basex.org/modules/websocket</nowiki></code> namespace. The module must be imported in the query prolog: | ||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
− | import module namespace | + | import module namespace ws = "http://basex.org/modules/Websocket"; |
... | ... | ||
</pre> | </pre> | ||
Line 12: | Line 12: | ||
=Functions= | =Functions= | ||
− | == | + | ==ws:send== |
+ | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func| | + | |{{Func|ws:send|$message as xs:anyAtomicType, $ids as xs:string* |empty-sequence()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 22: | Line 23: | ||
|} | |} | ||
− | == | + | ==ws:broadcast== |
+ | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func| | + | |{{Func|ws:broadcast|$message as xs:anyAtomicType|empty-sequence()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 32: | Line 34: | ||
|} | |} | ||
− | == | + | ==ws:emit== |
+ | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func| | + | |{{Func|ws:emit|$message as xs:anyAtomicType|empty-sequence()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 42: | Line 45: | ||
|} | |} | ||
− | == | + | ==ws:id== |
+ | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func| | + | |{{Func|ws:id||xs:string}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 52: | Line 56: | ||
|} | |} | ||
− | == | + | ==ws:ids== |
+ | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func| | + | |{{Func|ws:ids||xs:string*}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 62: | Line 67: | ||
|} | |} | ||
− | == | + | ==ws:path== |
+ | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func| | + | |{{Func|ws:path||xs:string}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 72: | Line 78: | ||
|} | |} | ||
− | == | + | ==ws:path== |
+ | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func| | + | |{{Func|ws:path|$id as xs:string|xs:string}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
Line 83: | Line 90: | ||
=Example 1= | =Example 1= | ||
+ | |||
==Code== | ==Code== | ||
+ | |||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
− | |||
module namespace websocketexample = 'http://basex.org/modules/web-page'; | module namespace websocketexample = 'http://basex.org/modules/web-page'; | ||
(: Import the WebSocket module :) | (: Import the WebSocket module :) | ||
− | import module namespace | + | import module namespace ws = "http://basex.org/modules/Websocket"; |
+ | declare | ||
%ws:connect("/") | %ws:connect("/") | ||
function websocketexample:connect( | function websocketexample:connect( | ||
− | + | ) { | |
− | + | let $client-id := ws:id() | |
− | + | let $client-path := ws:path() | |
− | + | let $response := json:serialize( | |
− | + | <json type="object"> | |
− | + | <messageType>UserConnected</messageType> | |
− | + | <clientId>{$client-id}</clientId> | |
− | + | <clientPath>{$client-path}</clientPath> | |
− | + | </json> | |
− | + | ) | |
− | + | return ws:broadcast($response) | |
− | + | }; | |
</pre> | </pre> | ||
+ | |||
==Explanation== | ==Explanation== | ||
+ | |||
* First of all: include the websocket module | * First of all: include the websocket module | ||
* The <code>$ws:connect("/")</code> annotation gets called if a client successfully creates a websocket to the path "/" (checkout [[WebSockets]] for further information). | * The <code>$ws:connect("/")</code> annotation gets called if a client successfully creates a websocket to the path "/" (checkout [[WebSockets]] for further information). | ||
− | * Get the <code>client-id</code> and the <code>client-path</code> with <code> | + | * Get the <code>client-id</code> and the <code>client-path</code> with <code>ws:id()</code> and <code>ws:path()</code> |
* Create a json-result | * Create a json-result | ||
* Broadcast the result to all connected clients without the calling client | * Broadcast the result to all connected clients without the calling client | ||
=Example 2= | =Example 2= | ||
+ | |||
==Code== | ==Code== | ||
+ | |||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
− | |||
(: Import the Websockets module :) | (: Import the Websockets module :) | ||
− | import module namespace | + | import module namespace ws = "http://basex.org/modules/Websocket"; |
+ | |||
declare | declare | ||
%ws:message("/","{$message}") | %ws:message("/","{$message}") | ||
− | + | function local:message( | |
− | + | $message as xs:string | |
− | + | ) as xs:string { | |
− | + | let $client-ids := ws:ids() | |
− | + | let $fist-client-id := fn:head($client-ids) | |
− | + | let $send-to-id := ws:send($message, $first-client-id) | |
− | + | let $path-first-client := ws:path($first-client-id) | |
− | + | let $response := json:serialize( | |
− | + | <json type="object"> | |
− | + | <messageType>PathFirstClient</messageType> | |
− | + | <path>{ $path-first-client }</path> | |
− | + | </json> | |
− | + | ) | |
− | + | return ws:emit($response) | |
− | + | }; | |
</pre> | </pre> | ||
+ | |||
==Explanatation== | ==Explanatation== | ||
+ | |||
* First of all, import the websocket module | * First of all, import the websocket module | ||
* The annotation <code>$ws:message("/",{$message}")</code> gets called if a message arrives at the server (checkout [[WebSockets]] for further information). | * The annotation <code>$ws:message("/",{$message}")</code> gets called if a message arrives at the server (checkout [[WebSockets]] for further information). | ||
− | * With <code> | + | * With <code>ws:ids()</code> you will get the ids of all connected clients. |
− | * The function <code> | + | * The function <code>ws:send($message,$first-client-id)</code> sends the <code>$message</code> to the client with the id <code>$first-client-id</code> |
− | * <code> | + | * <code>ws:path($first-client-id)</code> returns the path of the client with the id <code>$first-client-id</code> |
− | * To emit a message to all connected clients you call <code> | + | * To emit a message to all connected clients you call <code>ws:emit($response)</code> |
Revision as of 20:39, 13 August 2018
This XQuery Module contains functions for accessing specific WebSocket functions. This module is mainly useful in the context of WebSockets.
Contents
Conventions
- The
basex-api
package must be included in the classpath. This is always the case if you use one of the complete distributions (zip, exe, war) of BaseX. - All functions and errors are assigned to the
http://basex.org/modules/websocket
namespace. The module must be imported in the query prolog:
import module namespace ws = "http://basex.org/modules/Websocket"; ...
Functions
ws:send
Signatures | ws:send($message as xs:anyAtomicType, $ids as xs:string* ) as empty-sequence()
|
Summary | Sends a message which may be of type xs:string, xs:base64Binary, or xs:hexBinary to the user(s) with the ID(s) $ids
|
ws:broadcast
Signatures | ws:broadcast($message as xs:anyAtomicType) as empty-sequence()
|
Summary | Broadcasts message which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected clients except to the caller.
|
ws:emit
Signatures | ws:emit($message as xs:anyAtomicType) as empty-sequence()
|
Summary | Emits a message which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected clients.
|
ws:id
Signatures | ws:id() as xs:string
|
Summary | Returns the ID of the current client WebSocket connection. |
ws:ids
Signatures | ws:ids() as xs:string*
|
Summary | Returns the IDs of all current WebSocket connections. |
ws:path
Signatures | ws:path() as xs:string
|
Summary | Returns the path of the current WebSocketClient. |
ws:path
Signatures | ws:path($id as xs:string) as xs:string
|
Summary | Returns the path of specific user with the ID $id .
|
Example 1
Code
module namespace websocketexample = 'http://basex.org/modules/web-page'; (: Import the WebSocket module :) import module namespace ws = "http://basex.org/modules/Websocket"; declare %ws:connect("/") function websocketexample:connect( ) { let $client-id := ws:id() let $client-path := ws:path() let $response := json:serialize( <json type="object"> <messageType>UserConnected</messageType> <clientId>{$client-id}</clientId> <clientPath>{$client-path}</clientPath> </json> ) return ws:broadcast($response) };
Explanation
- First of all: include the websocket module
- The
$ws:connect("/")
annotation gets called if a client successfully creates a websocket to the path "/" (checkout WebSockets for further information). - Get the
client-id
and theclient-path
withws:id()
andws:path()
- Create a json-result
- Broadcast the result to all connected clients without the calling client
Example 2
Code
(: Import the Websockets module :) import module namespace ws = "http://basex.org/modules/Websocket"; declare %ws:message("/","{$message}") function local:message( $message as xs:string ) as xs:string { let $client-ids := ws:ids() let $fist-client-id := fn:head($client-ids) let $send-to-id := ws:send($message, $first-client-id) let $path-first-client := ws:path($first-client-id) let $response := json:serialize( <json type="object"> <messageType>PathFirstClient</messageType> <path>{ $path-first-client }</path> </json> ) return ws:emit($response) };
Explanatation
- First of all, import the websocket module
- The annotation
$ws:message("/",{$message}")
gets called if a message arrives at the server (checkout WebSockets for further information). - With
ws:ids()
you will get the ids of all connected clients. - The function
ws:send($message,$first-client-id)
sends the$message
to the client with the id$first-client-id
ws:path($first-client-id)
returns the path of the client with the id$first-client-id
- To emit a message to all connected clients you call
ws:emit($response)