|
|
|
|
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 1. 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(hJobResult);
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; // 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.