# Name

VixVM_PowerOn

# Description

    VixHandle
    VixVM_PowerOn(VixHandle vmHandle,
                  VixVMPowerOpOptions powerOnOptions,
                  VixHandle propertyListHandle,
                  VixEventProc *callbackProc,
                  void *clientData);

Powers on a virtual machine.

# Parameters

vmHandle
  Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.
powerOnOptions
  VIX_VMPOWEROP_NORMAL or VIX_VMPOWEROP_LAUNCH_GUI.
propertyListHandle
  Must be VIX_INVALID_HANDLE.
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 on a virtual machine. It is an asynchronous operation, and the job will be signalled when the operation completes.
- This operation completes when the virtual machine has started to boot. If the VMware Tools have been installed on this guest operating system, you can call VixVM_WaitForToolsInGuest to determine when the guest has finished booting.
- After powering on, you must call VixVM_WaitForToolsInGuest before executing guest operations or querying guest properties.
- In Server 1.0, when you power on a virtual machine, the virtual machine is powered on independent of a console window. If a console window is open, it remains open. Otherwise, the virtual machine is powered on without a console window.
- To display a virtual machine with a Workstation user interface, powerOnOptions must have the VIX_VMPOWEROP_LAUNCH_GUI flag, and you must be connected to the host with the VIX_SERVICEPROVIDER_VMWARE_WORKSTATION flag. If there is an existing instance of the Workstation user interface, the virtual machine will power on in a new tab within that instance. Otherwise, a new instance of Workstation will open, and the virtual machine will power on there.
- To display a virtual machine with a Player user interface, powerOnOptions must have the VIX_VMPOWEROP_LAUNCH_GUI flag, and you must be connected to the host with the VIX_SERVICEPROVIDER_VMWARE_PLAYER flag. A new instance of Player will always open, and the virtual machine will power on there.
- This function can also be used to resume execution of a suspended virtual machine.
- The VIX_VMPOWEROP_LAUNCH_GUI option is not supported for encrypted virtual machines; attempting to power on with this option results in VIX_E_NOT_SUPPORTED.

# 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);

    jobHandle = VixVM_PowerOn(vmHandle,
                              VIX_VMPOWEROP_NORMAL, // powerOnOptions,
                              VIX_INVALID_HANDLE, // propertyListHandle,
                              NULL, // callbackProc,
                              NULL); // clientData

    err = VixJob_Wait(jobHandle,
                      VIX_PROPERTY_NONE);

    abort:
    Vix_ReleaseHandle(jobHandle);
    Vix_ReleaseHandle(vmHandle);
    VixHost_Disconnect(hostHandle);

Copyright (C) 2007-2018 VMware, Inc. All rights reserved.