Using URIs to Configure Horizon Client

You can use uniform resource identifiers (URIs) to create web page or email links that end users can click to start Horizon Client, connect to a server, or open a remote desktop or published application.

You create these links by constructing URIs that provide some or all the following information so that your end users do not need to supply it.

Server address
Port number for the server
Active Directory user name
RADIUS or RSA SecurID user name, if different from the Active Directory user name
Domain name
Remote desktop or published application display name
Window size
Actions including reset, log out, and start session
Display protocol
Options for redirecting USB devices

To construct a URI, you use the vmware-view URI scheme with Horizon Client specific path and query parts.

To use URIs to start Horizon Client, Horizon Client must already be installed on client computers.

Syntax for Creating vmware-view URIs

URI syntax includes the vmware-view URI scheme, a path part to specify the remote desktop or published application, and, optionally, a query to specify remote desktop or published application actions or configuration options.

URI Specification

Use the following syntax to create URIs to start Horizon Client.

vmware-view://[authority-part][/path-part][?query-part]

The only required element is the URI scheme, vmware-view. Because the scheme name is case-sensitive for some versions of some client operating systems, type vmware-view.

Important: In all parts, non-ASCII characters must first be encoded according to UTF-8 [STD63], and then each octet of the corresponding UTF-8 sequence must be percent-encoded to be represented as URI characters.

For information about encoding for ASCII characters, see the URL encoding reference at http://www.utf8-chartable.de/.

authority-part

The server address and, optionally, a user name, a non-default port number, or both. Underscores (_) are not supported in server names. Server names must conform to DNS syntax.

To specify a user name, use the following syntax.

user1@server-address

You cannot specify a UPN address, which includes the domain. To specify the domain, you can use the domainName query part in the URI.

To specify a port number, use the following syntax.

server-address:port-number

path-part

The display name of the remote desktop or published application. The display name is specified in Horizon Console when the desktop pool or application pool is created. If the display name contains a space, use the %20 encoding mechanism to represent the space.

Alternatively, you can specify a desktop or application ID, which is a path string that includes the desktop or application pool ID. To find a desktop or application ID, open ADSI Edit on the Connection Server host, navigate to DC=vdi,dc=vmware,dc=int, and select the OU=Applications node. All the desktop and application pools are listed. The distinguishedName attribute specifies the ID value. You must encode the ID value before you specify it in a URI, for example, cn%3Dwin7-32%2Cou%3Dapplications%2Cdc%3Dvdi%2Cdc%3Dvmware%2Cdc%3Dint.

If you specify a desktop or application ID, you must use only lowercase letters, even if the desktop or application ID contains uppercase letters in ADSI Edit.

Note: More than one remote desktop or published application can have the same display name, but the desktop and application ID is unique. To specify a particular remote desktop or published application, use the desktop or application ID rather than the display name.

query-part

The configuration options to use, or the remote desktop or published application actions to perform. Queries are not case-sensitive. To use multiple queries, use an ampersand (&) between the queries. If the queries conflict, Horizon Client uses the last query in the list. Use the following syntax.

query1=value1[&query2=value2...]

Supported Queries

The following queries are supported for this type of Horizon Client. If you are creating URIs for multiple types of clients, such as desktop clients and mobile clients, see the guide document for each type of client system for the list of supported queries.

action

Table 1. Values That Can Be Used with the action Query
Value	Description
browse	Displays a list of available remote desktops and published applications hosted on the specified server. You are not required to specify a remote desktop or published application when using this action.
start-session	Opens the specified remote desktop or published application. If no action query is provided and the remote desktop or published application name is provided, start-session is the default action.
reset	Shuts down and restarts the specified remote desktop or published application. Unsaved data is lost. Resetting a remote desktop is the same as pressing the Reset button on a physical PC.
restart	Shuts down and restarts the specified remote desktop. Restarting a remote desktop is the same as the Windows operating system restart command. The operating system usually prompts the user to save any unsaved data before it restarts.
logoff	Logs the user out of the guest operating system in the remote desktop. If you specify a published application, the action is ignored or the end user sees the warning message "Invalid URI action."

args

Specifies command-line arguments to add when the published application starts. Use the syntax args= value, where value is a string. Use percent encoding for the following characters:

