Searching for Virtual Machines

A host computer may have virtual machines on its hard drive that are not currently registered with the Parallels Service. This can happen when a virtual machine is removed from the Parallels Service registry but its files are kept on the drive, or when a virtual machine files are manually copied to the drive from another computer. Parallels C API provides the PrlSrv_StartSearchVms function that can be used to find such virtual machines on the specified host at the specified location on the hard drive. The function accepts a string containing a directory name and path and searches the directory and all its subdirectories for unregistered virtual machines. It then returns a list of PHT_FOUND_VM_INFO handles, each containing information about an individual virtual machine that it finds. You can then decide whether you want to keep the machine as-is, register it, or remove it from the hard drive.

Since the search operation may take a long time (depending on the size of the specified directory tree), the PrlSrv_StartSearchVms function should be executed using the callback functionality. The callback function will be called for every virtual machine found and a single instance of the PHT_FOUND_VM_INFO handle will be passed to it. As we discussed earlier in this guide, a callback function can receive two types of objects: jobs (PHT_JOB) and events (PHT_EVENT). In this instance, the information is passed to the callback function as an event of type PET_DSP_EVT_FOUND_LOST_VM_CONFIG. To following steps are involved in processing the event inside the callback function:

Determine the type of the event using the PrlHandle_GetType function. If it is PET_DSP_EVT_FOUND_LOST_VM_CONFIG then the data passed to the callback function contains information about an unregistered virtual machine. If not, then the event was generated by some other function and contains the data relevant to that function.
Use the PrlEvent_GetParam function to obtain a handle of type PHT_EVENT_PARAMETER (this is a standard event processing step).
Use the PrlEvtPrm_ToHandle function to obtain a handle of type PHT_FOUND_VM_INFO containing the virtual machine information.
Use functions of the PHT_FOUND_VM_INFO object to determine the location of the virtual machine files, the virtual machine name, guest OS version, and some other information.

The following is an implementation of the steps above:

static PRL_RESULT callback(PRL_HANDLE hEvent, PRL_VOID_PTR pUserData)

{

PRL_RESULT ret = PRL_ERR_UNINITIALIZED;

PRL_HANDLE_TYPE nHandleType;

PrlHandle_GetType(hEvent, &nHandleType);

// If this is a job, release the handle and exit.

// Normally, we would process this, if we were after

// a job.

if (nHandleType == PHT_JOB)

{

PrlHandle_Free(hEvent);

return 0;

}

// If it's not a job, then it is an event (PHT_EVENT).

// Get the type of the event received.

PRL_EVENT_TYPE eventType;

PrlEvent_GetType(hEvent, &eventType);

// Check the event type. If it's what we are looking for, process it.

if (eventType == PET_DSP_EVT_FOUND_LOST_VM_CONFIG)

{

PRL_UINT32 nParamsCount = 0;

// this will receive the event parameter handle.

PRL_HANDLE hParam = PRL_INVALID_HANDLE;

// The PrlEvent_GetParam function obtains a handle of type

// PHT_EVENT_PARAMETER.

ret = PrlEvent_GetParam(hEvent, 0, &hParam);

if (PRL_FAILED(ret))

{

fprintf(stderr, "[4]%.8X: %s\n", ret,

prl_result_to_string(ret));

PrlHandle_Free(hParam);

PrlHandle_Free(hEvent);

return ret;

}

PRL_HANDLE hFoundVmInfo = PRL_INVALID_HANDLE;

ret = PrlEvtPrm_ToHandle(hParam, &hFoundVmInfo);

if (PRL_FAILED(ret))

{

fprintf(stderr, "[9]%.8X: %s\n", ret,

prl_result_to_string(ret));

PrlHandle_Free(hParam);

PrlHandle_Free(hEvent);

return ret;

}

// Get the virtual machine name.

PRL_CHAR sName[1024];

PRL_UINT32 nBufSize = sizeof(sName);

ret = PrlFoundVmInfo_GetName(hFoundVmInfo, sName, &nBufSize);

printf("VM name: %s\n", sName);

// Get the name and path of the virtual machine directory.

PRL_CHAR sPath[1024];

nBufSize = sizeof(sPath);

ret = PrlFoundVmInfo_GetConfigPath(hFoundVmInfo, sPath, &nBufSize);

printf("Path: %s\n\n", sPath);

PrlHandle_Free(hFoundVmInfo);

PrlHandle_Free(hEvent);

return 0;

}

// The received event handler MUST be freed.

PrlHandle_Free(hEvent);

}

