Searching for Virtual Machine by Name

This section contains am example of how to obtain a handle of type PHT_VIRTUAL_MACHINE identifying the virtual machine using the virtual machine name as a search parameter. We will use the sample as a helper function in the later section of this guide that demonstrate how to perform operations on virtual machines. The sample is based on the code provided in the Obtaining the Virtual Machine List section.

// Obtains a handle of type PHT_VIRTUAL_MACHINE using the

// virtual machine name as a search parameter.

// Parameters

//  hServer: A handle of type PHT_SERVER.

//  sVmName: The name of the virtual machine.

//  hVm: [out] A handle of type PHT_VIRTUAL_MACHINE

//             identifying the virtual machine.

PRL_RESULT GetVmByName(PRL_HANDLE hServer, PRL_STR sVmName, PRL_HANDLE &hVm)

{

    PRL_HANDLE hResult = PRL_INVALID_HANDLE;

    PRL_RESULT nJobResult = PRL_INVALID_HANDLE;

    // Get a list of available virtual machines.

    PRL_HANDLE hJob = PrlSrv_GetVmList(hServer);

    PRL_RESULT ret = PrlJob_Wait(hJob, 10000);

    if (PRL_FAILED(ret))

    {

        // Handle the error...

        PrlHandle_Free(hJob);

        PrlHandle_Free(hServer);

        return ret;

    }

    // Check the results of PrlSrv_GetVmList.

    ret = PrlJob_GetRetCode(hJob, &nJobResult);

    if (PRL_FAILED(nJobResult))

    {

        // Handle the error...

        PrlHandle_Free(hJob);

        PrlHandle_Free(hServer);

        return ret;

    }

    // Get the results of PrlSrv_GetVmList.

    ret = PrlJob_GetResult(hJob, &hResult);

    if (PRL_FAILED(ret))

    {

        // Handle the error...

        PrlHandle_Free(hJob);

        PrlHandle_Free(hServer);

        return ret;

    }

    PrlHandle_Free(hJob);

    // Iteratre through the results (list of virtual machines returned).

    PRL_UINT32 nParamsCount = 0;

    ret = PrlResult_GetParamsCount(hResult, &nParamsCount);

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

    {

        // Get a handle to result i.

        PrlResult_GetParamByIndex(hResult, i, &hVm);

        // Get the name of the virtual machine for result i.

        char vm_name[1024];

        PRL_UINT32 nBufSize = sizeof(vm_name);

        ret = PrlVmCfg_GetName(hVm, vm_name, &nBufSize);

        if (PRL_FAILED(ret))

        {

            // Handle the error...

            return PRL_ERR_FAILURE;

        }

        // If the name of the virtual machine at this index is equal to sVmName,

        // then this is the handle we need.

        if (strcmp(sVmName, vm_name) == 0)        

        {

            PrlHandle_Free(hResult);

            return PRL_ERR_SUCCESS;

        }

        // It's not the virtual machine being searched for, so free the handle to it.

        PrlHandle_Free(hVm);

    }

    // The specified virtual machine was not found.

    PrlHandle_Free(hResult);

    return PRL_ERR_NO_DATA;

}