For a colon (:), use %3A
For a back slash (\), use %5C
For a space ( ), use %20
For a double quotation mark ("), use %22

For example, to specify the filename "My new file.txt" for the Notepad++ application, use %22My%20new%20file.txt%22.

appProtocol

For published applications, valid values are PCOIP and BLAST. For example, to specify PCoIP, use the syntax appProtocol=PCOIP.

connectUSBOnInsert

Connects a USB device to the foreground remote desktop or published application when you plug in the device. This query is implicitly set if you specify the unattended query for a remote desktop. To use this query, you must set the action query to start-session or else not have an action query. Valid values are true and false. An example of the syntax is connectUSBOnInsert=true.

connectUSBOnStartup

Redirects all USB devices that are currently connected to the client system to the remote desktop or published application. This query is implicitly set if you specify the unattended query for a remote desktop. To use this query, you must set the action query to start-session or else not have an action query. Valid values are true and false. An example of the syntax is connectUSBOnStartup=true.

desktopLayout

Sets the size of the remote desktop window. To use this query, you must set the action query to start-session or not have an action query.

Table 2. Valid Values for the desktopLayout Query
Value	Description
fullscreen	Full screen on one monitor. This value is the default.
multimonitor	Full screen on all monitors.
windowLarge	Large window.
windowSmall	Small window.
`W`x`H`	Custom resolution, where you specify the width by height, in pixels. An example of the syntax is `desktopLayout=1280x800`.

desktopProtocol

For remote desktops, valid values are RDP, PCOIP, and BLAST. For example, to specify PCoIP, use the syntax desktopProtocol=PCOIP.

domainName

Specifies the NETBIOS domain name associated with the user who is connecting to the remote desktop or published application. For example, you might use mycompany rather than mycompany.com.

filePath

Specifies the path to the file on the local system that you want to open with the published application. You must specify the full path, including the drive letter. Use percent encoding for the following characters:

For a colon (:), use %3A
For a back slash (\), use %5C
For a space ( ), use %20

For example, to represent file path C:\test file.txt, use C%3A%5Ctest%20file.txt.

launchMinimized

Starts Horizon Client in minimized mode. Horizon Client remains minimized until the specified remote desktop or published application starts. The syntax is launchMinimized=true. You cannot use this query with the unattended query.

tokenUserName

Specifies the RSA or RADIUS user name. Use this query only if the RSA or RADIUS user name is different from the Active Directory user name. If you do not specify this query and RSA or RADIUS authentication is required, Horizon Client uses the Windows user name. The syntax is tokenUserName=name.

unattended

Creates a server connection to a remote desktop in kiosk mode. If you use this query, do not specify user information if you generated the account name from the MAC address of the client device. If you created custom account names in ADAM, such as names that begin with "custom-", you must specify the account information.

useExisting

If this option is set to true, only one Horizon Client instance can run. If users try to connect to a second server, they must log out of the first server, causing remote desktop and published application sessions to be disconnected. If this option is set to false, multiple Horizon Client instances can run and users can connect to multiple servers at the same time. The default is true. An example of the syntax is useExisting=false.

unauthenticatedAccessEnabled

If this option is set to true, the Unauthenticated Access feature is enabled by default. The Unauthenticated Access option is visible in the user interface and is selected. If this option is set to false, the Unauthenticated Access feature is deactivated. The Unauthenticated Access setting is hidden and deactivated. When this option is set to "", the Unauthenticated Access feature is deactivated and the Unauthenticated Access setting is hidden from the user interface and deactivated. An example of the syntax is unauthenticatedAccessEnabled=true.

unauthenticatedAccessAccount

If the Unauthenticated Access feature is enabled, sets the account to use. If Unauthenticated Access is deactivated, then this query is ignored. An example of the syntax using the anonymous1 user account is unauthenticatedAccessAccount=anonymous1.

Examples of vmware-view URIs

You can use the vmware-view URI scheme to create hypertext links or buttons and include these links in email or on a Web page. For example, an end user can click a URI link to start a remote desktop with the startup options that you specify.

Each URI example is followed by a description of what the end user sees after clicking the URI link.

```
vmware-view://view.mycompany.com/Primary%20Desktop?action=start-session
```
Horizon Client starts and connects to the view.mycompany.com server. The login dialog box prompts the user for a user name, domain name, and password. After a successful login, the client connects to the remote desktop that has the display name Primary Desktop, and the user is logged in to the guest operating system.

Note: In this example, the default display protocol and window size are used. The default display protocol is PCoIP and the default window size is full screen.
```
vmware-view://view.mycompany.com/cn%3Dwin7-32%2Cou%3Dapplications%2Cdc%3Dvdi%2Cdc%3Dvmware%2Cdc%3Dint
```
Horizon Client starts and connects to the view.mycompany.com server. The login dialog box prompts the user for a user name, domain name, and password. After a successful login, the client connects to the remote desktop that has the desktop ID CN=win7-32,OU=Applications,DC=vdi,DC=vmware,DC=int (encoded value cn%3Dwin7-32%2Cou%3Dapplications%2Cdc%3Dvdi%2Cdc%3Dvmware%2Cdc%3Dint).
```
vmware-view://view.mycompany.com:7555/Primary%20Desktop
```
This URI has the same effect as the previous example, except that it uses the nondefault port of 7555 for the Connection Server instance. (The default port is 443.) Because a remote desktop identifier is provided, the remote desktop opens, even though the start-session action is not included in the URI.
```
vmware-view://[email protected]/Finance%20Desktop?desktopProtocol=PCOIP
```
Horizon Client starts and connects to the view.mycompany.com server. In the login dialog box, the User name text box is populated with fred. The user must supply the domain name and password. After a successful login, the client connects to the remote desktop that has the display name Finance Desktop, and the user is logged in to the guest operating system. The connection uses the PCoIP display protocol.
```
vmware-view://view.mycompany.com/Calculator?action=start-session&appProtocol=BLAST
```
Horizon Client starts and connects to the view.mycompany.com server. In the login dialog box, the user must supply the user name, domain name, and password. After a successful login, the client connects to the published application that has the display name Calculator. The connection uses the VMware Blast display protocol.
```
vmware-view://[email protected]/Finance%20Desktop?domainName=mycompany
```
Horizon Client starts and connects to the view.mycompany.com server. In the login dialog box, the User name text box is populated with fred, and the Domain text box is populated with mycompany. The user must supply only a password. After a successful login, the client connects to the remote desktop that has the display name Finance Desktop, and the user is logged in to the guest operating system.
```
vmware-view://view.mycompany.com/
```
Horizon Client starts and the user is taken to the login prompt for connecting to the view.mycompany.com server.
```
vmware-view://view.mycompany.com/Primary%20Desktop?action=reset
```
Horizon Client starts and connects to the view.mycompany.com server. The login dialog box prompts the user for a user name, domain name, and password. After a successful login, Horizon Client resets the specified desktop.

Note: This action is available only if a Horizon administrator has enabled the reset feature for the remote desktop.
```
vmware-view://view.mycompany.com/Primary%20Desktop?action=restart
```
Horizon Client starts and connects to the view.mycompany.com server. The login dialog box prompts the user for a user name, domain name, and password. After a successful login, Horizon Client restarts the specified desktop.

Note: This action is available only if a Horizon administrator has enabled the restart feature for the remote desktop.
```
vmware-view://view.mycompany.com/Primary%20Desktop?action=start-session&connectUSBOnStartup=true
```
This URI has the same effect as the first example, and all USB devices connected to the client system are redirected to the remote desktop.
```
vmware-view://
```
If Horizon Client is not running, it starts. If Horizon Client is already running, it comes to the foreground.
```
vmware-view://10.10.10.10/My%20Notepad++?args=%22My%20new%20file.txt%22
```
Starts My Notepad++ on server 10.10.10.10 and passes the argument My new file.txt in the published application start command. Spaces and double quotes use percent escaping. The filename is enclosed in double quotes because it contains spaces.
You can also type this command at the Windows command-line prompt by using the following syntax:
```
vmware-view.exe --serverURL 10.10.10.10 --appName "My Notepad++" --args "\"my new.txt\""
```
In this example, double quotes are escaped by using the characters \".
```
vmware-view://10.10.10.10/Notepad++%2012?args=a.txt%20b.txt
```
Starts Notepad++ 12 on server 10.10.10.10 and passes the argument a.text b.txt in the published application start command. Because the argument is not enclosed in quotes, a space separates the filenames and the two files are opened separately in Notepad++.

Note: Published applications can differ in the way that they use command-line arguments. For example, if you pass the argument a.txt b.txt to WordPad, WordPad opens only one file, a.txt.
```
vmware-view://view.mycompany.com/Notepad?unauthenticatedAccessEnabled=true&unauthenticatedAccessAccount=anonymous1
```
Horizon Client starts and connects to the view.mycompany.com server using the anonymous1 user account. The Notepad application starts without prompting the user to provide login credentials.

HTML Code Examples

You can use URIs to make hypertext links and buttons to include in emails or on Web pages. The following examples show how to use the URI from the first URI example to code the hypertext link labeled Test Link and a button labeled TestButton.

<html>
<body>

<a href="vmware-view://view.mycompany.com/Primary%20Desktop?action=start-session">Test Link</a><br>

<form><input type="button" value="TestButton" onClick="window.location.href=
'vmware-view://view.mycompany.com/Primary%20Desktop?action=start-session'"></form> <br>

</body>
</html>