PrlVm_Clone Function

Clones an existing virtual machine.

Syntax

PRL_HANDLE PrlVm_Clone(
    PRL_HANDLE hVm, 
    PRL_CONST_STR new_vm_name, 
    PRL_CONST_STR new_vm_root_path, 
    PRL_BOOL bCreateTemplate
);

File

PrlApiVm.h

Parameters

hVm

A handle of type PHT_VIRTUAL_MACHINE identifying the virtual machine.

new_vm_name

The name to use for the new virtual machine.

new_vm_root_path

Name and path of the directory where the new virtual machine should be created. To create the machine in a default directory, pass an empty string.

bCreateTemplate

Specifies whether the clone should be created as a virtual machine or as a template. To create a template, set this parameter value to PRL_TRUE. To create a virtual machine, set it to PRL_FALSE. When creating a virtual machine from a template, set the parameter value to PRL_FALSE.

Returns

A handle of type PHT_JOB containing the results of this asynchronous operation or PRL_INVALID_HANDLE if there's not enough memory to instantiate the job object.

Remarks

The function creates an exact copy of the specified virtual machine on the same host using the specified new name and location. In order to perform a clone operation, the original machine must be registered with the Parallels Service. A clone can be created as a virtual machine or as a template. To create a template, set the bCreateTemplate parameter value to PRL_TRUE. The function can also be used to create new virtual machines from templates. In order to that, the hVm parameter must contain a handle to a template, the name and the path parameters must be set to desired values, and the bCreateTemplate parameter must be set to PRL_FALSE.

To get the return code from the PHT_JOB object, use the PrlJob_GetRetCode function. Possible values are:

PRL_ERR_INVALID_ARG - invalid handle or null pointer was passed.

PRL_ERR_SUCCESS - function completed successfully.

Links

PHT_VIRTUAL_MACHINE