To begin the search operation, place the following code into your main program:

PRL_HANDLE hJob = PRL_INVALID_HANDLE;

PRL_RESULT ret = PRL_ERR_UNINITIALIZED;

PRL_RESULT nJobReturnCode = PRL_ERR_UNINITIALIZED;

// Register the event handler.

PrlSrv_RegEventHandler(hServer, &callback, NULL);

// Create a string list object and populate it

// with the name and path of the directory to search.

PRL_HANDLE hStringList = PRL_INVALID_HANDLE;

ret = PrlApi_CreateStringsList(&hStringList );

ret = PrlStrList_AddItem(hStringList, "/Users/Shared/Parallels/");

// Begin the search operation.

hJob = PrlSrv_StartSearchVms(hServer, hStringList);

PrlHandle_Free(hJob);

In order for the callback function to be called, your program should have a global loop (the program never exits on its own). The callback function will be called as soon as the first virtual machine is found. If there are no unregistered virtual machines in the specified directory tree, then the function will never be called as a PET_DSP_EVT_FOUND_LOST_VM_CONFIG event (it will still be called at least once as a result of the started job and will receive the job object but this and possibly other callback invocations are irrelevant in the context of this example).

Receiving the search results synchronously

It is also possible to use this function synchronously using the PrlJob_Wait function. In this case, the information is returned as a list of PHT_FOUND_VM_INFO objects contained in the job object returned by the PrlSrv_StartSearchVms function. The following example demonstrates how to call the function and to process results synchronously.

PRL_RESULT SearchVMsSample(PRL_HANDLE hServer)

{

PRL_HANDLE hJob = PRL_INVALID_HANDLE;

PRL_HANDLE hJobResult = PRL_INVALID_HANDLE;

PRL_HANDLE hFoundVmInfo = PRL_INVALID_HANDLE;

PRL_RESULT ret = PRL_ERR_UNINITIALIZED;

PRL_RESULT nJobReturnCode = PRL_ERR_UNINITIALIZED;

// Create a string list object and populate it

// with the name and path of the directory to search.

PRL_HANDLE hStringList = PRL_INVALID_HANDLE;

PrlApi_CreateStringsList(&hStringList );

PrlStrList_AddItem(hStringList, "/Users/Shared/Parallels/");

// Begin the search operation.

hJob = PrlSrv_StartSearchVms(hServer, hStringList);

// Wait for the job to complete.

ret = PrlJob_Wait(hJob, 1000);

if (PRL_FAILED(ret))

{

// Handle the error...

return -1;

}

// Analyze the result of PrlSrv_StartSearchVms.

ret = PrlJob_GetRetCode(hJob, &nJobReturnCode);

if (PRL_FAILED(ret))

{

// Handle the error...

PrlHandle_Free(hJob);

return -1;

}

// Check 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;

}

// Iterate through the returned list obtaining a

// handle of type PHT_FOUND_VM_INFO in each iteration containing

// the information about an individual virtual machine.

PRL_UINT32 nIndex, nCount;

PrlResult_GetParamsCount(hJobResult, &nCount);

for(nIndex = 0; nIndex < nCount ; nIndex++)

{

PrlResult_GetParamByIndex(hJobResult, nIndex, &hFoundVmInfo);

// Get the virtual machine name.

PRL_CHAR sName[1024];

PRL_UINT32 nBufSize = sizeof(sName);

ret = PrlFoundVmInfo_GetName(hFoundVmInfo, sName, &nBufSize);

printf("VM name: %s\n", sName);

// Get the name and path of the virtual machine directory.

PRL_CHAR sPath[1024];

nBufSize = sizeof(sPath);

ret = PrlFoundVmInfo_GetConfigPath(hFoundVmInfo, sPath, &nBufSize);

printf("Path: %s\n\n", sPath);

PrlHandle_Free(hFoundVmInfo);

}

PrlHandle_Free(hJobResult);

PrlHandle_Free(hStringList);

}

Top of page

Feedback