|
|
|
|
The Parallels API functions return one of the two types:
PRL_RESULT
or
PRL_HANDLE
.
Functions that return PRL_RESULT
The type
PRL_RESULT
is an integer. Functions that return
PRL_RESULT
are synchronous by definition. The return value indicates success or failure of the call.
Consider the
PrlSrv_Create
function. The purpose of this function is to obtain a handle of type
PHT_SERVER
. The handle is required to access most of the functionality within the Parallels C API. The definition of
PrlSrv_Create
is as follows:
PRL_RESULT PrlSrv_Create(
PRL_HANDLE_PTR handle
);
The following is an example of the
PrlSrv_Create
function call:
// Declare a handle variable.
PRL_HANDLE hServer;
// Call the PrlSrv_Create to obtain the handle.
PRL_RESULT res = PrlSrv_Create(&hServer);
// Examine the function return code.
// PRL_FAILED is a macro that evaluates a variable of type PRL_RESULT.
// A return value of True indicates success; False indicates failure.
if (PRL_FAILED(res))
{
printf("PrlSrv_Create returned error: %s\n",
prl_result_to_string(res));
PrlHandle_Free(hServer);
exit(ret);
}
Functions that return PRL_HANDLE
A function that has a return type of
PRL_HANDLE
is an asynchronous function. When an asynchronous function is called, it will generate events (or jobs that are sent to the event handler/callback function). An asynchronous function can be used in a synchronous manner (and hence negate the need to write an event handler) by using
PrlJob_Wait
. For more information about asynchronous functions, consult the section called
Asynchronous Functions
.
When calling an asynchronous function in a synchronous manner, the steps involved to obtain the end result are:
PrlJob_Wait
to wait for the asynchronous function to complete.
PrlJob_GetRetCode
to determine if the asynchronous function succeeded or failed.
PrlJob_GetResult
to obtain a handle to the result object (a
PHT_RESULT
handle).
PrlResult_GetParam
(or
PrlResult_GetParamsCount
and
PrlResult_GetParamByIndex
if the function returned more than one handle) to get the final result. The handle type returned depends on the function that was initially called.
The following example shows how to use asynchronous function
PrlSrv_GetSrvConfig
synchronously. It also shows 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 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_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);
For an example of working with a handle of type
PHT_RESULT
that contains multiple results (more than a single handle), see section
Obtaining a List of Virtual Machines
.