org.virtualbox_5_2
Enum MachineState

java.lang.Object
  extended by java.lang.Enum<MachineState>
      extended by org.virtualbox_5_2.MachineState
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<MachineState>

public enum MachineState
extends java.lang.Enum<MachineState>

Virtual machine execution state. This enumeration represents possible values of theIMachine.getState()attribute. Below is the basic virtual machine state diagram. It shows how the state changes during virtual machine execution. The text in square braces shows a method of the IConsole or IMachine interface that performs the given state transition.

+---------[powerDown()] <- Stuck <--[failure]-+
V                                             |
+-> PoweredOff --+-->[powerUp()]--> Starting --+      | +-----[resume()]-----+
|                |                             |      | V                    |
|   Aborted -----+                             +--> Running --[pause()]--> Paused
|                                              |      ^ |                   ^ |
|   Saved -----------[powerUp()]--> Restoring -+      | |                   | |
|     ^                                               | |                   | |
|     |     +-----------------------------------------+-|-------------------+ +
|     |     |                                           |                     |
|     |     +- OnlineSnapshotting <--[takeSnapshot()]<--+---------------------+
|     |                                                 |                     |
|     +-------- Saving <--------[saveState()]<----------+---------------------+
|                                                       |                     |
+-------------- Stopping -------[powerDown()]<----------+---------------------+
Note that states to the right from PoweredOff, Aborted and Saved in the above diagram are calledonline VM states. These states represent the virtual machine which is being executed in a dedicated process (usually with a GUI window attached to it where you can see the activity of the virtual machine and interact with it). There are two special pseudo-states, FirstOnline and LastOnline, that can be used in relational expressions to detect if the given machine state is online or not:
if (machine.GetState() >= MachineState_FirstOnline &&
machine.GetState() <= MachineState_LastOnline)
{
...the machine is being executed...
}
When the virtual machine is in one of the online VM states (that is, being executed), only a few machine settings can be modified. Methods working with such settings contain an explicit note about that. An attempt to change any other setting or perform a modifying operation during this time will result in the VBOX_E_INVALID_VM_STATE error. All online states except Running, Paused and Stuck are transitional: they represent temporary conditions of the virtual machine that will last as long as the operation that initiated such a condition. The Stuck state is a special case. It means that execution of the machine has reached the "Guru Meditation" condition. This condition indicates an internal VMM (virtual machine manager) failure which may happen as a result of either an unhandled low-level virtual hardware exception or one of the recompiler exceptions (such as thetoo-many-trapscondition). Note also that any online VM state may transit to the Aborted state. This happens if the process that is executing the virtual machine terminates unexpectedly (for example, crashes). Other than that, the Aborted state is equivalent to PoweredOff. There are also a few additional state diagrams that do not deal with virtual machine execution and therefore are shown separately. The states shown on these diagrams are calledoffline VM states(this includes PoweredOff, Aborted and Saved too). The first diagram shows what happens when a lengthy setup operation is being executed (such asIMachine.attachDevice(String,Integer,Integer,org.virtualbox_5_2.DeviceType,org.virtualbox_5_2.IMedium)).
+----------------------------------(same state as before the call)------+
|                                                                       |
+-> PoweredOff --+                                                      |
|                |                                                      |
|-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
|                |
+-> Saved -------+
The next two diagrams demonstrate the process of taking a snapshot of a powered off virtual machine, restoring the state to that as of a snapshot or deleting a snapshot, respectively.
+----------------------------------(same state as before the call)------+
|                                                                       |
+-> PoweredOff --+                                                      |
|                +-->[takeSnapshot()] ------------------> Snapshotting -+
+-> Aborted -----+

+-> PoweredOff --+
|                |
|   Aborted -----+-->[restoreSnapshot()    ]-------> RestoringSnapshot -+
|                |   [deleteSnapshot()     ]-------> DeletingSnapshot --+
+-> Saved -------+                                                      |
|                                                                       |
+---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
Interface ID: {87F085C3-CA67-4E45-9225-6057F32E9E8E}


Enum Constant Summary
Aborted
          The process running the machine has terminated abnormally.
DeletingSnapshot
          A machine snapshot is being deleted; this can take a long time since this may require merging differencing media.
DeletingSnapshotOnline
          Like DeletingSnapshot, but the merging of media is ongoing in the background while the machine is running.
DeletingSnapshotPaused
          Like DeletingSnapshotOnline, but the machine was paused when the merging of differencing media was started.
FaultTolerantSyncing
          The machine is being synced with a fault tolerant VM running elsewhere.
FirstOnline
          Pseudo-state: first online state (for use in relational expressions).
FirstTransient
          Pseudo-state: first transient state (for use in relational expressions).
LastOnline
          Pseudo-state: last online state (for use in relational expressions).
LastTransient
          Pseudo-state: last transient state (for use in relational expressions).
LiveSnapshotting
          A live snapshot is being taken.
Null
          Null value (never used by the API).
OnlineSnapshotting
          Like LiveSnapshotting, but the machine was paused when the merging of differencing media was started.
Paused
          Execution of the machine has been paused.
PoweredOff
          The machine is not running and has no saved execution state; it has either never been started or been shut down successfully.
Restoring
          Execution state of the machine is being restored from a file after powering it on from the saved execution state.
