Changes

* The module will be available if the {{Code|basex-api}} package must be included library is found in the classpath. This is always the case if you use one of the complete distributions of BaseX (zip, exe, war) of BaseX.* All functions and errors are assigned to the <code><nowiki>http://basex.org/modules/websocketws</nowiki></code> namespace. The module must be imported in , which is statically bound to the query prolog:<pre class="brush:xquery">import module namespace {{Code|ws = "http://basex}} prefix.org/modules/Websocket";* As sessions are side-effecting operations, all functions are flagged as ''non-deterministic''.As a result, some query optimizations will be suppressed..</pre>

=General Functions= ==ws:id== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|ws:id||xs:string}}|-| '''Summary'''|Returns the ID of the current WebSocket.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.|} ==ws:ids== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|ws:ids||xs:string*}}|-| '''Summary'''|Returns the ids of all currently registered WebSockets.|} ==ws:path== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|ws:path|$id as xs:string|xs:string}}|-| '''Summary'''|Returns the path of the WebSocket with the specified {{Code|$id}}.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.|} ==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}}.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.|} =Sending Data=

|{{Func|ws:send|$message as xs:anyAtomicTypeitem(), $ids as xs:string* |empty-sequence()}}

|Sends a <code>$message</code> which may to the clients with the specified <code>$ids</code>. Ids that cannot be assigned to clients will be ignored. The message will be handled as follows:* Items of type xs:string, {{Code|xs:base64Binary, or }} and {{Code|xs:hexBinary to the user}} will be transmitted as binary messages.* Function items (smaps, arrays) will be serialized as JSON and transmitted as string messages.* All other items will be serialized with the ID(s) <code>$ids</code>default serialization options and transmitted as string messages.

|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. Invocations of this convenience function are equivalent to <code>ws:send($message, ws:ids()[. != ws:id()])</code>. See [[#ws:send|ws:send]] for more details on the message handling.

|Emits a <code>$message</code> which may be to all connected clients. Invocations of type this function are equivalent to <code>ws:send($message, ws:ids())</code>. See [[#ws:send|ws:send]] for more details on the message handling.|} ==ws:eval== {| width='100%'|-| width='120' | '''Signatures'''|{{Func|ws:eval|$query as xs:anyAtomicItem|xs:string}}<br />{{Func|ws:eval|$query as xs:anyAtomicItem, $bindings as map(*)?|xs:base64Binarystring}}<br />{{Func|ws:eval|$query as xs:anyAtomicItem, $bindings as map(*)?, $options as map(*)?|xs:string}}<br />|-| '''Summary'''|Schedules the evaluation of the supplied {{Code|$query}} and returns the result to the calling WebSocket client. The query can be a URI or xsa string, and variables and context items can be declared via {{Code|$bindings}} (see {{Function|XQuery|xquery:eval}} for more details). The following {{Code|$options}} can be supplied:* {{Code|base-uri}}: sets the [https://www.w3.org/TR/xquery-31/#dt-static-base-uri base-uri property] for the query. This URI will be used when resolving relative URIs, such as with {{Code|fn:doc}}.* {{Code|id}}:hexBinary sets a custom job id. The id must not start with the standard <code>job</code> prefix, and it can only be assigned if no job with the same name exists.Query scheduling is recommendable if the immediate query execution might be too time consuming and lead to all connected clientsa timeout.|-| '''Errors'''|{{Error|overflow|#Errors}} Query execution is rejected, because too many jobs are queued or being executed. <br/>{{Error|id|#Errors}} The specified id is invalid or has already been assigned.|-| '''Examples'''|* Schedule a second query that will notify the client 10 seconds later that a message was processed:<syntaxhighlight lang="xquery">declare %ws:message('/tasks', '{$message}')function local:message($message) { ws:eval('prof:sleep(10000), "Your message has been processed."')}; </syntaxhighlight>

=WebSocket Attributes= ==ws:idget==

|{{Func|ws:get|$idas xs:string, $name as xs:string|item()*}}<br/>{{Func|ws:get|$id as xs:string, $name as xs:string, $default as item()*|item()*}}

|Returns the ID value of an attribute with the current 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.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket clientwith the specified id exists.

==ws:idsset==

|{{Func|ws:ids|set|$id as xs:string, $name as xs:string, $value as item()*|empty-sequence()}}

|Returns the ids specified {{Code|value}} of all currently registered the attribute with the specified {{Code|$name}} from the WebSocket clientwith the specified {{Mono|$id}}.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.<br>{{Error|set|#Errors}} The supplied value cannot be materialized.

==ws:pathdelete==

|{{Func|ws:path|delete|$id as xs:string}}<br>{{Func|ws:path|, $id name as xs:string|xs:stringempty-sequence()}}

|Returns Deletes an attribute with the path of specified {{Code|$name}} from the current WebSocket client, or the client with the specified {{CodeMono|$id}}.|-| '''Errors'''|{{Error|not-found|#Errors}} No WebSocket with the specified id exists.

=Example 1Examples=

==CodeExample 1==

<pre classsyntaxhighlight lang="brush:xquery">(: Import the WebSocket module :)import module namespace ws = "http://basex.org/modules/Websocketws";

%ws:connect("'/"')function local:connect() as empty-sequence() { let $client-id := ws:id() let $client-path := ws:path() let $response message := json:serialize(map { <json 'type="object">': 'Connect', <messageType>UserConnected</messageType> <clientId>{ 'id': $client-id}</clientId> <clientPath>{$client-path }</clientPath> </json> ) return ws:broadcast($responsemessage)

</presyntaxhighlight>

=='''Explanation==:'''

* First of all: include the websocket module* The function has a <code>$%ws:connect("/")</code> annotation . It gets called if a client successfully creates a websocket WebSocket connection to the path "<code>/</" code> (checkout check out [[WebSockets]] for further information).* Get A JSON response is generated, which contains the <code>new client-id</code> and the a <code>client-path</code> with <code>ws:id()</code> and <code>ws:path()Connect</code>string.* Create a json-result * Broadcast the result This response will be sent to all other connected clients without the calling client.

==Example 2==

==Code== <pre classsyntaxhighlight lang="brush:xquery">(: Import the Websockets module :)import module namespace ws = "http://basex.org/modules/Websocketws";

%ws:message("'/"', "'{$message}"')

$message as xs:string

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>map { 'message': $path-first-client message }</path> </json> ) return ws:emit($responsemessage)

* First of all, import the websocket This module* The annotation <code>$ws:message("/",{$message}")</code> gets called if a message arrives at the server (checkout [[WebSockets]] for further information)was introduced with Version 9.* With <code>ws:ids()</code> you will get the ids of all connected clients1.* The function <code>ws:send($message,$first-client-id)</code> sends the <code>$message</code> to the client with the id <code>$first-client-id</code>* <code>ws: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>ws:emit($response)</code>