WebSocket Module
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.
Contents
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 theclient-path
withws:id()
andws: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)