# ISnapshot Interface Reference

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

List of all members.

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

- IConsole::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. If the machine is running, it will resume execution after the snapshot has been taken.

- IConsole::restoreSnapshot: this goes back to a previous snapshot. This resets the machine's state to that of the 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.

- IConsole::deleteSnapshot: deletes a snapshot without affecting the current machine state.

  This does not change the machine, but instead frees the resources allocated when the snapshot was taken: the settings and machine state is 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.

Each snapshot contains the settings of the virtual machine (hardware configuration etc.). 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 is saved (MachineState_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.

### Snapshot branches and the "current" snapshot

Snapshots can be chained, whereby every next snapshot is based on the previous one. This chaining is related to medium branching (see the IMedium description) in that every time a new snapshot is created, a new differencing medium is implicitly created for all normal media attached to the machine.

Each virtual machine has a "current snapshot", identified by IMachine::currentSnapshot. Presently, this is always set to the last snapshot in the chain. In a future version of VirtualBox, it will be possible to reset a machine's current state to that of an earlier snapshot without deleting the current state so that it will be possible to create alternative snapshot paths in a snapshot tree.

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.

Interface ID:
  `{1A2D0551-58A4-4107-857E-EF414FC42FFC}`

## Member Data Documentation

readonly attribute wstringUUID 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.

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