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

Inheritance diagram for ISnapshot:

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
	Timestamp 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).

readonly attribute unsigned long	childrenCount
	Returns the number of direct children of this snapshot.

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 IMachine interface which also manage the media associated with the snapshot. The following operations exist:

IMachine::takeSnapshot creates a new snapshot by creating new, empty differencing images for the machine's media and saving the VM settings and (if the VM is running) the current VM state in the snapshot.

The differencing images will then receive all data written to the machine's media, while their parent (base) images remain unmodified after the snapshot has been taken (see IMedium for details about differencing images). This simplifies restoring a machine to the state of a snapshot: only the differencing images need to be deleted.

The current machine state is not changed by taking a snapshot except that IMachine::currentSnapshot is set to the newly created snapshot, which is also added to the machine's snapshots tree.
IMachine::restoreSnapshot resets a machine to the state of a previous snapshot by deleting the differencing image of each of the machine's media and setting the machine's settings and state to the state that was saved in the snapshot (if any).

This destroys the machine's current state. After calling this, IMachine::currentSnapshot points to the snapshot that was restored.
IMachine::deleteSnapshot deletes a snapshot without affecting the current machine state.

This does not change the current machine state, but instead frees the resources allocated when the snapshot was taken: the settings and machine state file are deleted (if any), and the snapshot's differencing image for each of the machine's media gets merged with its parent image.

Neither the current machine state nor other snapshots are affected by this operation, except that parent media will be modified to contain the disk data associated with the snapshot being deleted.

When deleting the current snapshot, the IMachine::currentSnapshot attribute is set to the current snapshot's parent or null if it has no parent. Otherwise the attribute is unchanged.

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 the Saved or AbortedSaved state, 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:: {6CC49055-DAD4-4496-85CF-3F76BCB3B5FA}

Member Data Documentation

◆ id

readonly attribute wstringUUID ISnapshot::id

UUID of the snapshot.

◆ name

attribute wstring ISnapshot::name

Short name of the snapshot.

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

◆ description

attribute wstring ISnapshot::description

Optional description of the snapshot.

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

◆ timeStamp

readonly attribute long long ISnapshot::timeStamp

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

◆ online

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.

◆ machine

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.

◆ parent

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).

◆ children

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.

◆ childrenCount

readonly attribute unsigned long ISnapshot::childrenCount

Returns the number of direct children of this snapshot.

Public Attributes