To determine the current state of a virtual machine, first obtain a handle to the virtual machine as described in the Obtaining a List of Virtual Machines section. Then use the PrlVmCfg_GetState
function to obtain a handle of type PHT_VM_INFO
and call the PrlVmInfo_GetState
function to obtain the state information. The function returns the virtual machine state as an enumerator from the VIRTUAL_MACHINE_STATE
enumeration that defines every possible state and transition applicable to a virtual machine. The following table lists the available states and transitions:
Enumerator |
State/Transition |
Description |
|
State |
Unknown or unsupported state. |
|
State |
Virtual machine is stopped. |
|
Transition |
Virtual machine is starting. |
|
Transition |
Virtual machine is being restored from a snapshot. |
|
State |
Virtual machine is running. |
|
State |
Virtual machine is paused. |
|
Transition |
Virtual machine is going into "suspended" mode. |
|
Transition |
Virtual machine is stopping. |
|
Transition |
The Compact operation is being performed on a virtual machine. |
|
State |
Virtual machine is suspended. |
|
Transition |
A snapshot of the virtual machine is being taken. |
|
Transition |
Virtual machine is being reset. |
|
Transition |
Virtual machine is going into the "paused" mode. |
|
Transition |
Virtual machine is being brought back up from the "paused" mode. |
|
Transition |
Virtual machine is being migrated. |
|
Transition |
Virtual machine is being deleted. |
|
Transition |
Virtual machine is being resumed from the "suspended" mode. |
The following example demonstrates how obtain state/transition information for the specified virtual machine.
PRL_RESULT GetVMstate(PRL_HANDLE hVm)
{
PRL_HANDLE hJob = PRL_INVALID_HANDLE;
PRL_HANDLE hJobResult = PRL_INVALID_HANDLE;
PRL_HANDLE hVmInfo = PRL_INVALID_HANDLE;
PRL_RESULT ret = PRL_ERR_UNINITIALIZED;
PRL_RESULT nJobReturnCode = PRL_ERR_UNINITIALIZED;
// Obtain the PHT_VM_CONFIGURATION handle.
PRL_HANDLE hVmCfg = PRL_INVALID_HANDLE;
ret = PrlVm_GetConfig(hVm, &hVmCfg);
// Obtain a handle of type PHT_VM_INFO containing the
// state information. The object will also contain the
// virtual machine access rights info. We will discuss
// this functionality later in this guide.
hJob = PrlVm_GetState(hVmCfg);
// Wait for the job to complete.
ret = PrlJob_Wait(hJob, 1000);
if (PRL_FAILED(ret))
{
// Handle the error...
return -1;
}
// Analyze the result of PrlVm_GetState.
ret = PrlJob_GetRetCode(hJob, &nJobReturnCode);
if (PRL_FAILED(ret))
{
// Handle the error...
PrlHandle_Free(hJob);
return -1;
}
// Check the job return code.
if (PRL_FAILED(nJobReturnCode))
{
// Handle the error...
PrlHandle_Free(hJob);
return -1;
}
// Get job result.
ret = PrlJob_GetResult(hJob, &hJobResult);
PrlHandle_Free(hJob);
if (PRL_FAILED(ret))
{
// Handle the error...
return -1;
}
// Get the PHT_VM_INFO handle.
ret = PrlResult_GetParam(hJobResult, &hVmInfo);
PrlHandle_Free(hJobResult);
if (PRL_FAILED(ret))
{
// Handle the error...
return -1;
}
// Get the virtual machine state.
VIRTUAL_MACHINE_STATE vm_state = VMS_UNKNOWN;
ret = PrlVmInfo_GetState(hVmInfo, &vm_state);
if (PRL_FAILED(ret))
{
// Handle the error...
PrlHandle_Free(hVmInfo);
return -1;
}
switch (vm_state) {
case VMS_UNKNOWN:
printf("Unknown state\n");
break;
case VMS_STOPPED:
printf("Stopped\n");
break;
case VMS_STARTING:
printf("Starting...\n");
break;
case VMS_RESTORING:
printf("Restoring...\n");
break;
case VMS_RUNNING:
printf("Running\n");
break;
case VMS_PAUSED:
printf("Paused\n");
break;
case VMS_SUSPENDING:
printf("Suspending...\n");
break;
case VMS_STOPPING:
printf("Stopping...\n");
break;
case VMS_COMPACTING:
printf("Compacting...\n");
break;
case VMS_SUSPENDED:
printf("Suspended\n");
break;
default:
printf("Unknown state\n");
}
PrlHandle_Free(hVmCfg);
PrlHandle_Free(hVmInfo);
return 0;
}