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.
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

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

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