PrlVm_Reg Function

Creates a new virtual machine and registers it with the Parallels Service.

Syntax

PRL_HANDLE PrlVm_Reg(
    PRL_HANDLE hVm, 
    PRL_CONST_STR sVmParentPath, 
    PRL_BOOL bNonInteractiveMode
);

File

PrlApi.h

Parameters

hVm

A handle of type PHT_VIRTUAL_MACHINE identifying the virtual machine.

sVmParentPath

Optional. Name and path of the parent directory where the virtual machine directory should be created. If this parameter is omitted (null pointer or empty string is passed), the new virtual machine directory will be created in the default directory for this Parallels Service.

bNonInteractiveMode

Specifies if a non-interactive mode should be used. If set to PRL_TRUE , non-interactive mode will be used. If set to PRL_FALSE , interactive mode will be used. In interactive mode, the Parallels Service may ask client questions. Once a question is asked, the client must create and send a valid answer to the Parallels Service in order for the operation to continue.

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 steps involved in creating a typical virtual machine are:

Obtain a handle to a new virtual machine object using the PrlSrv_CreateVm function.
Populate the object with the desired configuration data.
Choose a name for the virtual machine and set it using the PrlVmCfg_SetName function.
Create and register the new machine with a Parallels Service using the PrlVm_Reg function. This step will create the necessary virtual machine files on the host and will add the machine to the Parallels Service VM registry. The directory containing the virtual machine files will have the same name as the name you've chosen for your virtual machine. The directory will be created in the default VM root directory for this Parallels Service. If you would like to create the virtual machine directory in a different location, you may specify the desired parent directory name and path.

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.

Example

The following example shows how to create a new virtual machine. The sample assumes that the client program has already obtained a server object handle (hServer) and performed the Parallels Service login operation.

PRL_HANDLE hVm;
PRL_HANDLE hResult;
PRL_RESULT nJobRetCode;
PRL_RESULT ret;

// Obtain a new virtual machine handle.
ret = PrlSrv_CreateVm(hServer, &hVm);
if (PRL_FAILED(ret))
{
    // Error handling goes here...
    return ret;
}

// Get the host config info.
hJob = PrlSrv_GetSrvConfig(hServer);
ret = PrlJob_Wait(hJob, 10000);

// Check the return code of PrlSrv_GetSrvConfig.
PrlJob_GetRetCode(hJob, &nJobRetCode);
if (PRL_FAILED(nJobRetCode))
{
    fprintf(stderr, "Error: %s\n", PRL_RESULT_TO_STRING(nJobRetCode));
    PrlHandle_Free(hJob);
    PrlHandle_Free(hVm);
    return nJobRetCode;
}

// Get a handle to the object containing the result of PrlSrv_GetSrvConfig,
// and then get a handle to the server configuration object from it.
ret = PrlJob_GetResult(hJob, &hResult);
PRL_HANDLE hSrvCfg;
PrlResult_GetParam(hResult, &hSrvCfg);

// Delete the job and the result handles.
PrlHandle_Free(hJob);
PrlHandle_Free(hResult);

// Now that we have the host machine configuration data,
// we can set the default configuration for the new virtual machine.
ret = PrlVm_SetDefaultConfig(
                hVm, // VM handle.
                hSrvCfg, // Host config data.
                PVS_GUEST_TYPE_WINDOWS, // Target OS type.
                PVS_GUEST_VER_WIN_2003, // Target OS version.
                PRL_TRUE); // Create and connect devices.

if (PRL_FAILED(ret))
{
    fprintf(stderr, "Error: %s\n", PRL_RESULT_TO_STRING(ret));
    PrlHandle_Free(hSrvCfg);
    PrlHandle_Free(hVm);
    return ret;
}

PrlHandle_Free(hSrvCfg);

// Set the virtual machine name.
ret = PrlVm_SetName(hVm, "My Windows Server 2003");

// The following two calls demonstrate how to modify
// some of the default values of the virtual machine configuration.
// These calls are optional. You may remove them to use the default values.

// Set the RAM size for the machine to 256 MB.
ret = PrlVm_SetRamSize(hVm, 256);

// Set the virtual hard disk size to 20 GB.
// First, get the handle to the hard disk object using the
// PrlVm_GetHardDisk function. The index of 0 is used
// because the default configuration has just one virtual hard disk.
// After that, use the handle to set the disk size to the desired value.

PRL_HANDLE hHDD;
ret = PrlVm_GetHardDisk(hVm, 0, &hHDD);
ret = PrlVmDevHd_SetDiskSize(hHDD, 20000);

// Create and register the machine with the Parallels Service.
hJob = PrlVm_Reg(hVm, // VM handle.
                 "", // VM root directory (using default).
                 PRL_TRUE); // Using non-interactive mode.

// Wait for the operation to complete.
ret = PrlJob_Wait(hJob, 10000);

// Check the return code of PrlVm_Reg.
PrlJob_GetRetCode(hJob, &nJobRetCode);
if (PRL_FAILED(nJobRetCode))
{
    fprintf(stderr, "Error: %s\n", PRL_RESULT_TO_STRING(nJobRetCode));
    PrlHandle_Free(hJob);
    PrlHandle_Free(hVm);
    return nJobRetCode;
}

// Delete handles.
PrlHandle_Free(hJob);
PrlHandle_Free(hVm);

Links

PrlApi.h , PHT_VIRTUAL_MACHINE , Example