Cloning a Virtual Machine

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:

1. A valid handle of type PHT_VIRTUAL_MACHINE containing information about the source virtual machine.
2. A unique name for the new virtual machine (the name is NOT generated automatically).
3. The name of the directory where the virtual machine files should be created (or an empty string to create the files in the default directory).
4. A boolean value specifying whether to create the new machine as a valid virtual machine or as a template. 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;

}