# ISnapshot Interface Reference

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

List of all members.

## Public Attributes
readonly attribute wstring | 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).

## 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:

- all settings of the virtual machine (i.e. its hardware configuration: RAM size, attached hard disks, etc.)
- the execution state of the virtual machine (memory contents, CPU state, etc.).

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

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

### 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:
  `{1A2D0551-58A4-4107-857E-EF414FC42FFC}`

## Member Data Documentation

readonly attribute wstring 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 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).

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.

readonly attribute ISnapshot [] ISnapshot::children

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.