Integrating iTap mobile RDP

Introduction

iTap mobile RDP can open and parse .rdp files containing connection settings. The basic format of .rdp files is specified here: Remote Desktop Protocol settings in Windows Server 2003 and in Windows XP

These .rdp file configurations can be loaded by opening a .rdp file with our client. But the better way is to use the URI scheme detailed below. It provides a way to only open up our client specifically and not another client which also knows .rdp files.

Examples:

  • itaprdp:http://my.server.com/path/to/file.rdp -> client loads http://my.server.com/path/to/file.rdp
  • itaprdp:https://my.server.com/path/to/file.rdp -> client loads https://my.server.com/path/to/file.rdp
  • itaprdp:http://user:pass@server/path/to/script.php -> user loads http://server/path/to/script.php with "user" and "pass" for http authentication (script.php should return the contents of the .rdp file)
  • http://my.server.com/path/to/file.rdp -> Android will show a dialog to launch iTap mobile RDP if the returned mime type is text/plain. If returned mime type is application/x-rdp Android will download the file which has to be opened manually.

Please note that the automatic download of .rdp files with the URL scheme handler does not show any login dialogs in case the source needs HTTP authentication. In these cases you must provide credentials as in the third example above or the download will fail.

Format

.rdp Files are text files. Currently iTap mobile RDP only supports UTF8 and UTF16 with BOM formats (and ASCII which is a subset of UTF8). All forms of line endings are supported. The content-type of the URL is ignored, but should be set to "text" with an encoding of UTF8.

Each line contains a single key-type-value triple. They are seperated by colons (:). All parts can contain spaces. Keys and types must not contain colons (:), but values may contain colons.

Example: "desktopwith:i:800"

This example contains the key "desktopwidth", the type "i" and the value "800"

The possible values for type are not specified by Microsoft, and the actual value is ignored by iTap mobile RDP. It must still be present however. It is recommended to use the values specified by Microsoft where possible, and otherwise use "i" for numeric values and "s" for strings.

Supported Keys

Of all the keys, only "full address" is needed. If this key is not present, the .RDP file will not load!

Microsoft compatible keys

Documented by Microsoft

The following keys are documented by Microsoft and supported by iTap mobile RDP:

  • screen mode id: integer, 0 and 1: windowed, 2: fullscreen; default: depends on platform, see below
    • iOS default: screen mode id is ignored, default resolution on iPhone/iPod touch: 800x600 and iPad: 1024x768, 32bpp
    • Android default: screen mode id default 1 (windowed), default resolution 800x600, if screen mode id 2 is specified session will go fullscreen
    • Mac default: screen mode id default 2 (fullscreen)
  • desktopwidth: width of the desktop
  • desktopheight: height of the desktop
  • session bpp: color depth of the desktop in bits per pixel (allowed=8,16,24,32, default=16)
  • full address: address of the server. May contain a port in host:port notation (default=none, must be present)
  • audiomode: where to play audio: 0=client, 1=server, 2=off (default=0)
  • username: username for login (default=none)
  • domain: domain for logon (default=none)
  • disable wallpaper: disable wallpaper (performance flag) (1=disable, 0=enable, default=0)
  • disable full window drag: disable showing window contents while dragging (performance flag) (1=disable, 0=enable, default=1)
  • disable menu anims: disable menu animations (performance flag) (1=disable, 0=enable, default=1)
  • disable themes: disable themes (performance flag) (1=disable, 0=enable, default=0)
  • alternate shell: name of executable to launch on login. This must be a full path (like "C:\Windows\notepad.exe") (default=none)
  • shell working directory: initial working directory for the "alternate shell" parameter (default=none)
  • remoteapplicationmode: whether RemoteApp (RAIL) should be launched/used (1=yes, 0=no, default=0)
  • remoteapplicationprogram: alias or executable name of RemoteApp (default=none)
  • remoteapplicationcmdline: optional command line parameters for RemoteApp (default=none)
  • use multimon: integer, detects all available monitors and mirrors the screen configuration to the client (if multiple monitors present, only works on Mac). 0: off 1: on; default: 0

Undocumented Keys

The following keys are not documented by Microsoft, but supported by both Microsoft's client and iTap mobile RDP:

  • gatewayhostname: address of TS Gateway server. May contain a port in host:port notation (default=none). You must purchase the TS Gateway extension to use this key.
  • gatewayusagemethod: type of gateway to use (0=do not use gateway, 1=use TS Gateway, default=0)
  • disable cursor setting: disable cursor effects (performance flag) (1=disable, 0=enable, default=0)
  • allow font smoothing: allow font antialiasing (performance flag) (1=enable, 0=disable, default=0)
  • allow desktop composition: allow desktop composition (performance flag) (1=enable, 0=disable, default=0)
  • authentication level: integer
    • 0: do not verify certificates, always connect
    • 1: verify certificates, deny connection on failure (requires TLS, will not fall back to non-TLS connections)
    • 2: verify certificates, ask user what to do on failure
    • on iOS the default is 2, and there is no UI setting to change it, since 0 is insecure and 1 is not usable on iOS for normal users. Android is probably like iOS, but qmote might want to make 1 the default (but is 2 right now), and add an option to bookmarks.

iTap mobile RDP specific Keys

The following keys are not supported by Microsoft clients, and are specific to iTap mobile RDP.

Generic keys common to all iTap mobile RDP clients

