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, @c 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 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()] -------------------> Saving ------+ +-> Aborted -----+ +-> PoweredOff --+ | | | Aborted -----+-->[restoreSnapshot() ]-------> RestoringSnapshot -+ | | [deleteSnapshot() ]-------> DeletingSnapshot --+ +-> Saved -------+ | | | +---(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.
<base_folder>/<machine_name>/<machine_name>.xmlThis method does not access the host disks. In particular, it does not check for whether a machine of this name already exists.
"VDI" "vdi" "VdI"refer to the same medium format. Note that the virtual medium framework is backend-based, therefore the list of supported formats depends on what backends are currently installed.
<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.
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 medium 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 medium will be the same, the only difference is the medium 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 medium. Upon successful operation completion, the storage units of all media in the chain between this (source) medium and the target medium, including the source medium itself, will be automatically deleted and the relevant medium objects (including this medium) 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 media. Note that Diff_2 in this case will become a base medium itself since it will no longer be based on any other medium. 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 medium format. This string is used in methods of other interfaces where it is necessary to specify a medium 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 |