PrlSrv_LookupParallelsServers Function

Searches the network for running Parallels Services and returns a handle of type PHT_SERVER_INFO for every Parallels Service that it finds.

Syntax

PRL_HANDLE PrlSrv_LookupParallelsServers(
    PRL_UINT32 timeout, 
    PRL_EVENT_HANDLER_PTR handler, 
    PRL_VOID_PTR userData
);

File

PrlApiDisp.h

Parameters

timeout

Timeout in milliseconds. The search operation will stop once this limit is reached.

handler

Optional. A pointer to a user callback function (event handler) that will be called every time a Parallels Service is found. The function will receive a handle of type PHT_SERVER_INFO containing the Parallels Service information.

userData

Optional. A pointer to a user data that will be passed to the optional callback function.

Returns

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.

Remarks

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:

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

Example

The following example illustrates how to call the PrlSrv_LookupParallelsServers synchronously.

Copy Code

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):

Copy Code

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:

Copy Code

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

Links

PHT_SERVER, Example