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 is mainly useful in the context of [[WebSockets]]. | This [[Module Library|XQuery Module]] contains functions for accessing specific WebSocket functions. This module is mainly useful in the context of [[WebSockets]]. | ||
− | |||
=Conventions= | =Conventions= | ||
Line 12: | Line 11: | ||
=Functions= | =Functions= | ||
+ | |||
+ | ==websocket:send== | ||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|websocket:send|$message as xs:anyAtomicType, $ids as xs:string* |empty-sequence()}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Sends a <code>message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to the user(s) with the ID(s) <code>$ids</code> | ||
+ | |} | ||
==websocket:broadcast== | ==websocket:broadcast== | ||
Line 20: | Line 29: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Broadcasts <code>message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected | + | |Broadcasts <code>message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected clients except to the caller. |
+ | |} | ||
+ | |||
+ | ==websocket:emit== | ||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|websocket:emit|$message as xs:anyAtomicType|empty-sequence()}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Emits a <code>message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected clients. | ||
|} | |} | ||
Line 30: | Line 49: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the ID of the current WebSocket connection. | + | |Returns the ID of the current client WebSocket connection. |
+ | |} | ||
+ | |||
+ | ==websocket:ids== | ||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|websocket:ids||xs:string*}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Returns the IDs of all current WebSocket connections. | ||
|} | |} | ||
Line 40: | Line 69: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the path of the current WebSocketClient | + | |Returns the path of the current WebSocketClient. |
|} | |} | ||
− | = | + | ==websocket:path== |
− | + | {| width='100%' | |
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|websocket:path|$id as xs:string|xs:string}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Returns the path of specific user with the ID <code>$id</code>. | ||
+ | |} | ||
− | =Example= | + | =Example 1= |
==Code== | ==Code== | ||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
Line 75: | Line 111: | ||
* Create a json-result | * Create a json-result | ||
* Broadcast the result to all connected clients without the calling client | * Broadcast the result to all connected clients without the calling client | ||
+ | |||
+ | =Example 2= | ||
+ | ==Code== | ||
+ | <pre class="brush:xquery"> | ||
+ | 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) | ||
+ | }; | ||
+ | |||
+ | </pre> | ||
+ | ==Explanatation== | ||
+ | * First of all, import the websocket module | ||
+ | * The annotation <code>$ws:message("/",{$message}")</code> gets called if a message arrives at the server (checkout [[WebSockets]] for further information). | ||
+ | * With <code>websocket:ids()</code> you will get the ids of all connected clients. | ||
+ | * The function <code>websocket:send($message,$first-client-id)</code> sends the <code>$message</code> to the client with the id <code>$first-client-id</code> | ||
+ | * <code>websocket:path($first-client-id)</code> returns the path of the client with the id <code>$first-client-id</code> | ||
+ | * To emit a message to all connected clients you call <code>websocket:emit($response)</code> |
Revision as of 00:09, 11 August 2018
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 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 theclient-path
withwebsocket:id()
andwebsocket: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)