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 ISnapshot[] | children |
Child snapshots (all snapshots having this one as a parent). |
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).
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 implementation, multiple snapshot branches within one virtual machine are not allowed. Every machine has a single branch, and IConsole::takeSnapshot operation adds a new snapshot to the top of that branch.
Existing snapshots can be discarded using IConsole::discardSnapshot.
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.
The current machine state is what represented 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.
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 |
{5DB6B1D9-C76B-4424-A6F4-8257F642D6EA}
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.
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.
readonly attribute ISnapshot ISnapshot::parent |
Parent snapshot (a snapshot this one is based on).
readonly attribute ISnapshot [] ISnapshot::children |
Child snapshots (all snapshots having this one as a parent).