Web Services API
The Web Services API is intended to allow external applications to access and manipulate some of Thinfinity® Remote Desktop Server data and settings.
Thinfinity® Remote Desktop Server has two different Web Services available:
a. Profiles Web Service:
If you need to manipulate Thinfinity® Remote Desktop Server users and their permissions from an external software application, you can use the Profiles Web Services to perform this task. If you don't know how to use the Access Profiles feature, take a look at the section that explains it's use and behavior.
b. Analytics Web Service:
The Thinfinity® Remote Desktop Server Analytics feature is included since version 2.0.0.16. This feature keeps statistic data of Thinfinity® Remote Desktop Server logins, sessions, connections and used browsers. The Analytics Web Service allows external applications to access these information.
Requirements for the Web Service API:
The integration has to be done at a programming level. You will need to develop or modify an application which will act as the Web Service requester and this application will have to implement the Thinfinity® Remote Desktop Server Web Service interface.
Architecture
The Thinfinity® Remote Desktop Server Web Service architecture is illustrated in the image below:
The "i" symbol represents the interface that should be used by the third-party application in order to make use of the Web Service. The interface is provided by Thinfinity® Remote Desktop Server on the following address, once the Web Service is installed:
https://ThinfinityRDPWebServiceIP:port/IWSThinRDP/wsd
Installing the Web Service
The first step to start developing the integration with Thinfinity® Remote Desktop Server Web Service API is to install it:
1. Download the installer from the link below:
http://www.cybelesoft.com/download/
2. Execute the installer on the same machine where Thinfinity® Remote Desktop Server is installed.
3. Besides installing the Web Service, the installer will also:
I. Set up a service on Windows, so the Web Service will be started every time Windows is turned on.
* If you do not want the Web Service to start automatically with Windows, change the "Startup type" to "Manual".
II. Create a shortcut for the "WebService Admin tool"
III. Create a shortcut for the "Demos" applications directory. These are the three example applications that should illustrate the Web Service use.
Setting up the Communication Settings
Setting up the Communication Settings
Open the "WebService Admin Tool" from the Windows start menu.
General tab:
1. By default, the WebService listens to HTTP and port 8444.
4. You can change this
Authorized IPs tab:
1. Go to the "Autorized IPs" tab.
2. If you don't want to restrict the IP addresses that will access the Web Service, leave the list empty.
3. If you want only determined IPs to access the Web Service, click on "Add" and and add the IPs separated by semicolons.
1. Substiture a byte by the "*" symbol to select all existing IP addresses from that byte on.
2. Substitute a byte by the "?" symbol, to select all combinations inside this octet.
Profiles Web Service
The Access Profiles Web Service integration allows external applications to:
1. Retrieve any information from the profiles configured in Thinfinity® Remote Desktop Server
2. Create new profiles
3. Delete existing profiles
4. Modify any information on an existing profile
The Web Service Transaction Manager, also available, enables you to execute a series of operations as a single unit of work. The Transaction Manager will guarantee that the series of operations will either be executed all together, or not executed at all.
Methods
The main goal of this Web Service is to manipulate the Access Profiles set up. The following methods are available for that purpose. By combining these methods, you will be able to perform pretty much any task regarding the profiles set up.
Method name
Method description
Input params
Output params
Exceptions
GetAllProfiles
Retrieves all the existing profiles.
all existing profiles from Thinfinity® Remote Desktop Server
If there are no profiles yet, returns a WSProfileArray with length = 0.
GetProfileCount
Counts how many profiles exist.
integer:
profiles count
GetProfile
Returns a profile located on a determined index.
integer:
profile index
profile located on the informed index.
If there is no profile on the indicated index, returns null.
FindByID
Returns the profile that has the indicated ID.
string:
profile ID
profile that has the informed ID.
If there is no profile that has the indicated ID, returns null.
FindByComputer
Returns all profiles associated with a computer.
string:
computer IP
profiles associated with the informed computer.
If there are no profiles associated with the computer, returns a WSProfileArray with length = 0.
FindByUserName
Returns all profiles assigned to the user.
string:
username
user granted profiles.
If there is are no profiles associated with the user, returns a WSProfileArray with length = 0.
CreateProfile
Creates a new profile.
profile to be created
created profile carrying the new generated ID and public Key.
If the profile could not be created, returns null.
DeleteProfile
Deletes an existing profile.
string:
profile ID
boolean:
returns true if the deletion was successful and false if the application could not delete the profile.
If there is no profile with the indicated ID, returns false.
UpdateProfile
Updates an existing profile.
profile to be updated with the new data already loaded in its structure.
int:
returns 0 if the profile was updated successfully. Any value different from 0 means the update could not be performed.
If there is no profile matching the WSProfile ID, returns a value <> 0.
NewPublicKey
Generates a new public key for an existing profile.
string:
profile ID
profile carrying the new Public Key.
If there is no profile matching the WSProfile ID, returns null.
Commit
Commits all the performed methods since the last commit or rollback.
Rollback
Rollbacks all the performed methods since the last commit or rollback.
Types
As you have already probably seen on the Methods sections, the WSProfile and the WSProfileArray type are sent and received as parameters of many methods. Here, you can learn what are these types and how to manage them.
Type name
Kind
Description
Value range
Complex
The WSProfile type represents one profile.
It has all the attributes that describe a profile.
WSProfileArray
Complex
The WSProfileArray is an array of WSProfile. It is used mostly as a parameter for methods that retrieve more than one profile from the server.
TRdpCredentials
Simple
This type is used to describe the kind of authentication the WSProfile will perform. "crAuthenticated" means no username and password will be required. "crAsk" will use the username and password configured inside the profile. When "crSaved" is set up, the profile will authenticate automatically using the same application credentials.
"crAuthenticated"
"crAsk"
"crSaved"
TRdpScreenBPP
Simple
Color Depth: sets the WSProfile remote desktop screen number of bits per pixel .
Set "bpp8" for 256 colors; "bpp15" for True Color (15 bit); "bpp16" for True Color (16 bit) ; "bpp24" for True Color (24 bit) ; "bpp32" for True Color (32 bit)
"bpp8",
"bpp15",
"bpp16",
"bpp24",
"bpp32"
TRdpScreenResolution
Simple
WSProfile remote desktop screen resolution.
"srCustom",
"srFitToBrowser",
"srFitToScreen",
"sr640x480",
"sr800x600",
"sr1024x768",
"sr1280x720",
"sr1280x768",
"sr1280x1024",
"sr1440x900",
"sr1440x1050",
"sr1600x1200",
"sr1680x1050",
"sr1920x1080",
"sr1920x1200"
TRdpImageQuality
Simple
WSProfile remote desktop image quality.
"iqHighest",
"iqOptimal",
"iqGood",
"iqFaster"
TRdpAppMode
Simple
The application mode is used to determine if Thinfinity® Remote Desktop Server will open a specific application and the mode it will use to do it.
The "amNone" value will show the whole desktop mode. The "StartApp" and "RemoteApp" are the two possible modes of connecting to a remote application.
"amNone",
"amStartApp",
"amRemoteApp"
TRdpSoundQuality
Simple
This type is used to describe the different sound qualities that Thinfinity® Remote Desktop Server works with.
"sqPoor"
"sqGood"
"sqOptimal"
"sqExcellent"
The WS Profile type
The WSProfile type
The complex WSProfile type represents a profile and carries all its information. In order to retrieve, create, delete and update the Thinfinity® Remote Desktop Server profiles, you will have to manipulate this WSProfile data structure.
Attribute name
Type
Description
Modifiable
ID
string
Profile ID
no
Name
string
Profile name
yes
Enabled
boolean
Set false if you want the profile to be disabled
yes
Unrestricted
boolean
Only the [any computer] profile has this property set to true. It means that the profile will enable the users to choose the computer they will access entering the IP, port and credentials on the connection moment.
no
GuestAllowed
boolean
Set true to make the profile public
yes
IsBuiltIn
boolean
This attribute identifies the [any computer] profile. Only this profile has this attribute set to true.
no
PublicKey
string
Key that identifies a profile .
no
Computer
string
The remote desktop IP and port to connect to
yes
Credentials
Configures the credential mode Thinfinity® Remote Desktop Server will operate on.
yes
LogonUserName
string
If the credential mode is set to "crAsk", will use this Username to log in into the computer.
yes
LogonPassword
string
If the credential mode is set to "crAsk", will use this Password to log in into the computer.
yes
ScreenWidth
int
Remote desktop screen width.
yes
ScreenHeight
int
Remote desktop screen height.
yes
UnicodeKbd
boolean
Allows for full unicode keyboard charsets. Set to false to connect to xRDP servers.
yes
ConsoleSession
boolean
Set to true to connect to the console session. This requires confirmation from the logged on user and will log out the current session.
yes
WebsocketCompression
boolean
Set to true to enable the compression for the exchanged Websocket data and have the application performance improved.
yes
RelativeMouseTouch
boolean
For mobile devices. Uncheck this option to have a mouse behaviour similar to a desktop mouse in which the cursor will always be positioned under the touch. Leave as true to use relative mouse like a trackpad.
yes
AppMode
Application Mode: sets whether the profile should connect to a specific application
yes
AppCmdLine
string
Specify the complete path to give access the application you want to start upon connection.
yes
AppCmdArgs
string
Arguments to start the application informed on the AppCmdLine field.
yes
AppWorkDir
string
Mark this option if you need to specify a context directory for the program set on the field "Program path and file name"
yes
DesktopBackground
boolean
Set to true to show the original remote desktop background.
yes
VisualStyles
boolean
Set to true to change the Start menu and other Windows features styles.
yes
MenuAnimation
boolean
Set to true to show an animation on the Start menu.
yes
FontSmoothing
boolean
Set to true to make text easier to read, especially the magnified text.
yes
ShowWindowOnDrag
boolean
Set to true to show windows content while dragging them.
yes
DesktopComposition
boolean
Set true to configure the DWM to redirected the desktop drawing to off-screen surfaces in video memory. Also, the desktop will present many visual effects.
yes
PrinterEnabled
boolean
Uncheck this option to disable Thinfinity® Remote Desktop Server PDF printer.
yes
PrinterSetAsDefault
boolean
Mark this option to make Thinfinity® Remote Desktop Server printer the remote machine default printer.
yes
PrinterName
string
Specify the printer name that you want to be shown on the remote machine's printer list.
yes
PrinterDriver
string
This is the driver to be used by Thinfinity® Remote Desktop Server in order to print the remote documents.
The "HP Color LaserJet 2800 Series PS" driver is compatible with 2008 Windows versions. The "HP Color LaserJet 8500 PS" driver is compatible with 2003 Windows versions. If you are not using 2003 or 2008 Windows versions, look for a driver that is already installed on the OS and inform this driver name in this attribute.
yes
Clipboard
boolean
Enables and disables the remote desktop clipboard.
yes
DiskEnabled
boolean
Check this option to have an intermediate disk available on the connections created through this profile.
yes
DiskName
string
This is the name to identify the intermediate disk among the other remote desktop disks.
yes
DiskAutoDownload
boolean
If set to true, Thinfinity® Remote Desktop Server will automatically download any file saved/copied in the Intermediate disk direction.
yes
SoundEnabled
boolean
Check this option to enable the remote sound to be reproduced within the browser. The remote sound works only with Firefox and Chrome web browsers.
yes
SoundQuality
Determines what quality Thinfinity® Remote Desktop Server will use to reproduce the remote sound. The highest the quality, the more resources it will require.
yes
Users
string
Windows Authentication Users or Groups that will be granted access to this profile. Separate each user or group by semicolons.
yes
The Demo Applications
We have packed with the Thinfinity® Remote Desktop Server installation two example applications that use Thinfinity® Remote Desktop Server Web Service to manipulate Access Profiles.
If you have already installed Thinfinity® Remote Desktop Server WebService, you can access the demos from the Windows Start menu: All Programs/Thinfinity Remote Desktop Server/Thinfinity Remote Desktop Server Demos.
Both applications were developed in C# and were designed to present you the many integration possibilities the Web Service provides you.
In order to compile this application, you can use the Microsoft Visual C# Studio 2010 Express. Download it here.
ThinRDPWS application example:
This application teaches you how to integrate each WebService method available.
Observe that the Filter part uses the methods GetAllProfiles (none), FindByComputer and FindByUserName. The FindByID method is used every time a profile is selected and loaded on the screen visual components.
The CreateProfile method is also always available. After selecting one listed profile the DeleteProfile, UpdateProfile and NewPublicKey will also became available.
The whole data you have modified will only be confirmed through the Commit method. If you want to cancel and not confirm the modifications, use the rollback method.
ThinRDPWS-CRUD application example:
This example shows how to create profiles simply associating Users and Computers, without any other setup. Be aware that this example is not committing the changes, so the created profiles won't be available on your Thinfinity® Remote Desktop Server application, until you call the Commit method on the Web Service.
Analytics Web Service
The Analytics Web Service integration allows external applications to retrieve information regarding the system use: logins, sessions, connections and used browsers.
Methods
The main goal of this Web Service is to access the Statistics information related to the system usage. The following methods are available for this purpose.
Method name
Method description
Input params
Output params
Exceptions
Count
Returns an integer value with the count of the records that satisfy the search criteria sent on the QueryType parameter.
QueryType: WSQueryType
Integer
List
The list method returns an array containing all the records that satisfy the search criteria sent on the QueryType parameter.
QueryType: WSQueryType
If the search does not match any record, the result will be a WSDBRecordArray with length = 0.
RangeList
The RangeList method returns an array containing all the records that satisfy the search criteria sent on the QueryInfo parameter. The QueryInfo is composed by the QueryType and also a date range to filter the records (QueryRange).
QueryInfo: WSQueryInfo
If the search does not match any record, the result will be a WSDBRecordArray with length = 0.
LoginList
The LoginList method returns an array containing all the records that satisfy the search criteria which is composed by a QueryRange and the login type (successful logins and failed logins).
If the search does not match any record, the result will be a WSDBRecordArray with length = 0.
Types
As you have probably seen on the Methods sections, the Web Service uses specific types as input and output parameters. Here, you can learn what are these types and how to manage them.
Type name
Kind
Description
Value range
WSQueryType
Simple
The WSQueryType represents the available query types to be performed on the Web Service. The possible options are "qtSessions", "qtConnections" and "qtBrowsers".
"qtSessions"
"qtConnections"
"qtBrowsers"
Complex
This type is used to send a filter criteria to the server when running a search method. It is composed by the queryTypeField (WSQueryType) and the queryRangeField (WSQueryRange).
Complex
This type is used to send a date filter criteria to the server when running a search method. It is composed by the dateFromField and the dateToField.
WSDBRecord
Simple
This type is a generalization interface of all analytics record types (WSLoginRecord, WSDBSessionRecord, WSDBConnectionRecord and WSDBBrowserRecord).
WSDBRecordArray
Simple
An Array of WSDBRecord. It is used mostly as an output parameter for methods that retrieve more than one WSDBRecord from the server.
Complex
The WSDBConnectionRecord type describes how a Connection record is structured.
WSQueryInfo
The WSQueryInfo complex type is the query information sent within the RangeList method.
Attribute name
Type
Description
Modifiable
WSQueryRange
The WSQueryRange complex type is date range information to be send to a Analytics query.
Attribute name
Type
Description
Modifiable
dateFromField
dateTime
Lower dateTime limit from where the records should be searched.
yes
dateToField
dateTime
Upper dateTime limit until where the records should be searched.
yes
WSDBLoginRecord
The WSProfile complex type represents a profile and carries all its information. In order to retrieve, create, delete and update the Thinfinity® Remote Desktop Server profiles, you will have to manipulate this WSProfile data structure.
Attribute name
Type
Description
accessTimeField
string
The date and time in which the login was performed.
userField
string
The username that did the login.
sourceIPField
string
IP Address from which the login was initiated.
successfulField
Boolean
Boolean value that informs whether the login was successful or not.
WSSessionRecord
The WSDBSessionRecord type describes how a Session record is structured.
Attribute name
Type
Description
sessionIDField
integer
The Session ID.
userField
string
User that started the new session.
sourceIPField
string
IP Address from which the session was started.
connectedOnField
string
Date and time when the Session was Started
disconnectedOnField
string
Date and time when the Session was Ended
connectionsField
integer
Counter of Connections established within the Session.
WSDBConnectionRecord
The WSDBConnectionRecord type describes how a Connection record is structured.
Attribute name
Type
Description
userField
string
User that established the connection.
sourceIPField
string
IP Address from which the connection was established.
hostField
string
Host Name to which the connection was established.
connStartField
string
Date and time when the Connection was Started.
connEndField
string
Date and time when the Connection was Ended.
WSDBBrowserRecord
The WSDBSessionBrowser type describes how a Browser record is structured.
Attribute name
Type
Description
userAgentField
string
Browser User Agent.
sessionsField
integer
Counter of Sessions established within the Same Browser userAgent.
The Demo Application
We have packed —along with the Thinfinity® Remote Desktop Server installation— one example that uses Analytics Thinfinity Remote Desktop Server WebService to show the application usage data.
If you have already installed Thinfinity® Remote Desktop Server WebService, you can access the demos from the Windows Start menu All Programs/Thinfinity/Remote Desktop Server/Thinfinity Remote Desktop Server Demos.
The application was developed in C# and was designed to present you an integration possibility the Web Service provides you.
In order to compile this application, you can use the Microsoft Visual C# Studio 2010 Express. Download it here.
ThinRDPWS-Query application example:
This application is an example of an external application integrating each available Web Service method.
Observe that the upper radio buttons are different date ranges used to filter the statistic records.
Select one of the date options, go to a specific tab (Logins, Sessions, Connections or Browsers) and click on the Refresh button.
The analytics data will be displayed on the tab grid.
