Name

VixVM_Clone

Description

VixHandle
VixVM_Clone(VixHandle vmHandle,
            VixHandle snapshotHandle,
            VixCloneType cloneType,
            const char *destConfigPathName,
            VixCloneOptions options,
            VixHandle propertyListHandle,
            VixEventProc *callbackProc,
            void *clientData);

Creates a copy of the virtual machine specified by the 'vmHandle' parameter.

Parameters

vmHandle

Identifies a virtual machine, which is referred to as the clone's parent. Call VixVM_Open() to create a virtual machine handle.

snapshotHandle

Optional. A snapshot belonging to the virtual machine specified by the 'vmHandle' parameter. If you pass VIX_INVALID_HANDLE, the clone will be based off the current state of the virtual machine. If you pass a valid snapshot handle, the clone will be a copy of the state of the virtual machine at the time the snapshot was taken.

cloneType

Must be either VIX_CLONETYPE_FULL or VIX_CLONETYPE_LINKED.

VIX_CLONETYPE_FULL - Creates a full, independent clone of the virtual machine.
VIX_CLONETYPE_LINKED - Creates a linked clone, which is a copy of a virtual machine that shares virtual disks with the parent virtual machine in an ongoing manner. This conserves disk space as long as the parent and clone do not change too much from their original state.

destConfigPathName

The path name of the virtual machine configuration file that will be created for the virtual machine clone produced by this operation. This should be a full absolute path name, with directory names delineated according to host system convention: \ for Windows and / for Linux.

options

Must be 0.

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

This function is asynchronous, and uses a job object to report when the operation is complete. The function returns a handle to the job object immediately. When the job is signaled, the virtual machine handle of the resulting clone is stored as the VIX_PROPERTY_JOB_RESULT_HANDLE property of the job object.
It is not possible to create a full clone of a powered on virtual machine. You must power off or suspend a virtual machine before creating a full clone of that machine.
With a suspended virtual machine, requesting a linked clone results in error 3007 VIX_E_VM_IS_RUNNING. Suspended virtual machines retain memory state, so proceeding with a linked clone could cause loss of data.
A linked clone must be based on a virtual machine's snapshot. If a clone of this type is requested and VIX_INVALID_HANDLE is passed as the 'snapshotHandle' parameter, a new snapshot will be created by the function. This snapshot will reflect the current state of the virtual machine and will be used as a basis for the linked clone.
A linked clone must have access to the parent's virtual disks. Without such access, you cannot use a linked clone at all because its file system will likely be incomplete or corrupt.
Deleting a virtual machine that is the parent of a linked clone renders the linked clone useless.
Because a full clone does not share virtual disks with the parent virtual machine, full clones generally perform better than linked clones. However, full clones take longer to create than linked clones. Creating a full clone can take several minutes if the files involved are large.
This function is not supported when using the VIX_SERVICEPROVIDER_VMWARE_PLAYER host type.

Side Effects

If the 'cloneType' parameter is VIX_CLONETYPE_LINKED and the 'snapshotHandle' parameter is VIX_INVALID_HANDLE, then the function will create a snapshot of the current virtual machine state and use that to created the linked clone.

Requirements

vix.h, since VMware Workstation 6.5 (not supported on VMware Server)

Example

VixError err = VIX_OK;
VixHandle hostHandle = VIX_INVALID_HANDLE;
VixHandle jobHandle = VIX_INVALID_HANDLE;
VixHandle vmHandle = VIX_INVALID_HANDLE;
VixHandle cloneVMHandle = 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_FAILED(err)) {
   // Handle the error...
   goto abort;
}
// Release handle after use.
Vix_ReleaseHandle(jobHandle);

jobHandle = VixVM_Open(hostHandle,
                       "c:\\Virtual Machines\\vm1\\ubuntu.vmx",
                       NULL, // callbackProc
                       NULL); // clientData
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &vmHandle,
                  VIX_PROPERTY_NONE);
if (VIX_FAILED(err)) {
   // Handle the error...
   goto abort;
}
Vix_ReleaseHandle(jobHandle);

// Create a clone of this virtual machine.
jobHandle = VixVM_Clone(vmHandle,
                        VIX_INVALID_HANDLE,  // snapshotHandle
                        VIX_CLONETYPE_LINKED,  // cloneType
                        "c:\\Virtual Machines\\vm2\\ubuntuClone.vmx",  // destConfigPathName
                        0,  //options,
                        VIX_INVALID_HANDLE,  // propertyListHandle
                        NULL,  // callbackProc
                        NULL);  // clientData
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &cloneVMHandle,
                  VIX_PROPERTY_NONE);
if (VIX_FAILED(err)) {
   // Handle the error...
   goto abort;
}
Vix_ReleaseHandle(jobHandle);

// You can use the new virtual machine as you would any other virtual machine. 
// For example, to power on the new clone:
jobHandle = VixVM_PowerOn(cloneVMHandle,
                          VIX_VMPOWEROP_LAUNCH_GUI,
                          VIX_INVALID_HANDLE,
                          NULL,
                          NULL);
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_NONE);
if (VIX_FAILED(err)) {
   // Handle the error...
   goto abort;
}

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