These keys are common to all iTap mobile RDP clients on all platforms.

  • itap console: connect to a console session (1=enable, 0=disable, default=0)
  • itap use proxy: use proxy for this connection (0=no, 1=yes, default=0)
    • Only available on Android and iOS!
  • itap max security level: highest security level to use (0=basic, 1=TLS, 2=NLA, default=2)
  • itap label: the label shown in the bookmark list for this connection (default=same as hostname)
  • itap password: the password for logon (default=none)
  • itap gateway username: username for gateway login (default=none). If this is not set, the normal username will be used for gateway authentication.
  • itap gateway domain: domain for gateway login (default=none). If this is not set, the normal username will be used for gateway authentication.
  • itap gateway password: password for gateway login (default=none). If this is not set, the normal username will be used for gateway authentication.
  • itap gateway authentication level: integer
    • 0: do not verify certificates, always connect
    • 1: verify certificates, deny connection on failure
    • 2: verify certificates, ask user what to do on failure
    • on iOS, Android and qmote the default is 2, and there is no UI setting to change it on iOS and Android, but on qmote. Since 0 is insecure and 1 is not usable on iOS for normal users the default is 2.
  • itap cacheID: a unique string identifying the bookmark (see below)
  • itap store bookmark: store the bookmark in the connection center (1=yes, 0=no, default=0)
    • OS X: always exported as 0
  • itap connection test: integer, 0: do not perform connection tests, 1: perform connection tests, only interesting for bookmarks stored with itap store bookmark:i:1
  • itap rail idle timeout: seconds to wait when RAIL desktop is idle before showing the idle screen; <= 0: use application default
    • Only available on Android and iOS!
  • itap high color fidelity: Higher visual quality in gradients and border cases, but uses much more bandwidth. 0: allow dynamic color fidelity in 32bit mode (default), 1: disable dynamic color fidelity by reporting no support on client.
    • Only available on Android and iOS!
  • itap welcome screen: URL of web page to show in a popup dialog after connection is established. Use itapaction:closeWelcome on that page to close the welcome view.
    • Only available on Android and iOS!

iOS specific extensions of iTap mobile RDP

These keys are iOS specific and may not be supported on other platforms.

  • itap mouse mode: the initial mouse mode (0=scope, 1=pointer, 2=draw, default=0)
  • itap mouse mode limit: comma separated integers, the list of allowed mouse modes (0=scope, 1=pointer, 2=draw, default=all allowed)
  • itap desktop manual: string, URL to load the desktop manual from. To use a file included in the distribution on the device, use "file://%@/some_file.html". If not given, defaults to "file://%@/manual_desktop.html". A fragment with the current mouse mode will be appended to the URL at runtime.
  • itap keyboard mode: the initial keyboard mode (0=Scancodes, 1=Smartmode, 2=Unicode, default=1)
  • itap border thickness: thickness of border around desktop to make tapping buttons at the edge easier (in pixels, default=0)
  • itap status bar: display device status bar during connection (0=no, 1=yes, default=0)
  • itap utility bar: initial state of the utility bar (0=off, 1=on, default=0)
  • itap swap mouse buttons: swap left and right mouse buttons (0=no, 1=yes, default=0)
  • itap scroll direction: scrolling direction and speed (1=iPad like scrolling, -1=Windows like scrolling, default= use setting from settings app, other numbers can be used to multiply scroll speed (i.e.: 2.0 is iPad like scrolling, twice as fast))
  • itap remember zoom: integer; remember zoom from last session or always start with desktop fully zoomed out; 0: don't remember (always zoom out), 1: remember last used zoom and position; default: 1
  • itap 3g mode: enable 3G mode (1=enable, 0=disable, default=1)
  • itap 3g width: width of the desktop in 3g mode (default=same as desktopwidth)
  • itap 3g height: height of the desktop (default=same as desktopheight)
  • itap 3g bpp: color depth of the desktop in 3g mode (allowed=8,16,24,32 default=8)
  • itap 3g disable wallpaper: disable wallpaper in 3g mode (performance flag) (1=disable, 0=enable, default=1)
  • itap 3g disable full window drag: disable showing window contents while dragging in 3g mode (performance flag) (1=disable, 0=enable, default=1)
  • itap 3g disable menu anims: disable menu animations in 3g mode (performance flag) (1=disable, 0=enable, default=1)
  • itap 3g disable themes: disable themes in 3g mode (performance flag) (1=disable, 0=enable, default=1)
  • itap 3g disable cursor setting: disable cursor effects in 3g mode (performance flag) (1=disable, 0=enable, default=1)
  • itap 3g allow font smoothing: allow font antialiasing in 3g mode (performance flag) (1=enable, 0=disable, default=0)
  • itap utility hover button: show the hover button to activate the utility bar in the top middle of the screen (0=no, 1=yes, default=0)
  • itap keyboard hover button: show the hover button to activate the keyboard in the lower right corner (0=no, 1=yes, default=0)

Bookmarks and cacheIDs

Bookmarks are internally identified by cacheIDs (RDP configuration option "itap cacheID"). These are random strings, and each bookmark needs a unique cacheID. If you wish to store a .rdp file as a bookmark, it is recommended that you specify a unique cacheID so that the bookmark is updated each time the .rdp file is openend (otherwise it will generate a new entry in the connection center each time).

If you do not want to store the bookmark, then it is recommended not to set a cacheID.

CacheIDs may contain the following characters:

  • Digits (0-9)
  • Characters (a-z, A-Z)
  • Underscores (_)
  • nothing else !

In order to avoid conflicts with cacheIDs generate by other parties, it is recommended that all cacheIDs start with a common string identifying your organization (for example your company domain name).

Generator

This URL scheme generator can be used to generate the itaprdp URL scheme and matching .rdp file contents.

 RDP connection data