PrlSrv_StartSearchVms Function

Searches for unregistered virtual machines at the specified location(s).

Syntax

PRL_HANDLE PrlSrv_StartSearchVms(
    PRL_HANDLE hServer, 
    PRL_HANDLE hStringsList
);

File

PrlApiVm.h

Parameters

hServer

A handle of type PHT_SERVER identifying the Parallels Service.

hStringsList

A handle of type PHT_STRINGS_LIST containing the list of pathnames to search. If the list is empty, all available drives and directories will be included in search scope.

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 used to search for virtual machines that are not currently registered with the specified Parallels Service but are otherwise valid machines to be registered with it. The virtual machine information is returned as a list of PHT_FOUND_VM_INFO objects. When the function is executed asynchronously using callback functionality, the callback function receives the information as an event of type PET_DSP_EVT_FOUND_LOST_VM_CONFIG.

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 virtual machines in the list.
Use the PrlResult_GetParam function to obtain individual handles of type PHT_FOUND_VM_INFO.

Example

Copy Code

PRL_HANDLE hStringList;
PrlApi_CreateStringsList( &hStringList );
PrlStrList_AddItem( hStringList, "/Users/Shared/Parallels/" );

hJob =
PrlSrv_StartSearchVms( hServer, hStringList );
PrlJob_Wait( hJob, 10000 );

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_HANDLE_TYPE nHandleType;
    PrlHandle_GetType( hParam, &nHandleType );

    printf( "Handle Type: %s\n",
        PRL_HANDLE_TYPE_TO_STRING( nHandleType ));

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

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

    if ( PRL_SUCCEEDED( nRetCode ))
        printf( "VM name: %s\n.", sBuf );
    else
        fprintf( stderr, "PrlFoundVmInfo_GetName failed, error: %s. \n",
            PRL_RESULT_TO_STRING( nRetCode ));

    PrlHandle_Free( hParam );
}
PrlHandle_Free( hJobResult );
PrlHandle_Free( hStringList );

Links

PHT_SERVER, Example