Main Page » XQuery » Functions » WebSocket Functions

WebSocket Functions

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

Conventions

  • The module will be available if the basex-api library is found in the classpath. This is the case if you use one of the complete distributions of BaseX (zip, exe, war).
  • All functions and errors are assigned to the http://basex.org/modules/ws namespace, which is statically bound to the ws prefix.
  • As sessions are side-effecting operations, all functions are flagged as nondeterministic. As a result, some query optimizations will be suppressed.

General Functions

ws:id

Signature
ws:id() as xs:string
SummaryReturns the ID of the current WebSocket.
Errors
not-foundNo WebSocket with the specified id exists.

ws:ids

Signature
ws:ids() as xs:string*
SummaryReturns the ids of all currently registered WebSockets.

ws:path

Signature
ws:path(
  $id  as xs:string
) as xs:string
SummaryReturns the path of the WebSocket with the specified $id.
Errors
not-foundNo WebSocket with the specified id exists.

ws:close

Signature
ws:close(
  $id  as xs:string
) as empty-sequence()
SummaryCloses the connection of the WebSocket with the specified $id.
Errors
not-foundNo WebSocket with the specified id exists.

Sending Data

ws:send

Signature
ws:send(
  $message  as item(),
  $ids      as xs:string*
) as empty-sequence()
SummarySends a $message to the clients with the specified $ids. Ids that cannot be assigned to clients will be ignored. The message will be handled as follows:
  • Items of type xs:base64Binary and xs:hexBinary will be transmitted as binary messages.
  • Function items (maps, arrays) will be serialized as JSON and transmitted as string messages.
  • All other items will be serialized with the default serialization options and transmitted as string messages.

ws:broadcast

Signature
ws:broadcast(
  $message  as item()
) as empty-sequence()
SummaryBroadcasts a $message to all connected clients except to the caller. Invocations of this convenience function are equivalent to ws:send($message, ws:ids()[. != ws:id()]). See ws:send for more details on the message handling.

ws:emit

Signature
ws:emit(
  $message  as item()
) as empty-sequence()
SummaryEmits a $message to all connected clients. Invocations of this function are equivalent to ws:send($message, ws:ids()). See ws:send for more details on the message handling.

ws:eval

Signature
ws:eval(
  $query     as (xs:string|xs:anyURI),
  $bindings  as map((xs:string|xs:QName), item()*)?  := (),
  $options   as map(*)?                              := {}
) as xs:string
SummarySchedules the evaluation of the supplied $query and returns the result to the calling WebSocket client. The query can be a URI or a string, and variables and context items can be declared via $bindings (see xquery:eval for more details). The following $options are available:
optiondefaultdescription
base-uri– The base-uri property for the query. This URI will be used when resolving relative URIs, such as with fn:doc.
id– A custom job id. The id must not start with the standard job prefix, and it can only be assigned if no job with the same name exists.

Scheduling is recommendable if the immediate query execution might be too time consuming and result in a timeout.

Errors
id
overflow
Examples
declare
  %ws:message('/tasks', '{$message}')
function local:message($message) {
  ws:eval('prof:sleep(10000), "Your message has been processed."')
};
Schedule a second query that will notify the client 10 seconds later that a message was processed.

WebSocket Attributes

ws:get

Signature
ws:get(
  $id       as xs:string,
  $name     as xs:string,
  $default  as item()*    := ()
) as item()*
SummaryReturns the value of an attribute with the specified $name for the WebSocket with the specified $id. If the attribute is unknown, an empty sequence or the optionally specified $default value will be returned instead.
Errors
not-foundNo WebSocket with the specified id exists.

ws:set

Signature
ws:set(
  $id     as xs:string,
  $name   as xs:string,
  $value  as item()*
) as empty-sequence()
SummaryAssigns the specified $value to the attribute with the specified $name for the WebSocket with the specified $id.
Errors
not-foundNo WebSocket with the specified id exists.

ws:delete

Signature
ws:delete(
  $id    as xs:string,
  $name  as xs:string
) as empty-sequence()
SummaryDeletes an attribute with the specified $name from the WebSocket with the specified $id.
Errors
not-foundNo WebSocket with the specified id exists.

Examples

Example 1

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

declare
  %ws:connect('/')
function local:connect() as empty-sequence() {
  let $id := ws:id()
  let $message := json:serialize({ '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/ws";

declare
  %ws:message('/', '{$message}')
function local:message(
  $message as xs:string
) as empty-sequence() {
  let $message := json:serialize({ '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).

Errors

CodeDescription
not-foundNo WebSocket with the specified id exists.

Changelog

Version 9.2Version 9.1
  • Added: New module added.
⚡Generated with XQuery
 
Login | Changelog | TOC | Imprint
WebSocket Functions