Name
VixVM_PowerOff
Description
VixHandle
VixVM_PowerOff(VixHandle vmHandle,
VixVMPowerOpOptions powerOffOptions,
VixEventProc *callbackProc,
void *clientData);
This function powers off a virtual machine.
Parameters
- vmHandle
-
Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.
- powerOffOptions
-
Must be VIX_VMPOWEROP_NORMAL or VIX_VMPOWEROP_FROM_GUEST.
- callbackProc
-
A callback function that will be invoked when the power
operation is complete.
- clientData
-
A parameter that will be passed to the callbackProc function.
Return Value
VixHandle. A job handle that describes the state of this asynchronous operation.
Remarks
- This function powers off a virtual machine. It is an asynchronous operation,
and the job will be signalled when the operation completes.
- If you call this function while the virtual machine is powered off, the
operation returns a VIX_E_VM_NOT_RUNNING error. You can safely ignore this
error.
- If you call this function while the virtual machine is suspended, the
operation returns a VIX_E_VM_NOT_RUNNING error. The virtual machine is
not powered off and remains suspended.
- The VIX_VMPOWEROP_FROM_GUEST flag will cause the function to try to power off
the guest OS. This will ensure a clean shutdown of the guest. This option
requires that the VMware Tools be installed and running in the guest.
- If VIX_VMPOWEROP_NORMAL is passed as the 'powerOffOptions' parameter, then the
virtual machine will be powered off at the hardware level. Any state of the
guest that has not been committed to disk will be lost.
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;
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;
}
Vix_ReleaseHandle(jobHandle);
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;
}
Vix_ReleaseHandle(jobHandle);
// Assume this virtual machine is already running.
jobHandle = VixVM_PowerOff(vmHandle,
VIX_VMPOWEROP_FROM_GUEST, // powerOffOptions,
NULL, // callbackProc,
NULL); // clientData
err = VixJob_Wait(jobHandle,
VIX_PROPERTY_NONE);
abort:
Vix_ReleaseHandle(jobHandle);
Vix_ReleaseHandle(vmHandle);
VixHost_Disconnect(hostHandle);