| E_INVALIDARG | Returned when the value of the method's argument is not within the range of valid values. This should not be confused with situations when the value is within the range but simply doesn't suit the current object state and there is a possibility that it will be accepted later (in such cases VirtualBox-specific codes are returned, for example, ). |
| E_POINTER | Returned if a memory pointer for the output argument is invalid (for example, NULL). Note that when pointers representing input arguments (such as strings) are invalid, E_INVALIDARG is returned. |
| E_ACCESSDENIED | Returned when the called object is not ready. Since the lifetime of a public COM object cannot be fully controlled by the implementation, VirtualBox maintains the readiness state for all objects it creates and returns this code in response to any method call on the object that was deactivated by VirtualBox and is not functioning any more. |
| E_OUTOFMEMORY | Returned when a memory allocation operation fails. |
+---------[powerDown()] <- Stuck <--[failure]-+
V |
+-> PoweredOff --+-->[powerUp()]--> Starting --+ | +-----[resume()]-----+
| | | | V |
| Aborted -----+ +--> Running --[pause()]--> Paused
| | ^ | ^ |
| Saved -----------[powerUp()]--> Restoring -+ | | | |
| ^ | | | |
| | +-----------------------------------------+-|-------------------+ +
| | | | |
| | +-- Saving <--------[takeSnapshot()]<-------+---------------------+
| | | |
| +-------- Saving <--------[saveState()]<----------+---------------------+
| | |
+-------------- Stopping -------[powerDown()]<----------+---------------------+
Note that states to the right from PoweredOff, Aborted and Saved in the
above diagram are called online 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 oter setting or perform a modifying operation during this time
will result in the 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 the too-many-traps
condition).
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 called offline VM states (this includes
PoweredOff, Aborted and Saved too).
The first diagram shows what happens when a lengthy setup operation is
being executed (such as ).
+-----------------------------------(same sate 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 and performing one of the "discard..."
operations, respectively.
+-----------------------------------(same sate as before the call)------+
| |
+-> PoweredOff --+ |
| +-->[takeSnapshot()] -------------------> Saving ------+
+-> Aborted -----+
+-> PoweredOff --+
| |
| Aborted -----+-->[discardSnapshot() ]-------------> Discarding --+
| | [discardCurrentState()] |
+-> Saved -------+ [discardCurrentSnapshotAndState()] |
| |
+---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
Note that the Saving state is present in both the offline state group and
online state group. Currently, the only way to determine what group is
assumed in a particular case is to remember the previous machine state: if
it was Running or Paused, then Saving is an online state, otherwise it is
an offline state. This inconsistency may be removed in one of the future
versions of VirtualBox by adding a new state.
x.y-platform
where x and y are the major and the minor format
versions, and platform is the platform identifier.
The current version usually matches the value of the
attribute unless the
settings file was created by an older version of VirtualBox and there
was a change of the settings file format since then.
Note that VirtualBox automatically converts settings files from older
versions to the most recent version when reading them (usually at
VirtualBox startup) but it doesn't save the changes back until
you call a method that implicitly saves settings (such as
) or call
explicitly. Therefore, if the value of this attribute differs from the
value of , then it
means that the settings file was converted but the result of the
conversion is not yet saved to disk.
The above feature may be used by interactive front-ends to inform users
about the settings file format change and offer them to explicitly save
all converted settings files (the global and VM-specific ones),
optionally create backup copies of the old settings files before saving,
etc.
x.y-platform
where x and y are the major and the minor format
versions, and platform is the platform identifier.
VirtualBox uses this version of the format when saving settings files
(either as a result of method calls that require to save settings or as
a result of an explicit call to ).
<base_folder>/<machine_name>/<machine_name>.xml
Note that if the resulting settings file already exists, this method
will fail with .
Optionally, you may specify an UUID of to assign to the created machine.
However, this is not recommended and you should normally pass an empty
(null) UUID to this method so that a new UUID will be automatically
generated for every created machine.
[[group.]subgroup.]name
where @c name is the property name and @c group, @c subgroup are zero
or more property group specifiers. Each element (group or name) in
the property mask may be either a Latin string or an asterisk symbol
(@c "*") which is used to match any string for the given element. A
property mask that doesn't contain asterisk symbols represents a
single fully qualified property name.
Groups in the fully qualified property name go from more generic (the
left-most part) to more specific (the right-most part). The first
element is usually a name of the object the property belongs to. The
second element may be either a property name, or a child object name,
or an index if the preceding element names an object which is one of
many objects of the same type. This way, property names form a
hierarchy of properties. Here are some examples of property names:
| VirtualBox.version | property |
| Machine.<UUID>.name | property of the machine with the given UUID |
| VirtualBox.* | Track all properties of the VirtualBox object |
| Machine.*.name | Track changes to the property of all registered virtual machines |
original.xml.x.y-platform.bak
where original.xml is the original settings file name
(excluding path), and x.y-platform is the version of the old
format of the settings file (before auto-conversion).
If the given backup file already exists, this method will try to add the
.N suffix to the backup file name (where N counts from
0 to 9) and copy it again until it succeeds. If all suffixes are
occupied, or if any other copy error occurs, this method will return a
failure.
If the copy operation succeeds, the @a bakFileName return argument will
receive a full path to the created backup file (for informational
purposes). Note that this will happen even if the subsequent
call performed by this method after the
copy operation, fails.
x.y-platform
where x and y are the major and the minor format
versions, and platform is the platform identifier.
The current version usually matches the value of the
attribute unless the
settings file was created by an older version of VirtualBox and there
was a change of the settings file format since then.
Note that VirtualBox automatically converts settings files from older
versions to the most recent version when reading them (usually at
VirtualBox startup) but it doesn't save the changes back until
you call a method that implicitly saves settings (such as
) or call
explicitly. Therefore, if the value of this attribute differs from the
value of , then it
means that the settings file was converted but the result of the
conversion is not yet saved to disk.
The above feature may be used by interactive front-ends to inform users
about the settings file format change and offer them to explicitly save
all converted settings files (the global and VM-specific ones),
optionally create backup copies of the old settings files before saving,
etc.
original.xml.x.y-platform.bak
where original.xml is the original settings file name
(excluding path), and x.y-platform is the version of the old
format of the settings file (before auto-conversion).
If the given backup file already exists, this method will try to add the
.N suffix to the backup file name (where N counts from
0 to 9) and copy it again until it succeeds. If all suffixes are
occupied, or if any other copy error occurs, this method will return a
failure.
If the copy operation succeeds, the @a bakFileName return argument will
receive a full path to the created backup file (for informational
purposes). Note that this will happen even if the subsequent
call performed by this method after the
copy operation, fails.
"VDI"
"vdi"
"VdI"
refer to the same hard disk format.
Note that the virtual hard disk framework is backend-based, therefore
the list of supported formats depends on what backends are currently
installed.
| Operation | Meaning | Remarks |
|---|---|---|
| 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) | |
| 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 | |
| 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 | |
| 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 |
<path>/{<uuid>}.<ext>
where <path> is the supplied path specification,
<uuid> is the newly generated UUID and <ext>
is the default extension for the storage format of this hard disk. After
that, you may call any of the methods that create a new hard disk storage
unit and they will use the generated UUID and file name.
| Hard Disk Type | Direct or Indirect? |
|---|---|
| Normal (Base) | Normal base hard disks that do not have children (i.e. differencing hard disks linked to them) and that are not already attached to virtual machines in snapshots are attached directly. Otherwise, they are attached indirectly because having dependent children or being part of the snapshot makes it impossible to modify hard disk contents without breaking the integrity of the dependent party. The attribute allows to quickly determine the kind of the attachment for the given hard disk. Note that if a normal base hard disk is to be indirectly attached to a virtual machine with snapshots then a special procedure called smart attachment is performed (see below). |
| Normal (Differencing) | Differencing hard disks are like normal base hard disks: attached directly if they do not have children and are not attached to virtual machines in snapshots, and indirectly otherwise. Note that the smart attachment procedure is never performed for differencing hard disks. |
| Immutable | Immutable hard disks are always attached indirectly because they are designed to be non-writable. If an immutable hard disk is attached to a virtual machine with snapshots then a special procedure called smart attachment is performed (see below). |
| Writethrough | Writethrough hard disks are always attached directly, also as designed. This also means that writethrough hard disks cannot have other hard disks linked to them at all. |
BEFORE attaching B.vdi: AFTER attaching B.vdi:
Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
Snapshot 4 (none) Snapshot 4 (none)
CurState (none) CurState (D3->D2.vdi)
NOT
...
CurState (D3->B.vdi)
The first column is the virtual machine configuration before the base hard
disk B.vdi is attached, the second column shows the machine after
this hard disk is attached. Constructs like D1->B.vdi and similar
mean that the hard disk that is actually attached to the machine is a
differencing hard disk, D1.vdi, which is linked to (based on)
another hard disk, B.vdi.
As we can see from the example, the hard disk B.vdi was detached
from the machine before taking Snapshot 4. Later, after Snapshot 4 was
taken, the user decides to attach B.vdi again. B.vdi has
dependent child hard disks (D1.vdi, D2.vdi), therefore
it cannot be attached directly and needs an indirect attachment (i.e.
implicit creation of a new differencing hard disk). Due to the smart
attachment procedure, the new differencing hard disk
(D3.vdi) will be based on D2.vdi, not on
B.vdi itself, since D2.vdi is the most recent view of
B.vdi existing for this snapshot branch of the given virtual
machine.
Note that if there is more than one descendant hard disk of the given base
hard disk found in a snapshot, and there is an exact device, channel and
bus match, then this exact match will be used. Otherwise, the youngest
descendant will be picked up.
There is one more important aspect of the smart attachment procedure which
is not related to snapshots at all. Before walking through the snapshots
as described above, the backup copy of the current list of hard disk
attachment is searched for descendants. This backup copy is created when
the hard disk configuration is changed for the first time after the last
call and used by
to undo the recent hard disk
changes. When such a descendant is found in this backup copy, it will be
simply re-attached back, without creating a new differencing hard disk for
it. This optimization is necessary to make it possible to re-attach the
base or immutable hard disk to a different bus, channel or device slot
without losing the contents of the differencing hard disk actually
attached to the machine in place of it.
Base <- Diff_1 <- Diff_2Here, calling this method on the Base hard disk object with Diff_2 as an argument will be a forward merge; calling it on Diff_2 with Base as an argument will be a backward merge. Note that in both cases the contents of the resulting hard disk will be the same, the only difference is the hard disk object that takes the result of the merge operation. In case of the forward merge in the above example, the result will be written to Diff_2; in case of the backward merge, the result will be written to Base. In other words, the result of the operation is always stored in the target hard disk. Upon successful operation completion, the storage units of all hard disks in the chain between this (source) hard disk and the target hard disk, including the source hard disk itself, will be automatically deleted and the relevant hard disk objects (including this hard disk) will become uninitialized. This means that any attempt to call any of their methods or attributes will fail with the "Object not ready" (E_ACCESSDENIED) error. Applied to the above example, the forward merge of Base to Diff_2 will delete and uninitialize both Base and Diff_1 hard disks. Note that Diff_2 in this case will become a base hard disk itself since it will no longer be based on any other hard disk. Considering the above, all of the following conditions must be met in order for the merge operation to succeed:
"VDI"
"vdi"
"VdI"
refer to the same hard disk format.
This string is used in methods of other interfaces where it is necessary
to specify a hard disk format, such as
.
| Bit 0 (0x01) | left mouse button |
| Bit 1 (0x02) | right mouse button |
| Bit 2 (0x04) | middle mouse button |
| Bit 0 (0x01) | left mouse button |
| Bit 1 (0x02) | right mouse button |
| Bit 2 (0x04) | middle mouse button |