PrlSrv_RegisterVm Function

Registers an existing virtual machine with Parallels Service.

Syntax

PRL_HANDLE PrlSrv_RegisterVm(
    PRL_HANDLE hServer, 
    PRL_CONST_STR strVmDirPath, 
    PRL_BOOL bNonInteractiveMode
);

File

PrlApiVm.h

Parameters

hServer

A handle of type PHT_SERVER identifying the Parallels Service.

strVmDirPath

An absolute path to the virtual machine directory to register.

bNonInteractiveMode

Set to PRL_TRUE to use non-interactive mode. Set to PRL_FALSE to use interactive mode. In interactive mode, a client may receive questions from the Parallels Service, which it is expected to answer in order for the operation to continue. In non-interactive mode, the Parallels Service will make decisions on its own.

Returns

A handle of type PHT_JOB containing the results of this asynchronous operation, including the return code and a handle of type PHT_VIRTUAL_MACHINE containing information about the virtual machine that was registered.

PRL_INVALID_HANDLE if there's not enough memory to instantiate the job object.

Remarks

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_GetParam function to obtain a handle of type PHT_VIRTUAL_MACHINE.

Example

The following sample function demonstrates how to add an existing virtual machine to the Parallels Service. The function takes a handle of type PHT_SERVER and a string specifying the name and path of the virtual machine directory. It registers the virtual machine with the Service and then modifies the MAC address of every virtual network adapter installed in it.

Copy Code

PRL_RESULT RegisterExistingVM(PRL_HANDLE hServer, PRL_CONST_STR sVmDirectory)
{
    PRL_HANDLE hJob = PRL_INVALID_HANDLE;
    PRL_HANDLE hJobResult = PRL_INVALID_HANDLE;

    PRL_RESULT ret = PRL_ERR_UNINITIALIZED;
    PRL_RESULT nJobRetCode = PRL_ERR_UNINITIALIZED;

    // Register the virtual machine with the Parallels Service.
    hJob = PrlSrv_RegisterVm(
        hServer,
        sVmDirectory,
        PRL_TRUE);  // Using non-interactive mode.

    ret = PrlJob_Wait(hJob, 10000);

    // Check the return code of PrlSrv_RegisterVm.
    PrlJob_GetRetCode(hJob, &nJobRetCode);
    if (PRL_FAILED(nJobRetCode))
    {
        printf("PrlSrv_RegisterVm returned error: %s\n",
            prl_result_to_string(nJobRetCode));
        PrlHandle_Free(hJob);
        return -1;
    }

    // Obtain the virtual machine handle from the job object.
    // We will use the handle later to modify the virtual machine
    // configuration.
    PRL_HANDLE hVm = PRL_INVALID_HANDLE;
    ret = PrlJob_GetResult(hJob, &hJobResult);
    if (PRL_FAILED(ret))
    {
        // Handle the error...
        return ret;
    }

    ret = PrlResult_GetParam(hJobResult, &hVm);
    if (PRL_FAILED(ret))
    {
        // Handle the error...
        return ret;
    }

    PrlHandle_Free(hJob);
    PrlHandle_Free(hJobResult);

    printf("Virtual machine '%s' was successfully registered.",
            sVmDirectory);

    // The following code will generate and set a new MAC address
    // for every virtual network adapter that exists in the virtual machine.
    // This step is optional and should normally be performed when the virtual
    // machine is a copy of another virtual machine.

    PRL_HANDLE hJobBeginEdit;
    PRL_HANDLE hJobCommit;

    // Begin the virtual machine editing operation.
    hJobBeginEdit = PrlVm_BeginEdit(hVm);
    ret = PrlJob_Wait(hJobBeginEdit, 10000);
    PrlJob_GetRetCode(hJobBeginEdit, &nJobRetCode);
    if (PRL_FAILED(nJobRetCode))
    {
        fprintf(stderr, "Error: %s\n", prl_result_to_string(nJobRetCode));
        PrlHandle_Free(hJobBeginEdit);
        return nJobRetCode;
    }

    // Obtain a handle of type PHT_VM_CONFIGURATION containing the
    // virtual machine configuration data.
    PRL_HANDLE hVmCfg = PRL_INVALID_HANDLE;
    ret = PrlVm_GetConfig(hVm, &hVmCfg);
    if (PRL_FAILED(ret))
    {
        // Handle the error...
        return ret;
    }

    // Determine the number of the network adapters
    // installed in the machine.
    PRL_UINT32 nCount = PRL_ERR_UNINITIALIZED;
    ret = PrlVmCfg_GetNetAdaptersCount(hVmCfg, &nCount);
    if (PRL_FAILED(ret))
    {
        // Handle the error...
        return ret;
    }

    // Itereate through the adapter list.
    PRL_HANDLE hNetAdapter = PRL_INVALID_HANDLE;
    for (PRL_UINT32 i = 0; i < nCount; ++i)
    {
        ret = PrlVmCfg_GetNetAdapter(hVmCfg, i, &hNetAdapter);
        if (PRL_FAILED(ret))
        {
            // Handle the error...
            return ret;
        }

        // Automatically generate new MAC address for the current adapter.
        // The address will be updated in the configuration object.
        ret = PrlVmDevNet_GenerateMacAddr(hNetAdapter);
        if (PRL_FAILED(ret))
        {
            // Handle the error...
            return ret;
        }
    }

    // Commit the changes to the virtual machine.
    hJobCommit = PrlVm_Commit(hVm);

    // Check the results of the commit operation.
    ret = PrlJob_Wait(hJobCommit, 10000);
    PrlJob_GetRetCode(hJobCommit, &nJobRetCode);
    if (PRL_FAILED(nJobRetCode))
    {
        fprintf(stderr, "Commit error: %s\n", prl_result_to_string(nJobRetCode));
        PrlHandle_Free(hJobCommit);
        return nJobRetCode;
    }

    PrlHandle_Free(hNetAdapter);
    PrlHandle_Free(hVm);
    PrlHandle_Free(hVmCfg);
    PrlHandle_Free(hJobCommit);
    PrlHandle_Free(hJobBeginEdit);

    return 0;
}

Links

PHT_SERVER, Example