Connecting to a Remote Host and Virtual Machine

After your Web application has initialized the VMRC browser plug-in, you can use the connect() method to connect to a remote host and access a particular virtual machine on that host. To use the connect() method, you must have the following information.

■	The hostname or IP address of the remote host and the thumbprint of the host SSL certificate.

■	A form of authentication, which can be either a username and password pair, or a VIM session ticket.

■	A form of identification for the target virtual machine, which can be either a virtual machine ID or a datacenter and vmpath pair.

You pass different parameters to the connect() method depending on how you choose to provide the required host identification, authentication, and virtual machine identification. Parameter List for VMRC connect() Method shows the parameters for the connect() method.

Parameter List for VMRC connect() Method

Parameter Name	Type	Description/Notes
host	string	Hostname or IP address of the remote host running the target virtual machine.
sslThumbprint	string	Expected thumbprint of the remote host’s SSL certificate. You must provide the SSL thumbprint if you authenticate the connection by using a username and password pair.
allowSSLErrors	boolean	Boolean value that determines whether or not the host SSL certificate validation checker allows connections that contain validation errors. You must provide a value in the sslThumpbrint parameter if you set the allowSSLErrors parameter to true.
ticket	string	VIM session ticket, used to authenticate with the remote host. You obtain the VIM session ticket by using the VIM call acquireCloneTicket() on an active VIM session. If you use a ticket to authenticate, you must not pass a value for the username or password parameters. The sslThumbprint and allowSSLerrors parameters are optional if you authenticate using the ticket.
username	string	Username to authenticate with the remote host. If you pass a username and password pair to authenticate, do not pass a value for the ticket parameter. You must also provide an SSL thumbprint using the sslThumbprint parameter.
password	string	Password, used to authenticate with the remote host.
vmid	string	Virtual machine ID, used to identify the target virtual machine. If you use the vmid parameter to specify the target virtual machine, you must not pass a value for the datacenter or vmpath parameters.
datacenter	string	Datacenter name on which the target virtual machine is stored, used to identify the target virtual machine. If you use a datacenter and vmpath pair to identify the target virtual machine, you must not pass a value for the vmid parameter.
vmpath	string	Full datastore path to the target virtual machine, of the format [datastore]vmpath(vm.vmx).

The connect() method does not return a value. If the connection is successful, the VMRC browser plug-in generates an onConnectionStateChange event. See Handling VMRC Events.

Note When using VMRC with vCloud Director, only the host, ticket, and vmid parameters are supported when calling connect(). You must pass false for the allowSSLErrors parameter, and empty strings (““) for all other parameters in connect().

The following is an example of how to call connect() when using VMRC with vCloud Director.

connect(hostname, ““, false, ticket, ““, ““, vmid, ““, ““);

Connection Authentication

You must provide a form of authentication when using the connect() method. This authentication can be a VIM session ticket, or a username and password pair on the remote host. The authentication methods are exclusive, meaning that if you use the parameters for one method, such as a session ticket, you must omit the parameters for the other and pass them as empty strings.

The following is an example of how to call connect(), by using a VIM session ticket as the authentication method. Note that the username, password, and SSL thumbprint parameters are passed as empty strings.

connect(hostname, ““, false, ticket, ““, ““, vmid, ““, ““);

If you authenticate using a username and password pair, you must provide the SSL thumbprint to the connect() method in the sslThumbprint parameter.

Note Username and password authentication is not supported when using VMRC with vCloud Director. You must use the ticket parameter when calling connect() in a vCloud Director configuration.

The following is an example of how to call connect(), by using a username and password as the authentication method. The ticket parameter is passed as an empty string.

connect(hostname, sslThumb, false, ““, uname, pass, vmid, ““, ““);

Virtual Machine Identifier

You must provide a way to identify the target virtual machine when using the connect() method. The virtual machine can be identified by a virtual machine ID that you obtain from an active VIM session on your Web application server, or a datacenter name and datastore path to a particular virtual machine.

The two methods of identifying the virtual machine are exclusive. If you use a virtual machine ID, you must pass that value by using the vmid parameter when calling connect(), and omit any values for datacenter and vmpath. Conversely, you must omit the vmid if you use values for datacenter and vmpath when calling connect().

Note If you use VMRC with vCloud Director, you must use the virtual machine ID to identify the target virtual machine when calling connect().

The following example shows how to call connect() by using the virtual machine ID to identify the target virtual machine.

connect(hostname, ““, false, ticket, ““, ““, vmid, ““, ““);

The following is an example of how to call connect() using the datacenter name and vmpath to identify the target virtual machine.

connect(hostname, ““, false, ticket, ““, ““, ““, dstore, vmpath);