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/ws namespace. The module must be imported in the query prolog:

import module namespace ws = "http://basex.org/modules/ws";
...

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 WebSocket client.

ws:ids

Signatures	ws:ids() as xs:string*
Summary	Returns the ids of all currently registered WebSocket client.

ws:path

Signatures	ws:path() as xs:string ws:path($id as xs:string) as xs:string
Summary	Returns the path of the current WebSocket client, or the client with the specified $id.

Examples

Example 1

(: Import the WebSocket module :)
import module namespace ws = "http://basex.org/modules/Websocket";

declare
  %ws:connect("/")
function local:connect(
) as empty-sequence() {
  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 the client-path with ws:id() and ws:path()
• Create a json-result
• Broadcast the result to all connected clients without the calling client

Example 2

(: 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 empty-sequence() {
  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)
};

Explanation:

• 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)