Difference between revisions of "WebSocket Module"

From BaseX Documentation
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 client.
+
|Returns the ID of the current WebSocket.
 
|}
 
|}
  
Line 32: Line 32:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the ids of all currently registered WebSocket clients.
+
|Returns the ids of all currently registered WebSocket.
 
|}
 
|}
  
Line 43: Line 43:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns the path of the WebSocket client with the specified {{Code|$id}}.
+
|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:close==
+
=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:close|$id as xs:string|empty-sequence()}}
+
|{{Func|ws:delete|$id as xs:string, $name as xs:string|empty-sequence()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Closes the connection of the WebSocket client with the specified {{Code|$id}}.
+
|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 12:15, 27 September 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/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.