# Name

VixVM_GetRootSnapshot

# Description

    VixError
    VixVM_GetRootSnapshot(VixHandle vmHandle,
                          int index,
                          VixHandle *snapshotHandle);

This function returns the handle of the specified snapshot belonging to the virtual machine referenced by vmHandle.

vmHandle
  Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.
index
  Identifies a root snapshot. See below for range of values.
snapshotHandle
  (output) A handle to a snapshot.

# Return Value

VixError.

# Remarks

- This function returns the handle of the specified snapshot belonging to the virtual machine referenced by vmHandle.
- Snapshots are indexed from 0 to n-1, where n is the number of root snapshots. Use the function VixVM_GetNumRootSnapshots() to get the value of n.
- VMware Server can manage only a single snapshot for each virtual machine. The value of index can only be 0.
- The snapshotHandle returned by this function is reference counted. The calling application is responsible for releasing the handle.
- This function is not supported when using the VIX_SERVICEPROVIDER_VMWARE_PLAYER host type.

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

    // No need to release jobHandle here. It's released at bottom.

    err = VixVM_GetNumRootSnapshots(vmHandle, &numRootSnapshots);
    if (VIX_OK != err) {
       // Handle the error...
       goto abort;
    }

    for (index = 0; index < numRootSnapshots; index++ ) {
       err = VixVM_GetRootSnapshot(vmHandle,
                                   index,
                                   &snapshotHandle);
       if (VIX_OK != err) {
          // Handle the error...
          goto abort;
       }

       // ...Access snapshot properties...

       Vix_ReleaseHandle(snapshotHandle);
    }

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

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