Calling VMRC API Methods on a Virtual Machine

After you have established a connection to the virtual machine remote host, you can use the VMRC API methods to interact with the target virtual machine.

Most methods in the VMRC API are associated with a specific mode of the VMRC browser plug-in, such as MKS mode or Devices mode. Methods associated with a particular operational mode are only available when the VMRC browser plug-in is started in that mode. For example, the MKS mode method setFullscreen() is only available if you specified VMRC_Mode.VMRC_MKS when starting up the VMRC browser plug-in. See Starting the VMRC Browser Plug-In.

Some methods in the VMRC API pertain only to the VMRC browser plug-in and can be used at any time, including before startup() has been called. These methods generally provide version information on VMRC and information about the supported APIs.

General-Purpose API Methods

General-purpose API methods provide information about VMRC and the APIs it supports. These methods can be called at any time, including before you call the startup() method for the VMRC browser plug-in.

getVersion()

The getVersion() method retrieves the current complete version number of the installed VMRC browser plug-in.

Method	getVersion()
Parameters	None
Return Value	string; contains the full version number for the VMRC plug-in
Example Call	var version = vmrc.getVersion();

getConnectionState()

The getConnectionState() method retrieves the current connection state from a VMRC browser plug-in.

Method	getConnectionState()
Parameters	None
Return Value	Property Value Constant; valid values are VMRC_CS_CONNECTED or VMRC_CS_DISCONNECTED
Example Call	var ret = vmrc.getConnectionState();

MKS Mode API Methods

When you use the VMRC browser plug-in using MKS mode, the VMRC processes provide access to the target virtual machine console. VMRC connects to the display console of the remote virtual machine and that display appears in your Web application window. When you use the VMRC browser plug-in using MKS mode, you can use the following VMRC API methods.

setScreenSize()

The setScreenSize() method commands the VMRC browser plug-in to set the screen resolution of the currently connected virtual machine.

Method	setScreenSize(width, height)
Parameters	width (int); represents the desired screen width of the console, in pixels height (int); represents the desired screen height of the console, in pixels
Return Value	void
Example Call	vmrc.setScreenSize(w, h);

If the call to setScreenSize() is successful, the VMRC browser plug-in generates an onScreenSizeChange() event. If the call is unsuccessful, an exception is thrown.

screenWidth()

The screenWidth() method retrieves the screen width, in pixels, of the currently connected virtual machine.

Method	screenWidth()
Parameters	None
Return Value	int; represents screen width in pixels
Example Call	var sw = vmrc.screenWidth();

screenHeight()

The screenHeight() method retrieves the screen height, in pixels, of the currently connected virtual machine.

Method	screenHeight()
Parameters	None
Return Value	int; represents screen height in pixels
Example Call	var sh = vmrc.screenHeight();

setFullscreen()

The setFullscreen() method commands the VMRC browser plug-in to enter or exit full-screen mode.

Method	setFullscreen(fs)
Parameters	fs (boolean); set to true to enter full-screen mode, false to exit
Return Value	boolean; true for success or false for failure
Example Call	var ret = vmrc.setFullscreen(true);

If the call to setFullscreen() is successful, the VMRC browser plug-in generates an onFullscreenChange() event. If the call is unsuccessful, an exception is thrown.

getFullScreen()

The getFullscreen() method retrieves the current state of the full-screen mode of the VMRC browser plug-in.

Method	getFullscreen()
Parameters	None
Return Value	boolean; true if full-screen mode is set, false if full-screen mode is not set
Example Call	var ret = vmrc.getFullscreen();

sendCAD()

The sendCAD() method sends a Control-Alt-Delete key sequence to the currently connected virtual machine.

Method	sendCAD()
Parameters	None
Return Value	boolean; true for success or false for failure
Example Call	var ret = vmrc.sendCAD();

grabInput()

The grabInput() method commands the VMRC browser plug-in to “grab” or capture the current mouse and keyboard input and send it to the currently connected virtual machine console.

Method	grabInput()
Parameters	None
Return Value	void
Example Call	vmrc.grabInput();

