6. – API and Plug-In

6.1 – Reporting API (query server status, client side JavaScript API)

Include "gateway.js" in your web page:

var gw = new Gateway("192.168.9.118");

gw.login("password");
gw.report(); //output to console
gw.report(callback); //output to callback method
gw.checkLicense(callback2); //check license status

function callback(obj) {
  if (obj.error) {
    console.log("Error on getting report:" + obj.error);
    return;
  }
  var c, cs = obj.connections;
  var len = cs.length;
  console.log("\nTotal connections:" + len);
  for ( var i = 0; i < len; i++) {
    c = cs[i];
    console.log("connection " + i + " ------");
    console.log("clientIp: " + c.clientIp);
    console.log("clientAgent: " + c.clientAgent);
    console.log("server: " + c.server);
    console.log("startTime: " + c.startTime);
  }
}

We also have a Java command line tool available for the same purpose. Please download it from our website.

We also have WebSocket client available which can be used to communicate with our gateway or other WebSocket servers.

6.2 – RDP library (client side JavaScript API)

6.2.1 – RDP parameters

Parameter                                                                                                                                        Value
gateway BindString, address and listening port of the gateway.
For example: 192.168.0.8:443
server String, address of the RDP host.
port Integer, RDP listening port. Optional, default is 3389
user String, user name (Windows User).
pwd String, password for user name.
domain String, domain name
keyboard Integer, keyboard layout, default is 0x409 (US)
useConsole Boolean, connecting to console session/Admin mode. Default is false.
legacyMode Boolean, connecting to xrdp or VirtualBox RDP
width Integer, screen width of RDP session. Default is 800
height Integer, screen height of RDP session. Default is 600
server_bpp Integer, color depth of RDP session. Default is 16
playSound Integer, Default is 1: Do not play sound; 0: bring sound to local; 2: leave sound on remote computer.
startProgram String, "shell": start a program on connection; "app": start a RemoteApp
command Command for “Start a program on connection (startProgram=shell)”
directory Directory for running command (startProgram=shell)
exe Program or file for RemoteApp (startProgram=app)
args Arguments for RemoteApp (startProgram=app)
background Boolean, default is false, disable background.
smoothfont Boolean, default is false, disable font smoothing.
contents Boolean, default is false, disable full windows drag.
animation Boolean, default is false, disable menu animations.
composition Boolean, default is false, disable desktop composition.
styles Boolean, default is false, disable theming.
mapClipboard Boolean, default is false, disable clipboard rediretioin.
mapPrinter Boolean, default is false, disable printer redirection.
mapDisk Boolean, default is false, disable disk redirection.
touchpad Boolean, default is false, touchpad mode (relative mouse movement, touch interface only).
waWidth Work area width for RemoteApp, Default value is the screen width. You may want to change it if you display app in a iframe.
waHeight Work area height for RemoteApp. Default value is the screen height. You may want to change it if you display app in a iframe.
printer Printer name. You can specify multiple printer names by using “;” as seperator, e.g. “Printer1;Printer2”. The first one will always be the default printer.
useSSL Use WSS (WebSocket secure connection), only used by Rdp2 class.
timezone The client time zone name. Please check the values you can use in rdp.html
loadBalanceInfo Load balance information
vmid Hyper-V VM GUID, For example: B3D5444C-2611-405A-9CA0-7AA8DA94DF0B, it’s for Hyper-V console connection.
minWidth Minimum width, some applications can only work on a minimum resolution
minHeight Minimum height, some applications can only work on a minimum resolution
connectType Connecting type:

CONNECTION_TYPE_MODEM 1
Modem (56 Kbps)

CONNECTION_TYPE_BROADBAND_LOW 2
Low-speed broadband (256 Kbps - 2 Mbps)

CONNECTION_TYPE_SATELLITE 3
Satellite (2 Mbps - 16 Mbps with high latency)

CONNECTION_TYPE_BROADBAND_HIGH 4
High-speed broadband (2 Mbps - 10 Mbps)

CONNECTION_TYPE_WAN 5
WAN (10 Mbps or higher with high latency)

CONNECTION_TYPE_LAN 6
LAN (10 Mbps or higher)

