Starting, Stopping, Resetting a Virtual Machine

Note: When stopping or resetting a virtual machine, please be aware of the following important information:

Stopping a virtual machine is not the same as performing a guest operating system shutdown operation. When a virtual machine is stopped, it is a cold stop (i.e. it is the same as turning off the power to a physical computer). Any unsaved data will be lost. However, if the OS in the virtual machine supports ACPI (Advanced Configuration and Power Interface) then you can set the second parameter of the PrlVm_Stop function to PRL_FALSE in which case, the ACPI will be used and the machine will be properly shut down.

Resetting a virtual machine is not the same as performing a guest operating system restart operation. It is the same as pressing the "Reset" button on a physical box. Any unsaved data will be lost.

The following sample function demonstrates how start, stop, and reset a virtual machine.

PRL_RESULT StartStopResetVm(PRL_HANDLE hVm, VIRTUAL_MACHINE_STATE action)

{

    PRL_RESULT ret = PRL_ERR_UNINITIALIZED;

    PRL_HANDLE hJob = PRL_INVALID_HANDLE;

    PRL_RESULT nJobReturnCode = PRL_ERR_UNINITIALIZED;

    if (action == VMS_RUNNING)

    {

        // Start the virtual machine.

        hJob = PrlVm_Start(hVm);

        printf("Starting the virtual machine... \n");

    }

    else if (action == VMS_STOPPED)

    {

        // Stop the virtual machine.

        hJob = PrlVm_Stop(hVm, PRL_TRUE);

        printf("Stopping the virtual machine... \n");

    }

    else if (action == VMS_RESETTING)

    {

        // Reset the virtual machine.

        hJob = PrlVm_Reset(hVm);

        printf("Resetting the virtual machine... \n");

    }

    else

    {

        printf ("Invalid action type specified \n");

        return PRL_ERR_FAILURE;

    }

    PrlJob_Wait(hJob, 10000);

    PrlJob_GetRetCode(hJob, &nJobReturnCode);

    if (PRL_FAILED(nJobReturnCode))

    {

        printf ("Error: %s\n", prl_result_to_string(nJobReturnCode));

        PrlHandle_Free(hJob);

        return PRL_ERR_FAILURE;

    }

    return PRL_ERR_SUCCESS;

}