Searching for Parallels Servers

This topic applies to Parallels Server only.

If you have multiple Parallels Servers running on your network and don't know their exact locations and/or connection parameters, you can search for them using the PrlSrv_LookupParallelsServers function. The function returns the information as a list of handles of type PHT_SERVER_INFO, each containing the information about an individual Parallels Server. The information includes host name, port number, version of the OS that a host is running, Parallels Server version number, and the global ID (UUID). This information can then be used to establish a connection with the Parallels Server of interest (you will have to know the correct user name and password in addition to the returned parameters).

The PrlSrv_LookupParallelsServers 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 first. The callback function pointer must then be passed to the PrlSrv_LookupParallelsServers as a parameter. During the search operation, the callback function will be called for every Parallels Server found and a handle of type PHT_SERVER_INFO containing the Parallels Server information will be passed to it. Searching an entire local area network can take a significant time, so using a callback is the recommended approach.

To use the PrlSrv_LookupParallelsServers 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.

Note: The PrlSrv_LookupParallelsServers function can be executed without being logged in to a Parallels Service. For example, if you are writing an application with a user interface, you can search the network for available Parallels Servers and present the list to the user so that he/she can select a server to connect to.

The following sample functions demonstrate how to search local network for Parallels Servers. The first sample function calls the PrlSrv_LookupParallelsServers function synchronously. The second function takes an asynchronous approach.

PRL_RESULT SearchServersSynch()

{

// Variables for handles.

PRL_HANDLE hJob = PRL_INVALID_HANDLE; // job handle

PRL_HANDLE hJobResult = PRL_INVALID_HANDLE; // job result

PRL_HANDLE hHostConfig = PRL_INVALID_HANDLE; // PHT_SERVER_CONFIG

// Variables for return codes.

PRL_RESULT ret = PRL_ERR_UNINITIALIZED;

PRL_RESULT nJobReturnCode = PRL_ERR_UNINITIALIZED;

// Search for Parallels servers.

hJob = PrlSrv_LookupParallelsServers(

1000, // timeout

NULL, // callback function (not used)

NULL // user object pointer (not used)

);

// Wait for the job to complete.

ret = PrlJob_Wait(hJob, 10000);

if (PRL_FAILED(ret))

{

// Handle the error...

PrlHandle_Free(hJob);

fprintf(stderr, "Error: %s. \n",

prl_result_to_string(ret));

return -1;

}

// Analyze the result of PrlSrv_LookupParallelsServers.

ret = PrlJob_GetRetCode(hJob, &nJobReturnCode);

if (PRL_FAILED(ret))

{

// Handle the error...

PrlHandle_Free(hJob);

return -1;

}

// Get the job return code.

if (PRL_FAILED(nJobReturnCode))

{

// Handle the error...

PrlHandle_Free(hJob);

return -1;

}

// Get job result.

ret = PrlJob_GetResult(hJob, &hJobResult);

PrlHandle_Free(hJob);

if (PRL_FAILED(ret))

{

// Handle the error...

return -1;

}

// Get the number of objects returned.

PRL_UINT32 nCount = 0;

PrlResult_GetParamsCount(hJobResult, &nCount);

// Iterate and a obtain handle to each object.

for (PRL_UINT32 i = 0; i < nCount ; ++i)

{

PRL_HANDLE hParam = PRL_INVALID_HANDLE;

PrlResult_GetParamByIndex(hJobResult, i, &hParam);

PRL_CHAR sBuf[1024];

PRL_UINT32 nBufSize = sizeof(sBuf);

// Get the host name.

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

if (PRL_SUCCEEDED(ret))

{

printf("Found Parallels Server: %s\n", sBuf);

}

else

{

fprintf(stderr, "Error: %s \n",

prl_result_to_string(ret));

}

PrlHandle_Free(hParam);

}

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

static PRL_RESULT ourCallback(PRL_HANDLE hEvent, PRL_VOID_PTR pUserData)

{

printf("%s: ", pUserData);

// Get the host name.

PRL_UINT32 nBufSize = 1024;

PRL_CHAR sBuf[nBufSize];

PrlSrvInfo_GetHostName(hEvent, sBuf, &nBufSize);

// Get the other server properties and process them here, if needed...

// The handle must be freed.

PrlHandle_Free(hEvent);

return rc;

}