Default value is 5.
shareClipboardId Connections will same shareClipboardId will use shared clipboard on gateway. User can copy anything among these connections
shareClipboard on: enabled shared clipboard, it’s enabled by default if mapClipboard is on.
symlink Id of the created symlink.
sessionRecord 0: no session recording, 1: recording grphic only (no sound), 3 means recording graphic and sound. This can only be configured in pluign
__record_name Recording file name. This can only be configured in pluign before version 4.8.8.
recording on: record session on client side
audioRecord on: enable remote audio recording
pingInterval Seconds for ping
soundPref 0: low quality sound; 1: high quality sound
smartcard on: enable smart card redirection
passwordIsPin Use password as the pin of smart card
name Show the name on the cursor on joined users
mac Computer MAC address for Wake on LAN. Need to enable it in gateway.conf (timeoutWoL)
macIP Network broadcast ip address for WoL.
decompressingRDP61 Enable RDP6.1 compression.
portCheckTimes Gateway will check if the port is open before connecting
portCheckInterval Interval of checking open port in ms.
copyToLocal on: user can copy data to local from remote. It can be used to disable bi-directional copy/paste
copyToRemote on: user can copy data to remote from local. It can be used to disable bi-directional copy/paste
copyTextOnly on: user can only copy plain text.
textPrinter on: redirect a text only printer (for receipts, label printers)
mapCamera Boolean, default is false, enable webcam redirection. Enable it in RDP server with Group Policy: Computer Configuration > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Device and Resource Redirection > Do not allow supported Plug and Play device redirection: Disabled
scanner Boolean, default is false, enable scanner redirection.

6.2.2 – Passing parameters via URL (Connection String)

URL components

❗️ Important

Please use "on" and "off" for Boolean value if you are using URL to pass parameters.

Basically, a RDP connection string consists of the following main components:

[protocol]://[domain]/rdpdirect.html?[parameters]

The parameters are the same as the parameters that can be set in servers.json for each target system. Please note the correct URL encoding (see below)! Link paramters with the ampersand (&). A parameters list can be found here.

Some example parameters can be:

&keyboard=1031
&fullBrowser=Full%20browser
&fullScreen=Full%20screen
&server_bpp=16
&timezone=W.%20Europe%20Standard%20Time
&playSound=0
&soundPref=0
&mapClipboard=on
&mapPrinter=on
&mapDisk=on
&startProgram=noapp
&smoothfont=on

The correct URL encoding:

If characters are to be transmitted as values that have special meaning in the context of a URL, they must be encoded.
Example: name=SparkView Server becomes name=SparkView%20Server.

For correct encoding, an online tool can also be applied for help: https://meyerweb.com/eric/tools/dencoder/.

Example connection string:

A minimal connection string can look like this:

https://mygateway.com/rdpdirect.html?server=192.168.12.55&port=3389&gateway=mygateway.com

Connecting to desktop

var parameters = "server=192.168.0.2&user=admin&pwd=" + encodeURIComponent("&=@#");
//use encodeURIComponent to escape special characters in value
var width = 800, height = 600, server_bpp = 16;
varr = new svGlobal.Rdp("http://" + gateway + "/RDP?" + parameters, width, height, server_bpp);
r.addSurface(new svGlobal.LocalInterface());
r.run();

Connecting to RemoteApp in current window

You only need to add some extra parameters:

parameters += encodeURIComponent("startProgram=app&exe=||EXCEL");

Connecting to RemoteApp in a new window

varparameters = "server=192.168.0.2&user=admin&pwd=" + encodeURIComponent("&=@#");
//use encodeURIComponent to escape special characters in value
parameters += encodeURIComponent("startProgram=app&exe=||EXCEL");
var width = 800, height = 600, server_bpp = 16;
var r = svManager.getInstance(); //try use the existed session.
if (r == null){
  r = new svGlobal.Rdp(protocol + gw + "/RDP?" + s, width, height, server_bpp);
}
var rail = window.open("rail.html");
function onSurfaceReady(surface){
  r.addSurface(surface);
  r.startApp(frmConn["exe"].value, frmConn["args"].value, "");
};
rail.svOnSurfaceReady = onSurfaceReady;
r.run();

6.2.3 – Passing parameter via object or cookie

Rdp2 class can be used to replace Rdp class. You can pass a object to Rdp2:

varobj = {gateway: "192.168.0.2", server:"192.168.0.8", user: "user"};
var r = new svGlobal.Rdp2(obj);

Rdp2 class will create an object from cookies if obj is undefined. If value of the document.cookie is "gateway=192.168.0.2;server=192.168.0.8;user=user", Rdp2 will create a object automatically for connection.

6.2.4 – Usage of RDP class

Properties:

