Public Member Functions | Public Attributes

ISnapshot Interface Reference

The ISnapshot interface represents a snapshot of the virtual machine. More...

List of all members.

Public Member Functions

void getChildrenCount ([retval] out unsigned long childrenCount)
 Returns the number of direct children of this snapshot.

Public Attributes

readonly attribute wstringUUID id
 UUID of the snapshot.
attribute wstring name
 Short name of the snapshot.
attribute wstring description
 Optional description of the snapshot.
readonly attribute long long timeStamp
 Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
readonly attribute boolean online
 true if this snapshot is an online snapshot and false otherwise.
readonly attribute IMachine machine
 Virtual machine this snapshot is taken on.
readonly attribute ISnapshot parent
 Parent snapshot (a snapshot this one is based on), or null if the snapshot has no parent (i.e.
readonly attribute ISnapshot[] children
 Child snapshots (all snapshots having this one as a parent).

Detailed Description

The ISnapshot interface represents a snapshot of the virtual machine.

Together with the differencing media that are created when a snapshot is taken, a machine can be brought back to the exact state it was in when the snapshot was taken.

The ISnapshot interface has no methods, only attributes; snapshots are controlled through methods of the IConsole interface which also manage the media associated with the snapshot. The following operations exist:

Each snapshot contains a copy of virtual machine's settings (hardware configuration etc.). This copy is contained in an immutable (read-only) instance of IMachine which is available from the snapshot's machine attribute. When restoring the snapshot, these settings are copied back to the original machine.

In addition, if the machine was running when the snapshot was taken (IMachine::state is MachineState_Running), the current VM state is saved in the snapshot (similarly to what happens when a VM's state is saved). The snapshot is then said to be online because when restoring it, the VM will be running.

If the machine was in saved saved, the snapshot receives a copy of the execution state file (IMachine::stateFilePath).

Otherwise, if the machine was not running (MachineState_PoweredOff or MachineState_Aborted), the snapshot is offline; it then contains a so-called "zero execution state", representing a machine that is powered off.

Interface ID:
{0472823B-C6E7-472A-8E9F-D732E86B8463}

Member Function Documentation

void ISnapshot::getChildrenCount ( [retval] out unsigned long  childrenCount  ) 

Returns the number of direct children of this snapshot.

Parameters:
childrenCount 

Member Data Documentation

readonly attribute wstringUUID ISnapshot::id

UUID of the snapshot.

attribute wstring ISnapshot::name

Short name of the snapshot.

Note:
Setting this attribute causes IMachine::saveSettings to be called implicitly.
attribute wstring ISnapshot::description

Optional description of the snapshot.

Note:
Setting this attribute causes IMachine::saveSettings to be called implicitly.
readonly attribute long long ISnapshot::timeStamp

Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.

readonly attribute boolean ISnapshot::online

true if this snapshot is an online snapshot and false otherwise.

When this attribute is true, the IMachine::stateFilePath attribute of the machine object associated with this snapshot will point to the saved state file. Otherwise, it will be an empty string.

readonly attribute IMachine ISnapshot::machine

Virtual machine this snapshot is taken on.

This object stores all settings the machine had when taking this snapshot.

Note:
The returned machine object is immutable, i.e. no any settings can be changed.
readonly attribute ISnapshot ISnapshot::parent

Parent snapshot (a snapshot this one is based on), or null if the snapshot has no parent (i.e.

is the first snapshot).

readonly attribute ISnapshot [] ISnapshot::children

Child snapshots (all snapshots having this one as a parent).

By inspecting this attribute starting with a machine's root snapshot (which can be obtained by calling IMachine::findSnapshot with a null UUID), a machine's snapshots tree can be iterated over.