Name, Description, Boot Options

The virtual machine name and description modifications are simple. They are performed using a single call for each parameter:

// Modify VM name.

ret = PrlVm_GetConfig(hVm, &hVmCfg);

ret = PrlVmCfg_SetName(hVmCfg, "New Name1");

// Modify VM description.

ret = PrlVmCfg_SetDescription(hVmCfg, "My updated VM");

To modify the boot options (boot device priority), first make the PrlVmCfg_GetBootDevCount call to determine the number of the available devices. Then obtain a handle to each device by making the PrlVmCfg_GetBootDev call in a loop. To place a device at the specified position in the boot device priority list, use the PrlBootDev_SetSequenceIndex function passing the device handle and the index (0 - first boot device, 1 - second boot device, and so forth).

The following sample illustrates how to make the above modifications.

PRL_HANDLE hJobBeginEdit = PRL_INVALID_HANDLE;

PRL_HANDLE hJobCommit = PRL_INVALID_HANDLE;

PRL_RESULT nJobRetCode = PRL_INVALID_HANDLE;

// Timestamp the beginning of the transaction.

hJobBeginEdit = PrlVm_BeginEdit(hVm);

ret = PrlJob_Wait(hJobBeginEdit, 10000);

PrlJob_GetRetCode(hJobBeginEdit, &nJobRetCode);

if (PRL_FAILED(nJobRetCode))

{

    fprintf(stderr, "Error: %s\n", prl_result_to_string(nJobRetCode));

    PrlHandle_Free(hJobBeginEdit);

    return nJobRetCode;

}

// Modify VM name.

ret = PrlVmCfg_SetName(hVmCfg, "New Name1");

// Modify VM description.

ret = PrlVmCfg_SetDescription(hVmCfg, "My updated VM");

// Modify boot options.

// Set boot device list as follows:

// 0. CD/DVD drive.

// 1. Hard disk.

// 2. Network adapter.

// 3. Floppy disk drive.

// Remove all other devices (if any) from the

// boot devices list for this VM.

// Device count.

PRL_UINT32 nDevCount;

// A handle identifying the device.

PRL_HANDLE hDevice = PRL_INVALID_HANDLE;

// Device type.

PRL_DEVICE_TYPE devType;

// Get the total number of devices.

ret = PrlVmCfg_GetBootDevCount(hVmCfg, &nDevCount);

// Iterate through the device list.

// Get a handle for each available device.

// Set an index for a device in the boot list.

for (int i = 0; i < nDevCount; ++i)

{

    ret = PrlVmCfg_GetBootDev(hVmCfg, i, &hDevice);

    ret = PrlBootDev_GetType(hDevice, &devType);

    if (devType == PDE_OPTICAL_DISK)

    {

        PrlBootDev_SetSequenceIndex(hDevice, 0);

    }

    if (devType == PDE_HARD_DISK)

    {

        PrlBootDev_SetSequenceIndex(hDevice, 1);

    }

    else if (devType == PDE_GENERIC_NETWORK_ADAPTER)

    {

        PrlBootDev_SetSequenceIndex(hDevice, 2);

    }

    else if (devType == PDE_FLOPPY_DISK)

    {

        PrlBootDev_SetSequenceIndex(hDevice, 3);

    }

    else

    {

        PrlBootDev_Remove(hDevice);

    }

}

// Commit the changes.

hJobCommit = PrlVm_Commit(hVm);

// Check the results of the commit operation.

ret = PrlJob_Wait(hJobCommit, 10000);

PrlJob_GetRetCode(hJobCommit, &nJobRetCode);

if (PRL_FAILED(nJobRetCode))

{

    fprintf(stderr, "Commit error: %s\n", prl_result_to_string(nJobRetCode));

    PrlHandle_Free(hJobCommit);

    return nJobRetCode;

}