PrlResult_GetParam Function

Obtains a handle to an object containing the results of the corresponding asynchronous operation.

Syntax

PRL_RESULT PrlResult_GetParam(
    PRL_HANDLE hResult, 
    PRL_HANDLE_PTR pHandle
);

File

PrlApiCore.h

Parameters

hResult

A handle of type PHT_RESULT identifying the result object.

pHandle

[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.

Returns

PRL_RESULT. Possible values:

PRL_ERR_INVALID_ARG - invalid handle or null pointer was passed.

PRL_ERR_NO_DATA - no result or the result is not a single handle.

PRL_ERR_SUCCESS - function completed successfully.

Remarks

Use this function when you know that the corresponding function always produces a single object as a result. This function is the equivalent of the PrlResult_GetParamByIndex(hResult, 0, &Handle) call (i.e. zero as the index value).

Example

The following example demonstrates using asynchronous function PrlSrv_GetSrvConfig synchronously, and the steps involved in obtaining a handle to an object of type PHT_SERVER_CONFIG (which is returned by PrlSrv_GetSrvConfig):

PRL_HANDLE hJob = PrlSrv_GetSrvConfig(hServer);

// Step 1 - emulate a synchronous call using PrlJob_Wait.

PRL_RESULT ret = PrlJob_Wait(hJob, 10000);
if (PRL_FAILED(ret))
{
    printf("PrlJob_Wait for job PrlSrv_GetSrvConfig returned error: %s\n",
        PRL_RESULT_TO_STRING(ret));

    PrlHandle_Free(hJob);
    PrlHandle_Free(hServer);
    PrlApi_Deinit();
    SdkWrap_Unload();
    return -1;
}

// Step 2 - determine if PrlSrv_GetSrvConfig succeeded or failed
// using PrlJob_GetRetCode.

PrlJob_GetRetCode(hJob, &nJobResult);
if (PRL_FAILED(nJobResult))
{
    printf("PrlSrv_GetSrvConfig returned error: %s\n",
        PRL_RESULT_TO_STRING(ret));

    PrlHandle_Free(hJob);
    PrlHandle_Free(hServer);
    PrlApi_Deinit();
    SdkWrap_Unload();
    return -1;
}

// Step 3 - Obtain a handle to the result object (a handle
// of type PHT_RESULT) using PrlJob_GetResult.

PRL_HANDLE hResult;
ret = PrlJob_GetResult(hJob, &hResult);
PrlHandle_Free(hJob); // hJob no longer needed, free it.

if (PRL_FAILED(ret))
{
    printf("PrlJob_GetResult for job PrlSrv_GetSrvConfig returned error: %s\n",
        PRL_RESULT_TO_STRING(ret));
    PrlHandle_Free(hResult);
    PrlHandle_Free(hServer);
    PrlApi_Deinit();
    SdkWrap_Unload();
    return -1;
}

// Step 4 - Get a handle to the final result (in this case,
// a handle of type PHT_SERVER_CONFIG) using PrlResult_GetParam.
// For PHT_RESULT handles that contain more than one result, first use
// PrlResult_GetParamsCount, then use PrlResult_GetParamByIndex.

PRL_HANDLE hServerConfig;
ret = PrlResult_GetParam(hResult, &hServerConfig);
PrlHandle_Free(hResult); // hResult no longer needed, free it.

if (PRL_FAILED(ret))
{
    printf("PrlResult_GetParam for job PrlSrv_GetSrvConfig returned error: %s\n",
        PRL_RESULT_TO_STRING(ret));

    PrlHandle_Free(hServerConfig);
    PrlHandle_Free(hServer);
    PrlApi_Deinit();
    SdkWrap_Unload();

    return -1;
}

// At this point, a handle of type PHT_SERVER_CONFIG is available, and
// functions that operate on PHT_SERVER_CONFIG handles can be used on
// the handle.

PRL_UINT32 nCpuCount = 0;
PrlSrvCfg_GetCpuCount(hServerConfig, &nCpuCount);
printf("Number of CPUs: %d\n", nCpuCount);

PRL_CPU_MODE CpuMode;
PrlSrvCfg_GetCpuMode(hServerConfig, &CpuMode);
printf("CPU Mode: %d bit\n", CpuMode == PCM_CPU_MODE_32 ? 32 : 64);

PRL_CHAR szCpuModel[1024];
PRL_UINT32 nCpuModelSize = sizeof(szCpuModel);
memset(szCpuModel, 0, nCpuModelSize);
PrlSrvCfg_GetCpuModel(hServerConfig, szCpuModel, &nCpuModelSize);
printf("CPU Model: %s\n", szCpuModel);

PRL_UINT32 nCpuSpeed = 0;
PrlSrvCfg_GetCpuSpeed(hServerConfig, &nCpuSpeed);
printf("CPU Speed: %.3f MHz\n", nCpuSpeed / 1000.0);

PRL_CHAR szHostOsString[1024];
PRL_UINT32 nHostOsStringSize = sizeof(szHostOsString);
PrlSrvCfg_GetHostOsStrPresentation(hServerConfig, szHostOsString, &nHostOsStringSize);
printf("Host OS: %s\n", szHostOsString);

PrlHandle_Free(hServerConfig);

Links

PHT_RESULT, Example