Suspending and Pausing a Virtual Machine

Suspending a Virtual Machine

When a virtual machine is suspended, the information about its state is stored in non-volatile memory. A suspended virtual machine can resume operating in the same state it was in at the point it was placed into a suspended state. Resuming a virtual machine from a suspended state is quicker than starting a virtual machine from a stopped state.

To suspend a virtual machine, obtain a handle to the virtual machine, then call PrlVm_Suspend.

The following example will suspend a virtual machine called Windows XP - 01.

const char *szVmName = "Windows XP - 01";

// Get a handle to virtual machine with name szVmName.

PRL_HANDLE hVm = GetVmByName((char*)szVmName, hServer);

if (hVm == PRL_INVALID_HANDLE)

{

    fprintf(stderr, "Virtual machine \"%s\" was not found.\n", szVmName);

    PrlHandle_Free(hServer);

    PrlApi_Deinit();

    SdkWrap_Unload();

    exit(-1);

}

PRL_RESULT nJobResult;

PRL_HANDLE hJob = PrlVm_Suspend(hVm);

PRL_RESULT ret = PrlJob_Wait(hJob, 1000);

if (PRL_FAIL(ret))

{

    fprintf(stderr, "PrlJob_Wait for PrlVm_Suspend failed. Error: %s",

        prl_result_to_string(ret));

    PrlHandle_Free(hServer);

    PrlHandle_Free(hJob);

    PrlApi_Deinit();

    SdkWrap_Unload();

    exit(-1);

}

PrlJob_GetRetCode(hJob, &nJobResult);

if (PRL_FAILED(nJobResult))

{

    fprintf(stderr, "PrlVm_Suspend failed with error: %s\n",

        prl_result_to_string(nJobResult));

    PrlHandle_Free(hVm);

    PrlHandle_Free(hJob);

    PrlHandle_Free(hServer);

    PrlApi_Deinit();

    SdkWrap_Unload();

    return -1;

}

A suspended virtual machine can be stopped completely (placed into a "stopped" state) using the PrlVm_DropSuspendedState function.

Pausing a Virtual Machine

Pausing a virtual machine will pause execution of the virtual machine. This can be achieved using PrlVm_Pause. PrlVm_Pause takes two parameters: a handle to the virtual machine, and a boolean value indicating if ACPI should be used. The above example could be modified to pause a virtual machine by replacing the line:

PRL_HANDLE hJob = PrlVm_Suspend(hVm);

with:

PRL_HANDLE hJob = PrlVm_Pause(hVm, PRL_FALSE);

It would also be necessary to change the error messages accordingly.

Resuming / Continuing a Virtual Machine

A suspended or paused virtual machine can be restarted using PrlVm_Start. Alternatively, PrlVm_Resume can be used to resume execution of a suspended virtual machine.

Dropping Suspended State

A suspended virtual machine can be shut down using PrlVm_DropSuspendedState. If this is used, any unsaved data will be lost.