PrlBootDev_SetSequenceIndex Function

Assigns a sequence index to a boot device in the boot priority list.

Syntax

PRL_RESULT PrlBootDev_SetSequenceIndex(
    PRL_HANDLE hVmBootDev, 
    PRL_UINT32 nSequenceIndex
);

File

PrlApiVm.h

Parameters

hVmBootDev

A handle of type PHT_BOOT_DEVICE identifying the boot device.

nSequenceIndex

The boot sequence index to set for the device. The value of 0 (zero) is the highest boot priority and indicates the first device to boot from. The value of 1 (one) indicates the second device to boot from, and so forth.

Returns

PRL_RESULT. Possible values:

PRL_ERR_INVALID_ARG - invalid handle or the device has been removed from the boot list.

PRL_ERR_SUCCESS - function completed successfully.

Remarks

The boot device sequence index starts with 0. When a virtual machine is powered on, it will first try to boot from the boot device that has a sequence index of 0. If it cannot boot from the device, it will try to boot from the device with sequence index 1, and so forth.

If you are changing a sequence index for an existing device, this is the only function that you have to call. If you are adding a new boot device to the list, you will have to set all the other properties, including the device index, type, and enabled/disabled flag. Please note that each device in the boot priority list must have a unique sequence index, so if you are modifying a sequence index for an existing device or assigning an index to a new device, you will have to make sure that no two devices have the same index.

See Also

PrlBootDev_GetSequenceIndex

Example

PRL_HANDLE hJobBeginEdit;
PRL_HANDLE hJobCommit;
PRL_RESULT nJobRetCode;

// Timestamp the beginning of the configuration changes operation.
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 boot options.
// Set boot device list as follows:
// 0. CD/DVD drive.
// 1. Hard disk.
// 2. Network adapter.
// 3. Floppy disk drive.
//
PRL_UINT32 nDevCount; // Device count.
PRL_HANDLE hDevice;   // A handle to the device.
PRL_DEVICE_TYPE devType; // Device type.

// Get the total number of devices.
ret = PrlVm_GetBootDevCount(hVm, &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 = PrlVm_GetBootDev(hVm, 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;
}

Links

PHT_BOOT_DEVICE, Example, See Also