The iTap mobile VNC Url Scheme
Integrating iTap mobile VNC with Safari

Introduction

iTap mobile VNC can open and parse .vnc files containing connection settings. The basic format of .vnc files is analogous to .rdp files as 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 "itapvnc" is used. The URL scheme is followed by a complete HTTP or HTTPS url which points to the .VNC file. On modern iOS versions (3.2 and higher) the file can also be used directly with the extension ".vnc" and the mime type application/x-vnc or text/plain.

Examples:

  • itapvnc:http://my.server.com/path/to/file.vnc -> client loads http://my.server.com/path/to/file.vnc
  • itapvnc:https://my.server.com/path/to/file.vnc -> client loads https://my.server.com/path/to/file.vnc
  • itapvnc: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 .vnc file)
  • http://my.server.com/path/to/file.vnc -> iOS will show a dialog to launch iTap mobile VNC if the returned mime type is application/x-vnc or text/plain.

Please note that the automatic download of .vnc 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

.vnc Files are text files. Currently iTap mobile VNC only supports UTF8 format (and ASCII which is a subset of UTF8). All forms of line endings are supported. The mime-type of the URL is ignored if the itapvnc scheme is used, 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.

Alternatively a line can consist of a key-value pair, separated by equals (=). This makes it compatible with .INI style configurations Keys and types must not contain equals (:), but values may contain equals.

Lines not fitting in the above two schemes are ignored.

Example: "session bpp:i:24"

Example: "session bpp=24"

This example contains the key "session bpp", the type "i" and the value "24"

The possible values for type are not specified by Microsoft, and the actual value is ignored by iTap mobile VNC. 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 .VNC file will not load!

The following keys are supported by iTap mobile VNC:

  • 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)
  • host: alternative to "full address" (default=none)
  • port: port number (overrides port given in "host" or "full address" (default=5900)
  • username: username for login (default=none)
  • domain: domain for logon (default=none)
  • itap 3g bpp: color depth of the desktop in 3g mode (allowed=8,16,24, default=8)
  • itap 3g mode: enable 3G mode (1=enable, 0=disable, default=1)
  • 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 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 .vnc file as a bookmark, it is recommended that you specify a unique cacheID so that the bookmark is updated each time the .vnc 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 itapvnc URL scheme and matching .vnc file contents.

 VNC connection data