Name
PowerOff
Description
HRESULT
PowerOff([in] LONG powerOffOptions,
[in] ICallback* jobDoneCallback,
[out,retval] IJob** powerJob);
This function powers off a virtual machine.
Parameters
- powerOffOptions
-
Must be VixCOM.Constants.VIX_VMPOWEROP_NORMAL or
VixCOM.Constants.VIX_VMPOWEROP_FROM_GUEST.
- jobDoneCallback
-
An ICallback instance that will be called when the
operation is complete.
- powerJob
-
Returns an IJob object that describes the state of this asynchronous operation.
Return Value
HRESULT
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
VixCOM.h, since VMware Workstation 6.0
Example
VBScript:
Dim lib
Dim host
Dim vm
Dim err
Dim results
Dim job
Set lib = CreateObject("VixCOM.VixLib")
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
err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE), results)
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If
Set host = results(0)
Set job = host.OpenVM("C:\VMs\winxpprowithsp2\winxpprowithsp2.vmx", 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)
' Assume this virtual machine is already running
Set job = vm.PowerOff(VixCOM.Constants.VIX_VMPOWEROP_FROM_GUEST, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If