To start or stop a virtual machine, a handle to it must first be obtained. PrlVm_Start
and PrlVm_Stop
can then be used to start and stop the virtual machine respectively.
To obtain a handle to a virtual machine by the specified machine name, the following sample function can be used:
// ---------------------------------------------------------------
// Return a handle to VM with name szVmName.
// Returns:
// PRL_HANDLE to object of type PHT_VIRTUAL_MACHINE.
// PRL_ERR_INVALID_HANDLE is returned if the VM was not found.
// ---------------------------------------------------------------
PRL_HANDLE GetVmByName(char *szVmName, PRL_HANDLE &hServer)
{
PRL_HANDLE hResult = PRL_INVALID_HANDLE;
PRL_RESULT nJobResult = PRL_INVALID_HANDLE;
// Get a list of available virtual machines.
PRL_HANDLE hJob = PrlSrv_GetVmList(hServer);
// Wait for a maximum of 10 seconds for PrlSrv_GetVmList.
PRL_RESULT ret = PrlJob_Wait(hJob, 10000);
if (PRL_FAILED(ret))
{
fprintf(stderr, "PrlJob_Wait for PrlSrv_GetVmList returned with error: %s\n",
prl_result_to_string(ret));
PrlHandle_Free(hJob);
PrlHandle_Free(hServer);
exit(ret);
}
// Check the results of PrlSrv_GetVmList.
ret = PrlJob_GetRetCode(hJob, &nJobResult);
if (PRL_FAILED(nJobResult))
{
fprintf(stderr, "PrlSrv_GetVmList returned with error: %s\n",
prl_result_to_string(ret));
PrlHandle_Free(hJob);
PrlHandle_Free(hServer);
exit(ret);
}
// Get the results of PrlSrv_GetVmList.
ret = PrlJob_GetResult(hJob, &hResult);
if (PRL_FAILED(ret))
{
fprintf( stderr, "PrlJob_GetResult returned with error: %s\n",
prl_result_to_string(ret));
PrlHandle_Free(hJob);
PrlHandle_Free(hServer);
exit(ret);
}
PrlHandle_Free(hJob);
// Iteratre through the results (list of virtual machines returned).
PRL_UINT32 nParamsCount = 0;
ret = PrlResult_GetParamsCount(hResult, &nParamsCount);
for (PRL_UINT32 i = 0; i < nParamsCount; ++i)
{
PRL_HANDLE hVm = PRL_INVALID_HANDLE;
// Get a handle to result i.
PrlResult_GetParamByIndex(hResult, i, &hVm);
// Get the name of the virtual machine for result i.
char szVmNameReturned[1024];
PRL_UINT32 nBufSize = sizeof(szVmNameReturned);
ret = PrlVmCfg_GetName(hVm, szVmNameReturned, &nBufSize);
if (PRL_FAILED(ret))
{
printf("PrlVmCfg_GetName returned with error (%s)\n",
prl_result_to_string(ret));
}
// printf("VM extracted with name '%s'\n\n", szVmNameReturned);
// If the name of the virtual machine at this index is equal to szVmName,
// then return the handle this virtual machine handle.
if (strcmp(szVmName, szVmNameReturned) == 0)
{
PrlHandle_Free(hResult);
return hVm;
}
// It's not the virtual machine being searched for, so free the handle to it.
PrlHandle_Free(hVm);
}
// The virtual machine being searched for was not found, so
// free the results and return an invalid handle.
PrlHandle_Free(hResult);
return PRL_INVALID_HANDLE;
}
An example of using the above GetVmByName
function:
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();
return -1;
}
If GetVmByName
successfully returns a handle to a virtual machine, the virtual machine can be started or stopped.
An example of starting a virtual machine:
PRL_RESULT nVmStartResult;
PRL_HANDLE hVmStartJob = PrlVm_Start(hVm);
PrlJob_Wait(hVmStartJob, 10000);
PrlJob_GetRetCode(hVmStartJob, &nVmStartResult);
if (PRL_FAILED(nVmStartResult))
{
fprintf(stderr, "PrlVm_Start failed with error: %s\n",
prl_result_to_string(nVmStartResult));
PrlHandle_Free(hVm);
PrlHandle_Free(hVmStartJob);
PrlHandle_Free(hServer);
PrlApi_Deinit();
SdkWrap_Unload();
return -1;
}
else
{
printf("Successfully started VM \"%s\".\n", szVmName);
}
An example of stopping a virtual machine:
PRL_RESULT nVmStopResult;
PRL_HANDLE hVmStopJob = PrlVm_Stop(hVm, PRL_FALSE);
PrlJob_Wait(hVmStopJob, 10000);
PrlJob_GetRetCode(hVmStopJob, &nVmStopResult);
if (PRL_FAILED(nVmStopResult))
{
fprintf(stderr, "PrlVm_Stop failed with error: %s\n",
prl_result_to_string(nVmStopResult));
PrlHandle_Free(hVm);
PrlHandle_Free(hVmStopJob);
PrlHandle_Free(hServer);
PrlApi_Deinit();
SdkWrap_Unload();
return -1;
}
else
{
printf("Sucessfully stopped virtual machine \"%s\".\n", szVmName);
}
Note: 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 (ie. it is the same as turning off the power to a 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.
An example of resetting a virtual machine:
PRL_RESULT nVmResetResult;
PRL_HANDLE hVmResetJob = PrlVm_Reset(hVm);
PrlJob_Wait(hVmResetJob, 10000);
PrlJob_GetRetCode(hVmResetJob, &nVmResetResult);
if (PRL_FAILED(nVmResetResult))
{
fprintf(stderr, "PrlVm_Rest failed with error: %s\n",
prl_result_to_string(nVmResetResult));
PrlHandle_Free(hVm);
PrlHandle_Free(hVmResetJob);
PrlHandle_Free(hServer);
PrlApi_Deinit();
SdkWrap_Unload();
return -1;
}
Note: 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.