Difference between revisions of "WebSocket Module"
Jump to navigation
Jump to search
Line 18: | Line 18: | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|ws:send|$message as xs:anyAtomicType, $ids as xs:string* |empty-sequence()}} | + | |{{Func|ws:send|$message as xs:anyAtomicType, $ids as xs:string*|empty-sequence()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Sends a <code>$message</code> which may be of type xs:string, xs:base64Binary | + | |Sends a <code>$message</code>, which may be of type xs:string, xs:base64Binary or xs:hexBinary, to the users with the specified <code>$ids</code>. |
|} | |} | ||
Line 32: | Line 32: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Broadcasts <code>$message</code> which may be of type xs:string, xs:base64Binary | + | |Broadcasts a <code>$message</code>, which may be of type xs:string, xs:base64Binary or xs:hexBinary, to all connected clients except to the caller. |
|} | |} | ||
Line 43: | Line 43: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Emits a <code>message</code> which may be of type xs:string, xs:base64Binary | + | |Emits a <code>$message</code>, which may be of type xs:string, xs:base64Binary or xs:hexBinary, to all connected clients. |
|} | |} | ||
Line 65: | Line 65: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the ids of all currently registered WebSocket | + | |Returns the ids of all currently registered WebSocket clients. |
|} | |} | ||
Line 73: | Line 73: | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | | | + | |{{Func|ws:path|$id as xs:string|xs:string}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the path of the | + | |Returns the path of the WebSocket client with the specified {{Code|$id}}. |
+ | |} | ||
+ | |||
+ | ==ws:close== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|ws:close|$id as xs:string|empty-sequence()}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Closes the connection of the WebSocket client with the specified {{Code|$id}}. | ||
|} | |} | ||
Line 84: | Line 95: | ||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
− | |||
import module namespace ws = "http://basex.org/modules/Websocket"; | import module namespace ws = "http://basex.org/modules/Websocket"; | ||
declare | declare | ||
− | %ws:connect( | + | %ws:connect('/') |
− | function local:connect( | + | function local:connect() as xs:string { |
− | ) as | + | let $id := ws:id() |
− | let $ | + | let $message := json:serialize(map { |
− | let $ | + | 'type': 'Connect', |
− | + | 'id': $id | |
− | + | }) | |
− | + | return ws:broadcast($message) | |
− | |||
− | |||
− | |||
− | |||
− | return ws:broadcast($ | ||
}; | }; | ||
</pre> | </pre> | ||
Line 106: | Line 111: | ||
'''Explanation:''' | '''Explanation:''' | ||
− | + | * The function has a <code>%ws:connect</code> annotation. It gets called if a client successfully creates a WebSocket connection to the path <code>/</code> (check out [[WebSockets]] for further information). | |
− | * The <code> | + | * A JSON response is generated, which contains the new client id and a <code>Connect</code> string. |
− | * | + | * This response will be sent to all other connected clients. |
− | * | ||
− | |||
==Example 2== | ==Example 2== | ||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
− | |||
import module namespace ws = "http://basex.org/modules/Websocket"; | import module namespace ws = "http://basex.org/modules/Websocket"; | ||
declare | declare | ||
− | %ws:message( | + | %ws:message('/', '{$message}') |
function local:message( | function local:message( | ||
− | $message | + | $message as xs:string |
− | ) as | + | ) as xs:string { |
− | let | + | let $message := json:serialize(map { 'message': $message }) |
− | + | return ws:emit($message) | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | return ws:emit($ | ||
}; | }; | ||
</pre> | </pre> | ||
Line 139: | Line 132: | ||
'''Explanation:''' | '''Explanation:''' | ||
− | + | * The function has a <code>%ws:message</code> annotation. It gets called if a client sends a new message. | |
− | * The | + | * A JSON response is generated, which contains the message string. |
− | * | + | * This response will be sent to all connected clients (including the calling client). |
− | |||
− | * | ||
− |
Revision as of 11:34, 27 September 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/ws
namespace. The module must be imported in the query prolog:
import module namespace ws = "http://basex.org/modules/ws"; ...
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 users with the specified $ids .
|
ws:broadcast
Signatures | ws:broadcast($message as xs:anyAtomicType) as empty-sequence()
|
Summary | Broadcasts a $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 clients. |
ws:path
Signatures | ws:path($id as xs:string) as xs:string
|
Summary | Returns the path of the WebSocket client with the specified $id .
|
ws:close
Signatures | ws:close($id as xs:string) as empty-sequence()
|
Summary | Closes the connection of the WebSocket client with the specified $id .
|
Examples
Example 1
import module namespace ws = "http://basex.org/modules/Websocket"; declare %ws:connect('/') function local:connect() as xs:string { 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/Websocket"; declare %ws:message('/', '{$message}') function local:message( $message as xs:string ) as xs:string { 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).