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 websocket = "http://basex.org/modules/Websocket";
...
Functions
websocket:send
Signatures
|
websocket: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
|
websocket:broadcast
Signatures
|
websocket: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.
|
websocket:emit
Signatures
|
websocket: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.
|
websocket:id
Signatures
|
websocket:id() as xs:string
|
Summary
|
Returns the ID of the current client WebSocket connection.
|
websocket:ids
Signatures
|
websocket:ids() as xs:string*
|
Summary
|
Returns the IDs of all current WebSocket connections.
|
websocket:path
Signatures
|
websocket:path() as xs:string
|
Summary
|
Returns the path of the current WebSocketClient.
|
websocket:path
Signatures
|
websocket:path($id as xs:string) as xs:string
|
Summary
|
Returns the path of specific user with the ID $id .
|
Example 1
Code
declare
module namespace websocketexample = 'http://basex.org/modules/web-page';
(: Import the WebSocket module :)
import module namespace websocket = "http://basex.org/modules/Websocket";
%ws:connect("/")
function websocketexample:connect(
) {
let $client-id := websocket:id()
let $client-path := websocket:path()
let $response := json:serialize(
<json type="object">
<messageType>UserConnected</messageType>
<clientId>{$client-id}</clientId>
<clientPath>{$client-path}</clientPath>
</json>
)
return websocket: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 websocket:id()
and websocket:path()
- Create a json-result
- Broadcast the result to all connected clients without the calling client
Example 2
Code
module namespace websocketsexample = 'http://basex.org/modules/web-page';
(: Import the Websockets module :)
import module namespace websocket = "http://basex.org/modules/Websocket";
declare
%ws:message("/","{$message}")
function websocketsexample:message(
$message as xs:string
){
let $client-ids := websocket:ids()
let $fist-client-id := fn:head($client-ids)
let $send-to-id := websocket:send($message,$first-client-id)
let $path-first-client := websocket:path($first-client-id)
let $response := json:serialize(
<json type="object">
<messageType>PathFirstClient</messageType>
<path>{$path-first-client}</path>
</json>
)
return websocket:emit($response)
};
Explanatation
- 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
websocket:ids()
you will get the ids of all connected clients.
- The function
websocket:send($message,$first-client-id)
sends the $message
to the client with the id $first-client-id
websocket: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
websocket:emit($response)