Name

Description

VixHandle
VixVM_Open(VixHandle hostHandle,
           const char *vmxFilePathName,
           VixEventProc *callbackProc,
           void *clientData);

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.

Parameters

hostHandle

The handle of a host object, typically returned from VixHost_Connect().

vmxFilePathName

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

callbackProc

A callback function that will be invoked when the operation is complete.

clientData

A parameter that will be passed to the callbackProc procedure.

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 VixHost_RegisterVM().

Side Effects

Requirements

Example

VixError err = VIX_OK;
VixHandle hostHandle = VIX_INVALID_HANDLE;
VixHandle jobHandle = VIX_INVALID_HANDLE;
VixHandle vmHandle = VIX_INVALID_HANDLE;

// Connect to the local host:
jobHandle = VixHost_Connect(VIX_API_VERSION,
                            VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
                            NULL, // hostName
                            0, // hostPort
                            NULL, // userName
                            NULL, // password
                            0, // options
                            VIX_INVALID_HANDLE, // propertyListHandle
                            NULL, // callbackProc
                            NULL); // clientData

err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &hostHandle,
                  VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
// Release handle when done:
Vix_ReleaseHandle(jobHandle);

// Open the virtual machine:
jobHandle = VixVM_Open(hostHandle,
                       "c:\\Virtual Machines\\vm1\\win2000.vmx",
                       NULL, // callbackProc
                       NULL); // clientData
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &vmHandle,
                  VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
// Release handle when done:
Vix_ReleaseHandle(jobHandle);