|
|
|
|
The Parallels C API contains synchronous and asynchronous functions. Synchronous functions run in the same thread as the caller and have a return type of
PRL_RESULT
. When a synchronous function is called, it completes executing before returning control to the client application.
Some functions are time consuming, like starting a virtual machine on a remote host. It makes sense to execute such functions within their own thread (ie. asynchronously). Asynchronous functions have a return type of
PRL_HANDLE.
The general procedure for using asynchronous functions is as follows:
The Callback Function (Event Handler)
Asynchronous functions return data to the caller by means of an
event handler
(or
callback function
). The callback function could be called at any time, depending on how long the asynchronous function takes to complete. The callback function must have a specific signature. The prototype can be found in
PrlApi.h
and is as follows:
typedef PRL_METHOD_PTR(PRL_EVENT_HANDLER_PTR) (
PRL_HANDLE hEvent,
PRL_VOID_PTR data
);
An example of a callback function implementation:
static PRL_RESULT OurCallback(PRL_HANDLE handle, void *pData)
{
// Event handler code...
// You must always release the handle before exiting.
PrlHandle_Free(handle);
}
A handle received by the callback function can be of type
PHT_EVENT
or
PHT_JOB
. The type can be determined using the
PrlHandle_GetType
function. The
PHT_EVENT
type indicates that the callback was called by a system event. If the type is
PHT_JOB
then the callback was called by an asynchronous job.
To handle system events within a callback function:
PrlEvent_GetType
.
PHT_EVENT_PARAMETER
can be extracted using
PrlEvent_GetParam
.
PHT_EVENT_PARAMETER
handle to the appropriate handle type using
PrlEvtPrm_ToHandle
.
To handle jobs within a callback function:
PrlJob_GetType
. A job type can be used to identify the function that started the job and to determine the type of the result it contains. For example, a job of type
PJOC_SRV_GET_VM_LIST
is started by
PrlSrv_GetVmList
function call, which returns a list of virtual machines.
PrlJob_GetRetCode
. If it doesn't contain an error, proceed to the next step.
PHT_RESULT)
from the job handle using
PrlJob_GetResult
.
PrlResult_GetParam
. Note that some functions return a list (ie. there can be more than a single parameter in the result). For example,
PrlSrv_GetVmList
returns a list of available virtual machines. In such cases, use
PrlResult_GetParamCount
and
PrlResult_GetParamByIndex
.
Note: You must always free the handle that was passed to the callback function before exiting, regardless of whether you actually used it or not. Failure to do so will result in a memory leak.
The following skeleton code demonstrates implementation of the above steps. In this example, the objective is to handle events of type
PET_DSP_EVT_HOST_STATISTICS_UPDATED
that are generated by a call to function
PrlSrv_SubscribeToHostStatistics
, and to obtain the result from a job of type
PJOC_SRV_GET_VM_LIST
.
static PRL_RESULT OurCallbackFunction(PRL_HANDLE hHandle, PRL_VOID_PTR pUserData)
{
PRL_JOB_OPERATION_CODE nJobType = PJOC_UNKNOWN; // job type
PRL_HANDLE_TYPE nHandleType = PHT_ERROR; // handle type
PRL_HANDLE hVm = PRL_INVALID_HANDLE; // virtual machine handle
PRL_HANDLE hParam = PRL_INVALID_HANDLE; // event parameter
PRL_HANDLE hJobResult = PRL_INVALID_HANDLE; // job result
PRL_UINT32 nParamsCount = -1; // parameter count
PRL_UINT32 nParamIndex = -1; // parameter index
PRL_RESULT err = PRL_ERR_UNINITIALIZED; // error
// Check the type of the received handle.
PrlHandle_GetType(hHandle, &nHandleType);
if (nHandleType == PHT_EVENT) // Event handle
{
PRL_EVENT_TYPE EventType;
PrlEvent_GetType(hHandle, &EventType);
// Check if the event type is a statistics update.
if (EventType == PET_DSP_EVT_HOST_STATISTICS_UPDATED)
{
// Get handle to PHT_EVENT_PARAMETER.
PRL_HANDLE hEventParameters;
PrlEvent_GetParam(hHandle, 0, &hEventParameters);
// Get handle to PHT_SYSTEM_STATISTICS.
PRL_HANDLE hServerStatistics;
PrlEvtPrm_ToHandle(hEventParameters, &hServerStatistics);
// Code goes here to extract the statistics data
// using hServerStatistics.
PrlHandle_Free(hServerStatistics);
PrlHandle_Free(hEventParameters);
}
}
else if (nHandleType == PHT_JOB) // Job handle
{
// Get job type.
PrlJob_GetOpCode(hHandle, &nJobType);
// Check if the job type is PJOC_SRV_GET_VM_LIST.
if (nJobType == PJOC_SRV_GET_VM_LIST)
{
// Check the job return code.
PRL_RESULT nJobRetCode;
PrlJob_GetRetCode(hHandle, &nJobRetCode);
if (PRL_FAILED(nJobRetCode))
{
fprintf(stderr, "[B]%.8X: %s\n", nJobRetCode,
prl_result_to_string(nJobRetCode));
PrlHandle_Free(hHandle);
return nJobRetCode;
}
err = PrlJob_GetResult(hHandle, &hJobResult);
// if (err != PRL_ERR_SUCCESS), process the error here.
// Determine the number of parameters in the result.
PrlResult_GetParamsCount(hJobResult, &nParamsCount);
// Iterate through the parameter list.
for(nParamIndex = 0; nParamIndex < nParamsCount ; nParamIndex++)
{
// Obtain a virtual machine handle (PHT_VIRTUAL_MACHINE).
PrlResult_GetParamByIndex(hJobResult, nParamIndex, &hVm);
// Code goes here to obtain virtual machine info from hVm.
// Free the handle when done using it.
PrlHandle_Free(hVm);
}
PrlHandle_Free(hJobResult);
}
}
PrlHandle_Free(hHandle);
return PRL_ERR_SUCCESS;
}
Registering / Unregistering an Event Handler
The
PrlSrv_RegEventHandler
function is used to register an event handler,
PrlSrv_UnregEventHandler
is used to unregister an event handler.
Note: When an event handler is registered, it will receive all of the events/jobs regardless of their origin. It is the responsibility of the client application to identify the type of the event and to handle each one accordingly.
// Register an event handler.
ReturnDataClass rd; // some user-defined class.
PrlSrv_RegEventHandler(hServer, OurCallbackFunction, &rd);
// Make a call to an asynchronous function here.
// OurCallbackFunction will be called by the background thread
// as soon as the job is completed, and code within
// OurCallbackFunction can populate the ReturnDataClass instance.
// For example, we can make the following call here:
hJob = PrlSrv_GetVmList(hServer);
PrlHandle_Free(hJob);
// Please note that we still have to obtain the
// job object (hJob above) and free it; otherwise
// we will have memory leaks.
// Unregister the event handler when it is no longer needed.
PrlSrv_UnregEventHandler(hServer, OurCallbackFunction, &rd);
Using Asynchronous Functions Synchronously
It is possible to use an asynchronous function like a synchronous function by using
PrlJob_Wait
and
PrlJob_GetRetCode
.
PrlJob_Wait
takes two parameters - the handle of an asynchronous job that has been executed, and a timeout value in milliseconds. The timeout value is the maximum amount of time
PrlJob_Wait
will wait before timing out. If the asynchronous job completes before this timeout value, then
PrlJob_Wait
will exit and execution of the calling thread will continue.
The following code snippet illustrates how to call an asynchronous function
PrlServer_Login
in a synchronous manner:
// Log in (PrlSrv_Login is asynchronous).
PRL_HANDLE hJob = PrlSrv_Login(
hServer,
szHostnameOrIpAddress,
szUsername,
szPassword,
0,
0,
0,
PSL_LOW_SECURITY);
// Wait for a maximum of 10 seconds for
// asynchronous function PrlSrv_Login to complete.
ret = PrlJob_Wait(hJob, 10000);
if (PRL_FAILED(ret))
{
fprintf(stderr, "PrlJob_Wait for PrlSrv_Login returned with error: %s\n",
prl_result_to_string(ret));
PrlHandle_Free(hJob);
PrlHandle_Free(hServer);
return -1;
}
// Analyse the result of the PrlServer_Login call.
PRL_RESULT nJobResult;
ret = PrlJob_GetRetCode(hJob, &nJobResult);
if (PRL_FAILED(nJobResult))
{
PrlHandle_Free(hJob);
PrlHandle_Free(hServer);
printf("Login job returned with error: %s\n",
prl_result_to_string(nJobResult));
return -1;
}
else
{
printf("login successfully performed\n");
}