PrlVm_BeginEdit and PrlVm_Commit Functions

All virtual machine configuration changes must begin with the PrlVm_BeginEdit and end with the PrlVm_Commit call. These two functions are used to detect collisions with other clients trying to modify the configuration settings of the same virtual machine.

When PrlVm_BeginEdit is called, the Parallels Service timestamps the beginning of a configuration change(s) operation. It does not lock the machine, so other clients can make changes to the same virtual machine at the same time. The function will also automatically update your local virtual machine object with the current virtual machine configuration information. This is done in order to ensure that your local object contains the changes that might have have happened since you obtained the virtual machine handle.

When you are done making the changes, you must call the PrlVm_Commit function. The first thing that the function will do is verify that the virtual machine configuration has not been modified by other client(s) since you called the PrlVm_BeginEdit function. If it has been, your changes will be rejected and PrlVm_Commit will return with error. In such a case, you will have to reapply your changes. In order to do that, you will have to get the latest configuration using the PrlVm_GetConfig function, compare your changes with the latest changes, and make a decision about merging them. Please note that PrlVm_GetConfig function will update the configuration data in your current virtual machine object and will overwrite all existing data, including the changes that you've made to it. Furthermore, the PrlVm_BeginEdit function will also overwrite all existing data (see above). If you don't want to loose your data, save it locally before calling PrlVm_GetConfig or PrlVm_BeginEdit.

The following example demonstrates how to use the PrlVm_BeginEdit and PrlVm_Commit functions:

PRL_HANDLE hJobBeginEdit = PRL_INVALID_HANDLE;

PRL_HANDLE hJobCommit = PRL_INVALID_HANDLE;

PRL_RESULT nJobRetCode = PRL_INVALID_HANDLE;

// Timestamps the beginning of the "transaction".

// Updates the hVm object with current configuration data.

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;

}

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

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

}