Name                                                                               Type                           Description
appTimeout Int Close the RemoteApp if no Windows found after this period, default is 800 ms.
displayMsg Boolean If display error or warning message, default is true
reconnectOnResize Boolean If reconnect when resize the browser window, default is true
reconnectTimes Int Automatically reconnecting time,default 0.
sessionTimeout Int Close the session disconnection if no RemoteApp running after this period. Default value is 3000 (3 seconds). You may want to make it longer, so user can use the current session for new RemoteApp.
windowState Int State of RemoteApp main window, 3: always maximized, 0: controlled by user
openLink Boolean Display a web link button when user copy a web link in remote computer, default is true
sessionInfo Object Current session information. Including following properties: sessionId, userName, domain etc.
remoteAppLogin Boolean If display login details when using RemoteApp, default is true
setTitle Boolean If allow client to change browser title, default is true, the browser title will be set as the RDP host name.

Methods:

Name                                                                                                                                                                                                                                                                                                                                                                                                   Description
close() Close current RDP session
exeAppCmd(cmd) Execute command on current RemoteApp, cmd (Int) values:
0xF020: Minimize the window
0xF030: Maximize the window
0xF060: Close the window
0xF100: Display the windo’s system menu
0xF120: Restore the window
mouseDown(x, y, button) Send mouse down to RDP host. X, Y: mouse position, button: which button, same as event.button.
mouseUp(x, y, button) Send mouse up to RDP host.
mouseMove(x, y) Send mouse move to RDP host.
pauseSession(numericId, pause) Pause a session output, pause: true or false. Pause all joined sessions if numericId is 0
running() Check if connected to a RDP session
setAudioBuffer(seconds) Audio buffer size, default is 2.0 seconds
writeKeyCode(down, keyCode) Send browser keyCode to RDP host. “down”: Boolean
writeText(txt, interval, doneCallback) Send Unicode to RDP host. RDP server could ignore some characters if the client is sending them too fast. Please use the optional interval and call back arguments.
writeRawInput(input) Send raw keyboard, mouse events to RDP host. Please use
onactivity event to get the raw input events.
writeKeyComb(keys, interval, doneCallback) Write any key combinations like “Ctrl+Alt+Del”. if interval > 0, every key stroke (down or up) will be sent with delay.
notify(message, sessionIDArray) Send message to other session. sessionIDArray is optional. If sessionIDArray is not given, this will send message to all other joined and main session. If sessionIDArray is provided, it will send message to sessions with the given ID. For example: [id1, id2, id3]. The id can be the 9 digit number id or the GUID.
saveSession(info) This will leave the session open on the gateway, so you can connect to it later from same or different device. For example: saveSession({save: true, timeout:5, id: xxxx}) will leave the session open for 5 minutes on gateway with id xxxx. You can connect to this cached session with the given id. Please check 3.14 for more information about cached session. You can also use plugin to save session. This feature will be disabled if savedSessionTimeout in gateway.conf is 0.
startPing(interval, noResponTime) Start to ping the gateway when the session is idle. Interval: seconds. noResponTime: seconds, time limit for no response. onnoresponse event will be fired if this value reached, default is 0 will never fire onnoresponse event.
setJoinMode(mode) 0: Every one can control; 1: Only one can control; 2: Only one can control (others can move mouse)
setJoinCloseMode(mode) 0: close all joined sessions after initiated session is closed; 1: leave all joined sessions open even initiated session is closed.
writeClipboard(text, type) dp.writeClipboard('Plain text');
rdp.writeClipboard('<h>Header</h>', 'text/html');
var reader = new FileReader();
reader.onloadend = function (e) {
if (e.target.readyState == FileReader.DONE) {
var imgB64 = hi5.Base64.enc(new Uint8Array(e.target.result));
rdp.writeClipboard(imgB64, 'image/png');
}
};
reader.readAsArrayBuffer(blob);
sendKeyboardSynchronize(scroll, numlock, capital) Turn off/on lock key state on remote computer.

Events:

