RealityServer® Client

Class: Service

RS.Service

The Service class provides a WebSocket connection to RealityServer that allows the user to execute commands as well as stream rendered images from a render loop. This allows for push based image updates rather than the polling system required in HTTP.

new RS.Service ()

Creates the service class.

Extends

Members

RS.Service.supported static

Returns whether the service is supported or not. Web sockets are required and must be accessible either through window.WebSocket or by setting RS.Service.websocket

RS.Service.websocket WebSocket static

The WebSocket implementation to use. This will default to window.WebSocket if available. Otherwise the constructor of a W3C WebSocket API implementation must be set on this member, or an instance of such an object provided when calling RS.Service#connect.

connected_protocol_version

The protocol version negotiated with the connected RealityServer. This value is undefined if not currently connected.

connector_name String readonly

Returns the name of the current connector. The connector encapsulates the on-the-wire protocol used to process commands. Currently one connector is available WS which indicates that commands are processed using WebSocket requests.

debug_commands Boolean

Whether debug mode is used for the WebSocket protocol. When true commands and responses are sent in string mode (where possible) for easier debugging over the WebSocket connection. Defaults to false.

default_scope_name String

The name of the scope to execute commands in. By default the service executes all commands in the global scope. For convenience it is possible to change this default scope so it is not necessary to manually add use_scope commands to every call. Note this scope is only used for commands executed directly on the service. Commands executed on streams are executed in the scope of the underlying render loop.

The value undefined is used to represent the global scope.

The scope must already exist before being set.

log_commands Boolean

If set to true then events are emitted for each command execution providing details of the command request and response. Note that if enabled this will cause responses to be sent for every command, not just ones that specify the want_response flag. Also note that this is not meant as a replacement for the promise based response handling system but as a debug tool. Should not be enabled in production.

Methods

associate_scope (scope_name)Promise

Associates the given scope with this service connection. When the connection closes the scope will automatically be removed from RealityServer.

Name Type Description
scope_name String

The name of the scope to associate with the service.
Returns:
Type Description
Promise A promise that resolves when the scope has been associated or rejects on error.

close (code, reason)

Closes the WebSocket connection

Name Type Default Description
code Number 1000 optional

Code indicating the reason for closing the connection. Default value indicates normal closure
reason String User request optional

Explanation of why we are closing, must be less than 128 UTF8 bytes.
See:
Fires:

connect (url, extra_constructor_args)Promise

Connects to RealityServer and performs the initial handshake to ensure streaming functionality is available. Returns a Promise that resolves when connected. The promise will reject in the following circumstances:

  • Websockets are not supported
  • Creation of the WebSocket instance fails.
  • The RealityServer connection fails.
  • Invalid RealityServer handshake.
  • The connected RealityServer does not support the required WebSocket protocol version.
Name Type Default Description
url String | Object

If a string then the web service URL to connect to. Typically of the form ws[s]://HOST::PORT/service/. If not a string then must be an object that implements the W3C WebSocket API interface.
extra_constructor_args Array null optional

Extra list of arguments to be passed to the WebSocket constructor after the protocols parameter.
Returns:
Type Description
Promise A promise that resolves when the WebSocket is connected.

create_stream ()RS.Stream

Creates a stream that can be used to receive rendered images from a render loop. A single web socket connection can stream from multiple render loops simultaneously however a given render loop can only be streamed once over a given web socket. Returns a RS.Stream which can then have a stream started on it.

Returns:
Type Description
RS.Stream A stream instance

execute_command (command, options)Promise

Executes a single command and returns a Promise that resolves to an iterable. The iterable will contain a single result which will be the result of the command or a RS.Command_error.

