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. 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 12: Line 11:
  
 
=Functions=
 
=Functions=
 +
 +
==websocket:send==
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|websocket:send|$message as xs:anyAtomicType, $ids as xs:string* |empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Sends a <code>message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to the user(s) with the ID(s) <code>$ids</code>
 +
|}
  
 
==websocket:broadcast==
 
==websocket:broadcast==
Line 20: Line 29:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Broadcasts <code>message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected members except to the caller.  
+
|Broadcasts <code>message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected clients except to the caller.
 +
|}
 +
 
 +
==websocket:emit==
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|websocket:emit|$message as xs:anyAtomicType|empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Emits a <code>message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected clients.
 
|}
 
|}
  
Line 30: Line 49:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the ID of the current WebSocket connection.
+
|Returns the ID of the current client WebSocket connection.
 +
|}
 +
 
 +
==websocket:ids==
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|websocket:ids||xs:string*}}
 +
|-
 +
| '''Summary'''
 +
|Returns the IDs of all current WebSocket connections.
 
|}
 
|}
  
Line 40: Line 69:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the path of the current WebSocketClient. If the <code>$id</code> parameter is set, the path of a specific user with the ID <code>$id</code> will be returned.
+
|Returns the path of the current WebSocketClient.
 
|}
 
|}
  
=Usage Tips=
+
==websocket:path==
* <code>websocket:id</code> returns your current session id. You can use all [[Session Module]] and [[Sessions Module]] functions within the websocket context.
+
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|websocket:path|$id as xs:string|xs:string}}
 +
|-
 +
| '''Summary'''
 +
|Returns the path of specific user with the ID <code>$id</code>.
 +
|}
  
=Example=
+
=Example 1=
 
==Code==
 
==Code==
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
Line 75: Line 111:
 
* 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=
 +
==Code==
 +
<pre class="brush:xquery">
 +
module namespace websocketsexample = 'http://basex.org/modules/web-page';
 +
(: Import the Websockets module :)
 +
import module namespace websocket = "http://basex.org/modules/Websocket";
 +
declare
 +
  %ws:message("/","{$message}")
 +
  function websocketsexample:message(
 +
    $message as xs:string
 +
  ){
 +
    let $client-ids := websocket:ids()
 +
    let $fist-client-id := fn:head($client-ids)
 +
    let $send-to-id := websocket:send($message,$first-client-id)
 +
    let $path-first-client := websocket:path($first-client-id)
 +
    let $response := json:serialize(
 +
                              <json type="object">
 +
                                <messageType>PathFirstClient</messageType>
 +
                                <path>{$path-first-client}</path>
 +
                              </json>
 +
                            )
 +
    return websocket:emit($response)
 +
  };
 +
 +
</pre>
 +
==Explanatation==
 +
* 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).
 +
* With <code>websocket:ids()</code> you will get the ids of all connected clients.
 +
* The function <code>websocket:send($message,$first-client-id)</code> sends the <code>$message</code> to the client with the id <code>$first-client-id</code>
 +
* <code>websocket: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>websocket:emit($response)</code>

Revision as of 23:09, 10 August 2018

This XQuery Module contains functions for accessing specific WebSocket functions. This module is mainly useful in the context of WebSockets.

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:send

Signatures websocket: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

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 clients except to the caller.

websocket:emit

Signatures websocket: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.

websocket:id

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

websocket:ids

Signatures websocket:ids() as xs:string*
Summary Returns the IDs of all current WebSocket connections.

websocket:path

Signatures websocket:path() as xs:string
Summary Returns the path of the current WebSocketClient.

websocket:path

Signatures websocket:path($id as xs:string) as xs:string
Summary Returns the path of specific user with the ID $id.

Example 1

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

Example 2

Code

module namespace websocketsexample = 'http://basex.org/modules/web-page';
(: Import the Websockets module :)
import module namespace websocket = "http://basex.org/modules/Websocket";
declare
  %ws:message("/","{$message}")
  function websocketsexample:message(
    $message as xs:string
  ){
     let $client-ids := websocket:ids()
     let $fist-client-id := fn:head($client-ids)
     let $send-to-id := websocket:send($message,$first-client-id)
     let $path-first-client := websocket:path($first-client-id)
     let $response := json:serialize(
                              <json type="object">
                                <messageType>PathFirstClient</messageType>
                                <path>{$path-first-client}</path>
                              </json>
                            ) 
     return websocket: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 websocket:ids() you will get the ids of all connected clients.
  • The function websocket:send($message,$first-client-id) sends the $message to the client with the id $first-client-id
  • websocket: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 websocket:emit($response)