PrlApi.h

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.

The PrlVm_BeginEdit and the PrlVm_Commit functions are used to detect collisions with other clients trying to modify the same virtual machine at the same time. The PrlVm_BeginEdit call timestamps the beginning of the editing operation. It does not lock the machine, so other clients can modify the same machine at the same time. When you are done making the changes, you must call the PrlVm_Commit function to save them in the virtual machine configuration. The function will verify that the configuration has not been modified by another client. If a collision is detected, your changes will be rejected.

To get the return code from the PHT_JOB object, use the PrlJob_GetRetCode function. Possible values are:

PRL_ERR_INVALID_ARG - invalid handle or null pointer was passed.

PRL_ERR_SUCCESS - function completed successfully.

The following example illustrates how to use PrlVm_BeginEdit and PrlVm_Commit functions.

PRL_HANDLE hJobBeginEdit;
PRL_HANDLE hJobCommit;
PRL_RESULT nJobRetCode;

// Timestamp the beginning of the configuration changes operation.
hJobBeginEdit = PrlVm_BeginEdit(hVm);

// Wait for the job to complete.
ret = PrlJob_Wait(hJobBeginEdit, 10000);

// Check for errors.
PrlJob_GetRetCode(hJobBeginEdit, &nJobRetCode);

if (PRL_FAILED(nJobRetCode))
{
    fprintf(stderr, "Error: %s\n", PRL_RESULT_TO_STRING(nJobRetCode));
    PrlHandle_Free(hJobBeginEdit);
    return nJobRetCode;
}

// The code modifying configuration parameters goes here...

// Commit the changes when done.
hJobCommit = PrlVm_Commit(hVm);

// Wait for the job to complete.
ret = PrlJob_Wait(hJobCommit, 10000);

// Check the results of the commit operation.
PrlJob_GetRetCode(hJobCommit, &nJobRetCode);

if (PRL_FAILED(nJobRetCode))
{
    fprintf(stderr, "Commit error: %s\n", PRL_RESULT_TO_STRING(nJobRetCode));
    PrlHandle_Free(hJobCommit);
    return nJobRetCode;
}