# IHardDisk Interface Reference

The IHardDisk interface represents a virtual hard disk drive used by virtual machines. More...

List of all members.

## 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).

## Detailed Description

The IHardDisk interface represents a virtual hard disk drive used by virtual machines.

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.

### Storage Types

The storage type of the virtual hard disk determines where and how it stores its data (sectors). Currently, the following storage types are supported:

- Virtual Disk Image (VDI), a regular file in the file system of the host OS (represented by the IVirtualDiskImage interface). This file has a special format optimized so that unused sectors of data occupy much less space than on a physical hard disk.
- iSCSI Remote Disk, a disk accessed via the Internet SCSI protocol over a TCP/IP network link (represented by the IISCSIHardDisk interface).
- VMware VMDK image, a regular file in the file system of the host OS (represented by the IVMDKImage interface). Note that the regular file may be just a descriptor referring to further files, so don't make assumptions about the OS representation of a VMDK image.
- Custom HardDisk, a disk accessed via a plugin which is loaded when the disk is accessed (represented by the ICustomHardDisk interface).
- Virtual PC VHD Image, a regular file in the file system of the host OS (represented by the IVHDImage interface).

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.

### Virtual Hard Disk Types

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:

- Normal
- Immutable
- Writethrough

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,

- The virtual hard disk geometry seen by the guest OS is always defined by the root hard disk.
- All hard disks on a branch, up to the root, must be accessible for a given differencing hard disk in order to let it function properly when the virtual machine is running.

Differencing hard disks can be implicitly created by VirtualBox in the following cases:

- When a hard disk is indirectly attached to the virtual machine using IMachine::attachHardDisk(). In this case, all disk writes performed by the guest OS will go to the created diffferencing hard disk, as opposed to the direct attachment, where all changes are written to the attached hard disk itself.
- When a snapshot of the virtual machine is taken. After that, disk writes to hard disks the differencing ones have been created for, will be directed to those differencing hard disks, to preserve the contents of the original disks.

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.

### Creating, Opening and Registering Hard Disks

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.

### More about Indirect Hard Disk Attachments

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.

### Hard Disk Accessibility

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).

Note:
  Since checking the accessibility of a hard disk is a potentially very slow operation, it is not performed implicitly when the VirtualBox server process starts up to prevent the application from freezing. In particular, this means that if you try to read hard disk properties that depend on the accessibility state without first reading the value of the accessible attribute and ensuring its value is `true`, you will get wrong (zero) values.

Interface ID:
  `{FD443EC1-000F-4F5B-9282-D72760A66916}`

## Member Function Documentation

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.

Parameters:

  | 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.

Note:
  In the current implementation, only non-differencing hard disks can be cloned.

## Member Data Documentation

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`.

Note:
  For some storage types, reading this property is meaningless when accessible is `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.

Note:
  In the current implementation, this property can be changed only on an unregistered hard disk object. This may be changed later.

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`:

- size
- actualSize

Individual hard disk storage type interfaces may define additional attributes that depend on the accessibility state.

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.

Note:
  Reading this property on a differencing hard disk will return the size of its root hard disk.

  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.

Note:
  Reading this property is meaningless when accessible is `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).

Note:
  Immutable hard disks are never attached directly, so this attribute is always `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).

Note:
  This attribute is always `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`.