Name

Description

VixHandle
VixVM_CreateSnapshot(VixHandle vmHandle,
                     const char *name,
                     const char *description,
                     int options,
                     VixHandle propertyListHandle,
                     VixEventProc *callbackProc,
                     void *clientData);

This function saves a copy of the virtual machine state as a snapshot object. The handle of the snapshot object is returned in the job object properties.

Parameters

vmHandle

Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.

name

A user-defined name for the snapshot; need not be unique.

description

A user-defined description for the snapshot.

options

Flags to specify how the shapshot should be created. Any combination of the following or 0:

• VIX_SNAPSHOT_INCLUDE_MEMORY - Captures the full state of a running virtual machine, including the memory.

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

Remarks

• This function creates a child snapshot of the current snapshot.
• VMware Server supports only a single snapshot for each virtual machine. The following considerations apply to VMware Server:
  • If you call this function a second time for the same virtual machine without first deleting the snapshot, the second call will overwrite the previous snapshot.
  • A virtual machine imported to VMware Server from another VMware product might have more than one snapshot at the time it is imported. In that case, you can use this function to add a new snapshot to the series.
• The 'name' and 'description' parameters can be set but not retrieved using the VIX API.
• 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.

Side Effects

Requirements

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;
}
// Release handle after use:
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;
}
// Release handle after use:
Vix_ReleaseHandle(jobHandle);

// Power on the virtual machine before copying file.
jobHandle = VixVM_PowerOn(vmHandle,
                          0, // powerOnOptions
                          VIX_INVALID_HANDLE, // propertyListHandle
                          NULL, // callbackProc
                          NULL); // clientData

err = VixJob_Wait(jobHandle,VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
// Release handle after use:
Vix_ReleaseHandle(jobHandle);

// Create snapshot in powered-on state.
jobHandle = VixVM_CreateSnapshot(vmHandle,
                                 NULL, // name
                                 NULL, // description
                                 VIX_SNAPSHOT_INCLUDE_MEMORY, // options
                                 VIX_INVALID_HANDLE, // propertyListHandle
                                 NULL, // callbackProc
                                 NULL); // clientData
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &snapshotHandle,
                  VIX_PROPERTY_NONE);

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