Public Member Functions | |
void | cloneToImage (in wstring filePath, out IVirtualDiskImage image,[retval] out IProgress progress) |
Starts creating a clone of this hard disk. | |
Public Attributes | |
readonly attribute uuid | id |
UUID of the hard disk. | |
attribute wstring | description |
Optional description of the hard disk. | |
readonly attribute HardDiskStorageType | storageType |
Storage type of this hard disk. | |
readonly attribute wstring | location |
Storage location of this hard disk. | |
attribute HardDiskType | type |
Type (behavior) of this hard disk. | |
readonly attribute IHardDisk | parent |
Parent of this hard disk (a hard disk this one is directly based on). | |
readonly attribute IHardDiskCollection | children |
Children of this hard disk (all differencing hard disks for those this one is a parent). | |
readonly attribute IHardDisk | root |
Root hard disk of this hard disk. | |
readonly attribute boolean | accessible |
Whether the hard disk storage is currently accessible or not. | |
readonly attribute boolean | allAccessible |
Whether the whole hard disk branch, starting from this image and going through its ancestors up to the root, is accessible or not. | |
readonly attribute wstring | lastAccessError |
String describing the reason of inaccessibility of this hard disk after the last call to accessible that returned false . | |
readonly attribute unsigned long long | size |
Logical size of this hard disk (in megabytes), as reported to the guest OS running inside the vurtual machine this disk is attached to. | |
readonly attribute unsigned long long | actualSize |
Physical size of the storage used to store hard disk data (in bytes). | |
readonly attribute uuid | machineId |
UUID of the machine this hard disk is attached to (or a null UUID if it is not attached). | |
readonly attribute uuid | snapshotId |
UUID of the snapshot this hard disk is associated with (or null UUID if it is not associated with any snapshot). |
The virtual hard disk drive virtualizes the hard disk hardware and looks like a regular hard disk inside the virtual machine and the guest OS.
The storage type of the virtual hard disk determines where and how it stores its data (sectors). Currently, the following storage types are supported:
The storage type of the particular hard disk object is indicated by the storageType property.
Each storage type is represented by its own interface (as shown above), that allows to query and set properties and perform operations specific to that storage type. When an IHardDisk object reports it uses some particular storage type, it also guaranteed to support the corresponding interface which you can query. And vice versa, every object that supports a storage-specific interface, also supports IHardDisk.
The type of the virtual hard disk determines how it is attached to the virtual machine when you call IMachine::attachHardDisk() and what happens to it when a snapshot of the virtual machine is taken.
There are three types of virtual hard disks:
The virtual disk type is indicated by the type property. Each of the above types is described in detail further down.
There is also a forth, "hidden" virtual disk type: Differencing. It is "hidden" because you cannot directly create hard disks of this type -- they are automatically created by VirtualBox when necessary.
Differencing Hard Disks
Unlike disks of other types (that are similar to real hard disks), the differencing hard disk does not store the full range of data sectors. Instead, it stores only a subset of sectors of some other disk that were changed since the differencing hard disk has been created. Thus, every differencing hard disk has a parent hard disk it is linked to, and represents the difference between the initial and the current hard disk state. A differencing hard disk can be linked to another differencing hard disk -- this way, differencing hard disks can form a branch of changes. More over, a given virtual hard disk can have more than one differencing hard disk linked to it.
A disk the differencing hard disk is linked to (or, in other words, based on) is called a parent hard disk and is accessible through the parent property. Similarly, all existing differencing hard disks for a given parent hard disk are called its child hard disks (and accessible through the children property).
All differencing hard disks use Virtual Disk Image files to store changed sectors. They have the type property set to Normal, but can be easily distinguished from normal hard disks using the parent property: all differencing hard disks have a parent, while all normal hard disks don't.
When the virtual machine makes an attempt to read a sector that is missing in a differencing hard disk, its parent is accessed to resolve the sector in question. This process continues until the sector is found, or until the root hard disk is encountered, which always contains all sectors. As a consequence,
Differencing hard disks can be implicitly created by VirtualBox in the following cases:
Whether to create a differencing hard disk or not depends on the type of the hard disk attached to the virtual machine. This is explained below.
Note that in the current implementation, only the VirtualDiskImage storage type is used to represent differencing hard disks. In other words, all differencing hard disks are IVirtualDiskImage objects.
Normal Hard Disks
Normal hard disks are the most commonly used virtual hard disk. A normal hard disk is attached to the machine directly if it is not already attached to some other machine. Otherwise, an attempt to make an indirect attachment through a differencing hard disk will be made. This attempt will fail if the hard disk is attached to a virtual machine without snapshots (because it's impossible to create a differencing hard disk based on a hard disk that is subject to change).
When an indirect attachment takes place, in the simplest case, where the machine the hard disk is being attached to doesn't have snapshots, the differencing hard disk will be based on the normal hard disk being attached. Otherwise, the first (i.e. the most recent) descendant of the given normal hard disk found in the current snapshot branch (starting from the current snapshot and going up to the root) will be actually used as a base.
Note that when you detach an indirectly attached hard disk from the machine, the created differencing hard disk image is simply deleted, so all changes are lost. If you attach the same disk again, a clean differencing disk will be created based on the most recent child, as described above.
When taking a snapshot, the contents of all normal hard disks (and all differencing disks whose roots are normal hard disks) currently attached to the virtual machine is preserved by creating differencing hard disks based on them.
Immutable Hard Disks
Immutable hard disks can be used to provide a sort of read-only access. An immutable hard disk is always attached indirectly. The created differencing hard disk is automatically wiped out (recreated from scratch) every time you power off the virtual machine. Thus, the contents of the immutable disk remains unchanged between runs.
Detaching an immutable hard disk deletes the differencing disk created for it, with the same effect as in case with normal hard disks.
When taking a snapshot, the differencing part of the immutable hard disk is cloned (i.e. copied to a separate Virtual Disk Image file) without any changes. This is necessary to preserve the exact virtual machine state when you create an online snapshot.
Writethrough Hard Disks
Hard disks of this type are always attached directly. This means that every given writethrough hard disk can be attached only to one virtual machine at a time.
It is impossible to take a snapshot of a virtual machine with the writethrough hard disk attached, because taking a snapshot implies saving the execution state and preserving the contents of all hard disks, but writethrough hard disks cannot be preserved. Preserving hard disk contents is necessary to ensure the guest OS stored in the snapshot will get the same hard disk state when restored, which is especially important when it has open file handles or when there are cached files and directories stored in memory.
Non-differencing hard disks are either created from scratch using IVirtualBox::createHardDisk() or opened from a VDI file using IVirtualBox::openVirtualDiskImage() (only for hard disks using the VirtualDiskImage storage type). Once a hard disk is created or opened, it needs to be registered using IVirtualBox::registerHardDisk() to make it available for attaching to virtual machines. See the documentation of individual interfaces for various storage types to get more information.
Differencing hard disks are never created explicitly and cannot be registered or unregistered; they are automatically registered upon creation and deregistered when deleted.
Normally, when you attach a hard disk to the virtual machine, and then query the corresponding attachment using IMachine::getHardDisk() or IMachine::hardDiskAttachments you will get the same hard disk object, whose UUID you passed earlier to IMachine::attachHardDisk(). However, when an indirect attachment takes place, calling IMachine::getHardDisk() will return a differencing hard disk object, that is either based on the attached hard disk or on another differencing hard disk, the attached hard disk is eventually a root for (as described above). In both cases the returned hard disk object is the object the virtual machine actually uses to perform disk writes to.
Regardless of whether the attachment is direct or indirect, the machineId property of the attached disk will contain an UUID of the machine object IMachine::attachHardDisk() has been called on.
Note that both IMachine::attachHardDisk() and IMachine::detachHardDisk() are lazy operations. In particular, this means that when an indirect attachment is made, differencing hard disks are not created until machine settings are committed using IMachine::saveSettings(). Similarly, when a differencing hard disk is detached, it is not deleted until IMachine::saveSettings() is called. Calling IMachine::discardSettings() cancels all lazy attachments or detachments made since the last commit and effectively restores the previous set of hard disks.
The accessible attribute of the hard disk object defines the accessibility state of the respective hard disk storage (for example, the VDI file for IVirtualDiskImage objects). If the value of this attribute is false
then some hard disk attributes may contain invalid or outdated values (for example, the virtual or the actual hard disk size) until a new accessibility check is done that returns true
(see the attribute description for more details).
true
, you will get wrong (zero) values.{FD443EC1-000F-4F5B-9282-D72760A66916}
void IHardDisk::cloneToImage | ( | in wstring | filePath, | |
out IVirtualDiskImage | image, | |||
[retval] out IProgress | progress | |||
) |
Starts creating a clone of this hard disk.
The cloned hard disk will use the specified Virtual Disk Image file as a storage and 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 specified image file path can be absolute (full path) or relative to the VirtualBox home directory. If only a file name without any path is given, the default VDI folder will be used as a path to the image file.
It is an error to use the object returned in the image parameter until the returned progress object reports success.
filePath | Path to a file where to store the cloned hard disk. | |
image | Cloned hard disk object. | |
progress | Progress object to track the operation completion. |
readonly attribute uuid IHardDisk::id |
UUID of the hard disk.
For newly created hard disk objects, this value is a randomly generated UUID.
attribute wstring IHardDisk::description |
Optional description of the hard disk.
For a newly created hard disk, this value is null
.
false
. Also, you cannot assign it a new value in this case. readonly attribute HardDiskStorageType IHardDisk::storageType |
Storage type of this hard disk.
Storage type is defined when you open or create a new hard disk object.
readonly attribute wstring IHardDisk::location |
Storage location of this hard disk.
The returned string serves for informational purposes only. To access detailed information about the storage, query the appropriate storage-specific interface.
attribute HardDiskType IHardDisk::type |
Type (behavior) of this hard disk.
For a newly created or opened hard disk, this value is HardDiskType::Normal.
readonly attribute IHardDisk IHardDisk::parent |
Parent of this hard disk (a hard disk this one is directly based on).
Only differencing hard disks have parents, so a null
object is returned for a hard disk of any other type.
readonly attribute IHardDiskCollection IHardDisk::children |
Children of this hard disk (all differencing hard disks for those this one is a parent).
An empty collection is returned, if this hard disk doesn't have any children.
readonly attribute IHardDisk IHardDisk::root |
Root hard disk of this hard disk.
If this hard disk is a differencing hard disk, its root hard disk is the first disk on the branch. For all other types of hard disks, this property returns the hard disk object itself (i.e. the same object you read this property on).
readonly attribute boolean IHardDisk::accessible |
Whether the hard disk storage is currently accessible or not.
The storage, for example, can be unaccessible if it doesn't exist or if it is placed on a network resource that is not available by the time this attribute is read.
In the current implementation, the value of this property is also false
if this hard disk is attached to a running virtual machine.
The accessibility check is performed automatically every time this attribute is read. You should keep it in mind that this check may be slow and can block the calling thread for a long time (for example, if the network resourse where the hard disk storage is located is down).
The following attributes of the hard disk object are considered to be invalid when this attribute is false
:
readonly attribute boolean IHardDisk::allAccessible |
Whether the whole hard disk branch, starting from this image and going through its ancestors up to the root, is accessible or not.
This property makes sense only for differencing hard disks. For all other types of hard disks it returns the same value as accessible.
readonly attribute wstring IHardDisk::lastAccessError |
String describing the reason of inaccessibility of this hard disk after the last call to accessible that returned false
.
A null
value of this property means that the last accessibility check returned true
.
readonly attribute unsigned long long IHardDisk::size |
Logical size of this hard disk (in megabytes), as reported to the guest OS running inside the vurtual machine this disk is attached to.
The logical size is defined when the hard disk is created.
Reading this property is meaningless when accessible is false
readonly attribute unsigned long long IHardDisk::actualSize |
Physical size of the storage used to store hard disk data (in bytes).
This size is usually less than the logical size of the hard disk, depending on the storage type and on the size optimization method used for that storage.
false
readonly attribute uuid IHardDisk::machineId |
UUID of the machine this hard disk is attached to (or a null
UUID if it is not attached).
null
in this case. readonly attribute uuid IHardDisk::snapshotId |
UUID of the snapshot this hard disk is associated with (or null
UUID if it is not associated with any snapshot).
null
if machineId is null
.
Writethrough hard disks are always attached directly and cannot be involved when taking snapshots, so this attribute is meaningless and therefore always null
.