Difference between revisions of "WebSocket Module"
Jump to navigation
Jump to search
Line 11: | Line 11: | ||
</pre> | </pre> | ||
− | =Functions= | + | =General Functions= |
==ws:id== | ==ws:id== | ||
Line 21: | Line 21: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the ID of the current WebSocket | + | |Returns the ID of the current WebSocket. |
|} | |} | ||
Line 32: | Line 32: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the ids of all currently registered WebSocket | + | |Returns the ids of all currently registered WebSocket. |
|} | |} | ||
Line 43: | Line 43: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the path of the WebSocket | + | |Returns the path of the WebSocket 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 with the specified {{Code|$id}}. | ||
+ | |} | ||
+ | |||
+ | =Sending Data= | ||
==ws:send== | ==ws:send== | ||
Line 79: | Line 92: | ||
|} | |} | ||
− | ==ws: | + | =WebSocket Attributes= |
+ | |||
+ | ==ws:get== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|ws:get|$id as xs:string, $name as xs:string|item()*}}<br/>{{Func|ws:get|$id as xs:string, $name as xs:string, $default as item()*|item()*}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Returns the value of an attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Code|$id}}. If the attribute is unknown, an empty sequence or the optionally specified {{Code|$default}} value will be returned instead. | ||
+ | |} | ||
+ | |||
+ | ==ws:set== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|ws:set|$id as xs:string, $name as xs:string, $value as item()*|empty-sequence()}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Returns the specified {{Code|value}} of the attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Mono|$id}}. | ||
+ | |- | ||
+ | | '''Errors''' | ||
+ | |{{Error|set|#Errors}} The supplied value cannot be materialized. | ||
+ | |} | ||
+ | |||
+ | ==ws:delete== | ||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|ws: | + | |{{Func|ws:delete|$id as xs:string, $name as xs:string|empty-sequence()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | | + | |Deletes an attribute with the specified {{Code|$name}} from the WebSocket with the specified {{Mono|$id}}. |
|} | |} | ||
Line 135: | Line 175: | ||
* A JSON response is generated, which contains the message string. | * A JSON response is generated, which contains the message string. | ||
* This response will be sent to all connected clients (including the calling client). | * This response will be sent to all connected clients (including the calling client). | ||
+ | |||
+ | =Errors= | ||
+ | |||
+ | {| class="wikitable" width="100%" | ||
+ | ! width="110"|Code | ||
+ | |Description | ||
+ | |- | ||
+ | |{{Code|set}} | ||
+ | |The supplied value cannot be materialized. | ||
+ | |- | ||
+ | |{{Code|not-found}} | ||
+ | |The specified WebSocket was not found. | ||
+ | |} | ||
+ | |||
+ | =Changelog= | ||
+ | |||
+ | This module was introduced with Version 9.1. |
Revision as of 13:15, 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"; ...
General Functions
ws:id
Signatures | ws:id() as xs:string
|
Summary | Returns the ID of the current WebSocket. |
ws:ids
Signatures | ws:ids() as xs:string*
|
Summary | Returns the ids of all currently registered WebSocket. |
ws:path
Signatures | ws:path($id as xs:string) as xs:string
|
Summary | Returns the path of the WebSocket with the specified $id .
|
ws:close
Signatures | ws:close($id as xs:string) as empty-sequence()
|
Summary | Closes the connection of the WebSocket with the specified $id .
|
Sending Data
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 clients 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. Invocations of this convenience function are equivalent to ws:send($message, ws:ids()[. != ws:id()]) .
|
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. Invocations of this function are equivalent to ws:send($message, ws:ids()) .
|
WebSocket Attributes
ws:get
Signatures | ws:get($id as xs:string, $name as xs:string) as item()* ws:get($id as xs:string, $name as xs:string, $default as item()*) as item()*
|
Summary | Returns the value of an attribute with the specified $name from the WebSocket with the specified $id . If the attribute is unknown, an empty sequence or the optionally specified $default value will be returned instead.
|
ws:set
Signatures | ws:set($id as xs:string, $name as xs:string, $value as item()*) as empty-sequence()
|
Summary | Returns the specified value of the attribute with the specified $name from the WebSocket with the specified $id .
|
Errors | set : The supplied value cannot be materialized.
|
ws:delete
Signatures | ws:delete($id as xs:string, $name as xs:string) as empty-sequence()
|
Summary | Deletes an attribute with the specified $name from the WebSocket 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).
Errors
Code | Description |
---|---|
set
|
The supplied value cannot be materialized. |
not-found
|
The specified WebSocket was not found. |
Changelog
This module was introduced with Version 9.1.