VirtualBox

Changeset 35918 in vbox


Ignore:
Timestamp:
Feb 9, 2011 4:27:31 PM (14 years ago)
Author:
vboxsync
Message:

Main: API docs (IMedium + IMediumAttachment cleanup, media registry updates)

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Main/idl/VirtualBox.xidl

    r35910 r35918  
    18711871        The format of the location string is storage format specific. See
    18721872        <link to="IMedium::location"/> and IMedium for more details.
    1873 
    1874         Prior to VirtualBox 4.0, opening a medium added it to a global media
    1875         registry in the VirtualBox.xml file, which was shared between all machines
    1876         and made transporting machines and their media from one host to another
    1877         difficult.
    1878 
    1879         Starting with VirtualBox 4.0, media are only added to a registry when
    1880         they are attached to a machine. Machines created with VirtualBox 4.0
    1881         or later can have their own media registry. As a result, a medium attached
    1882         to such a machine will be remembered in that machine's XML settings file.
    1883         Media attached to older machines will continue to be added to the global
    1884         registry.
    18851873
    18861874        <result name="VBOX_E_FILE_ERROR">
    … …  
    34213409    </const>
    34223410    <const name="DetachAllReturnHardDisksOnly"    value="3">
    3423       <desc>Delete all snapshots, detach all media and return hard disks for closing, but not removeable media.</desc>
     3411      <desc>Delete all snapshots, detach all media and return hard disks for closing, but not removable media.</desc>
    34243412    </const>
    34253413    <const name="Full"                            value="4">
    … …  
    43964384        This method is intended for managing storage devices in general while a
    43974385        machine is powered off. It can be used to attach and detach fixed
    4398         and removeable media. The following kind of media can be attached
     4386        and removable media. The following kind of media can be attached
    43994387        to a machine:
    44004388
    … …  
    44094397            in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/>
    44104398            arrays to indicate a host drive.
    4411             For removeable devices, you can also use <link to="IMachine::mountMedium"/>
     4399            For removable devices, you can also use <link to="IMachine::mountMedium"/>
    44124400            to change the media while the machine is running.
    44134401          </li>
    … …  
    52525240          <li>With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved"
    52535241            state or if it has snapshots or media attached. All media attached to the current machine
    5254             state or in snapshots will be detached. For machines created with VirtualBox 4.0 or
    5255             later, media which are registered in this machine's media registry which are still
    5256             attached to another machine besides this machine will be moved a another machine's
    5257             registry. No medium objects will be returned; all of the machine's media will remain open.</li>
     5242            state or in snapshots will be detached. No medium objects will be returned;
     5243            all of the machine's media will remain open.</li>
    52585244          <li>With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone",
    52595245            except that all the hard disk medium objects which were detached from the machine will
    … …  
    52615247            API for closing and deletion.</li>
    52625248          <li>With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except
    5263             that all media will be returned in the array, including removeable media like DVDs and
     5249            that all media will be returned in the array, including removable media like DVDs and
    52645250            floppies. This might be useful if the user wants to inspect in detail which media were
    52655251            attached to the machine. Be careful when passing the media array to <link to="#delete" />
    … …  
    52675253        </ul>
    52685254
     5255        A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the
     5256        resulting IMedium array to <link to="#delete"/>. This way, the machine is completely
     5257        deleted with all its saved states and hard disk images, but images for removable
     5258        drives (such as ISO and RAW files) will remain on disk.
     5259
    52695260        This API does not verify whether the media files returned in the array are still
    52705261        attached to other machines (i.e. shared between several machines). If such a shared
    … …  
    52725263        and the image will be silently skipped.
    52735264
    5274         A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the
    5275         resulting IMedia array to <link to="#delete"/>. This way, the machine is completely
    5276         deleted with all its saved states and hard disk images, but images for removeable
    5277         drives (such as ISO and RAW files) will remain on disk.
    5278 
    5279         The call will fail if the machine is currently locked (see <link to="ISession" />).
    5280         It implicitly calls <link to="#saveSettings"/> to save all current machine settings
    5281         before unregistering it.
     5265        This API may, however, move media from this machine's media registry to other media
     5266        registries (see <link to="IMedium" /> for details on media registries). For machines
     5267        created with VirtualBox 4.0 or later, if media from this machine's media registry
     5268        are also attached to another machine (shared attachments), each such medium will be
     5269        moved to another machine's registry. This is because without this machine's media
     5270        registry, the other machine cannot find its media any more and would become inaccessible.
     5271
     5272        This API implicitly calls <link to="#saveSettings"/> to save all current machine settings
     5273        before unregistering it. It may also silently call saveSettings() on other machines
     5274        if media are moved to other machines' media registries.
    52825275
    52835276        After successful method invocation, the <link to="IMachineRegisteredEvent"/> event
    52845277        is fired.
     5278
     5279        The call will fail if the machine is currently locked (see <link to="ISession" />).
    52855280
    52865281        <note>
    … …  
    89538948    >
    89548949    <desc>
    8955       Virtual medium type.
    8956       <see>IMedium</see>
     8950      Virtual medium type. For each <link to="IMedium" />, this defines how the medium is
     8951      attached to a virtual machine (see <link to="IMediumAttachment" />) and what happens
     8952      when a snapshot (see <link to="ISnapshot" />) is taken of a virtual machine which has
     8953      the medium attached. At the moment DVD and floppy media are always of type "writethrough".
    89578954    </desc>
    89588955
    … …  
    90579054      hard disk or floppy or DVD image.
    90589055
    9059       For removeable media (DVDs or floppies), there are two additional
     9056      For removable media (DVDs or floppies), there are two additional
    90609057      options. For one, the IMedium instance can be @c null to represent
    90619058      an empty drive with no media inserted (see <link to="IMachine::mountMedium" />);
    90629059      secondly, the medium can be one of the pseudo-media for host drives
    90639060      listed in <link to="IHost::DVDDrives"/> or <link to="IHost::floppyDrives"/>.
    9064     </desc>
    9065 
    9066     <attribute name="medium" type="IMedium" readonly="yes">
    9067       <desc>Medium object associated with this attachment; it
    9068         can be @c null for removable devices.</desc>
    9069     </attribute>
    9070 
    9071     <attribute name="controller" type="wstring" readonly="yes">
    9072       <desc>Name of the storage controller of this attachment; this
    9073         refers to one of the controllers in <link to="IMachine::storageControllers" />
    9074         by name.</desc>
    9075     </attribute>
    9076 
    9077     <attribute name="port" type="long" readonly="yes">
    9078       <desc>Port number of this attachment.
    9079         See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
    9080       </desc>
    9081     </attribute>
    9082 
    9083     <attribute name="device" type="long" readonly="yes">
    9084       <desc>Device slot number of this attachment.
    9085         See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
    9086       </desc>
    9087     </attribute>
    9088 
    9089     <attribute name="type" type="DeviceType" readonly="yes">
    9090       <desc>Device type of this attachment.</desc>
    9091     </attribute>
    9092 
    9093     <attribute name="passthrough" type="boolean" readonly="yes">
    9094       <desc>Pass I/O requests through to a device on the host.</desc>
    9095     </attribute>
    9096 
    9097     <attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
    9098       <desc>The bandwidth group this medium attachment is assigned to.</desc>
    9099     </attribute>
    9100 
    9101   </interface>
    9102 
    9103   <interface
    9104     name="IMedium" extends="$unknown"
    9105     uuid="9edda847-1279-4b0a-9af7-9d66251ccc18"
    9106     wsmap="managed"
    9107     >
    9108     <desc>
    9109       The IMedium interface represents virtual storage for a machine's
    9110       hard disks, CD/DVD or floppy drives. It will typically represent
    9111       a disk image on the host, for example a VDI or VMDK file representing
    9112       a virtual hard disk, or an ISO or RAW file representing virtual
    9113       removable media, but can also point to a network location (e.g.
    9114       for iSCSI targets).
    9115 
    9116       Instances of IMedium are connected to virtual machines by way of
    9117       medium attachments (see <link to="IMediumAttachment" />), which link
    9118       the storage medium to a particular device slot of a storage controller
    9119       of the virtual machine.
    9120       In the VirtualBox API, virtual storage is therefore always represented
    9121       by the following chain of object links:
    9122 
    9123       <ul>
    9124         <li><link to="IMachine::storageControllers"/> contains an array of
    9125           storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
    9126           these are instances of <link to="IStorageController"/>).</li>
    9127         <li><link to="IMachine::mediumAttachments"/> contains an array of
    9128           medium attachments (instances of <link to="IMediumAttachment"/>),
    9129           each containing a storage controller from the above array, a
    9130           port/device specification, and an instance of IMedium representing
    9131           the medium storage (image file).
    9132 
    9133           For removable media, the storage medium is optional; a medium
    9134           attachment with no medium represents a CD/DVD or floppy drive
    9135           with no medium inserted. By contrast, hard disk attachments
    9136           will always have an IMedium object attached.</li>
    9137         <li>Each IMedium in turn points to a storage unit (such as a file
    9138           on the host computer or a network resource) that holds actual
    9139           data. This location is represented by the <link to="#location"/>
    9140           attribute.</li>
    9141       </ul>
    9142 
    9143       Existing media are opened using <link to="IVirtualBox::openMedium"/>;
    9144       new hard disk media can be created with the VirtualBox API using the
    9145       <link to="IVirtualBox::createHardDisk"/> method.
    9146 
    9147       CD/DVD and floppy images (ISO and RAW files) are usually created outside
    9148       VirtualBox, e.g. by storing a copy of the real medium of the corresponding
    9149       type in a regular file.
    9150 
    9151       Only for CD/DVDs and floppies, an IMedium instance can also represent a host
    9152       drive; in that case the <link to="#id" /> attribute contains the UUID of
    9153       one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
    9154 
    9155       <h3>Known media</h3>
    9156 
    9157       When an existing medium is opened and attached to a virtual machine, it
    9158       is automatically added to a media registry. If the medium has first
    9159       been attached to a machine which was created by VirtualBox 4.0 or later,
    9160       it is added to that machine's media registry (in the machine XML settings
    9161       file; this way all information about a machine's media attachments is
    9162       contained in a single file). For older media attachments (i.e. if the
    9163       medium was first attached to a machine which was created with a VirtualBox
    9164       version before 4.0), media continue to be registered in the global
    9165       VirtualBox settings file, for backwards compatibility.
    9166 
    9167       See <link to="IVirtualBox::openMedium" /> for more information.
    9168 
    9169       All known media can be enumerated using
    9170       <link to="IVirtualBox::hardDisks"/>,
    9171       <link to="IVirtualBox::DVDImages"/> and
    9172       <link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
    9173       quickly found using the <link to="IVirtualBox::findMedium"/> method.
    9174 
    9175       Only known media can be attached to virtual machines.
    9176 
    9177       Removing known media from the media registry is performed when the given
    9178       medium is closed using the <link to="#close"/> method or when its
    9179       associated storage unit is deleted.
    9180 
    9181       <h3>Accessibility checks</h3>
    9182 
    9183       VirtualBox defers media accessibility checks until the <link to="#refreshState" />
    9184       method is called explicitly on a medium. This is done to make the VirtualBox object
    9185       ready for serving requests as fast as possible and let the end-user
    9186       application decide if it needs to check media accessibility right away or not.
    9187 
    9188       As a result, when VirtualBox starts up (e.g. the VirtualBox
    9189       object gets created for the first time), all known media are in the
    9190       "Inaccessible" state, but the value of the <link to="#lastAccessError"/>
    9191       attribute is an empty string because no actual accessibility check has
    9192       been made yet.
    9193 
    9194       After calling <link to="#refreshState" />, a medium is considered
    9195       <i>accessible</i> if its storage unit can be read. In that case, the
    9196       <link to="#state"/> attribute has a value of "Created". If the storage
    9197       unit cannot be read (for example, because it is located on a disconnected
    9198       network resource, or was accidentally deleted outside VirtualBox),
    9199       the medium is considered <i>inaccessible</i>, which is indicated by the
    9200       "Inaccessible" state. The exact reason why the medium is inaccessible can be
    9201       obtained by reading the <link to="#lastAccessError"/> attribute.
    9202 
    9203       <h3>Medium types</h3>
    9204 
    9205       There are four types of medium behavior (see <link to="MediumType" />):
    9206       "normal", "immutable", "writethrough" and "shareable", represented by the
    9207       <link to="#type"/> attribute. The type of the medium defines how the
    9208       medium is attached to a virtual machine and what happens when a
    9209       <link to="ISnapshot">snapshot</link> of the virtual machine with the
    9210       attached medium is taken. At the moment DVD and floppy media are always
    9211       of type "writethrough".
    9212 
    9213       All media can be also divided in two groups: <i>base</i> media and
    9214       <i>differencing</i> media. A base medium contains all sectors of the
    9215       medium data in its own storage and therefore can be used independently.
    9216       In contrast, a differencing medium is a "delta" to some other medium and
    9217       contains only those sectors which differ from that other medium, which is
    9218       then called a <i>parent</i>. The differencing medium is said to be
    9219       <i>linked to</i> that parent. The parent may be itself a differencing
    9220       medium, thus forming a chain of linked media. The last element in that
    9221       chain must always be a base medium. Note that several differencing
    9222       media may be linked to the same parent medium.
    9223 
    9224       Differencing media can be distinguished from base media by querying the
    9225       <link to="#parent"/> attribute: base media do not have parents they would
    9226       depend on, so the value of this attribute is always @c null for them.
    9227       Using this attribute, it is possible to walk up the medium tree (from the
    9228       child medium to its parent). It is also possible to walk down the tree
    9229       using the <link to="#children"/> attribute.
    9230 
    9231       Note that the type of all differencing media is "normal"; all other
    9232       values are meaningless for them. Base media may be of any type.
    9233 
    9234       <h3>Creating hard disks</h3>
    9235 
    9236       New base hard disks are created using
    9237       <link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
    9238       opened using <link to="IVirtualBox::openMedium"/>. Differencing hard
    9239       disks are usually implicitly created by VirtualBox when needed but may
    9240       also be created explicitly using <link to="#createDiffStorage"/>.
    9241 
    9242       After the hard disk is successfully created (including the storage unit)
    9243       or opened, it becomes a known hard disk (remembered in the internal media
    9244       registry). Known hard disks can be attached to a virtual machine, accessed
    9245       through <link to="IVirtualBox::findMedium"/> or enumerated using the
    9246       <link to="IVirtualBox::hardDisks"/> array (only for base hard disks).
    9247 
    9248       The following methods, besides <link to="IMedium::close"/>,
    9249       automatically remove the hard disk from the media registry:
    9250       <ul>
    9251         <li><link to="#deleteStorage"/></li>
    9252         <li><link to="#mergeTo"/></li>
    9253       </ul>
    9254 
    9255       If the storage unit of the hard disk is a regular file in the host's
    9256       file system then the rules stated in the description of the
    9257       <link to="IMedium::location"/> attribute apply when setting its value.
    9258 
    9259       <h4>Automatic composition of the file name part</h4>
    9260 
    9261       Another extension to the <link to="IMedium::location"/> attribute is that
    9262       there is a possibility to cause VirtualBox to compose a unique value for
    9263       the file name part of the location using the UUID of the hard disk. This
    9264       applies only to hard disks in <link to="MediumState_NotCreated"/> state,
    9265       e.g. before the storage unit is created, and works as follows. You set the
    9266       value of the <link to="IMedium::location"/> attribute to a location
    9267       specification which only contains the path specification but not the file
    9268       name part and ends with either a forward slash or a backslash character.
    9269       In response, VirtualBox will generate a new UUID for the hard disk and
    9270       compose the file name using the following pattern:
    9271       <pre>
    9272         &lt;path&gt;/{&lt;uuid&gt;}.&lt;ext&gt;
    9273       </pre>
    9274       where <tt>&lt;path&gt;</tt> is the supplied path specification,
    9275       <tt>&lt;uuid&gt;</tt> is the newly generated UUID and <tt>&lt;ext&gt;</tt>
    9276       is the default extension for the storage format of this hard disk. After
    9277       that, you may call any of the methods that create a new hard disk storage
    9278       unit and they will use the generated UUID and file name.
    92799061
    92809062      <h3>Attaching Hard Disks</h3>
    … …  
    92829064      Hard disks are attached to virtual machines using the
    92839065      <link to="IMachine::attachDevice"/> method and detached using the
    9284       <link to="IMachine::detachDevice"/> method. Depending on their
    9285       <link to="#type"/>, hard disks are attached either
     9066      <link to="IMachine::detachDevice"/> method. Depending on a medium's
     9067      type (see <link to="IMedium::type" />), hard disks are attached either
    92869068      <i>directly</i> or <i>indirectly</i>.
    92879069
    … …  
    93069088            dependent children or being part of the snapshot makes it impossible
    93079089            to modify hard disk contents without breaking the integrity of the
    9308             dependent party. The <link to="#readOnly"/> attribute allows to
     9090            dependent party. The <link to="IMedium::readOnly"/> attribute allows to
    93099091            quickly determine the kind of the attachment for the given hard
    93109092            disk. Note that if a normal base hard disk is to be indirectly
    … …  
    93649146      (for example, as a result of virtual machine execution). If these hard
    93659147      disks are no more necessary, the caller can always delete them explicitly
    9366       using <link to="#deleteStorage"/> after they are actually de-associated
     9148      using <link to="IMedium::deleteStorage"/> after they are actually de-associated
    93679149      from this machine by the <link to="IMachine::saveSettings"/> call.
    93689150
    … …  
    94369218      without losing the contents of the differencing hard disk actually
    94379219      attached to the machine in place of it.
     9220
     9221    </desc>
     9222
     9223    <attribute name="medium" type="IMedium" readonly="yes">
     9224      <desc>Medium object associated with this attachment; it
     9225        can be @c null for removable devices.</desc>
     9226    </attribute>
     9227
     9228    <attribute name="controller" type="wstring" readonly="yes">
     9229      <desc>Name of the storage controller of this attachment; this
     9230        refers to one of the controllers in <link to="IMachine::storageControllers" />
     9231        by name.</desc>
     9232    </attribute>
     9233
     9234    <attribute name="port" type="long" readonly="yes">
     9235      <desc>Port number of this attachment.
     9236        See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
     9237      </desc>
     9238    </attribute>
     9239
     9240    <attribute name="device" type="long" readonly="yes">
     9241      <desc>Device slot number of this attachment.
     9242        See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
     9243      </desc>
     9244    </attribute>
     9245
     9246    <attribute name="type" type="DeviceType" readonly="yes">
     9247      <desc>Device type of this attachment.</desc>
     9248    </attribute>
     9249
     9250    <attribute name="passthrough" type="boolean" readonly="yes">
     9251      <desc>Pass I/O requests through to a device on the host.</desc>
     9252    </attribute>
     9253
     9254    <attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
     9255      <desc>The bandwidth group this medium attachment is assigned to.</desc>
     9256    </attribute>
     9257
     9258  </interface>
     9259
     9260  <interface
     9261    name="IMedium" extends="$unknown"
     9262    uuid="9edda847-1279-4b0a-9af7-9d66251ccc18"
     9263    wsmap="managed"
     9264    >
     9265    <desc>
     9266      The IMedium interface represents virtual storage for a machine's
     9267      hard disks, CD/DVD or floppy drives. It will typically represent
     9268      a disk image on the host, for example a VDI or VMDK file representing
     9269      a virtual hard disk, or an ISO or RAW file representing virtual
     9270      removable media, but can also point to a network location (e.g.
     9271      for iSCSI targets).
     9272
     9273      Instances of IMedium are connected to virtual machines by way of medium
     9274      attachments, which link the storage medium to a particular device slot
     9275      of a storage controller of the virtual machine.
     9276      In the VirtualBox API, virtual storage is therefore always represented
     9277      by the following chain of object links:
     9278
     9279      <ul>
     9280        <li><link to="IMachine::storageControllers"/> contains an array of
     9281          storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
     9282          these are instances of <link to="IStorageController"/>).</li>
     9283        <li><link to="IMachine::mediumAttachments"/> contains an array of
     9284          medium attachments (instances of <link to="IMediumAttachment"/>
     9285          created by <link to="IMachine::attachDevice" />),
     9286          each containing a storage controller from the above array, a
     9287          port/device specification, and an instance of IMedium representing
     9288          the medium storage (image file).
     9289
     9290          For removable media, the storage medium is optional; a medium
     9291          attachment with no medium represents a CD/DVD or floppy drive
     9292          with no medium inserted. By contrast, hard disk attachments
     9293          will always have an IMedium object attached.</li>
     9294        <li>Each IMedium in turn points to a storage unit (such as a file
     9295          on the host computer or a network resource) that holds actual
     9296          data. This location is represented by the <link to="#location"/>
     9297          attribute.</li>
     9298      </ul>
     9299
     9300      Existing media are opened using <link to="IVirtualBox::openMedium"/>;
     9301      new hard disk media can be created with the VirtualBox API using the
     9302      <link to="IVirtualBox::createHardDisk"/> method. Differencing hard
     9303      disks (see below) are usually implicitly created by VirtualBox as
     9304      needed, but may also be created explicitly using <link to="#createDiffStorage"/>.
     9305      VirtualBox cannot create CD/DVD or floppy images (ISO and RAW files); these
     9306      should be created with external tools and then opened from within VirtualBox.
     9307
     9308      Only for CD/DVDs and floppies, an IMedium instance can also represent a host
     9309      drive. In that case the <link to="#id" /> attribute contains the UUID of
     9310      one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
     9311
     9312      <h3>Media registries</h3>
     9313
     9314      When a medium has been opened or created using one of the aforementioned
     9315      APIs, it becomes "known" to VirtualBox. Known media can be attached
     9316      to virtual machines and accessed through <link to="IVirtualBox::findMedium"/>.
     9317      They also appear in the global
     9318      <link to="IVirtualBox::hardDisks" />,
     9319      <link to="IVirtualBox::DVDImages" /> and
     9320      <link to="IVirtualBox::floppyImages" /> arrays.
     9321
     9322      Prior to VirtualBox 4.0, opening a medium added it to a global media registry
     9323      in the VirtualBox.xml file, which was shared between all machines and made
     9324      transporting machines and their media from one host to another difficult.
     9325
     9326      Starting with VirtualBox 4.0, media are only added to a registry when they are
     9327      <i>attached</i> to a machine using <link to="IMachine::attachDevice" />. For
     9328      backwards compatibility, which registry a medium is added to depends on which
     9329      VirtualBox version created a machine:
     9330
     9331      <ul>
     9332        <li>If the medium has first been attached to a machine which was created by
     9333          VirtualBox 4.0 or later, it is added to that machine's media registry in
     9334          the machine XML settings file. This way all information about a machine's
     9335          media attachments is contained in a single file and can be transported
     9336          easily.</li>
     9337        <li>For older media attachments (i.e. if the medium was first attached to a
     9338          machine which was created with a VirtualBox version before 4.0), media
     9339          continue to be registered in the global VirtualBox settings file, for
     9340          backwards compatibility.</li>
     9341      </ul>
     9342
     9343      See <link to="IVirtualBox::openMedium" /> for more information.
     9344
     9345      Media are removed from media registries by the <link to="#close"/>,
     9346      <link to="#deleteStorage"/> and  <link to="#mergeTo"/> methods.
     9347
     9348      <h3>Accessibility checks</h3>
     9349
     9350      VirtualBox defers media accessibility checks until the <link to="#refreshState" />
     9351      method is called explicitly on a medium. This is done to make the VirtualBox object
     9352      ready for serving requests as fast as possible and let the end-user
     9353      application decide if it needs to check media accessibility right away or not.
     9354
     9355      As a result, when VirtualBox starts up (e.g. the VirtualBox
     9356      object gets created for the first time), all known media are in the
     9357      "Inaccessible" state, but the value of the <link to="#lastAccessError"/>
     9358      attribute is an empty string because no actual accessibility check has
     9359      been made yet.
     9360
     9361      After calling <link to="#refreshState" />, a medium is considered
     9362      <i>accessible</i> if its storage unit can be read. In that case, the
     9363      <link to="#state"/> attribute has a value of "Created". If the storage
     9364      unit cannot be read (for example, because it is located on a disconnected
     9365      network resource, or was accidentally deleted outside VirtualBox),
     9366      the medium is considered <i>inaccessible</i>, which is indicated by the
     9367      "Inaccessible" state. The exact reason why the medium is inaccessible can be
     9368      obtained by reading the <link to="#lastAccessError"/> attribute.
     9369
     9370      <h3>Medium types</h3>
     9371
     9372      There are five types of medium behavior which are stored in the
     9373      <link to="#type"/> attribute (see <link to="MediumType" />) and
     9374      which define the medium's behavior with attachments and snapshots.
     9375
     9376      All media can be also divided in two groups: <i>base</i> media and
     9377      <i>differencing</i> media. A base medium contains all sectors of the
     9378      medium data in its own storage and therefore can be used independently.
     9379      In contrast, a differencing medium is a "delta" to some other medium and
     9380      contains only those sectors which differ from that other medium, which is
     9381      then called a <i>parent</i>. The differencing medium is said to be
     9382      <i>linked to</i> that parent. The parent may be itself a differencing
     9383      medium, thus forming a chain of linked media. The last element in that
     9384      chain must always be a base medium. Note that several differencing
     9385      media may be linked to the same parent medium.
     9386
     9387      Differencing media can be distinguished from base media by querying the
     9388      <link to="#parent"/> attribute: base media do not have parents they would
     9389      depend on, so the value of this attribute is always @c null for them.
     9390      Using this attribute, it is possible to walk up the medium tree (from the
     9391      child medium to its parent). It is also possible to walk down the tree
     9392      using the <link to="#children"/> attribute.
     9393
     9394      Note that the type of all differencing media is "normal"; all other
     9395      values are meaningless for them. Base media may be of any type.
     9396
     9397      <h3>Automatic composition of the file name part</h3>
     9398
     9399      Another extension to the <link to="IMedium::location"/> attribute is that
     9400      there is a possibility to cause VirtualBox to compose a unique value for
     9401      the file name part of the location using the UUID of the hard disk. This
     9402      applies only to hard disks in <link to="MediumState_NotCreated"/> state,
     9403      e.g. before the storage unit is created, and works as follows. You set the
     9404      value of the <link to="IMedium::location"/> attribute to a location
     9405      specification which only contains the path specification but not the file
     9406      name part and ends with either a forward slash or a backslash character.
     9407      In response, VirtualBox will generate a new UUID for the hard disk and
     9408      compose the file name using the following pattern:
     9409      <pre>
     9410        &lt;path&gt;/{&lt;uuid&gt;}.&lt;ext&gt;
     9411      </pre>
     9412      where <tt>&lt;path&gt;</tt> is the supplied path specification,
     9413      <tt>&lt;uuid&gt;</tt> is the newly generated UUID and <tt>&lt;ext&gt;</tt>
     9414      is the default extension for the storage format of this hard disk. After
     9415      that, you may call any of the methods that create a new hard disk storage
     9416      unit and they will use the generated UUID and file name.
    94389417    </desc>
    94399418
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette