This topic applies to Parallels Server only.
If you have multiple Parallels Services 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 Service. The information includes host name, port number, version of the OS that a host is running, Parallels Service version number, and the global ID (UUID). This information can then be used to establish a connection with the Parallels Service 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 Service found and a handle of type PHT_SERVER_INFO
containing the Service 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. If you are writing an application with a user interface, you can search the network for available Parallels Services and then present the list to the user so that he/she can select a Service to connect to.
The following sample functions demonstrate how to search local network for Parallels Services. 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 Service: %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 other Service properties and process them here, if needed...
// 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"));