If the call to grabInput() is successful, the VMRC browser plug-in generates an onGrabStateChange() event. If the call is unsuccessful, an exception is thrown.

ungrabInput()

The ungrabInput() method commands the VMRC browser plug-in to discontinue capturing the current mouse and keyboard input.

Method	ungrabInput()
Parameters	None
Return Value	void
Example Call	vmrc.ungrabInput();

If the call to ungrabInput() is successful, the VMRC browser plug-in generates an onGrabStateChange() event. If the call is unsuccessful, an exception is thrown.

setInputRelease()

The setInputRelease() method commands the VMRC browser plug-in to disable all mouse and keyboard input capture, regardless of the current grab state. You can use this method to lock any input from reaching the connected VM. For example, if your web application displays a modal dialog, or enters a state in which you want to prevent any input from reaching the connected VM, you can call setInputRelease() with a parameter value of true.

You can call setInputRelease() with a parameter value of false to revert the VMRC browser plug-in to normal input behavior. When you have done so, you can change the input grab state using the grabInput() and ungrabInput() methods.

Method	setInputRelease(release)
Parameters	release (boolean); set to true to lock input capture, false to revert to normal grab/ungrab behavior
Return Value	void
Example Call	vmrc.setInputRelease(true);

Devices Mode API Methods

When you use the VMRC browser plug-in using Devices mode, you can use the physical devices on the local client machine with the currently connected virtual machine. To use devices in this way, you must connect the local physical devices to remote virtual device backings by using methods in the VMRC API. The connection methods differ for USB and non-USB devices.

Note Devices mode API methods are not supported for use with USB devices when using VMRC with vCloud Director.

Obtaining Device Keys and Connecting Devices

To connect non-USB devices, such as a CD-ROM or floppy disk drive, you use the VMRC API to obtain both a physical and virtual device key. A device key is a unique identifier for a local physical device or a remote virtual device. You then use the device keys with the connectDevice() VMRC API method to connect the devices. For USB devices, only the physical device key for the local client device is required.

For file-backed physical devices, such as a file backing for a CD-ROM or floppy device, you must substitute the full path to the device file for the physical key.

To connect a local physical device to a remote virtual device

1	Use the getPhysicalClientDevices() API method to obtain a list of device keys for the physical devices on the local machine.

The getPhysicalClientDevices() method returns a physical device key for each device that is available for remote connection.

2	Use the getPhysicalClientDeviceDetails() API method with the desired physical device key to obtain more information about the specific physical device you want to connect.

3	If you are connecting a non-USB device, use the getVirtualDevices() API method to obtain a list of device keys for the virtual devices on the currently connected virtual machine.

The getVirtualDevices() method returns a virtual device key for each device that is available for remote connection. You do not provide a virtual device key when you connect a USB device.

4	If you are connecting a non-USB device, use the getVirtualDeviceDetails() API method with the appropriate virtual device key to obtain more information about the specific virtual device you want to connect, including the virtual device’s remote backing type.

5	Use the connectDevice() API method to connect the local physical device to the corresponding remote virtual device.

To use the connectDevice() method to connect a non-USB device, you must specify the device key for both the local physical device and remote virtual device, as well as the backing type. For USB devices, you must specify a blank parameter for the virtual device key, the physical device key for the local USB device, and the backing type.

For file-backed physical devices, use the full path to the device file as the physical key.

6	When you are finished with device operations, use the disconnectDevice() API method to disconnect the device.

Managing USB Devices

To connect a USB device, you use the VMRC API to obtain a physical client device key for the local physical USB device. When you connect the local USB device to a remote virtual machine, the USB device becomes a new virtual USB device for that virtual machine. A connected USB device appears in both the local physical device list that you obtain using the getPhysicalClientDevices() method, and the remote virtual device list that you obtain using getVirtualDevices().

Note USB devices are not supported when using VMRC with vCloud Director.

You can match the USB device on the local physical machine with the corresponding remote virtual device by performing the following steps.

To match a local physical USB device with a remote USB device connection

