The IMedium interface represents virtual storage for a machine's hard disks, CD/DVD or floppy drives. More...
Public Member Functions | |
void | refreshState ([retval] out MediumState state) |
If the current medium state (see MediumState) is one of "Created", "Inaccessible" or "LockedRead", then this performs an accessibility check on the medium and sets the value of the state attribute accordingly; that value is also returned for convenience. | |
void | getSnapshotIds (in wstringUUID machineId,[retval] out wstringUUID[] snapshotIds) |
Returns an array of UUIDs of all snapshots of the given machine where this medium is attached to. | |
void | lockRead ([retval] out MediumState state) |
Locks this medium for reading. | |
void | unlockRead ([retval] out MediumState state) |
Cancels the read lock previously set by lockRead. | |
void | lockWrite ([retval] out MediumState state) |
Locks this medium for writing. | |
void | unlockWrite ([retval] out MediumState state) |
Cancels the write lock previously set by lockWrite. | |
void | close () |
Closes this medium. | |
void | getProperty (in wstring name,[retval] out wstring value) |
Returns the value of the custom medium property with the given name. | |
void | setProperty (in wstring name, in wstring value) |
Sets the value of the custom medium 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 MediumVariant 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 medium. | |
void | createDiffStorage (in IMedium target, in MediumVariant variant,[retval] out IProgress progress) |
Starts creating an empty differencing storage unit based on this medium in the format and at the location defined by the target argument. | |
void | mergeTo (in IMedium target,[retval] out IProgress progress) |
Starts merging the contents of this medium and all intermediate differencing media in the chain to the given target medium. | |
void | cloneTo (in IMedium target, in MediumVariant variant, in IMedium parent,[retval] out IProgress progress) |
Starts creating a clone of this medium in the format and at the location defined by the target argument. | |
void | compact ([retval] out IProgress progress) |
Starts compacting of this medium. | |
void | resize (in unsigned long long logicalSize,[retval] out IProgress progress) |
Starts resizing this medium. | |
void | reset ([retval] out IProgress progress) |
Starts erasing the contents of this differencing medium. | |
Public Attributes | |
readonly attribute wstringUUID | id |
UUID of the medium. | |
attribute wstring | description |
Optional description of the medium. | |
readonly attribute MediumState | state |
Returns the current medium state, which is the last state set by the accessibility check performed by refreshState. | |
attribute wstring | location |
Location of the storage unit holding medium data. | |
readonly attribute wstring | name |
Name of the storage unit holding medium data. | |
readonly attribute DeviceType | deviceType |
Kind of device (DVD/Floppy/HardDisk) which is applicable to this medium. | |
readonly attribute boolean | hostDrive |
True if this corresponds to a drive on the host. | |
readonly attribute unsigned long long | size |
Physical size of the storage unit used to hold medium data (in bytes). | |
readonly attribute wstring | format |
Storage format of this medium. | |
readonly attribute IMediumFormat | mediumFormat |
Storage medium format object corresponding to this medium. | |
attribute MediumType | type |
Type (role) of this medium. | |
readonly attribute IMedium | parent |
Parent of this medium (the medium this medium is directly based on). | |
readonly attribute IMedium[] | children |
Children of this medium (all differencing media directly based on this medium). | |
readonly attribute IMedium | base |
Base medium of this medium. | |
readonly attribute boolean | readOnly |
Returns true if this medium is read-only and false otherwise. | |
readonly attribute unsigned long long | logicalSize |
Logical size of this medium (in megabytes), as reported to the guest OS running inside the virtual machine this medium is attached to. | |
attribute boolean | autoReset |
Whether this differencing medium will be automatically reset each time a virtual machine it is attached to is powered up. | |
readonly attribute wstring | lastAccessError |
Text message that represents the result of the last accessibility check performed by refreshState. | |
readonly attribute wstringUUID[] | machineIds |
Array of UUIDs of all machines this medium is attached to. |
The IMedium interface represents virtual storage for a machine's hard disks, CD/DVD or floppy drives.
It will typically represent a disk image on the host, for example a VDI or VMDK file representing a virtual hard disk, or an ISO or RAW file representing virtual removable media, but can also point to a network location (e.g. for iSCSI targets).
Instances of IMedium are connected to virtual machines by way of medium attachments (see IMediumAttachment), which link the storage medium to a particular device slot of a storage controller of the virtual machine. In the VirtualBox API, virtual storage is therefore always represented by the following chain of object links:
IMachine::mediumAttachments contains an array of medium attachments (instances of IMediumAttachment), each containing a storage controller from the above array, a port/device specification, and an instance of IMedium representing the medium storage (image file).
For removable media, the storage medium is optional; a medium attachment with no medium represents a CD/DVD or floppy drive with no medium inserted. By contrast, hard disk attachments will always have an IMedium object attached.
Existing media are opened using the following methods, depending on the media type:
New hard disk media can be created with the VirtualBox API using the IVirtualBox::createHardDisk method.
CD/DVD and floppy images (ISO and RAW files) are usually created outside VirtualBox, e.g. by storing a copy of the real medium of the corresponding type in a regular file.
Only for CD/DVDs and floppies, an IMedium instance can also represent a host drive; in that case the id attribute contains the UUID of one of the drives in IHost::DVDDrives or IHost::floppyDrives.
When an existing medium is opened for the first time, it is automatically remembered by the given VirtualBox installation or, in other words, becomes a known medium. Known media are stored in the media registry transparently maintained by VirtualBox and stored in settings files so that this registry is preserved when VirtualBox is not running.
Newly created virtual media are remembered only when the associated storage unit is actually created.
All known media can be enumerated using IVirtualBox::hardDisks, IVirtualBox::DVDImages and IVirtualBox::floppyImages attributes. Individual media can be quickly found by UUID using IVirtualBox::getHardDisk and similar methods or by location using IVirtualBox::findHardDisk and similar methods.
Only known media can be attached to virtual machines.
Removing known media from the media registry is performed when the given medium is closed using the close method or when its associated storage unit is deleted.
VirtualBox defers media accessibility checks until the refreshState method is called explicitly on a medium. This is done to make the VirtualBox object ready for serving requests as fast as possible and let the end-user application decide if it needs to check media accessibility right away or not.
As a result, when VirtualBox starts up (e.g. the VirtualBox object gets created for the first time), all known media are in the "Inaccessible" state, but the value of the lastAccessError attribute is an empty string because no actual accessibility check has been made yet.
After calling refreshState, a medium is considered accessible if its storage unit can be read. In that case, the state attribute has a value of "Created". If the storage unit cannot be read (for example, because it is located on a disconnected network resource, or was accidentally deleted outside VirtualBox), the medium is considered inaccessible, which is indicated by the "Inaccessible" state. The exact reason why the medium is inaccessible can be obtained by reading the lastAccessError attribute.
There are four types of medium behavior (see MediumType): "normal", "immutable", "writethrough" and "shareable", represented by the type attribute. The type of the medium defines how the medium is attached to a virtual machine and what happens when a snapshot of the virtual machine with the attached medium is taken. At the moment DVD and floppy media are always of type "writethrough".
All media can be also divided in two groups: base media and differencing media. A base medium contains all sectors of the medium data in its own storage and therefore can be used independently. In contrast, a differencing mediun is a "delta" to some other medium and contains only those sectors which differ from that other medium, which is then called a parent. The differencing medium is said to be linked to that parent. The parent may be itself a differencing medium, thus forming a chain of linked media. The last element in that chain must always be a base medium. Note that several differencing media may be linked to the same parent medium.
Differencing media can be distinguished from base media by querying the parent attribute: base media 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 medium tree (from the child medium to its parent). It is also possible to walk down the tree using the children attribute.
Note that the type of all differencing media is "normal"; all other values are meaningless for them. Base media 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 MediumState_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::attachDevice method and detached using the IMachine::detachDevice 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::attachDevice performs a direct attachment then the same hard disk will be returned in response to the subsequent IMachine::getMedium call; however if an indirect attachment is performed then IMachine::getMedium will return the implicitly created differencing hard disk, not the original one passed to IMachine::attachDevice. In detail:
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::detachDevice 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::attachDevice for these indirect attachments. Such implicitly created hard disks will also be immediately deleted when detached explicitly using the IMachine::detachDevice 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::attachDevice 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.
{1D578F43-5EF1-4415-B556-7592D3CCDC8F}
void IMedium::refreshState | ( | [retval] out MediumState | state | ) |
If the current medium state (see MediumState) is one of "Created", "Inaccessible" or "LockedRead", then this performs an accessibility check on the medium and sets the value of the state attribute accordingly; that value is also returned for convenience.
For all other state values, this does not perform a refresh but returns the state only.
The refresh, if performed, may take a long time (several seconds or even minutes, depending on the storage unit location and format) because it performs an accessibility check of the storage unit. This check may cause a significant delay if the storage unit of the given medium is, for example, a file located on a network share which is not currently accessible due to connectivity problems. In that case, the call will not return until a timeout interval defined by the host OS for this operation expires. For this reason, it is recommended to never read this attribute on the main UI thread to avoid making the UI unresponsive.
If the last known state of the medium is "Created" and the accessibility check fails, then the state would be set to "Inaccessible", and lastAccessError may be used to get more details about the failure. If the state of the medium is "LockedRead", then it remains the same, and a non-empty value of lastAccessError will indicate a failed accessibility check in this case.
Note that not all medium states are applicable to all medium types.
state | New medium state. |
void IMedium::getSnapshotIds | ( | in wstringUUID | machineId, | |
[retval] out wstringUUID[] | snapshotIds | |||
) |
Returns an array of UUIDs of all snapshots of the given machine where this medium is attached to.
If the medium is attached to the machine in the current state, then the first element in the array will always be the ID of the queried machine (i.e. the value equal to the machineId
argument), followed by snapshot IDs (if any).
If the medium is not attached to the machine in the current state, then the array will contain only snapshot IDs.
The returned array may be null
if this medium is not attached to the given machine at all, neither in the current state nor in one of the snapshots.
machineId | UUID of the machine to query. | |
snapshotIds | Array of snapshot UUIDs of the given machine using this medium. |
void IMedium::lockRead | ( | [retval] out MediumState | state | ) |
Locks this medium for reading.
A read lock is shared: many clients can simultaneously lock the same medium for reading unless it is already locked for writing (see lockWrite) in which case an error is returned.
When the medium is locked for reading, it cannot be modified from within VirtualBox. This means that any method that changes the properties of this medium or contents of the storage unit will return an error (unless explicitly stated otherwise). That includes an attempt to start a virtual machine that wants to write to the the medium.
When the virtual machine is started up, it locks for reading all media it uses in read-only mode. If some medium cannot be locked for reading, the startup procedure will fail. A medium is typically locked for reading while it is used by a running virtual machine but has a depending differencing image that receives the actual write operations. This way one base medium can have multiple child differencing images which can be written to simultaneously. Read-only media such as DVD and floppy images are also locked for reading only (so they can be in use by multiple machines simultaneously).
A medium is also locked for reading when it is the source of a write operation such as cloneTo or mergeTo.
The medium locked for reading must be unlocked using the unlockRead method. Calls to lockRead can be nested and must be followed by the same number of paired unlockRead calls.
This method sets the medium state (see state) to "LockedRead" on success. The medium's previous state must be one of "Created", "Inaccessible" or "LockedRead".
Locking an inaccessible medium is not an error; this method performs a logical lock that prevents modifications of this medium through the VirtualBox API, not a physical file-system lock of the underlying storage unit.
This method returns the current state of the medium before the operation.
state | State of the medium after the operation. |
VBOX_E_INVALID_OBJECT_STATE | Invalid medium state (e.g. not created, locked, inaccessible, creating, deleting). |
void IMedium::unlockRead | ( | [retval] out MediumState | state | ) |
Cancels the read lock previously set by lockRead.
For both success and failure, this method returns the current state of the medium after the operation.
See lockRead for more details.
state | State of the medium after the operation. |
VBOX_E_INVALID_OBJECT_STATE | Medium not locked for reading. |
void IMedium::lockWrite | ( | [retval] out MediumState | state | ) |
Locks this medium for writing.
A write lock, as opposed to lockRead, is exclusive: there may be only one client holding a write lock, and there may be no read locks while the write lock is held. As a result, read-locking fails if a write lock is held, and write-locking fails if either a read or another write lock is held.
When a medium is locked for writing, it cannot be modified from within VirtualBox, and it is not guaranteed that the values of its properties are up-to-date. Any method that changes the properties of this medium or contents of the storage unit will return an error (unless explicitly stated otherwise).
When a virtual machine is started up, it locks for writing all media it uses to write data to. If any medium could not be locked for writing, the startup procedure will fail. If a medium has differencing images, then while the machine is running, only the last ("leaf") differencing image is locked for writing, whereas its parents are locked for reading only.
A medium is also locked for writing when it is the target of a write operation such as cloneTo or mergeTo.
The medium locked for writing must be unlocked using the unlockWrite method. Write locks cannot be nested.
This method sets the medium state (see state) to "LockedWrite" on success. The medium's previous state must be either "Created" or "Inaccessible".
Locking an inaccessible medium is not an error; this method performs a logical lock that prevents modifications of this medium through the VirtualBox API, not a physical file-system lock of the underlying storage unit.
For both, success and failure, this method returns the current state of the medium before the operation.
state | State of the medium after the operation. |
VBOX_E_INVALID_OBJECT_STATE | Invalid medium state (e.g. not created, locked, inaccessible, creating, deleting). |
void IMedium::unlockWrite | ( | [retval] out MediumState | state | ) |
Cancels the write lock previously set by lockWrite.
For both success and failure, this method returns the current state of the medium after the operation.
See lockWrite for more details.
state | State of the medium after the operation. |
VBOX_E_INVALID_OBJECT_STATE | Medium not locked for writing. |
void IMedium::close | ( | ) |
Closes this medium.
The medium must not be attached to any known virtual machine and must not have any known child media, otherwise the operation will fail.
When the medium is successfully closed, it gets removed from the list of remembered media, but its storage unit is not deleted. In particular, this means that this medium can be later opened again using the IVirtualBox::openHardDisk call.
Note that after this method successfully returns, the given medium object becomes uninitialized. This means that any attempt to call any of its methods or attributes will fail with the "Object not ready" (E_ACCESSDENIED)
error.
VBOX_E_INVALID_OBJECT_STATE | Invalid medium state (other than not created, created or inaccessible). |
VBOX_E_OBJECT_IN_USE | Medium attached to virtual machine. |
VBOX_E_FILE_ERROR | Settings file not accessible. |
VBOX_E_XML_ERROR | Could not parse the settings file. |
void IMedium::getProperty | ( | in wstring | name, | |
[retval] out wstring | value | |||
) |
Returns the value of the custom medium property with the given name.
The list of all properties supported by the given medium format can be obtained with IMediumFormat::describeProperties.
Note that if this method returns an empty string in 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 IMedium::setProperty | ( | in wstring | name, | |
in wstring | value | |||
) |
Sets the value of the custom medium property with the given name.
The list of all properties supported by the given medium format can be obtained with IMediumFormat::describeProperties.
Note that setting the property value to null
or an empty string 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 IMedium::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 an empty string 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 medium format can be obtained with IMediumFormat::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, an empty string 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 IMedium::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 medium format can be obtained with IMediumFormat::describeProperties.
Note that setting the property value to null
or an empty string 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 IMedium::createBaseStorage | ( | in unsigned long long | logicalSize, | |
in MediumVariant | 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 medium is placed in MediumState_Creating state. If the create operation fails, the medium will be placed back in MediumState_NotCreated state.
After the returned progress object reports that the operation has successfully completed, the medium state will be set to MediumState_Created, the medium will be remembered by this VirtualBox installation and may be attached to virtual machines.
logicalSize | Maximum logical size of the medium 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 IMediumFormat::capabilities. |
void IMedium::deleteStorage | ( | [retval] out IProgress | progress | ) |
Starts deleting the storage unit of this medium.
The medium must not be attached to any known virtual machine and must not have any known child media, 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 medium is being in use (locked for read or for write) or inaccessible. Therefore, the only valid state for this operation to succeed is MediumState_Created.
Before the operation starts, the medium is placed in MediumState_Deleting state and gets removed from the list of remembered hard disks (media registry). If the delete operation fails, the medium will be remembered again and placed back to MediumState_Created state.
After the returned progress object reports that the operation is complete, the medium state will be set to MediumState_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 | Medium is attached to a virtual machine. |
VBOX_E_NOT_SUPPORTED | Storage deletion is not allowed because neither of storage creation operations are supported. See IMediumFormat::capabilities. |
void IMedium::createDiffStorage | ( | in IMedium | target, | |
in MediumVariant | variant, | |||
[retval] out IProgress | progress | |||
) |
Starts creating an empty differencing storage unit based on this medium in the format and at the location defined by the target argument.
The target medium must be in MediumState_NotCreated state (i.e. must not have an existing storage unit). Upon successful completion, this operation will set the type of the target medium to MediumType_Normal and create a storage unit necessary to represent the differencing medium 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 medium gets remembered by this VirtualBox installation and may be attached to virtual machines.
target | Target medium. | |
variant | Exact image variant which should be created. | |
progress | Progress object to track the operation completion. |
VBOX_E_OBJECT_IN_USE | Medium not in NotCreated state. |
Starts merging the contents of this medium and all intermediate differencing media in the chain to the given target medium.
The target medium must be either a descendant of this medium 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 medium chain:
Base <- Diff_1 <- Diff_2
Here, 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:
target | Target medium. | |
progress | Progress object to track the operation completion. |
void IMedium::cloneTo | ( | in IMedium | target, | |
in MediumVariant | variant, | |||
in IMedium | parent, | |||
[retval] out IProgress | progress | |||
) |
Starts creating a clone of this medium in the format and at the location defined by the target argument.
The target medium must be either in MediumState_NotCreated state (i.e. must not have an existing storage unit) or in MediumState_Created state (i.e. created and not locked, and big enough to hold the data or else the copy will be partial). Upon successful completion, the cloned medium will contain exactly the same sector data as the medium being cloned, except that in the first case a new UUID for the clone will be randomly generated, and in the second case the UUID will remain unchanged.
The parent argument defines which medium 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 medium for this parameter, including the parent of the medium which is being cloned. Even cloning to a child of the source medium is possible. Note that when cloning to an existing image, the parent irgument is ignored.
After the returned progress object reports that the operation is successfully complete, the target medium gets remembered by this VirtualBox installation and may be attached to virtual machines.
target | Target medium. | |
variant | Exact image variant which should be created. | |
parent | Parent of the cloned medium. | |
progress | Progress object to track the operation completion. |
E_NOTIMPL | The specified cloning variant is not supported at the moment. |
void IMedium::compact | ( | [retval] out IProgress | progress | ) |
Starts compacting of this medium.
This means that the medium 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 medium will be placed to MediumState_LockedWrite state and all its parent media (if any) will be placed to MediumState_LockedRead state for the duration of this operation.
Please note that the results can be either returned straight away, or later as the result of the background operation via the object returned via the progress parameter.
progress | Progress object to track the operation completion. |
VBOX_E_NOT_SUPPORTED | Medium format does not support compacting (but potentially needs it). |
void IMedium::resize | ( | in unsigned long long | logicalSize, | |
[retval] out IProgress | progress | |||
) |
Starts resizing this medium.
This means that the nominal size of the medium is set to the new value. Both increasing and decreasing the size is possible, and there are no safety checks, since VirtualBox does not make any assumptions about the medium contents.
Resizing usually needs additional disk space, and possibly also some temporary disk space. Note that resize does not create a full temporary copy of the medium, so the additional disk space requirement is usually much lower than using the clone operation.
This medium will be placed to MediumState_LockedWrite state for the duration of this operation.
Please note that the results can be either returned straight away, or later as the result of the background operation via the object returned via the progress parameter.
logicalSize | New nominal capacity of the medium in megabytes. | |
progress | Progress object to track the operation completion. |
VBOX_E_NOT_SUPPORTED | Medium format does not support resizing. |
void IMedium::reset | ( | [retval] out IProgress | progress | ) |
Starts erasing the contents of this differencing medium.
This operation will reset the differencing medium to its initial state when it does not contain any sector data and any read operation is redirected to its parent medium. This automatically gets called during VM power-up for every medium whose autoReset attribute is true
.
The medium will be write-locked for the duration of this operation (see lockWrite).
progress | Progress object to track the operation completion. |
VBOX_E_NOT_SUPPORTED | This is not a differencing medium. |
VBOX_E_INVALID_OBJECT_STATE | Medium is not in MediumState_Created or MediumState_Inaccessible state. |
readonly attribute wstringUUID IMedium::id |
UUID of the medium.
For a newly created medium, this value is a randomly generated UUID.
attribute wstring IMedium::description |
Optional description of the medium.
For a newly created medium the value of this attribute is an empty string.
Medium types that don't support this attribute will return E_NOTIMPL in attempt to get or set this attribute's value.
readonly attribute MediumState IMedium::state |
Returns the current medium state, which is the last state set by the accessibility check performed by refreshState.
If that method has not yet been called on the medium, the state is "Inaccessible"; as opposed to truly inaccessible media, the value of lastAccessError will be an empty string in that case.
attribute wstring IMedium::location |
Location of the storage unit holding medium data.
The format of the location string is medium type specific. For medium types using regular files in a host's file system, the location string is the full file name.
Some medium types may support changing the storage unit location by simply changing the value of this property. If this operation is not supported, the implementation will return E_NOTIMPL in attempt to set this attribute's value.
When setting a value of the location attribute which is a regular file in the host's file system, the given file name may be either relative to the VirtualBox home folder or absolute. Note that if the given location specification does not contain the file extension part then a proper default extension will be automatically appended by the implementation depending on the medium type.
readonly attribute wstring IMedium::name |
Name of the storage unit holding medium data.
The returned string is a short version of the location attribute that is suitable for representing the medium in situations where the full location specification is too long (such as lists and comboboxes in GUI frontends). This string is also used by frontends to sort the media list alphabetically when needed.
For example, for locations that are regular files in the host's file system, the value of this attribute is just the file name (+ extension), without the path specification.
Note that as opposed to the location attribute, the name attribute will not necessary be unique for a list of media of the given type and format.
readonly attribute DeviceType IMedium::deviceType |
Kind of device (DVD/Floppy/HardDisk) which is applicable to this medium.
readonly attribute boolean IMedium::hostDrive |
True if this corresponds to a drive on the host.
readonly attribute unsigned long long IMedium::size |
Physical size of the storage unit used to hold medium data (in bytes).
readonly attribute wstring IMedium::format |
Storage format of this medium.
The value of this attribute is a string that specifies a backend used to store medium data. The storage format is defined when you create a new medium or automatically detected when you open an existing medium, and cannot be changed later.
The list of all storage formats supported by this VirtualBox installation can be obtained using ISystemProperties::mediumFormats.
readonly attribute IMediumFormat IMedium::mediumFormat |
Storage medium format object corresponding to this medium.
The value of this attribute is a reference to the medium format object that specifies the backend properties used to store medium data. The storage format is defined when you create a new medium or automatically detected when you open an existing medium, and cannot be changed later.
null
is returned if there is no associated medium format object. This can e.g. happen for medium objects representing host drives and other special medium objects. attribute MediumType IMedium::type |
Type (role) of this medium.
The following constraints apply when changing the value of this attribute:
The type of a newly created or opened medium is set to MediumType_Normal, except for DVD and floppy media, which have a type of MediumType_Writethrough.
readonly attribute IMedium IMedium::parent |
Parent of this medium (the medium this medium is directly based on).
Only differencing media have parents. For base (non-differencing) media, null
is returned.
readonly attribute IMedium [] IMedium::children |
Children of this medium (all differencing media directly based on this medium).
A null
array is returned if this medium does not have any children.
readonly attribute IMedium IMedium::base |
Base medium of this medium.
If this is a differencing medium, its base medium is the medium the given medium branch starts from. For all other types of media, this property returns the medium object itself (i.e. the same object this property is read on).
readonly attribute boolean IMedium::readOnly |
Returns true
if this medium is read-only and false
otherwise.
A medium is considered to be read-only when its contents cannot be modified without breaking the integrity of other parties that depend on this medium such as its child media or snapshots of virtual machines where this medium is attached to these machines. If there are no children and no such snapshots then there is no dependency and the medium 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 medium to a virtual machine. If the value is false
then the medium will be attached directly. If the value is true
then the medium will be attached indirectly by creating a new differencing child medium for that. See the interface description for more information.
Note that all Immutable media are always read-only while all Writethrough media are always not.
readonly attribute unsigned long long IMedium::logicalSize |
Logical size of this medium (in megabytes), as reported to the guest OS running inside the virtual machine this medium is attached to.
The logical size is defined when the medium is created and cannot be changed later.
attribute boolean IMedium::autoReset |
Whether this differencing medium will be automatically reset each time a virtual machine it is attached to is powered up.
This attribute is automatically set to true
for the last differencing image of an "immutable" medium (see MediumType).
See reset for more information about resetting differencing media.
VBOX_E_NOT_SUPPORTED | This is not a differencing medium (when changing the attribute value). |
false
. Changing the value of this property in this case is not supported. readonly attribute wstring IMedium::lastAccessError |
Text message that represents the result of the last accessibility check performed by refreshState.
An empty string is returned if the last accessibility check was successful or has not yet been called. As a result, if state is "Inaccessible" and this attribute is empty, then refreshState has yet to be called; this is the default value of media after VirtualBox initialization. A non-empty string indicates a failure and should normally describe a reason of the failure (for example, a file read error).
readonly attribute wstringUUID [] IMedium::machineIds |
Array of UUIDs of all machines this medium is attached to.
A null
array is returned if this medium is not attached to any machine or to any machine's snapshot.