This XQuery 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. The module must be imported in the query prolog:
import module namespace ws = "http://basex.org/modules/ws";
...
- In this document, the namespace is bound to the
ws
prefix.
- As sessions are side-effecting operations, all functions are flagged as non-deterministic. As a result, some query optimizations will be suppressed.
General Functions
ws:id
Signatures
|
ws:id() as xs:string
|
Summary
|
Returns the ID of the current WebSocket.
|
Errors
|
not-found : No WebSocket with the specified id exists.
|
ws:ids
Signatures
|
ws:ids() as xs:string*
|
Summary
|
Returns the ids of all currently registered WebSocket.
|
ws:path
Signatures
|
ws:path($id as xs:string) as xs:string
|
Summary
|
Returns the path of the WebSocket with the specified $id .
|
Errors
|
not-found : No WebSocket with the specified id exists.
|
ws:close
Signatures
|
ws:close($id as xs:string) as empty-sequence()
|
Summary
|
Closes the connection of the WebSocket with the specified $id .
|
Errors
|
not-found : No WebSocket with the specified id exists.
|
Sending Data
ws:send
Signatures
|
ws:send($message as item(), $ids as xs:string*) as empty-sequence()
|
Summary
|
Sends 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
Signatures
|
ws:broadcast($message as xs:anyAtomicType) as empty-sequence()
|
Summary
|
Broadcasts 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
Signatures
|
ws:emit($message as xs:anyAtomicType) as empty-sequence()
|
Summary
|
Emits 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.
|
WebSocket Attributes
ws:get
Signatures
|
ws:get($id as xs:string, $name as xs:string) as item()*
ws:get($id as xs:string, $name as xs:string, $default as item()*) as item()*
|
Summary
|
Returns the value of an attribute with the specified $name from 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-found : No WebSocket with the specified id exists.
|
ws:set
Signatures
|
ws:set($id as xs:string, $name as xs:string, $value as item()*) as empty-sequence()
|
Summary
|
Returns the specified value of the attribute with the specified $name from the WebSocket with the specified $id .
|
Errors
|
not-found : No WebSocket with the specified id exists.
set : The supplied value cannot be materialized.
|
ws:delete
Signatures
|
ws:delete($id as xs:string, $name as xs:string) as empty-sequence()
|
Summary
|
Deletes an attribute with the specified $name from the WebSocket with the specified $id .
|
Errors
|
not-found : No 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(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/ws";
declare
%ws:message('/', '{$message}')
function local:message(
$message as xs:string
) as empty-sequence() {
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).
Errors
Code
|
Description
|
set
|
The supplied value cannot be materialized.
|
not-found
|
No WebSocket with the specified id exists.
|
Changelog
This module was introduced with Version 9.1.