1	Obtain the virtual device key for the remote virtual USB device on the connected virtual machine.

You can use the getVirtualDevices() method and specify VMRC_DeviceType.VMRC_DEVICE_USB to retrieve only USB devices.

2	To obtain device details for the remote virtual USB device, use the getVirtualDeviceDetails() method, passing the virtual device key.

The device detail connectedByMe indicates whether the remote virtual USB device is connected from your local physical machine. If connectedByMe is true, the remote virtual USB device corresponds to a local physical USB device. The device detail backingKey contains the physical device key for the local physical USB device.

If connectedByMe is false, a different VMRC client has connected a physical USB device to the virtual machine. The device detail hostName provides the name of the machine that owns the physical USB device.

3	To obtain device details for the local physical USB device, use the getPhysicalClientDeviceDetails() method, passing the backingKey that you obtained in step 2.

getPhysicalClientDevices()

You use the getPhysicalClientDevices() method to obtain a list of physical device keys. These physical device keys correspond to physical client devices on the local machine, accessing your Web application, that are eligible for remove device connections. When you call the getPhysicalClientDevices() method, you pass a property value constant that specifies the types of devices for which to obtain device keys.

Note When using the getPhysicalClientDevices() method with the Internet Explorer browser, you must wrap the return value array as a VBArray. The following example shows how to process the return value of getPhysicalClientDevices() as a VBArray.

var devices = new VBArray(vmrc.getPhysicalClientDevices(mask)).toArray();

Method	getPhysicalClientDevices(mask)
Parameters	mask (property value constant); the mask value specifies what types of device keys the method returns. The mask parameter can contain any combination of the values VMRC_DEVICE_FLOPPY, VMRC_DEVICE_CDROM, and VMRC_DEVICE_USB. You can also use VMRC_DEVICE_ALL to specify all device types. When using VMRC with vCloud Director, VMRC_DEVICE_ALL specifies only floppy and CD-ROM device types.
Return Value	string[] vector of physical device key strings.
Example Call	var deviceKeys = vmrc.getPhysicalClientDevices(VMRC_DEVICE_FLOPPY | VMRC_DEVICE_CDROM);

getPhysicalClientDeviceDetails()

You use the getPhysicalClientDeviceDetails() method to obtain detailed information about a particular local physical device. The getPhysicalClientDeviceDetails() method returns a JavaScript object that contains the device information.

Method	getPhysicalClientDeviceDetails(physicalKey)
Parameters	physicalKey (string); the physical device key for the specified device, retrieved using the getPhysicalClientDevices() method.
Return Value	JavaScript Object that contains the following fields (keyed by strings): key (string): Device key type (VMRC_DeviceType): Device type state (VMRC_DeviceState): Device state connectedByMe (boolean): Whether the device is connected by the current VMRC instance name (string): Device-friendly name path (string): Device path usbFamilies (VMRC_USBDeviceFamily): (USB only) Mask of VMRC_USBDeviceFamily property value constant values usbSharable (boolean): (USB only) Whether the device is sharable by multiple VMRC instances usbSpeeds (VMRC_USBDeviceSpeed): (USB only) Mask of VMRC_USBDeviceSpeed property value constant values
Example Call	var ret = vmrc.getPhysicalClientDeviceDetails(key);

getVirtualDevices()

You use the getVirtualDevices() method to obtain a list of virtual device keys. These virtual device keys correspond to virtual devices on the currently connected virtual machine that are eligible for remote device connections. When you call the getVirtualDevices() method, you pass a property value constant that specifies the types of devices for which to obtain device keys.

Note When using the getVirtualDevices() method with the Internet Explorer browser, you must wrap the return value array as a VBArray. The following example shows how to process the return value of getVirtualDevices() as a VBArray.

var devices = new VBArray(vmrc.getVirtualDevices(mask)).toArray();