RestoringSnapshot
          A machine snapshot is being restored; this typically does not take long.
Running
          The machine is currently being executed.
Saved
          The machine is not currently running, but the execution state of the machine has been saved to an external file when it was running, from where it can be resumed.
Saving
          Machine is saving its execution state to a file.
SettingUp
          Lengthy setup operation is in progress.
Snapshotting
          Taking an (offline) snapshot.
Starting
          Machine is being started after powering it on from a zero execution state.
Stopping
          Machine is being normally stopped powering it off, or after the guest OS has initiated a shutdown sequence.
Stuck
          Execution of the machine has reached the "Guru Meditation" condition.
Teleported
          The machine was teleported to a different host (or process) and then powered off.
Teleporting
          The machine is about to be teleported to a different host or process.
TeleportingIn
          Teleporting the machine state in from another host or process.
TeleportingPausedVM
          The machine is being teleported to another host or process, but it is not running.
 
Method Summary
static MachineState fromValue(long v)
           
static MachineState fromValue(java.lang.String v)
           
 int value()
           
static MachineState valueOf(java.lang.String name)
          Returns the enum constant of this type with the specified name.
static MachineState[] values()
          Returns an array containing the constants of this enum type, in the order they are declared.
 
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Enum Constant Detail

Null

public static final MachineState Null
Null value (never used by the API).


PoweredOff

public static final MachineState PoweredOff
The machine is not running and has no saved execution state; it has either never been started or been shut down successfully.


Saved

public static final MachineState Saved
The machine is not currently running, but the execution state of the machine has been saved to an external file when it was running, from where it can be resumed.


Teleported

public static final MachineState Teleported
The machine was teleported to a different host (or process) and then powered off. Take care when powering it on again may corrupt resources it shares with the teleportation target (e.g. disk and network).


Aborted

public static final MachineState Aborted
The process running the machine has terminated abnormally. This may indicate a crash of the VM process in host execution context, or the VM process has been terminated externally.


Running

public static final MachineState Running
The machine is currently being executed.


Paused

public static final MachineState Paused
Execution of the machine has been paused.


Stuck

public static final MachineState Stuck
Execution of the machine has reached the "Guru Meditation" condition. This indicates a severe error in the hypervisor itself.


Teleporting

public static final MachineState Teleporting
The machine is about to be teleported to a different host or process. It is possible to pause a machine in this state, but it will go to the TeleportingPausedVM state and it will not be possible to resume it again unless the teleportation fails.


LiveSnapshotting

public static final MachineState LiveSnapshotting
A live snapshot is being taken. The machine is running normally, but some of the runtime configuration options are inaccessible. Also, if paused while in this state it will transition to OnlineSnapshotting and it will not be resume the execution until the snapshot operation has completed.


Starting

public static final MachineState Starting
Machine is being started after powering it on from a zero execution state.


Stopping

public static final MachineState Stopping
Machine is being normally stopped powering it off, or after the guest OS has initiated a shutdown sequence.


Saving

public static final MachineState Saving
Machine is saving its execution state to a file.


Restoring

public static final MachineState Restoring
Execution state of the machine is being restored from a file after powering it on from the saved execution state.


TeleportingPausedVM

public static final MachineState TeleportingPausedVM
The machine is being teleported to another host or process, but it is not running. This is the paused variant of the Teleporting state.


TeleportingIn

public static final MachineState TeleportingIn
Teleporting the machine state in from another host or process.


FaultTolerantSyncing

public static final MachineState FaultTolerantSyncing
The machine is being synced with a fault tolerant VM running elsewhere.


DeletingSnapshotOnline

public static final MachineState DeletingSnapshotOnline
Like DeletingSnapshot, but the merging of media is ongoing in the background while the machine is running.


DeletingSnapshotPaused

public static final MachineState DeletingSnapshotPaused
Like DeletingSnapshotOnline, but the machine was paused when the merging of differencing media was started.


OnlineSnapshotting

public static final MachineState OnlineSnapshotting
Like LiveSnapshotting, but the machine was paused when the merging of differencing media was started.


RestoringSnapshot

public static final MachineState RestoringSnapshot
A machine snapshot is being restored; this typically does not take long.


DeletingSnapshot

public static final MachineState DeletingSnapshot
A machine snapshot is being deleted; this can take a long time since this may require merging differencing media. This value indicates that the machine is not running while the snapshot is being deleted.


SettingUp

public static final MachineState SettingUp
Lengthy setup operation is in progress.


Snapshotting

public static final MachineState Snapshotting
Taking an (offline) snapshot.


FirstOnline

public static final MachineState FirstOnline
Pseudo-state: first online state (for use in relational expressions).


LastOnline

public static final MachineState LastOnline
Pseudo-state: last online state (for use in relational expressions).


FirstTransient

public static final MachineState FirstTransient
Pseudo-state: first transient state (for use in relational expressions).


LastTransient

public static final MachineState LastTransient
Pseudo-state: last transient state (for use in relational expressions).

Method Detail

values

public static MachineState[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (MachineState c : MachineState.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static MachineState valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
java.lang.NullPointerException - if the argument is null

value

public int value()

fromValue

public static MachineState fromValue(long v)

fromValue

public static MachineState fromValue(java.lang.String v)