Name                                                                                         Description
onclose(expected) Fired when RDP session is closed. Expected is true if the session is closed by user (log off) or administrators. Please be aware, the Rdp object will be released and cannot be reused after this event.
onerror(error) Fired on an error. Use error.name, error.message to get error details.
onloggedin() Fired when user logged in (It's not supported by xRDP and VirtualBox RDP)
beforeupload(file, path) Fired before uploading a file:

file: File object
path: file absolute path or name if path cannot be obtained.

Return true if it's processed and prevent default behavior happening.
onfileuploaded(fileName) Fired after a file was uploaded
onuploaded() Fired after all files were uploaded
onsessionjoin(appInfo) Fired when a new user joined the session. appInfo has following properties:

numericId: the 9 digit id
__ip: joined user’s hone name or ip address
name: if provided

Return true will override the default behavior.
onsessionexit(sessionInfo) Fired when a joined user existed the session.
Return true will override the default behavior.
ongivecontrol() Fired when current user can control the session.
Return true will override the default behavior.
ontakebackcontrol() Fired when current user cannot control the session anymore
onrequirecontrol() Fired when another require current user to control the session.
onremoteappstart(e) Fired after a RemoteApp was started, you can get the RemoteApp id from e.id which is like:

{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\mspaint.exe
onactivity(input) Fired after a client activity was sent to the server (Mouse, keyboard events). Input (string) is the mouse and keyboard event. You can use writeRawInput to send them to the RDP host.
onurlredirection(URL) Fired when an URL was copied on remote computer
ontitlechange(title) Fired when client before change the browser title. You can return a new title in this event.
onsessionstart(sessionInfo) sessionInfo is same as the sessionInfo property
onservercopy(strValue) Fired when copying from remote to local. strValue is in “mimeType;value” format, for example: “text/plain;textCopied”.
onrequestcredential(info) Fired when wrong credential was given and credSSP is enabled on gateway). Return true will override the default behavior. Info object has following properties:

domain: server’s FQDN domain name
nbDomain: server’s NetBIOS domain name
nbComputer: server’s NetBIOS computer name
onprintingready(printJob) Return true will override the default behavior. printJob has following properties:

link: the PDF file link
printerName: target printer name
printerDriver: target printer driver name
onresolutionchange(width, height) Fired when resolution of RDP session changes.
onnoresponse() Need to be used with startPing(interval, missTimes)
onLockKeyState({"capsLock": capsLock, "numLock": numLock, "scrollLock": scrollLock)

6.2.5 – Extend RDP: Virtual Channel and Dynamic Virtual Channel

You can create multiple virtual channels and dynamic virtual channels on client side using JavaScript (you can only create one VC before 4.0):

var r = new svGlobal.Rdp(protocol + gw + "/RDP?"+ s, w, h, server_bpp);
var vc = new r.VirtualChannel(); //Use r.DynamicChannel to create a dynamic virtual channel
vc.name = "CUST";
vc.process = function(buffer){
  console.log(buffer.getByte());
  console.log(buffer.getLittleEndian16());
};
vc.onopen = function(){
  var data = new Array(7);
  var rb = new RdpBuffer(data, 0, 7);
  rb.setByte(1);
  rb.setLittleEndian16(345);
  rb.setLittleEndian32(567);
  rb.markEnd();
  vc.send(rb);
};
r.addChannel(vc);

Virtual Channel is used to communicate with RDP host. You also need to write a plugin for the RDP host. Please check followings for more information:

6.2.6 – Extend Gateway: Gateway Channel

You can create multiple gateway channels to create a communication layer between client browser and the gateway:

var gvc = new r.GatewayChannel();
gvc.name = "gwc";
gvc.process = function(buffer){
  console.log(buffer.getByte());
  console.log(buffer.getLittleEndian16());
};
gvc.onopen = function(){
  var data = new Array(7);
  var rb = new RdpBuffer(data, 0, 7);
  rb.setByte(3);
  rb.setLittleEndian16(45);
  rb.setLittleEndian32(678);
  rb.markEnd();
  gvc.send(rb);
};
r.addGatewayChannel(gvc);

On gateway side, you class must extend com.toremote.gateway.plugin.AbstractGatewayChannel and register it with the same name using HandlerManager.registerChannel(). Please check the plugin example for more information.

6.3 – Plug-ins (server side Java API)

Your plug-in must implement com.toremote.gateway.plugin.ManagerInterface. With the plugin, you can do authentication integration, session querying and reporting, RemoteApp management and RDP virtual channel extensions, player integration, new websocket protocol handler etc. Please download our plugin example project for more information:

http://www.remotespark.com/Plugin.zip

6.4 – HTTP Request API (server side)

You can use HTTP request to create server, symlink dynamically if you don't want to write a plug-in.

Create servers on gateway:

http://gatewayAddress/SERVER?id=serverId&displayName=Name&server=hostName&gatewayPwd=pas swordInGateway.conf&...

gatewayPwd is hexadecimal MD5 hash of the password which is configured in gateway.conf. Please check 5.2.1 for other parameters you can use.

http://gatewayAddress/SYMLINK?symlink=symlinkId&server=existingServerId&validTime=20m& gatewayPwd=passwordInGateway.conf&...

You can also use "validFrom", "validTo" parameters. Please check http://www.remotespark.com/view/doc/com/toremote/gateway/connection/SymLink.html for more information.

To delete a server or symlink, add "&action=delete" to the URL; To update a server or symlnk, add "&action=update" to the URL.

HTTP request will return status code 200 if operation succeeded, 500 if operation failed.

For more details, please check the Integration Guide.