# Name

VixVM_RevertToSnapshot

# Description

    VixHandle
    VixVM_RevertToSnapshot(VixHandle vmHandle,
                           VixHandle snapshotHandle,
                           int options,
                           VixHandle propertyListHandle,
                           VixEventProc *callbackProc,
                           void *clientData);

Restores the virtual machine to the state when the specified snapshot was created.

# Parameters

vmHandle
  Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.
snapshotHandle
  A handle to a snapshot. Call VixVM_GetRootSnapshot() to get a snapshot handle.
options
  Any applicable VixVMPowerOpOptions. If the virtual machine was powered on when the snapshot was created, then this will determine how the virtual machine is powered back on. To prevent the virtual machine from being powered on regardless of the power state when the snapshot was created, use the VIX_VMPOWEROP_SUPPRESS_SNAPSHOT_POWERON flag. VIX_VMPOWEROP_SUPPRESS_SNAPSHOT_POWERON is mutually exclusive to all other VixVMPowerOpOptions.
propertyListHandle
  Must be VIX_INVALID_HANDLE.
callbackProc
  A callback function that will be invoked when the 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

- Restores the virtual machine to the state when the specified snapshot was created. This function can power on, power off, or suspend a virtual machine. The resulting power state reflects the power state when the snapshot was created.
- When you revert a powered on virtual machine and want it to display in the Workstation user interface, options must have the VIX_VMPOWEROP_LAUNCH_GUI flag, unless the VIX_VMPOWEROP_SUPPRESS_SNAPSHOT_POWERON is used.
- The VIX_PROPERTY_VM_TOOLS_STATE property of the virtual machine handle is undefined after the snapshot is reverted.
- Starting in VMware Workstation 6.5, snapshot operations are allowed on virtual machines that are part of a team. Previously, this operation failed with error code VIX_PROPERTY_VM_IN_VMTEAM. Team members snapshot independently so they can have different and inconsistent snapshot states.
- This function is not supported when using the VIX_SERVICEPROVIDER_VMWARE_PLAYER host type.
- If the virtual machine is open and powered off in the UI, this function now closes the virtual machine in the UI before reverting to the snapshot. To refresh this property, you must wait for tools in the guest.
- After reverting to a snapshot, you must call VixVM_WaitForToolsInGuest before executing guest operations or querying guest properties.

# Side Effects

None.

# Requirements

vix.h, since VMware Server 1.0

# Example

This example reverts to the root snapshot belonging to a virtual machine.

    VixError err = VIX_OK;
    VixHandle hostHandle = VIX_INVALID_HANDLE;
    VixHandle jobHandle = VIX_INVALID_HANDLE;
    VixHandle vmHandle = VIX_INVALID_HANDLE;
    VixHandle snapshotHandle = 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);

    // Revert to snapshot #0.
    snapshotIndex = 0;
    err = VixVM_GetRootSnapshot(vmHandle,
                                snapshotIndex,
                                &snapshotHandle);
    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }
    jobHandle = VixVM_RevertToSnapshot(vmHandle,
                                       snapshotHandle,
                                       0, // options
                                       VIX_INVALID_HANDLE, // propertyListHandle
                                       NULL, // callbackProc
                                       NULL); // clientData

    err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);

    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

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

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