WebSocket Module

From BaseX Documentation
Revision as of 19:44, 13 August 2018 by CG (talk | contribs)
Jump to navigation Jump to search

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

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)