Creating a New Virtual Machine

The first step in creating a new virtual machine is to create a blank virtual machine and register it with the Parallels Service. A blank virtual machine is the equivalent of a hardware box with no operating system installed on the hard drive. Once a blank virtual machine is created and registered, it can be powered on and an operating system can be installed on it.

In this section, we will discuss how to create a typical virtual machine for a particular OS type using a sample configuration. By using this approach, you can easily create a virtual machine without knowing all of the little details about configuring a virtual machine for a particular operating system type.

The steps involved in creating a typical virtual machine are:

1. Obtain a new handle of type PHT_VIRTUAL_MACHINE using the PrlSrv_CreateVm function. The handle will identify our new virtual machine.
2. Obtain a handle of type PHT_VM_CONFIGURATION by calling the PrlVm_GetConfig function. The handle is used for manipulating virtual machine configuration settings.
3. Set the default configuration parameters based on the version of the OS that you will later install in the virtual machine. This step is performed using the PrlVmCfg_SetDefaultConfig function. You supply the version of the target OS, and the function will generate the appropriate configuration parameters automatically. The OS version parameter value is specified using predefined macros. The names of the macros are prefixed with PVS_GUEST_VER_. You can find the macro definitions in the C API Reference guide or in the PrlOses.h file. In addition to the OS information, the PrlVmCfg_SetDefaultConfig function allows to specify the physical host configuration which will be used to connect the virtual devices inside a virtual machine to their physical counterparts. The devices include floppy disk drive, CD drive, serial and parallel ports, sound card, etc. To connect the available host devices, obtain a handle of type PHT_SERVER_CONFIG (physical host configuration) using the PrlSrv_GetSrvConfig function. The handle should then be passed to PrlVmCfg_SetDefaultConfig together with OS information and other parameters. If you don't want to connect the devices, set the hSrvConfig parameter to PRL_INVALID_HANDLE.
4. Choose a name for the new virtual machine and set it using the PrlVmCfg_SetName function.
5. Modify some of the default configuration parameters if needed. For example, you may want to modify the hard disk image type and size, the amount of memory available to the machine, and the networking options. You will have to obtain an appropriate handle for the type of the parameter that you would like to modify and call one of its functions to perform the modification. The code sample below shows how to modify some of the default values.
6. Create and register the new machine using the PrlVm_Reg function. This step will create the necessary virtual machine files on the host and register the machine with the Parallels Service. The directory containing the virtual machine files will have the same name as the virtual machine name. The directory will be created in the default location 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.

The following sample demonstrates 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 login operation.

PRL_HANDLE hVm = PRL_INVALID_HANDLE;

PRL_HANDLE hVmCfg = PRL_INVALID_HANDLE;

PRL_HANDLE hResult = PRL_INVALID_HANDLE;

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 hosts configuration handle from it.

ret = PrlJob_GetResult(hJob, &hResult);

PRL_HANDLE hSrvCfg = PRL_INVALID_HANDLE;

PrlResult_GetParam(hResult, &hSrvCfg);

// Free job and result handles.

PrlHandle_Free(hJob);

PrlHandle_Free(hResult);

// Now that we have the host configuration data,

// we can set the default configuration for the new virtual machine.

ret = PrlVm_GetConfig(hVm, &hVmCfg);

ret = PrlVmCfg_SetDefaultConfig(

                hVmCfg,                 // VM config handle.

                hSrvCfg,                // Host config data.

                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(hVmCfg);

    PrlHandle_Free(hVm);

    return ret;

}

PrlHandle_Free(hSrvCfg);

// Set the virtual machine name.

ret = PrlVmCfg_SetName(hVmCfg, "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 RAM size for the machine to 256 MB.

ret = PrlVmCfg_SetRamSize(hVmCfg, 256);

// Set virtual hard disk size to 20 GB.

// First, get the handle to the hard disk object using the

// PrlVmCfg_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.

PRL_HANDLE hHDD = PRL_INVALID_HANDLE;

ret = PrlVmCfg_GetHardDisk(hVmCfg, 0, &hHDD);

ret = PrlVmDevHd_SetDiskSize(hHDD, 20000);

// Create and register the machine with the Parallels Service.

// This is an asynchronous call. Returns a job handle.

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(hVmCfg);

    PrlHandle_Free(hVm);

    return nJobRetCode;

}

// Delete handles.

PrlHandle_Free(hJob);

PrlHandle_Free(hVmCfg);

PrlHandle_Free(hVm);