PrlApi.h

A handle of type PHT_JOB containing the results of this asynchronous operation or PRL_INVALID_HANDLE if there's not enough memory to instantiate the job object.

The function can be executed asynchronously using the callback functionality, or it can be used synchronously.

To use the function asynchronously, you must implement a callback function and pass a pointer to it to this function as a parameter. The callback function will be called for every Parallels Service found, and a handle of type PHT_SERVER_INFO containing the Parallels Service information will be passed to it.

To use this function synchronously, pass a null pointer instead of the callback function pointer, and use PrlJob_Wait to wait for the job to complete. The returned job object will contain a list of PHT_SERVER_INFO objects.

To get the return code from the PHT_JOB object, use the PrlJob_GetRetCode function. Possible values are:

PRL_ERR_INVALID_ARG - invalid handle was passed.

PRL_ERR_SUCCESS - function completed successfully.

To get the results from the PHT_JOB object:

1. Use the PrlJob_GetResult function to obtain a handle to the PHT_RESULT object.
2. Use the PrlResult_GetParamsCount function to get the number of servers in the result set.
3. Use the PrlResult_GetParamByIndex function in a loop, or by passing a specific index, to obtain a handle to each server object.

The following example illustrates how to call the PrlSrv_LookupParallelsServers synchronously.

hJob =
PrlSrv_LookupParallelsServers(
    10000,  // timeout
    NULL,   // callback function (not used)
    NULL    // user object pointer (not used)
);

printf("Searching for Parallels Services...\n");

nRetCode =
PrlJob_Wait(hJob, 100000);

if (PRL_FAILED(nRetCode))
{
    fprintf(stderr, "PrlJob_Wait returned with error: %s.\n",
        PRL_RESULT_TO_STRING( nRetCode));
    PrlApi_Deinit();
    SdkWrap_Unload();
    return nRetCode;
}

PrlJob_GetResult(hJob, &hJobResult);
PrlHandle_Free(hJob);

PRL_UINT32 nIndex, nCount;
PrlResult_GetParamsCount(hJobResult, &nCount);

for (nIndex = 0; nIndex < nCount ; nIndex++)
{
    PRL_HANDLE hParam;
    PrlResult_GetParamByIndex(hJobResult, nIndex, &hParam);

    PRL_CHAR sBuf[1024];
    PRL_UINT32 nBufSize = sizeof(sBuf);

    nRetCode =
    PrlSrvInfo_GetHostName(hParam, sBuf, &nBufSize);

    if (PRL_SUCCEEDED(nRetCode))
        printf("Found Service: %s.\n", &sBuf[0]);
    else
        fprintf(stderr, "PrlSrvInfo_GetHostName failed, error: %s. \n",
            PRL_RESULT_TO_STRING(nRetCode));

    PrlHandle_Free(hParam);
}

PrlHandle_Free(hJobResult);

In the following example, the PrlSrv_LookupParallelsServers is called asynchronously. In order to that, we first have to implement a callback function (let's call it ourCallback):

static PRL_RESULT ourCallback(PRL_HANDLE hEvent, PRL_VOID_PTR pUserData)
{
    printf("%s: ", pUserData);

    // Get the name of the host machine.
    PRL_UINT32 nBufSize = 1024;
    PRL_CHAR sBuf[nBufSize];
    PrlSrvInfo_GetHostName(hEvent, sBuf, &nBufSize);

    // Get the other properties and process them here...

    // The handle must be freed.
    PrlHandle_Free(hEvent);
    return rc;
}

The PrlSrv_LookupParallelsServers function can now be called as follows:

hJob =
PrlSrv_LookupParallelsServers(
    1000,
    &ourCallback,
    (PRL_VOID_PTR)("callback")
);