Obtaining the Virtual Machines List

Any virtual machine operation begins with obtaining a handle of type PHT_VIRTUAL_MACHINE identifying the virtual machine. Once a handle identifying a virtual machine is obtained, its functions can be used to perform a full range of virtual machine operations. This sections describes how to obtain a list of handles, each identifying an individual 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:

1. Log in to the Parallels Service and obtain a handle of type PHT_SERVER . See Obtaining Server Handle and Logging In for more info and code samples.
2. Call PrlSrv_GetVmList . This is an asynchronous function that returns a handle of type PHT_JOB .
3. Call 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.
4. Free the job handle using PrlHandle_Free as it is no longer needed.
5. Call PrlResult_GetParamsCount to determine the number of virtual machines contained in the PHT_RESULT object.
6. Call the 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.
7. Use functions of the PHT_VIRTUAL_MACHINE object to obtain the virtual machine information. For example, use PrlVmCfg_GetName to obtain the virtual machine name.
8. Free the virtual machine handle using PrlHandle_Free .
9. Free the result handle using PrlHandle_Free .

The following sample function implements the steps described above.

PRL_RESULT GetVmList(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 the 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);

printf("\nVirtual Machines:\n");

for (PRL_UINT32 i = 0; i < nParamsCount; ++i)

{

PRL_HANDLE hVm = PRL_INVALID_HANDLE; // virtual machine handle

// Get a handle to the 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(" (%d) %s\n\n", i+1, szVmNameReturned);

}

// Free the virtual machine handle.

PrlHandle_Free(hVm);

}

return PRL_ERR_SUCCESS;

}