This sections describes how to obtain a list of virtual machines registered with a Parallels Service. If you would like to search for unregistered virtual machines on the host computer, please refer to the Searching for Virtual Machines section.
The steps that must be performed to obtain the virtual machine list are:
PHT_SERVER
. See Obtaining Server Handle and Logging In for more info and code samples.PrlSrv_GetVmList
. This is an asynchronous function that returns a handle of type PHT_JOB
.PrlJob_GetResults
passing the PHT_JOB
object obtained in step 2. This function returns a handle of type PHT_RESULT
containing the virtual machine list.PrlSrv_GetVmList
as it is no longer needed.PrlResult_GetParamsCount
to determine the number of virtual machines contained in the PHT_RESULT
object.PrlResult_GetParamByIndex
function in a loop passing an index from 0 to the total virtual machine count. The function obtains a handle of type PHT_VIRTUAL_MACHINE
containing information about an individual virtual machine.PHT_VIRTUAL_MACHINE
object to obtain the virtual machine information. For example, use PrlVmCfg_GetName
to obtain the virtual machine name.PrlHandle_Free
.PrlHandle_Free
.The following sample function implements the steps described above.
PRL_RESULT DisplayVmList(const PRL_HANDLE &hServer)
{
// Variables for handles.
PRL_HANDLE hJob = PRL_INVALID_HANDLE; // job handle
PRL_HANDLE hJobResult = PRL_INVALID_HANDLE; // job result
// Variables for return codes.
PRL_RESULT ret = PRL_ERR_UNINITIALIZED;
PRL_RESULT nJobReturnCode = PRL_ERR_UNINITIALIZED;
// Get a list of the available virtual machines.
hJob = PrlSrv_GetVmList(hServer);
// Wait for a maximum of 10 seconds for PrlSrv_GetVmList.
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);
return ret;
}
// Check the results of PrlSrv_GetVmList.
ret = PrlJob_GetRetCode(hJob, &nJobReturnCode);
if (PRL_FAILED(ret))
{
fprintf(stderr, "PrlJob_GetRetCode returned with error: %s\n",
prl_result_to_string(ret));
PrlHandle_Free(hJob);
return ret;
}
if (PRL_FAILED(nJobReturnCode))
{
fprintf(stderr, "PrlSrv_GetVmList returned with error: %s\n",
prl_result_to_string(ret));
PrlHandle_Free(hJob);
return ret;
}
// Get the results of PrlSrv_GetVmList.
ret = PrlJob_GetResult(hJob, &hJobResult);
if (PRL_FAILED(ret))
{
fprintf(stderr, "PrlJob_GetResult returned with error: %s\n",
prl_result_to_string(ret));
PrlHandle_Free(hJob);
return ret;
}
// Handle to the result object is available,
// job handle is no longer needed, so free it.
PrlHandle_Free(hJob);
// Iterate through the results (list of virtual machines returned).
PRL_UINT32 nParamsCount = 0;
ret = PrlResult_GetParamsCount(hJobResult, &nParamsCount);
for (PRL_UINT32 i = 0; i < nParamsCount; ++i)
{
PRL_HANDLE hVm = PRL_INVALID_HANDLE; // virtual machine handle
// Get a handle to result at index i.
PrlResult_GetParamByIndex(hJobResult, i, &hVm);
// Now that we have a handle of type PHT_VIRTUAL_MACHINE,
// we can use its functions to retrieve or to modify the
// virtual machine information.
// As an example, we will get the virtual machine name.
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));
}
else
{
printf("Virtual machine '%s' is available.\n\n",
szVmNameReturned);
}
// Free the virtual machine handle.
PrlHandle_Free(hVm);
}
return PRL_ERR_SUCCESS;
}
The rest of the examples in this chapter assume that the virtual machine handle has been obtained as shown in the example above.