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;

}