WebSocket Module

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)