Name

Description

HRESULT
OpenVMEx([in] BSTR vmxFilePath,
         [in] LONG openVMOptions,
         [in] IVixHandle* propertyList,
         [in] ICallback* jobDoneCallback,
         [out,retval] IJob** openJob);

This function opens a virtual machine on the host that is identified by the hostHandle parameter and returns a context to that machine as a virtual machine handle. This function supercedes OpenVM.

Parameters

vmxFilePathName

The path name of the virtual machine configuration file on the local host.

openVMOptions

Must be VixCOM.Constants.VIX_VMOPEN_NORMAL.

propertyList

A property list containing extra information that might be needed to open the VM. You can pass NULL (C++), null (C#), or Nothing (VB) if no extra information is needed.

jobDoneCallback

An ICallback instance that will be called when the operation is complete.

openJob

Returns an IJob object that describes the state of this asynchronous operation.

Return Value

Remarks

• This function opens a virtual machine on the host that is identified by the hostHandle parameter. The virtual machine is identified by vmxFilePathName, which is a path name to the configuration file (.VMX file) for that virtual machine.
• The format of the path name depends on the host operating system. For example, a path name for a Windows host requires backslash as a directory separator, whereas a Linux host requires a forward slash. If the path name includes backslash characters, you need to precede each one with an escape character. For VMware Server 2.x, the path contains a preceeding data store, for example [storage1] vm/vm.vmx.
• This function is asynchronous, and uses a job object to report when the operation is complete. The function returns a handle to the job object immediately. When the job is signaled, the virtual machine handle is stored as the VIX_PROPERTY_JOB_RESULT_HANDLE property of the job object.
• For VMware Server hosts, a virtual machine must be registered before you can open it. You can register a virtual machine by opening it with the VMware Server Console, through the vmware-cmd command with the register parameter, or with Host::RegisterVM().
• For vSphere, the virtual machine opened may not be the one desired if more than one Datacenter contains vmxFilePathName.
• To open an encrypted virtual machine, pass a handle to a property list containing the property VIX_PROPERTY_VM_ENCRYPTION_PASSWORD set to the password for the virtual machine.
• To enable SSL certificate checking, refer to the Host::Connect function. If enabled, one must check the boolean property VIX_PROPERTY_VM_SSL_ERROR on the resulting Virtual Machine handle to determine if the host machine's SSL certificate was signed by a trusted certificate authority.
• For ESX/ESXi hosts and vSphere, the user account specified in the call to Host::Connect must have "System.View" privilege at the level of the Datacenter containing the ESX server that hosts the VM to be opened.
• For ESX/ESXi hosts and vSphere, the user account specified in the call to Host::Connect must have sufficient privileges to access guest operations in the virtual machine. For vSphere 4.1 and later, the privilege is "Virtual Machine.Interaction.Acquire Guest Control Ticket". For 4.0, the privilege is "Virtual Machine.Interaction.Console Interaction".

Requirements

Example

Dim lib
Dim host
Dim vm
Dim err
Dim results
Dim job

Set lib = CreateObject("VixCOM.VixLib")

' Connect to the local installation of Workstation. This also initializes the VIX API.
Set job = lib.Connect(VixCOM.Constants.VIX_API_VERSION, VixCOM.Constants.VIX_SERVICEPROVIDER_VMWARE_WORKSTATION, Empty, 0, Empty, Empty, 0, Nothing, Nothing)

' results needs to be initialized before it's used, even if it's just going to be overwritten.
Set results = Nothing

' Wait waits until the job started by an asynchronous function call has finished. It also
' can be used to get various properties from the job. The first argument is an array
' of VIX property IDs that specify the properties requested. When Wait returns, the
' second argument will be set to an array that holds the values for those properties,
' one for each ID requested.
err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE), results)
If lib.ErrorIndicatesFailure(err) Then
   ' Handle the error...
End If

' The job result handle will be first element in the results array.
Set host = results(0)

' Open the virtual machine with the given .vmx file.
Set job = host.OpenVMEx("C:\VMs\winxpprowithsp2\winxpprowithsp2.vmx", VixCOM.Constants.VIX_VMOPEN_NORMAL, Nothing, Nothing)
err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE), results)
If lib.ErrorIndicatesFailure(err) Then
   ' Handle the error...
End If

Set vm = results(0)

'Execute other commands here

Set results = Nothing
Set job = Nothing
Set vm = Nothing

host.Disconnect()