PrlVm_GetSnapshotsTree Function

Retrieves snapshot information for the specified virtual machine.

Syntax

PRL_HANDLE PrlVm_GetSnapshotsTree(
    PRL_HANDLE hVm
);

File

PrlApiVm.h

Parameters

handle

A handle of type PHT_VIRTUAL_MACHINE identifying the virtual machine.

flags

A flags from enum PRL_GET_SNAPSHOT_TREE_FLAGS and PRL_API_COMMAND_FLAGS

Returns

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.

Remarks

Snapshot information is returned as an XML file containing the snapshot tree. Some of the important XML elements are:

SavedStateItem -- the root element of the branch containing information about an individual snapshot. The element has an attribute "guid" containing the snapshot ID. The ID is required when performing other operations on a snapshot.

Name -- contains the snapshot name.

DateTime -- the snapshot creation date and time.

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 a snapshot tree from the PHT_JOB object:

Use the PrlJob_GetResult function to obtain a handle to the PHT_RESULT object.
Use the PrlResult_GetParamAsString function to obtain a string value containing the snapshots tree XML data.

Please note that no parser is provided to traverse the returned XML. To use this functionality, you will have to parse the returned XML yourself. This function will be replaced in the future releases of the Parallels SDK.