Public Member Functions | |
void | getProperty (in wstring name,[retval] out wstring value) |
Returns the value of the custom hard disk property with the given name. | |
void | setProperty (in wstring name, in wstring value) |
Sets the value of the custom hard disk property with the given name. | |
void | getProperties (in wstring names, out wstring[] returnNames,[retval] out wstring[] returnValues) |
Returns values for a group of properties in one call. | |
void | setProperties (in wstring[] names, in wstring[] values) |
Sets values for a group of properties in one call. | |
void | createBaseStorage (in unsigned long long logicalSize, in HardDiskVariant variant,[retval] out IProgress progress) |
Starts creating a hard disk storage unit (fixed/dynamic, according to the variant flags) in in the background. | |
void | deleteStorage ([retval] out IProgress progress) |
Starts deleting the storage unit of this hard disk. | |
void | createDiffStorage (in IHardDisk target, in HardDiskVariant variant,[retval] out IProgress progress) |
Starts creating an empty differencing storage unit based on this hard disk in the format and at the location defined by the target argument. | |
void | mergeTo (in uuid targetId,[retval] out IProgress progress) |
Starts merging the contents of this hard disk and all intermediate differencing hard disks in the chain to the given target hard disk. | |
void | cloneTo (in IHardDisk target, in HardDiskVariant variant, in IHardDisk parent,[retval] out IProgress progress) |
Starts creating a clone of this hard disk in the format and at the location defined by the target argument. | |
void | compact ([retval] out IProgress progress) |
Starts compacting of this hard disk. | |
void | reset ([retval] out IProgress progress) |
Starts erasing the contents of this differencing hard disk. | |
Public Attributes | |
readonly attribute wstring | format |
Storage format of this hard disk. | |
attribute HardDiskType | type |
Type (role) of this hard disk. | |
readonly attribute IHardDisk | parent |
Parent of this hard disk (a hard disk this hard disk is directly based on). | |
readonly attribute IHardDisk[] | children |
Children of this hard disk (all differencing hard disks directly based on this hard disk). | |
readonly attribute IHardDisk | root |
Root hard disk of this hard disk. | |
readonly attribute boolean | readOnly |
Returns true if this hard disk is read-only and false otherwise. | |
readonly attribute unsigned long long | logicalSize |
Logical size of this hard disk (in megabytes), as reported to the guest OS running inside the virtual machine this disk is attached to. | |
attribute boolean | autoReset |
Whether this differencing hard disk will be automatically reset each time a virtual machine it is attached to is powered up. |
This is a subclass of IMedium; see remarks there.
Virtual hard disk objects virtualize the hard disk hardware and look like regular hard disks for the guest OS running inside the virtual machine.
There are three types of hard disks: Normal, Immutable and Writethrough. The type of the hard disk defines how the hard disk is attached to a virtual machine and what happens when a snapshot of the virtual machine with the attached hard disk is taken. The type of the hard disk is defined by the type attribute.
All hard disks can be also divided in two big groups: base hard disks and differencing hard disks. A base hard disk contains all sectors of the hard disk data in its storage unit and therefore can be used independently. On the contrary, a differencing hard disk contains only some part of the hard disk data (a subset of sectors) and needs another hard disk to get access to the missing sectors of data. This another hard disk is called a parent hard disk and defines a hard disk to which this differencing hard disk is known to be linked to. The parent hard disk may be itself a differencing hard disk. This way, differencing hard disks form a linked hard disk chain. This chain always ends with the base hard disk which is sometimes referred to as the root hard disk of this chain. Note that several differencing hard disks may be linked to the same parent hard disk. This way, all known hard disks form a hard disk tree which is based on their parent-child relationship.
Differencing hard disks can be distinguished from base hard disks by querying the parent attribute: base hard disks do not have parents they would depend on, so the value of this attribute is always null
for them. Using this attribute, it is possible to walk up the hard disk tree (from the child hard disk to its parent). It is also possible to walk down the tree using the children attribute.
Note that the type of all differencing hard disks is Normal; all other values are meaningless for them. Base hard disks may be of any type.
New base hard disks are created using IVirtualBox::createHardDisk. Existing hard disks are opened using IVirtualBox::openHardDisk. Differencing hard disks are usually implicitly created by VirtualBox when needed but may also be created explicitly using createDiffStorage.
After the hard disk is successfully created (including the storage unit) or opened, it becomes a known hard disk (remembered in the internal media registry). Known hard disks can be attached to a virtual machine, accessed through IVirtualBox::getHardDisk and IVirtualBox::findHardDisk methods or enumerated using the IVirtualBox::hardDisks array (only for base hard disks).
The following methods, besides IMedium::close, automatically remove the hard disk from the media registry:
If the storage unit of the hard disk is a regular file in the host's file system then the rules stated in the description of the IMedium::location attribute apply when setting its value. In addition, a plain file name without any path may be given, in which case the default hard disk folder will be prepended to it.
Another extension to the IMedium::location attribute is that there is a possibility to cause VirtualBox to compose a unique value for the file name part of the location using the UUID of the hard disk. This applies only to hard disks in MediaState_NotCreated state, e.g. before the storage unit is created, and works as follows. You set the value of the IMedium::location attribute to a location specification which only contains the path specification but not the file name part and ends with either a forward slash or a backslash character. In response, VirtualBox will generate a new UUID for the hard disk and compose the file name using the following pattern:
<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 disks are attached to virtual machines using the IMachine::attachHardDisk method and detached using the IMachine::detachHardDisk method. Depending on their type, hard disks are attached either directly or indirectly.
When a hard disk is being attached directly, it is associated with the virtual machine and used for hard disk operations when the machine is running. When a hard disk is being attached indirectly, a new differencing hard disk linked to it is implicitly created and this differencing hard disk is associated with the machine and used for hard disk operations. This also means that if IMachine::attachHardDisk performs a direct attachment then the same hard disk will be returned in response to the subsequent IMachine::getHardDisk call; however if an indirect attachment is performed then IMachine::getHardDisk will return the implicitly created differencing hard disk, not the original one passed to IMachine::attachHardDisk. The following table shows the dependency of the attachment type on the hard disk type:
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 readOnly 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. |
Note that the same hard disk, regardless of its type, may be attached to more than one virtual machine at a time. In this case, the machine that is started first gains exclusive access to the hard disk and attempts to start other machines having this hard disk attached will fail until the first machine is powered down.
Detaching hard disks is performed in a deferred fashion. This means that the given hard disk remains associated with the given machine after a successful IMachine::detachHardDisk call until IMachine::saveSettings is called to save all changes to machine settings to disk. This deferring is necessary to guarantee that the hard disk configuration may be restored at any time by a call to IMachine::discardSettings before the settings are saved (committed).
Note that if IMachine::discardSettings is called after indirectly attaching some hard disks to the machine but before a call to IMachine::saveSettings is made, it will implicitly delete all differencing hard disks implicitly created by IMachine::attachHardDisk for these indirect attachments. Such implicitly created hard disks will also be immediately deleted when detached explicitly using the IMachine::detachHardDisk call if it is made before IMachine::saveSettings. This implicit deletion is safe because newly created differencing hard disks do not contain any user data.
However, keep in mind that detaching differencing hard disks that were implicitly created by IMachine::attachHardDisk before the last IMachine::saveSettings call will not implicitly delete them as they may already contain some data (for example, as a result of virtual machine execution). If these hard disks are no more necessary, the caller can always delete them explicitly using deleteStorage after they are actually de-associated from this machine by the IMachine::saveSettings call.
When normal base or immutable hard disks are indirectly attached to a virtual machine then some additional steps are performed to make sure the virtual machine will have the most recent "view" of the hard disk being attached. These steps include walking through the machine's snapshots starting from the current one and going through ancestors up to the first snapshot. Hard disks attached to the virtual machine in all of the encountered snapshots are checked whether they are descendants of the given normal base or immutable hard disk. The first found child (which is the differencing hard disk) will be used instead of the normal base or immutable hard disk as a parent for creating a new differencing hard disk that will be actually attached to the machine. And only if no descendants are found or if the virtual machine does not have any snapshots then the normal base or immutable hard disk will be used itself as a parent for this differencing hard disk.
It is easier to explain what smart attachment does using the following example:
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 IMachine::saveSettings call and used by IMachine::discardSettings 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.
{91648DC6-BB19-46BF-9E1C-4BF5B960C8E2}
void IHardDisk::getProperty | ( | in wstring | name, | |
[retval] out wstring | value | |||
) |
Returns the value of the custom hard disk property with the given name.
The list of all properties supported by the given hard disk format can be obtained with IHardDiskFormat::describeProperties.
Note that if this method returns a null
value, the requested property is supported but currently not assigned any value.
name | Name of the property to get. | |
value | Current property value. |
VBOX_E_OBJECT_NOT_FOUND | Requested property does not exist (not supported by the format). |
E_INVALIDARG | name is NULL or empty. |
void IHardDisk::setProperty | ( | in wstring | name, | |
in wstring | value | |||
) |
Sets the value of the custom hard disk property with the given name.
The list of all properties supported by the given hard disk format can be obtained with IHardDiskFormat::describeProperties.
Note that setting the property value to null
is equivalent to deleting the existing value. A default value (if it is defined for this property) will be used by the format backend in this case.
name | Name of the property to set. | |
value | Property value to set. |
VBOX_E_OBJECT_NOT_FOUND | Requested property does not exist (not supported by the format). |
E_INVALIDARG | name is NULL or empty. |
void IHardDisk::getProperties | ( | in wstring | names, | |
out wstring[] | returnNames, | |||
[retval] out wstring[] | returnValues | |||
) |
Returns values for a group of properties in one call.
The names of the properties to get are specified using the names argument which is a list of comma-separated property names or null
if all properties are to be returned. Note that currently the value of this argument is ignored and the method always returns all existing properties.
The list of all properties supported by the given hard disk format can be obtained with IHardDiskFormat::describeProperties.
The method returns two arrays, the array of property names corresponding to the names argument and the current values of these properties. Both arrays have the same number of elements with each elemend at the given index in the first array corresponds to an element at the same index in the second array.
Note that for properties that do not have assigned values, null
is returned at the appropriate index in the returnValues array.
names | Names of properties to get. | |
returnNames | Names of returned properties. | |
returnValues | Values of returned properties. |
void IHardDisk::setProperties | ( | in wstring[] | names, | |
in wstring[] | values | |||
) |
Sets values for a group of properties in one call.
The names of the properties to set are passed in the names array along with the new values for them in the values array. Both arrays have the same number of elements with each elemend at the given index in the first array corresponding to an element at the same index in the second array.
If there is at least one property name in names that is not valid, the method will fail before changing the values of any other properties from the names array.
Using this method over setProperty is preferred if you need to set several properties at once since it will result into less IPC calls.
The list of all properties supported by the given hard disk format can be obtained with IHardDiskFormat::describeProperties.
Note that setting the property value to null
is equivalent to deleting the existing value. A default value (if it is defined for this property) will be used by the format backend in this case.
names | Names of properties to set. | |
values | Values of properties to set. |
void IHardDisk::createBaseStorage | ( | in unsigned long long | logicalSize, | |
in HardDiskVariant | variant, | |||
[retval] out IProgress | progress | |||
) |
Starts creating a hard disk storage unit (fixed/dynamic, according to the variant flags) in in the background.
The previous storage unit created for this object, if any, must first be deleted using deleteStorage, otherwise the operation will fail.
Before the operation starts, the hard disk is placed in MediaState_Creating state. If the create operation fails, the media will be placed back in MediaState_NotCreated state.
After the returned progress object reports that the operation has successfully completed, the media state will be set to MediaState_Created, the hard disk will be remembered by this VirtualBox installation and may be attached to virtual machines.
logicalSize | Maximum logical size of the hard disk in megabytes. | |
variant | Exact image variant which should be created. | |
progress | Progress object to track the operation completion. |
VBOX_E_NOT_SUPPORTED | The variant of storage creation operation is not supported. See IHardDiskFormat::capabilities. |
void IHardDisk::deleteStorage | ( | [retval] out IProgress | progress | ) |
Starts deleting the storage unit of this hard disk.
The hard disk must not be attached to any known virtual machine and must not have any known child hard disks, otherwise the operation will fail. It will also fail if there is no storage unit to delete or if deletion is already in progress, or if the hard disk is being in use (locked for read or for write) or inaccessible. Therefore, the only valid state for this operation to succeed is MediaState_Created.
Before the operation starts, the hard disk is placed to MediaState_Deleting state and gets removed from the list of remembered hard disks (media registry). If the delete operation fails, the media will be remembered again and placed back to MediaState_Created state.
After the returned progress object reports that the operation is complete, the media state will be set to MediaState_NotCreated and you will be able to use one of the storage creation methods to create it again.
progress | Progress object to track the operation completion. |
VBOX_E_OBJECT_IN_USE | Hard disk is attached to a virtual machine. |
VBOX_E_NOT_SUPPORTED | Storage deletion is not allowed because neither of storage creation operations are supported. See IHardDiskFormat::capabilities. |
void IHardDisk::createDiffStorage | ( | in IHardDisk | target, | |
in HardDiskVariant | variant, | |||
[retval] out IProgress | progress | |||
) |
Starts creating an empty differencing storage unit based on this hard disk in the format and at the location defined by the target argument.
The target hard disk must be in MediaState_NotCreated state (i.e. must not have an existing storage unit). Upon successful completion, this operation will set the type of the target hard disk to HardDiskType_Normal and create a storage unit necessary to represent the differencing hard disk data in the given format (according to the storage format of the target object).
After the returned progress object reports that the operation is successfully complete, the target hard disk gets remembered by this VirtualBox installation and may be attached to virtual machines.
target | Target hard disk. | |
variant | Exact image variant which should be created. | |
progress | Progress object to track the operation completion. |
VBOX_E_OBJECT_IN_USE | Hard disk not in NotCreated state. |
void IHardDisk::mergeTo | ( | in uuid | targetId, | |
[retval] out IProgress | progress | |||
) |
Starts merging the contents of this hard disk and all intermediate differencing hard disks in the chain to the given target hard disk.
The target hard disk must be either a descendant of this hard disk or its ancestor (otherwise this method will immediately return a failure). It follows that there are two logical directions of the merge operation: from ancestor to descendant (forward merge) and from descendant to ancestor (backward merge). Let us consider the following hard disk chain:
Base <- Diff_1 <- Diff_2
Here, 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:
targetId | UUID of the target ancestor or descendant hard disk. | |
progress | Progress object to track the operation completion. |
void IHardDisk::cloneTo | ( | in IHardDisk | target, | |
in HardDiskVariant | variant, | |||
in IHardDisk | parent, | |||
[retval] out IProgress | progress | |||
) |
Starts creating a clone of this hard disk in the format and at the location defined by the target argument.
The target hard disk must be in MediaState_NotCreated state (i.e. must not have an existing storage unit). Upon successful completion, the cloned hard disk will contain exactly the same sector data as the hard disk being cloned, except that a new UUID for the clone will be randomly generated.
The parent argument defines which hard disk will be the parent of the clone. Passing a NULL reference indicates that the clone will be a base image, i.e. completely independent. It is possible to specify an arbitrary hard disk for this parameter, including the parent of the hard disk which is being cloned. Even cloning to a child of the source hard disk is possible.
After the returned progress object reports that the operation is successfully complete, the target hard disk gets remembered by this VirtualBox installation and may be attached to virtual machines.
target | Target hard disk. | |
variant | Exact image variant which should be created. | |
parent | Parent of the cloned hard disk. | |
progress | Progress object to track the operation completion. |
void IHardDisk::compact | ( | [retval] out IProgress | progress | ) |
Starts compacting of this hard disk.
This means that the disk is transformed into a possibly more compact storage representation. This potentially creates temporary images, which can require a substantial amount of additional disk space.
This hard disk will be placed to MediaState_LockedWrite state and all its parent hard disks (if any) will be placed to MediaState_LockedRead state for the duration of this operation.
progress | Progress object to track the operation completion. |
void IHardDisk::reset | ( | [retval] out IProgress | progress | ) |
Starts erasing the contents of this differencing hard disk.
This operation will reset the differencing hard disk to its initial state when it does not contain any sector data and any read operation is redirected to its parent hard disk.
This hard disk will be placed to MediaState_LockedWrite for the duration of this operation.
progress | Progress object to track the operation completion. |
VBOX_E_NOT_SUPPORTED | This is not a differencing hard disk. |
VBOX_E_INVALID_OBJECT_STATE | Hard disk is not in MediaState_Created or MediaState_Inaccessible state. |
readonly attribute wstring IHardDisk::format |
Storage format of this hard disk.
The value of this attribute is a string that specifies a backend used to store hard disk data. The storage format is defined when you create a new hard disk or automatically detected when you open an existing hard disk medium, and cannot be changed later.
The list of all storage formats supported by this VirtualBox installation can be obtained using ISystemProperties::hardDiskFormats.
attribute HardDiskType IHardDisk::type |
Type (role) of this hard disk.
The following constraints apply when changing the value of this attribute:
The type of a newly created or opened hard disk is set to HardDiskType_Normal.
readonly attribute IHardDisk IHardDisk::parent |
Parent of this hard disk (a hard disk this hard disk is directly based on).
Only differencing hard disks have parents. For base (non-differencing) hard disks, null
is returned.
readonly attribute IHardDisk [] IHardDisk::children |
Children of this hard disk (all differencing hard disks directly based on this hard disk).
A null
array is returned if this hard disk does not have any children.
readonly attribute IHardDisk IHardDisk::root |
Root hard disk of this hard disk.
If this is a differencing hard disk, its root hard disk is the base hard disk the given hard disk branch starts from. For all other types of hard disks, this property returns the hard disk object itself (i.e. the same object this property is read on).
readonly attribute boolean IHardDisk::readOnly |
Returns true
if this hard disk is read-only and false
otherwise.
A hard disk is considered to be read-only when its contents cannot be modified without breaking the integrity of other parties that depend on this hard disk such as its child hard disks or snapshots of virtual machines where this hard disk is attached to these machines. If there are no children and no such snapshots then there is no dependency and the hard disk is not read-only.
The value of this attribute can be used to determine the kind of the attachment that will take place when attaching this hard disk to a virtual machine. If the value is false
then the hard disk will be attached directly. If the value is true
then the hard disk will be attached indirectly by creating a new differencing child hard disk for that. See the interface description for more information.
Note that all Immutable hard disks are always read-only while all Writethrough hard disks are always not.
readonly attribute unsigned long long IHardDisk::logicalSize |
Logical size of this hard disk (in megabytes), as reported to the guest OS running inside the virtual machine this disk is attached to.
The logical size is defined when the hard disk is created and cannot be changed later.
For hard disks whose state is state is MediaState_Inaccessible, the value of this property is the last known logical size. For MediaState_NotCreated hard disks, the returned value is zero.
attribute boolean IHardDisk::autoReset |
Whether this differencing hard disk will be automatically reset each time a virtual machine it is attached to is powered up.
See reset() for more information about resetting differencing hard disks.
VBOX_E_NOT_SUPPORTED | This is not a differencing hard disk (when changing the attribute value). |
false
. Changing the value of this property in this case is not supported.