The iTap RDP Url Scheme
Integrating iTap RDP with Safari

Introduction

iTap 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

Older iOS versions do not allow the handling of URLs based on MIME type, therefore the url scheme "itaprdp" is used. The URL scheme is followed by a complete HTTP or HTTPS url which points to the .RDP file. On modern iOS versions (3.2 and higher) the file can also be used directly with the extension ".rdp" and the mime type application/x-rdp or text/plain.

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 -> iOS will show a dialog to launch iTap RDP if the returned mime type is application/x-rdp or text/plain.

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.

Deprecated format:

These examples do the same as the above samples, but the schemes are deprecated and should not be used anymore.

  • rdp://my.server.com/path/to/file.rdp -> client loads http://my.server.com/path/to/file.rdp
  • rdps://my.server.com/path/to/file.rdp -> client loads https://my.server.com/path/to/file.rdp
  • rdp://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)

Format

.rdp Files are text files. Currently iTap RDP only supports UTF8 format (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 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!

Documented Keys

The following keys are documented in the above link and supported by iTap RDP client:

  • desktopwidth: width of the desktop (min=320, max=1024, default=800)
  • desktopheight: height of the desktop (min=320, max=1024, default=600)
  • session bpp: color depth of the desktop in bits per pixel (allowed=8,16,24, 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)

Undocumented Keys

The following keys are not documented in the above link, but are produced by Microsoft RDP clients and are supported by iTap RDP client:

  • 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=1)
  • 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)

iTap RDP specific Keys

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

  • itap 3g width: width of the desktop in 3g mode (min=320, max=1024, default=same as desktopwidth)
  • itap 3g height: height of the desktop (min=320, max=1024, default=same as desktopheight)
  • itap 3g bpp: color depth of the desktop in 3g mode (allowed=8,16,24, 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 3g mode: enable 3G mode (1=enable, 0=disable, default=1)
  • itap console: connect to a console session (1=enable, 0=disable, default=0)
  • 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 keyboard mode: the initial keyboard mode (0=Scancodes, 1=Smartmode, 2=Unicode, default=1)
  • itap mouse mode: the initial mouse mode (0=scope, 1=pointer, 2=draw, default=0)
  • 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 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 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)

Bookmarks and cacheIDs

Bookmarks are internally identified by cacheIDs. 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