Difference between revisions of "WebSocket Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 46: Line 46:
 
* <code>websocket:id</code> returns your current session id. You can use all [[Session Module]] and [[Sessions Module]] functions within the websocket context.
 
* <code>websocket:id</code> returns your current session id. You can use all [[Session Module]] and [[Sessions Module]] functions within the websocket context.
  
=Examples=
+
=Example=
 
==Code==
 
==Code==
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
Line 71: Line 71:
 
==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 "/"
+
* 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>websocket:id()</code> and <code>websocket:path()</code>
 
* Get the <code>client-id</code> and the <code>client-path</code> with <code>websocket:id()</code> and <code>websocket: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

Revision as of 08:34, 10 August 2018

This XQuery Module contains functions for accessing specific WebSocket functions. This module is mainly useful in the context of WebSockets. Within the WebSocket module you can access functions in the context of the specific client. You can access the clientid, the clientpath and broadcast a message to all connected clients without the caller/client. If you have to access functions with more rights, like getting the clientids of other connected clients, you should checkout the WebSockets Module

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 websocket = "http://basex.org/modules/Websocket";
...

Functions

websocket:broadcast

Signatures websocket: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 members except to the caller.

websocket:id

Signatures websocket:id() as xs:string
Summary Returns the ID of the current WebSocket connection.

websocket:path

Signatures websocket:path() as xs:string
Summary Returns the path of the current WebSocketClient. If the $id parameter is set, the path of a specific user with the ID $id will be returned.

Usage Tips

Example

Code

declare
module namespace websocketexample = 'http://basex.org/modules/web-page';
(: Import the WebSocket module :)
import module namespace websocket = "http://basex.org/modules/Websocket";

  %ws:connect("/")
  function websocketexample:connect(
  )  {
     let $client-id := websocket:id()
     let $client-path := websocket:path()
     let $response := json:serialize(
                              <json type="object">
                                <messageType>UserConnected</messageType>
                                <clientId>{$client-id}</clientId>
                                <clientPath>{$client-path}</clientPath>
                              </json>
                            )
    return websocket: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 the client-path with websocket:id() and websocket:path()
  • Create a json-result
  • Broadcast the result to all connected clients without the calling client