Difference between revisions of "WebSocket Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 1: Line 1:
This [[Module Library|XQuery Module]] contains functions for accessing specific WebSocket functions and setting attributes on a WebSocket connection. This module is mainly useful in the context of [[WebSockets]].
+
This [[Module Library|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=
 
=Conventions=
Line 6: Line 7:
 
* 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 websocket = "http://basex.org/modules/websocket";
+
import module namespace websocket = "http://basex.org/modules/Websocket";
 
...
 
...
 
</pre>
 
</pre>
Line 44: Line 45:
 
=Usage Tips=
 
=Usage Tips=
 
* <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=
 +
==Code==
 +
<pre class="brush:xquery">
 +
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)
 +
  };
 +
</pre>
 +
==Explanation==
 +
* 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 "/"
 +
* 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
 +
* Broadcast the result to all connected clients without the calling client

Revision as of 08:17, 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

Examples

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 "/"
  • 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