The promise will reject in the following circumstances:

  • there is no WebSocket connection.
  • the WebSocket connection has not started (IE: RS.Service#connect has not yet resolved).
Name Type Description
command RS.Command

The command to execute.
options Object optional
Name Type Description
want_response Boolean optional

If true then the returned promise resolves to the response of the command. If false then the promise resolves immediately to undefined.
scope_name String optional

If provided then commands are executed in this scope. If not the default service scope is used.
longrunning Boolean optional

A hint as to whether the commands are expected to be long running or not. Long running commands are executed asynchronously on the server to ensure they do not tie up the web socket connection. Note this hint is only supported in protocol version 7 and above (RealityServer 6.2 3938.141 or later). See "Long running commands" in Concepts for more details.
Fires:
Returns:
Type Description
Promise A Promise that resolves to an iterable.

queue_commands (options)RS.Command_queue

Returns a RS.Command_queue that can be used to queue up a series of commands to be executed.

Name Type Description
options Object optional
Name Type Description
scope_name String optional

If provided then commands are executed in this scope. If not the default service scope is used.
longrunning Boolean optional

A hint as to whether the commands are expected to be long running or not. Long running commands are executed asynchronously on the server to ensure they do not tie up the web socket connection. Note this hint is only supported in protocol version 7 and above (RealityServer 6.2 3938.141 or later). See "Long running commands" in Concepts for more details.
Returns:
Type Description
RS.Command_queue The command queue to add commands to and then execute.

send_command (command, options)Array.<Promise>

Sends a single command and returns an Array of Promises that will resolve with the responses. The array will contain up to 1 Promise.

  • if want_response is true then the first Promise will resolve to the result of the command or a RS.Command_error.
  • otherwise the array will be empty.
Name Type Description
command RS.Command

The command to execute.
options Object optional
Name Type Description
want_response Boolean optional

If true then the reponses promise resolves to the response of the command. If false then the promise resolves immediately to undefined.
scope_name String optional

If provided then commands are executed in this scope. If not the default service scope is used.
longrunning Boolean optional

A hint as to whether the commands are expected to be long running or not. Long running commands are executed asynchronously on the server to ensure they do not tie up the web socket connection. Note this hint is only supported in protocol version 7 and above (RealityServer 6.2 3938.141 or later). See "Long running commands" in Concepts for more details.
Fires:
Throws:

This call will throw an error in the following circumstances:

  • there is no WebSocket connection.
  • the WebSocket connection has not started (IE: RS.Service#connect has not yet resolved).
Type
RS.Error
Returns:
Type Description
Array.<Promise> An Array of Promises. These promises will not reject.

set_max_rate (max_rate)Promise

Sets the maximum transfer rate for this stream. Manually setting a maximum rate will be enforced on the server side so a stream will not generate more than the given amount of bandwidth. Automatic rate control will attempt to fill the available bandwidth, but not flood the connection. Note that even if a manual rate is set flood control will still be enabled so setting a max rate larger than the available bandwidth will not overwhelm the connection. Rate control is implemented using frame dropping rather than adjusting image compression settings.

The returned promise will reject in the following circumstances:

  • there is no WebSocket connection.
  • the WebSocket connection has not started (IE: RS.Service#connect has not yet resolved).
  • Setting the max rate failed.
Name Type Description
max_rate Number

The maximum rate in bytes per second. Set to 0 to use automatic rate control (the default) or -1 to disable rate control entirely.
Returns:
Type Description
Promise A promise that resolves when the max rate has been set.

streaming (render_loop_name)Boolean

Returns true if we are currently streaming the given render loop.

Name Type Description
render_loop_name String

The name of the render loop to check.
Returns:
Type Description
Boolean true if streaming, false if not or unknown.

Type Definitions

Progress_data Object

Data emitted when progress has been made during command execution.

Properties:
Name Type Description
id String

The id registered when the command was executed.
value Number

0 to 100 value indicating progress.
area String

The area of execution the command is currently in.
message String

A message associated with the progress event.

Events

close

Close event.

Emitted when the web socket connection is closed.

Name Type Description
event CloseEvent

The underlying WebSocket close event. See https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent

command_requests

Command request event.

Emitted when command requests are sent and RS.Service#log_commands is enabled.

Name Type Description
event Object

The request event.

Name Type Description
id Number

The request ID. There will be a corresponding RS.Service#event:command_results event emitted with this ID.
commands Array

The commands to be executed, note this will include any commands prepended by the service for scope management.
render_loop_name String optional

If these commands are to be executed on a stream then the name of ther render loop associated with the stream.

command_results

Command response event.

Emitted when command responses are received and RS.Service#log_commands is enabled.

Name Type Description
event Object

The response event.

Name Type Description
id Number

The request ID that these responses are for.
results Array

The command results, note this will include results for any prepended scope commands.
commands Array

The commands these results are for.
render_loop_name String optional

If these commands were executed on a stream then the name of ther render loop associated with the stream.

error

Error event.

Emitted when the web socket connection encounters an error.

Name Type Description
event Event

The underlying WebSocket error event. See https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/onerror

open

Open event.

Emitted when the web socket connection is opened.

Name Type Description
event Event

The underlying WebSocket open event. See https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/onopen

progress

Progress event.

Fired whenever a command has completed some measure of progress. This event will be fired on RS.Service for all streams.

Name Type Description
progress RS.Service~Progress_data

The command progress data