Method	getVirtualDevices(mask)
Parameters	mask (property value constant); the mask value specifies what types of device keys the method returns. The mask parameter can contain any combination of the values VMRC_DEVICE_FLOPPY, VMRC_DEVICE_CDMROM, and VMRC_DEVICE_USB. You can also use VMRC_DEVICE_ALL to specify all device types. When using VMRC with vCloud Director, VMRC_DEVICE_ALL specifies only floppy and CD-ROM device types.
Return Value	string[] vector of virtual device key strings.
Example Call	var deviceKeys = vmrc.getVirtualDevices(VMRC_DEVICE_FLOPPY | VMRC_DEVICE_CDROM);

getVirtualDeviceDetails()

You use the getVirtualDeviceDetails() method to obtain detailed information about a particular virtual device. The getVirtualDeviceDetails() method returns a JavaScript object that contains the device information.

Method	getVirtualDeviceDetails(virtualKey)
Parameters	virtualKey (string); the virtual device key for the specified device, retrieved using the getVirtualDevices() method..
Return Value	JavaScript Object that contains the following fields (keyed by strings): key (string): Device key type (VMRC_DeviceType): Device type state (VMRC_DeviceState): Device state connectedByMe (boolean): Whether the device is connected by the current VMRC instance name (string): Device-friendly name hostName (string): Host name of the physical machine that provides the virtual device backing clientBacking (boolean): Whether the device is configured to support a client backing backingKey (string): Physical key for the physical device backing the virtual device backing (VMRC_DeviceBacking): Device backing type
Example Call	var ret = vmrc.getVirtualDeviceDetails(key);

connectDevice()

You use the connectDevice() method to connect a physical client device to the currently connected virtual machine, either directly, for USB devices, or through a remote device backing, for non-USB devices. You must have an active connection to use the connectDevice() method and you must also have obtained the device keys for the specified physical client and remote virtual device for non-USB devices.

Note To connect a USB device, the remote virtual machine must have a USB controller installed. Connecting USB devices is not supported when using VMRC with vCloud Director.

Method	connectDevice(virtualKey, physicalKey, backingType)
Parameters	virtualKey (string); The identifier of the target virtual machine’s virtual device, which you can retrieve by using the getVirtualDevices() method. For USB devices, this parameter should be passed as an empty string (““). physicalKey (string); The identifier of the physical device on the client system, which you can retrieve by using the getPhysicalClientDevices() method. If you are using a physical device with a file backing, the physicalKey string must be the file path. backingType (property value constant); This parameter indicates whether the physicalKey parameter refers to a physical device or a local file. Valid values include VMRC_DB_FILE and VMRC_DB_PHYSICAL. If you are using VMRC_DB_FILE to represent a CD-ROM or floppy device with a file backing, the physical key must be the absolute file path.
Return Value	void
Example Call	For non-USB devices (pKey refers to a physical CD-ROM device): vmrc.connectDevice(vKey, pKey, VMRC_DB_PHYSICAL); For USB devices (pKey refers to a physical USB device): vmrc.connectDevice(““, pKey, VMRC_DB_PHYSICAL); For a file-backed physical device (pKey refers to a file path): vmrc.connectDevice(vKey, pKey, VMRC_DB_FILE);

If the call to connectDevice() is successful, the VMRC browser plug-in generates an onDeviceStateChange() event. If the call is unsuccessful, the VMRC browser plug-in throws an exception.

disconnectDevice()

You use the disconnectDevice() method to disconnect a physical client device from the currently connected virtual machine. You must have an active connection to use the disconnectDevice() method. For non-USB devices, you must specify the virtual device key of the remote virtual device to disconnect. For USB devices, you must specify the physical device key of the physical client device to disconnect.

Method	disconnectDevice(deviceKey)
Parameters	deviceKey (string); The identifier of the device to disconnect. For non-USB devices, this must be the virtual key of the virtual device on the target virtual machine. For USB devices, this must be the physical key of the physical client device.
Return Value	void
Example Call	vmrc.disconnectDevice(deviceKey);

If the call to disconnectDevice() is successful, the VMRC browser plug-in generates an onDeviceStateChange() event. If the call is unsuccessful, the VMRC browser plug-in throws an exception.