PrlResult_GetParamByIndex Function

Obtains a handle from the result object identified by the index.

Syntax

PRL_RESULT PrlResult_GetParamByIndex(
    PRL_HANDLE hResult, 
    PRL_UINT32 nIndex, 
    PRL_HANDLE_PTR phParam
);

File

PrlApiCore.h

Parameters

nIndex

An index identifying the handle in the list.

phParam

[out] A pointer to a variable that receives the handle. The type of handle returned depends on the corresponding operation. The description of each asynchronous function in this documentation provides information about the type of handle that the function returns.

handle

A handle of type PHT_RESULT identifying the result object.

Returns

PRL_RESULT. Possible values:

PRL_ERR_INVALID_ARG - invalid handle or null pointer was passed.

PRL_ERR_SUCCESS - function completed successfully.

Remarks

Use this function when the result contains (or may contain) multiple objects. To obtain multiple handles from the result object, first, determine the number of handles contained in the object using the PrlResult_GetParamsCount function. Then, iterate through the list and use the iteration number as the value of the nIndex parameter.

Example

The following example demonstrates using asynchronous function PrlSrv_GetVmList (getting the list of virtual machines), and the steps involved in obtaining handles to objects of type PHT_VIRTUAL_MACHINE returned by PrlSrv_GetVmList (each object contains information about an individual virtual machine):

PRL_RESULT DisplayVmList(const PRL_HANDLE &hServer)
{
    PRL_HANDLE hResult;
    PRL_RESULT nJobResult;

    // Get a list of virtual machines.
    PRL_HANDLE hJob = PrlSrv_GetVmList(hServer);

    // Wait for the job to complete.
    PRL_RESULT 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, &nJobResult);
    if (PRL_FAILED(nJobResult))
    {
        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, &hResult);
    if (PRL_FAILED(ret))
    {
        fprintf(stderr, "PrlJob_GetResult returned with error: %s\n",
            PRL_RESULT_TO_STRING(ret));
        PrlHandle_Free(hResult);
        PrlHandle_Free(hJob);
        return ret;
    }

    // Handle to result object is available,
    // job handle is not longer needed, so free it.
    PrlHandle_Free(hJob);

    // Iteratre through the result list.
    PRL_UINT32 nParamsCount = 0;
    ret = PrlResult_GetParamsCount(hResult, &nParamsCount);

    for (PRL_UINT32 i = 0; i < nParamsCount; ++i)
    {
        PRL_HANDLE hVm;

        // Get a handle to result at index i.
        PrlResult_GetParamByIndex(hResult, i, &hVm);

        // Get the name of the virtual machine for result i.
        char szVmNameReturned[1024];
        PRL_UINT32 nBufSize = sizeof(szVmNameReturned);
        ret = PrlVm_GetName(hVm, szVmNameReturned, &nBufSize);

        if (PRL_FAILED(ret))
        {
            printf("PrlVm_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;
}

Links

PHT_RESULT, Example