Name
VixVM_Open
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
VixHandle. A job handle that describes the state of this asynchronous call.
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
None.
Requirements
vix.h, since VMware Server 1.0
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);