Deleting a Virtual Machine

If a virtual machine is no longer needed, it can be removed. There are two options for removing a virtual machine:

1. Un-register the virtual machine using PrlVm_Unreg. This will remove the virtual machine from the list of the virtual machines registered with the Service. Once a virtual machine has been unregistered it is not possible to use it. The directory containing the virtual machine files will remain on the hard drive of the host computer, and the virtual machine can later be re-registered and used.
2. Delete the virtual machine using PrlVm_Delete. The virtual machine will be unregistered, and the directory (or just some of its files that you can specify) will be deleted.

The following example demonstrates un-registering a virtual machine. Note that this example makes use of a function called GetVmByName that can be found in the Obtaining a List of Virtual Machines section.

const char *szVmName = "Windows XP - 02";

// Get a handle to virtual machine with name szVmName.

PRL_HANDLE hVm = GetVmByName((char*)szVmName, hServer);

if (hVm == PRL_INVALID_HANDLE)

{

    fprintf(stderr, "VM \"%s\"was not found.\n", szVmName);

    PrlHandle_Free(hServer);

    PrlApi_Deinit();

    SdkWrap_Unload();

    return -1;

}

// Unregister a virtual machine.

PRL_HANDLE hJob = PrlVm_Unreg(hVm);

PRL_RESULT ret = PrlJob_Wait(hJob, 10000);

if (PRL_FAILED(ret))

{

    printf("PrlJob_Wait failed for PrlVm_Unreg. Error returned: %s\n",

        prl_result_to_string(ret));

    PrlHandle_Free(hVm);

    PrlHandle_Free(hJob);

    return -1;

}

PrlJob_GetRetCode(hJob, &nJobResult);

if (PRL_FAILED(nJobResult))

{

    printf("PrlVm_Unreg failed. Error returned: %s\n",

        prl_result_to_string(nJobResult));

    PrlHandle_Free(hVm);

    PrlHandle_Free(hJob);

    return -1;

}

The following example demonstrates deleting a virtual machine and deleting config.pvs within the virtual machine directory:

// Delete a virtual machine and a specified file.

PRL_HANDLE hDeviceList = PRL_INVALID_HANDLE;

PrlApi_CreateStringsList(&hDeviceList);

PrlStrList_AddItem(hDeviceList, "/Users/Shared/Parallels/WinXP02/config.pvs");

hJob = PrlVm_Delete(hVm, hDeviceList);

PrlHandle_Free(hDeviceList);

ret = PrlJob_Wait(hJob, 10000);

if (PRL_FAILED(ret))

{

    printf("PrlJob_Wait failed for PrlVm_Unreg. Error returned: %s\n", prl_result_to_string(ret));

    PrlHandle_Free(hVm);

    PrlHandle_Free(hJob);

    PrlHandle_Free(hServer);

    PrlApi_Deinit();

    SdkWrap_Unload();

    return -1;

}

PrlJob_GetRetCode(hJob, &nJobResult);

if (PRL_FAILED(nJobResult))

{

    printf("PrlVm_Delete failed. Error returned: %s\n", prl_result_to_string(nJobResult));

    PrlHandle_Free(hVm);

    PrlHandle_Free(hJob);

    PrlHandle_Free(hServer);

    PrlApi_Deinit();

    SdkWrap_Unload();

    return -1;

}

To delete the virtual machine and the virtual machine directory (all files belonging to the virtual machine), omit the line:

PrlStrList_AddItem(hDeviceList, "/Users/Shared/Parallels/WinXP02/config.pvs");

from the above example. Note that this operation is irreversible.