Creating a Template From Scratch

The steps in creating a new template and the steps in creating a new virtual machine are exactly the same, with one exception: before registering a template with the Parallels Service, a call to PrlVmCfg_SetTemplateSign function must be made passing the PRL_TRUE in the bVmIsTemplate parameter. This will set a flag in the configuration structure indicating that you want to create a template, not a regular virtual machine. The rest of the configuration parameters are set exactly as they are set for a regular virtual machine. See the Creating a New Virtual Machine section for the detailed information about creating a virtual machine.

The following example illustrates how to create a virtual machine template. For simplicity reasons, we only set a template name in this example. The rest of the configuration parameters are omitted. As a result, a blank template will be created. It still can be used to create new virtual machines from it but you will not be able to run them until you configure them properly. Once again, the Creating a New Virtual Machine section provides all the necessary information and code samples needed to properly configure a virtual machine or a template.

PRL_RESULT CreateTemplateFromScratch(PRL_HANDLE hServer)

{

    PRL_HANDLE hVm = PRL_INVALID_HANDLE;

    PRL_HANDLE hJob = PRL_INVALID_HANDLE;

    PRL_RESULT ret = PRL_ERR_UNINITIALIZED;

    PRL_RESULT nJobReturnCode = PRL_ERR_UNINITIALIZED;

    // Create a new virtual machine handle.

    ret = PrlSrv_CreateVm(hServer, &hVm);

    if (PRL_FAILED(ret))

    {

        // Handle the error...

        return -1;

    }

    // Set the name for the new template.

    ret = PrlVmCfg_SetName(hVm, "A simple template");

    if (PRL_FAILED(ret))

    {

        // Handle the error...

        PrlHandle_Free(hVm);

        return -1;

    }

    // Set a flag indicating to create a template.

    PRL_BOOL isTemplate = PRL_TRUE;

    ret = PrlVmCfg_SetTemplateSign(hVm, isTemplate);

    if (PRL_FAILED(ret))

    {

        // Handle the error...

        PrlHandle_Free(hVm);

        return -1;

    }

    // Create and register the new template.

    // The empty string in the configuration path

    // indicates to create a template in the default

    // virtual machine directory.

    // The bNonInteractiveMode parameter indicates not to

    // use interactive mode (the Service will not send questions

    // to the client and will make all decisions on its own).

    PRL_CHAR_PTR sVmConfigPath = "";

    PRL_BOOL bNonInteractiveMode = PRL_TRUE;

    hJob = PrlVm_Reg(hVm, sVmConfigPath, bNonInteractiveMode);

    // Wait for the job to complete.

    ret = PrlJob_Wait(hJob, 1000);

    if (PRL_FAILED(ret))

    {

        // Handle the error...

        PrlHandle_Free(hJob);

        PrlHandle_Free(hVm);

        return -1;

    }

    // Analyze the result of PrlVm_Reg.

    ret = PrlJob_GetRetCode(hJob, &nJobReturnCode);

    if (PRL_FAILED(ret))

    {

        // Handle the error...

        PrlHandle_Free(hJob);

        PrlHandle_Free(hVm);

        return -1;

    }

    // Check the job return code.

    if (PRL_FAILED(nJobReturnCode))

    {

        // Handle the error...

        PrlHandle_Free(hJob);

        PrlHandle_Free(hVm);

        return -1;

    }

    PrlHandle_Free(hJob);

    PrlHandle_Free(hVm);

    return 0;

}