Difference between revisions of "WebSocket Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 20: Line 20:
 
|-
 
|-
 
| '''Summary'''
 
| '''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>
+
|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>
 
|}
 
|}
  
Line 31: Line 31:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Broadcasts <code>message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected clients except to the caller.  
+
|Broadcasts <code>$message</code> which may be of type xs:string, xs:base64Binary, or xs:hexBinary to all connected clients except to the caller.  
 
|}
 
|}
  
Line 53: Line 53:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the ID of the current client WebSocket connection.
+
|Returns the ID of the current WebSocket client.
 
|}
 
|}
  
Line 64: Line 64:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the IDs of all current WebSocket connections.
+
|Returns the ids of all currently registered WebSocket client.
 
|}
 
|}
  
Line 72: Line 72:
 
|-
 
|-
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|ws:path||xs:string}}
+
|{{Func|ws:path||xs:string}}<br>{{Func|ws:path|$id as xs:string|xs:string}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the path of the current WebSocketClient.
+
|Returns the path of the current WebSocket client, or the client with the specified {{Code|$id}}.
|}
 
 
 
==ws:path==
 
 
 
{| width='100%'
 
|-
 
| width='120' | '''Signatures'''
 
|{{Func|ws:path|$id as xs:string|xs:string}}
 
|-
 
| '''Summary'''
 
|Returns the path of specific user with the ID <code>$id</code>.
 
 
|}
 
|}
  
Line 94: Line 83:
  
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
module namespace websocketexample = 'http://basex.org/modules/web-page';
 
 
(: Import the WebSocket module :)
 
(: Import the WebSocket module :)
 
import module namespace ws = "http://basex.org/modules/Websocket";
 
import module namespace ws = "http://basex.org/modules/Websocket";
Line 100: Line 88:
 
declare
 
declare
 
   %ws:connect("/")
 
   %ws:connect("/")
  function websocketexample:connect(
+
function local:connect(
) {
+
) as empty-sequence() {
 
   let $client-id := ws:id()
 
   let $client-id := ws:id()
 
   let $client-path := ws:path()
 
   let $client-path := ws:path()
Line 132: Line 120:
  
 
declare
 
declare
   %ws:message("/","{$message}")
+
   %ws:message("/", "{$message}")
 
function local:message(
 
function local:message(
 
   $message  as xs:string
 
   $message  as xs:string
) as xs:string {
+
) as empty-sequence() {
 
   let $client-ids := ws:ids()
 
   let $client-ids := ws:ids()
 
   let $fist-client-id := fn:head($client-ids)
 
   let $fist-client-id := fn:head($client-ids)

Revision as of 19:42, 13 August 2018

This XQuery Module contains functions for accessing specific WebSocket functions. This module is mainly useful in the context of WebSockets.

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 ws = "http://basex.org/modules/Websocket";
...

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 user(s) with the ID(s) $ids

ws:broadcast

Signatures ws: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.

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 client.

ws:path

Signatures ws:path() as xs:string
ws:path($id as xs:string) as xs:string
Summary Returns the path of the current WebSocket client, or the client with the specified $id.

Example 1

Code

(: Import the WebSocket module :)
import module namespace ws = "http://basex.org/modules/Websocket";

declare
  %ws:connect("/")
function local:connect(
) as empty-sequence() {
  let $client-id := ws:id()
  let $client-path := ws:path()
  let $response := json:serialize(
    <json type="object">
      <messageType>UserConnected</messageType>
      <clientId>{$client-id}</clientId>
      <clientPath>{$client-path}</clientPath>
    </json>
  )
  return ws: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 the client-path with ws:id() and ws:path()
  • Create a json-result
  • Broadcast the result to all connected clients without the calling client

Example 2

Code

(: Import the Websockets module :)
import module namespace ws = "http://basex.org/modules/Websocket";

declare
  %ws:message("/", "{$message}")
function local:message(
  $message  as xs:string
) as empty-sequence() {
  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>{ $path-first-client }</path>
    </json>
  ) 
  return ws: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 ws:ids() you will get the ids of all connected clients.
  • The function ws:send($message,$first-client-id) sends the $message to the client with the id $first-client-id
  • ws: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 ws:emit($response)