A new virtual machine can also be created by cloning an existing virtual machine. The machine will be created as an exact copy of the source virtual machine and will be automatically registered with the Parallels Service. The cloning operation is performed using the PrlVm_Clone
function. The following parameters must be specified when cloning a virtual machine:
PHT_VIRTUAL_MACHINE
containing information about the source virtual machine.PRL_TRUE
indicates to create a template. PRL_FALSE
indicates to create a virtual machine. See the Working with Virtual Machine Templates section for more virtual machine info and examples.The source virtual machine must be registered with the Parallels Service before it can be cloned.
The following sample function demonstrates how to clone an existing virtual machine. When testing a function, the hVm
parameter must contain a valid handle of type PHT_VIRTUAL_MACHINE
(the source virtual machine to clone). On completion, the new virtual machine should appear in the list of registered virtual machines.
PRL_RESULT CloneVmSample(PRL_HANDLE hVm)
{
PRL_HANDLE hJob = PRL_INVALID_HANDLE;
PRL_RESULT nJobReturnCode = PRL_ERR_UNINITIALIZED;
PRL_RESULT ret = PRL_ERR_UNINITIALIZED;
// Declare and populate variables that
// will be used as input parameters
// in the function that clones a VM.
// Virtual machine name.
// Get the name of the original VM and use
// it in the new virtual machine name. You can
// use any name that you like of course.
char vm_name[1024];
PRL_UINT32 nBufSize = sizeof(vm_name);
PRL_HANDLE hVmCfg = PRL_INVALID_HANDLE;
ret = PrlVm_GetConfig(hVm, &hVmCfg);
ret = PrlVmCfg_GetName(hVmCfg, vm_name, &nBufSize);
char new_vm_name[1024] = "Clone of ";
strcat(new_vm_name, vm_name);
// Name of the target directory on the
// host.
// Empty string indicates that the default
// directory should be used.
PRL_CHAR_PTR new_vm_root_path = "";
// Virtual machine or template?
// The cloning functionality allows to create
// a new virtual machine or a new template.
// True indicates to create a template.
// False indicates to create a virtual machine.
// We are creating a virtual machine.
PRL_BOOL bCreateTemplate = PRL_FALSE;
// Begin the cloning operation.
hJob = PrlVm_Clone(hVm, new_vm_name, new_vm_root_path, bCreateTemplate);
// Wait for the job to complete.
ret = PrlJob_Wait(hJob, 1000);
if (PRL_FAILED(ret))
{
// Handle the error...
printf("Error: (%s)\n",
prl_result_to_string(ret));
PrlHandle_Free(hJob);
PrlHandle_Free(hVmCfg);
return -1;
}
// Analyze the result of PrlVm_Clone.
ret = PrlJob_GetRetCode(hJob, &nJobReturnCode);
if (PRL_FAILED(ret))
{
// Handle the error...
PrlHandle_Free(hJob);
PrlHandle_Free(hVmCfg);
return -1;
}
// Check the job return code.
if (PRL_FAILED(nJobReturnCode))
{
// Handle the error...
printf("Error: (%s)\n",
prl_result_to_string(nJobReturnCode));
PrlHandle_Free(hJob);
PrlHandle_Free(hVmCfg);
return -1;
}
PrlHandle_Free(hJob);
PrlHandle_Free(hVmCfg);
return 0;
}