Name
Clone
Description
HRESULT
Clone(ISnapshot* snapshot,
LONG cloneType,
BSTR destConfigPathName,
LONG cloneOptions,
IVixHandle* propertyList,
ICallback* jobDoneCallback,
IJob** cloneJob)
Creates a copy of the virtual machine specified by the 'vmHandle' parameter.
Parameters
- snapshot
-
Optional. A snapshot belonging to this virtual machine. If you pass
NULL (C++), null (C#), or Nothing (VB), the clone will be based off the
current state of the virtual machine. If you pass a valid snapshot object, the
clone will be a copy of the state of the virtual machine at the time the snapshot
was taken.
- cloneType
-
Must be either VixCOM.Constants.VIX_CLONETYPE_FULL or
VixCOM.Constants.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 NULL (C++), null (C#), or Nothing (VB).
- jobDoneCallback
-
An ICallback instance that will be called when the
operation is complete.
- cloneJob
-
Returns an IJob object that describes the state of this
asynchronous operation.
Return Value
HRESULT
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
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 NULL (C++), null (C#), or Nothing (VB) is passed as the 'snapshot' 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.
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
VixCOM.h, since VMware Workstation 6.5
(not supported on VMware Server)
Example
VBScript:
Set job = host.OpenVM("c:\Virtual Machines\vm1\ubuntu.vmx", Nothing)
err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE), results)
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If
vm = results(0)
' Create a clone of this virtual machine.
Set job = vm.Clone(Nothing, VixCOM.Constants.VIX_CLONETYPE_LINKED, _
"c:\\Virtual Machines\\vm2\\ubuntuClone.vmx", 0, Nothing, Nothing)
err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE), results)
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If
cloneVM = results(0)
' You can use the new virtual machine as you would any other virtual machine.
' For example, to power on the new clone:
cloneVM.PowerOn(VixCOM.Constants.VIX_VMPOWEROP_LAUNCH_GUI, Nothing, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If