ISnapshot Interface Reference

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

List of all members.

Public Attributes

readonly attribute uuid 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).
readonly attribute
ISnapshotCollection 
children
 Child snapshots (all snapshots having this one as a parent).


Detailed Description

The ISnapshot interface represents a snapshot of the virtual machine.

The snapshot stores all the information about a virtual machine necessary to bring it to exactly the same state as it was at the time of taking the snapshot. The snapshot includes:

Snapshots can be offline (taken when the VM is powered off) or online (taken when the VM is running). The execution state of the offline snapshot is called a zero execution state (it doesn't actually contain any information about memory contents or the CPU state, assuming that all hardware is just powered off).

Snapshot branches

Snapshots can be chained. Chained snapshots form a branch where every next snapshot is based on the previous one. This chaining is mostly related to hard disk branching (see IHardDisk description). This means that every time a new snapshot is created, a new differencing hard disk is implicitly created for all normal hard disks attached to the given virtual machine. This allows to fully restore hard disk contents when the machine is later reverted to a particular snapshot.

In the current implelemtation, multiple snapshot branches within one virtual machine are not allowed. Every machine has a signle branch, and IConsole::takeSnapshot() operation adds a new snapshot to the top of that branch.

Existings snapshots can be discarded using IConsole::discardSnapshot().

Current snapshot

Every virtual machine has a current snapshot, identified by IMachine::currentSnapshot. This snapshot is used as a base for the current machine state (see below), to the effect that all normal hard disks of the machine and its execution state are based on this snapshot.

In the current implementation, the current snapshot is always the last taken snapshot (i.e. the head snapshot on the branch) and it cannot be changed.

The current snapshot is null if the machine doesn't have snapshots at all; in this case the current machine state is just current settings of this machine plus its current execution state.

Current machine state

The current machine state is what represened by IMachine instances got directly from IVirtualBox using getMachine(), findMachine(), etc. (as opposed to instances returned by ISnapshot::machine). This state is always used when the machine is powered on.

The current machine state also includes the current execution state. If the machine is being currently executed (IMachine::state is MachineState::Running and above), its execution state is just what's happening now. If it is powered off (MachineState::PoweredOff or MachineState::Aborted), it has a zero execution state. If the machine is saved (MachineState::Saved), its execution state is what saved in the execution state file (IMachine::stateFilePath).

If the machine is in the saved state, then, next time it is powered on, its execution state will be fully restored from the saved state file and the execution will continue from the point where the state was saved.

Similarly to snapshots, the current machine state can be discarded using IConsole::discardCurrentState().

Taking and discarding snapshots

The table below briefly explains the meaning of every snapshot operation:

Operation Meaning Remarks
IConsole::takeSnapshot() Save the current state of the virtual machine, including all settings, contents of normal hard disks and the current modifications to immutable hard disks (for online snapshots) The current state is not changed (the machine will continue execution if it is being executed when the snapshot is taken)
IConsole::discardSnapshot() Forget the state of the virtual machine stored in the snapshot: dismiss all saved settings and delete the saved execution state (for online snapshots) Other snapshots (including child snapshots, if any) and the current state are not directly affected
IConsole::discardCurrentState() Restore the current state of the virtual machine from the state stored in the current snapshot, including all settings and hard disk contents The current state of the machine existed prior to this operation is lost
IConsole::discardCurrentSnapshotAndState() Completely revert the virtual machine to the state it was in before the current snapshot has been taken The current state, as well as the current snapshot, are lost

Interface ID:
{9F1BBF79-13B0-4DA2-ABBA-4A992C65C083}

Member Data Documentation

readonly attribute uuid ISnapshot::id

UUID of the snapshot.

attribute wstring ISnapshot::name

Short name of the snapshot.

attribute wstring ISnapshot::description

Optional description of the snapshot.

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.

Note:
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 null.

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

Note:
It's not an error to read this attribute on a snapshot that doesn't have a parent -- a null object will be returned to indicate this.

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

Note:
In the current implementation, there can be only one child snapshot, or no children at all, meaning this is the last (head) snapshot.


Generated on Fri Nov 21 21:38:41 2008 for VirtualBox Main API by  doxygen 1.5.5