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: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 clients.

ws:path

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

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 users with the specified $ids.

ws:broadcast

Signatures	ws:broadcast($message as xs:anyAtomicType) as empty-sequence()
Summary	Broadcasts a $message, which may be of type xs:string, xs:base64Binary or xs:hexBinary, to all connected clients except to the caller. This convenience function is equivalent to ws:send($message, ws:ids()[. != ws:id()]).

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. This convenience function is equivalent to ws:send($message, ws:ids()).

ws:close

Signatures	ws:close($id as xs:string) as empty-sequence()
Summary	Closes the connection of the WebSocket client with the specified $id.

Examples

Example 1

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

declare
  %ws:connect('/')
function local:connect() as xs:string {
  let $id := ws:id()
  let $message := json:serialize(map {
    'type': 'Connect',
    'id': $id
  })
  return ws:broadcast($message)
};

Explanation:

• The function has a %ws:connect annotation. It gets called if a client successfully creates a WebSocket connection to the path / (check out WebSockets for further information).
• A JSON response is generated, which contains the new client id and a Connect string.
• This response will be sent to all other connected clients.

Example 2

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

declare
  %ws:message('/', '{$message}')
function local:message(
  $message as xs:string
) as xs:string {
  let $message := json:serialize(map { 'message': $message })
  return ws:emit($message)
};

Explanation:

• The function has a %ws:message annotation. It gets called if a client sends a new message.
• A JSON response is generated, which contains the message string.
• This response will be sent to all connected clients (including the calling client).