VirtualBox Main API
Public Attributes | List of all members
IMediumAttachment Interface Reference

The IMediumAttachment interface links storage media to virtual machines. More...

Inheritance diagram for IMediumAttachment:

Public Attributes

readonly attribute IMedium medium
 Medium object associated with this attachment; it can be null for removable devices. More...
 
readonly attribute wstring controller
 Name of the storage controller of this attachment; this refers to one of the controllers in IMachine::storageControllers by name. More...
 
readonly attribute long port
 Port number of this attachment. More...
 
readonly attribute long device
 Device slot number of this attachment. More...
 
readonly attribute DeviceType type
 Device type of this attachment. More...
 
readonly attribute boolean passthrough
 Pass I/O requests through to a device on the host. More...
 
readonly attribute boolean temporaryEject
 Whether guest-triggered eject results in unmounting the medium. More...
 
readonly attribute boolean isEjected
 Signals that the removable medium has been ejected. More...
 
readonly attribute boolean nonRotational
 Whether the associated medium is non-rotational. More...
 
readonly attribute boolean discard
 Whether the associated medium supports discarding unused blocks. More...
 
readonly attribute boolean hotPluggable
 Whether this attachment is hot pluggable or not. More...
 
readonly attribute IBandwidthGroup bandwidthGroup
 The bandwidth group this medium attachment is assigned to. More...
 

Detailed Description

The IMediumAttachment interface links storage media to virtual machines.

For each medium (IMedium) which has been attached to a storage controller (IStorageController) of a machine (IMachine) via the IMachine::attachDevice method, one instance of IMediumAttachment is added to the machine's IMachine::mediumAttachments array attribute.

Each medium attachment specifies the storage controller as well as a port and device number and the IMedium instance representing a virtual hard disk or floppy or DVD image.

For removable media (DVDs or floppies), there are two additional options. For one, the IMedium instance can be null to represent an empty drive with no media inserted (see IMachine::mountMedium); secondly, the medium can be one of the pseudo-media for host drives listed in IHost::DVDDrives or IHost::floppyDrives.

Attaching Hard Disks

Hard disks are attached to virtual machines using the IMachine::attachDevice method and detached using the IMachine::detachDevice method. Depending on a medium's type (see IMedium::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 <i>deferred</i> fashion. This means
  that the given hard disk remains associated with the given machine after a
  successful @link IMachine::detachDevice IMachine::detachDevice@endlink<b></b> call until
  @link IMachine::saveSettings IMachine::saveSettings@endlink<b></b> 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
  @link IMachine::discardSettings IMachine::discardSettings@endlink<b></b> before the settings
  are saved (committed).

  Note that if @link IMachine::discardSettings IMachine::discardSettings@endlink<b></b> is called after
  indirectly attaching some hard disks to the machine but before a call to
  @link IMachine::saveSettings IMachine::saveSettings@endlink<b></b> is made, it will implicitly delete
  all differencing hard disks implicitly created by
  @link IMachine::attachDevice IMachine::attachDevice@endlink<b></b> for these indirect attachments.
  Such implicitly created hard disks will also be immediately deleted when
  detached explicitly using the @link IMachine::detachDevice IMachine::detachDevice@endlink<b></b>
  call if it is made before @link IMachine::saveSettings IMachine::saveSettings@endlink<b></b>. 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 @link IMachine::attachDevice IMachine::attachDevice@endlink<b></b>
  before the last @link IMachine::saveSettings IMachine::saveSettings@endlink<b></b> call will
  <b>not</b> 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 @link IMedium::deleteStorage IMedium::deleteStorage@endlink<b></b> after they are actually de-associated
  from this machine by the @link IMachine::saveSettings IMachine::saveSettings@endlink<b></b> call.

  <h3>Smart Attachment</h3>

  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.

Interface ID:
{3785B3F7-7B5F-4000-8842-AD0CC6AB30B7}

Member Data Documentation

readonly attribute IMedium IMediumAttachment::medium

Medium object associated with this attachment; it can be null for removable devices.

readonly attribute wstring IMediumAttachment::controller

Name of the storage controller of this attachment; this refers to one of the controllers in IMachine::storageControllers by name.

readonly attribute long IMediumAttachment::port

Port number of this attachment.

See IMachine::attachDevice for the meaning of this value for the different controller types.

readonly attribute long IMediumAttachment::device

Device slot number of this attachment.

See IMachine::attachDevice for the meaning of this value for the different controller types.

readonly attribute DeviceType IMediumAttachment::type

Device type of this attachment.

readonly attribute boolean IMediumAttachment::passthrough

Pass I/O requests through to a device on the host.

readonly attribute boolean IMediumAttachment::temporaryEject

Whether guest-triggered eject results in unmounting the medium.

readonly attribute boolean IMediumAttachment::isEjected

Signals that the removable medium has been ejected.

This is not necessarily equivalent to having a null medium association.

readonly attribute boolean IMediumAttachment::nonRotational

Whether the associated medium is non-rotational.

readonly attribute boolean IMediumAttachment::discard

Whether the associated medium supports discarding unused blocks.

readonly attribute boolean IMediumAttachment::hotPluggable

Whether this attachment is hot pluggable or not.

readonly attribute IBandwidthGroup IMediumAttachment::bandwidthGroup

The bandwidth group this medium attachment is assigned to.