Difference between revisions of "WebSocket Module"
Jump to navigation
Jump to search
Line 1: | Line 1: | ||
− | This [[Module Library|XQuery Module]] contains functions for accessing specific WebSocket functions | + | This [[Module Library|XQuery Module]] contains functions for accessing specific WebSocket functions. This module is mainly useful in the context of [[WebSockets]]. |
+ | Within the WebSocket module you can access functions in the context of the specific client. You can access the clientid, the clientpath and broadcast a message to all connected clients without the caller/client. If you have to access functions with more rights, like getting the clientids of other connected clients, you should checkout the [[WebSockets Module]] | ||
=Conventions= | =Conventions= | ||
Line 6: | Line 7: | ||
* All functions and errors are assigned to the <code><nowiki>http://basex.org/modules/websocket</nowiki></code> namespace. The module must be imported in the query prolog: | * All functions and errors are assigned to the <code><nowiki>http://basex.org/modules/websocket</nowiki></code> namespace. The module must be imported in the query prolog: | ||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
− | import module namespace websocket = "http://basex.org/modules/ | + | import module namespace websocket = "http://basex.org/modules/Websocket"; |
... | ... | ||
</pre> | </pre> | ||
Line 44: | Line 45: | ||
=Usage Tips= | =Usage Tips= | ||
* <code>websocket:id</code> returns your current session id. You can use all [[Session Module]] and [[Sessions Module]] functions within the websocket context. | * <code>websocket:id</code> returns your current session id. You can use all [[Session Module]] and [[Sessions Module]] functions within the websocket context. | ||
+ | |||
+ | =Examples= | ||
+ | ==Code== | ||
+ | <pre class="brush:xquery"> | ||
+ | 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) | ||
+ | }; | ||
+ | </pre> | ||
+ | ==Explanation== | ||
+ | * First of all: include the websocket module | ||
+ | * The <code>$ws:connect("/")</code> annotation gets called if a client successfully creates a websocket to the path "/" | ||
+ | * Get the <code>client-id</code> and the <code>client-path</code> with <code>websocket:id()</code> and <code>websocket:path()</code> | ||
+ | * Create a json-result | ||
+ | * Broadcast the result to all connected clients without the calling client |
Revision as of 08:17, 10 August 2018
This XQuery Module contains functions for accessing specific WebSocket functions. This module is mainly useful in the context of WebSockets. Within the WebSocket module you can access functions in the context of the specific client. You can access the clientid, the clientpath and broadcast a message to all connected clients without the caller/client. If you have to access functions with more rights, like getting the clientids of other connected clients, you should checkout the WebSockets Module
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 websocket = "http://basex.org/modules/Websocket"; ...
Functions
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 members except to the caller.
|
websocket:id
Signatures | websocket:id() as xs:string
|
Summary | Returns the ID of the current WebSocket connection. |
websocket:path
Signatures | websocket:path() as xs:string
|
Summary | Returns the path of the current WebSocketClient. If the $id parameter is set, the path of a specific user with the ID $id will be returned.
|
Usage Tips
websocket:id
returns your current session id. You can use all Session Module and Sessions Module functions within the websocket context.
Examples
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 "/" - Get the
client-id
and theclient-path
withwebsocket:id()
andwebsocket:path()
- Create a json-result
- Broadcast the result to all connected clients without the calling client