Starting the VMRC Browser Plug-In

Before you call any other API methods, your Web application must first initialize the VMRC browser plug-in. You can also use VMRC API methods to verify the VMRC browser plug-in version before starting the plug-in.

Verifying the VMRC Browser Plug-In Version

You can use the getVersion() API method to obtain the specific version of the VMRC browser plug-in and VMRC SDK that is installed on the local client system. You can call getVersion() at any time after loading the VMRC plug-in, even before you start the plug-in.

The getVersion() method is present in every version of the VMRC API. For detailed information on calling getVersion(), see General-Purpose API Methods.

The specific VMRC API version that your Web application uses depends on the CLSID or MIME type that your application supplied when loading the VMRC browser plug-in. See Loading the VMRC Browser Plug-In.

Initializing the VMRC Browser Plug-In

To initialize the VMRC browser plug-in, you must use call the following API methods in sequence.

1	Use the isReadyToStart() API method to determine whether the VMRC browser plug-in has been successfully loaded and is ready to be started.

2	Use the startup() API method to start the processes in the VMRC browser plug-in.

Using isReadyToStart()

The isReadyToStart() method takes no parameters and returns a boolean value. A return value of true indicates that the VMRC browser plug-in has been loaded and is ready to start. You may call startup() once the isReadyToStart() method returns a value of true.

Note The VMRC browser plug-in does not generate an event when the plug-in is ready to start. You must poll the return value of the isReadyToStart() method to determine whether the VMRC browser plug-in has loaded and can be started.

An example call to isReadyToStart() might appear as follows:

var ret = vmrc.isReadyToStart();

Using the startup() Method

You must use the startup() API method to start the processes in the VMRC browser plug-in. When you call the startup() method, you also set the modes in which the VMRC browser plug-in can operate. The available modes are Mouse-Keyboard-Screen (MKS) mode and Devices mode.

You can choose to start the VMRC browser plug-in with one or both of the available mode settings. The mode parameter to the startup() API method accepts a mask of values. You can include one or both mode settings in the value that you pass for the mode parameter by using the bitwise or (|) operator.

MKS Mode

When you start the VMRC browser plug-in using MKS mode, the screen contents of the target virtual machine are displayed in the local browser window. The user can interact with the input to the target virtual machine, such as the mouse and keyboard. The VMRC API contains methods specific to MKS mode, where your Web application can interact with the screen, send key sequences, or grab the virtual machine input. See MKS Mode API Methods.

You start the VMRC browser plug-in using MKS mode by calling the startup() method and including the property value constant VMRC_Mode.VMRC_MKS in the mode parameter.

Devices Mode

When you start the VMRC browser plug-in using Devices mode, you can use VMRC to manage virtual devices. You can connect virtual devices on the target virtual machine to physical devices on the local system. The VMRC API contains methods specific to Devices mode, where your Web application can connect physical client devices to virtual devices, and allow the target virtual machine to access physical devices on the local system that is running your Web application. See Devices Mode API Methods.

You start the VMRC browser plug-in using Devices mode by calling the startup() method and including the property value constant VMRC_Mode.VMRC_DEVICES in the mode parameter.

Parameter List for VMRC startup() Method

Parameter Name	Type	Description/Notes
mode	VMRC_Mode property value constant; one or both of the values VMRC_Mode.VMRC_MKS and VMRC_Mode.VMRC_DEVICES (both can be conjoined using the | operator)	The mode parameter is specified at startup, and determines the operational mode of the VMRC plug-in instance for the lifetime of its connection. The plug-in can operate in the following modes. VMRC_Mode.VMRC_MKS: In MKS mode, guest screen contents are displayed and the user can interact with the guest. VMRC_Mode.VMRC_DEVICES: In Devices mode, the user can manage remote device backings and their mappings to virtual machine devices.
msgmode	VMRC_MessageMode property value constant; VMRC_MessageMode.VMRC_EVENT_MESSAGES, VMRC_MessageMode.VMRC_DIALOG_MESSAGES, VMRC_MessageMode.VMRC_NO_MESSAGES	The msgmode parameter is specified at startup, and determines by which mode messages are delivered from the plug-in to the containing document element in your Web application. The VMRC_MessageMode.VMRC_DIALOG_MESSAGE and VMRC_MessageMode.VMRC_NO_MESSAGES values are not supported on the Linux operating system.
advancedconfig	string	A string containing advanced configuration options. Values for this parameter must follow the format “flag=value”, as in “usebrowserproxy=true”. See Advanced Configuration Flags for VMRC startup() Method for valid configuration flags.

The startup() method returns a string value, which is implementation-specific and opaque to the client.

Advanced Configuration Flags

Advanced Configuration Flags for VMRC startup() Method shows the available advanced configuration flags that you can use in the startup() method’s advancedconfig parameter. To use a flag, you must include the string “{flag}=true” in the advancedconfig parameter, where {flag} is your flag of choice. You can include multiple flags by separating each flag and value with a semicolon.

When using VMRC with vCloud Director, you must include advanced configuration flags usebrowserproxy and tunnelmks, with the values set to true.

Advanced Configuration Flags for VMRC startup() Method

Flag	Description
usebrowserproxy	If true, VMRC connections use the same proxy settings as the Web browser running the VMRC browser plug-in.
autoanswerquestions	If true, end-user questions from the connected Virtual Machine are automatically answered by VMRC using the default choice that the Virtual Machine designates. You can use the autoanswerquestions flag for simple or devices-only clients that do not require end-user interaction.
cacheconnections	If true, VMRC preserves device connections to a given Virtual Machine even after VMRC disconnects from that Virtual Machine using the disconnect() method. You can use the cacheconnections flag for advanced clients that provide client device functionality for multiple Virtual Machines with a single VMRC instance.
tunnelmks	If true, VMRC MKS console traffic is tunneled over HTTPS.

Example Call

An example call to startup() in the Firefox browser might appear as follows:

var ret = vmrc.startup(vmrc.VMRC_Mode.VMRC_MKS, vmrc.VMRC_MessageMode.VMRC_EVENT_MESSAGES, “usebrowserproxy=true;tunnelmks=true”);