VirtualBox

Changeset 23946 in vbox for trunk


Ignore:
Timestamp:
Oct 21, 2009 4:59:20 PM (16 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
53764
Message:

API: medium terminology cleanup, no actual interface change

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r23936 r23946  
    686686      <desc>
    687687        A machine snapshot is being deleted; this can take a long time since this
    688         may require merging differencing hard disk images.
     688        may require merging differencing media.
    689689      </desc>
    690690    </const>
    … …  
    19431943          The specified machine must not be in the Saved state, have an open
    19441944          (or a spawning) direct session associated with it, have snapshots or
    1945           have hard disks attached.
     1945          have any medium attached.
    19461946        </note>
    19471947
    … …  
    19661966        </result>
    19671967        <result name="VBOX_E_INVALID_OBJECT_STATE">
    1968           Machine has snapshot or open session or hard disk attached.
     1968          Machine has snapshot or open session or medium attached.
    19691969        </result>
    19701970
    … …  
    38293829          <ul>
    38303830            <li>setting up (weight 1);</li>
    3831             <li>one for each hard disk attachment that needs a differencing image (weight 1 each);</li>
     3831            <li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
    38323832            <li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
    38333833            <li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
    … …  
    46474647        be @c 0.
    46484648
    4649         For fixed media such as hard disks, the given medium cannot be NULL. It may
    4650         be NULL for removable media such as DVDs and floppies.
     4649        For fixed media such as hard disks, the given medium identifier cannot
     4650        be a zero UUID. It may be a zero UUID for removable media such as DVDs
     4651        and floppies.
    46514652
    46524653        After calling this returns successfully, a new instance of
    … …  
    46544655        attachments (<link to="IMachine::mediumAttachments"/>).
    46554656
    4656         The specified device slot must not have another disk attached to it, or
    4657         this method will fail.
     4657        The specified device slot must not have a device attached to it,
     4658        or this method will fail.
    46584659
    46594660        See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
    … …  
    46614662
    46624663        <note>
    4663           You cannot attach a hard disk to a running machine. Also, you cannot
    4664           attach a hard disk to a newly created machine until this machine's
     4664          You cannot attach a device to a running machine. Also, you cannot
     4665          attach a device to a newly created machine until this machine's
    46654666          settings are saved to disk using <link to="#saveSettings"/>.
    46664667        </note>
    … …  
    47014702      </param>
    47024703      <param name="id" type="uuid" mod="string" dir="in">
    4703         <desc>UUID of the medium to mount. NULL UUID means do not mount any
     4704        <desc>UUID of the medium to mount. Zero UUID means do not mount any
    47044705        medium.</desc>
    47054706      </param>
    … …  
    47174718
    47184719        <note>
    4719           You cannot detach the hard disk from a running machine.
     4720          You cannot detach a device from a running machine.
    47204721        </note>
    47214722        <note>
    … …  
    47364737        </result>
    47374738        <result name="VBOX_E_NOT_SUPPORTED">
    4738           Hard disk format does not support storage deletion.
     4739          Medium format does not support storage deletion.
    47394740        </result>
    47404741
    … …  
    62436244        Starts the virtual machine execution using the current machine
    62446245        state (that is, its current execution state, current settings and
    6245         current hard disks).
     6246        current storage devices).
    62466247
    62476248        If the machine is powered off or aborted, the execution will
    … …  
    64556456          It's a caller's responsibility to make sure the given saved state
    64566457          file is compatible with the settings of this virtual machine that
    6457           represent its virtual hardware (memory size, hard disk configuration
     6458          represent its virtual hardware (memory size, storage disk configuration
    64586459          etc.). If there is a mismatch, the behavior of the virtual machine
    64596460          is undefined.
    … …  
    66766677        See <link to="ISnapshot" /> for an introduction to snapshots.
    66776678
    6678         The execution state
    6679         and settings of the associated machine stored in the snapshot
    6680         will be deleted. The contents of all differencing media of
    6681         this snapshot will be merged with the contents of their
    6682         dependent child media to keep the disks valid (in other
    6683         words, all changes represented by media being discarded
    6684         will be propagated to their child medium). After that, this
    6685         snapshot's differencing medium will be deleted. The parent
    6686         of this snapshot will become a new parent for all its child
    6687         snapshots.
     6679        The execution state and settings of the associated machine stored in
     6680        the snapshot will be deleted. The contents of all differencing media of
     6681        this snapshot will be merged with the contents of their dependent child
     6682        media to keep the medium chain valid (in other words, all changes
     6683        represented by media being discarded will be propagated to their child
     6684        medium). After that, this snapshot's differencing medium will be
     6685        deleted. The parent of this snapshot will become a new parent for all
     6686        its child snapshots.
    66886687
    66896688        If the discarded snapshot is the current one, its parent
    … …  
    67166715        to other machines. Such snapshots can be only discarded after
    67176716        you discard all snapshots of other machines containing "foreign"
    6718         child disks, or detach these "foreign" child disks from machines
     6717        child media, or detach these "foreign" child media from machines
    67196718        they are attached to.
    67206719
    … …  
    67456744        <note>
    67466745          Merging medium contents can be very time and disk space
    6747           consuming, if these disks are big in size and have many
     6746          consuming, if these media are big in size and have many
    67486747          children. However, if the snapshot being discarded is the last
    67496748          (head) snapshot on the branch, the operation will be rather
    … …  
    81728171
    81738172              Neither the current machine state nor other snapshots are affected
    8174               by this operation, except that parent disk images will be modified
     8173              by this operation, except that parent media will be modified
    81758174              to contain the disk data associated with the snapshot being deleted.
    81768175          </li>
    … …  
    84128411      and device number. Fixed media (hard disks) will always also specify
    84138412      an instance of IMedium in <link to="#medium" />, referring to the hard disk
    8414       image or images that represent the virtual hard disk. For removeable media,
    8415       the IMedia instance is optional; it can be NULL if no media is mounted (see
    8416       <link to="IMachine::mountMedium" />).
     8413      medium. For removeable media, the IMedia instance is optional; it can be
     8414      @c null if no media is mounted (see <link to="IMachine::mountMedium" />).
    84178415    </desc>
    84188416
    84198417    <attribute name="medium" type="IMedium" readonly="yes">
    84208418      <desc>Medium object associated with this attachment; it
    8421         can be NULL for removable devices.</desc>
     8419        can be @c null for removable devices.</desc>
    84228420    </attribute>
    84238421
    … …  
    85548552      check media accessibility right away or not.
    85558553
    8556       <h3>Hard disk types</h3>
    8557 
    8558       There are three types of hard disk images (see <link to="MediumType" />):
     8554      <h3>Medium types</h3>
     8555
     8556      There are three types of medium behavior (see <link to="MediumType" />):
    85598557      "normal", "immutable" and "writethrough", represented by the
    8560       <link to="#type"/> attribute. The type of the hard disk defines how the
    8561       hard disk is attached to a virtual machine and what happens when a
     8558      <link to="#type"/> attribute. The type of the medium defines how the
     8559      medium is attached to a virtual machine and what happens when a
    85628560      <link to="ISnapshot">snapshot</link> of the virtual machine with the
    8563       attached hard disk is taken.
    8564 
    8565       All hard disks can be also divided in two groups: <i>base</i> hard
    8566       disks and <i>differencing</i> hard disks. A base hard disk contains all
    8567       sectors of the hard disk data in its own storage and therefore can be
    8568       used independently. On the contrary, a differencing hard disk is a
    8569       "delta" to some other disk and contains only those sectors which differ
    8570       from that other disk, which is then called a <i>parent</i>. The differencing
    8571       hard disk is said to be <i>linked to</i> that parent.
    8572       The parent may be itself a differencing image, thus forming a chain of
    8573       linked hard disks. The last element in that chain
    8574       must always be a base medium. Note that several differencing
    8575       hard disks may be linked to the same parent hard disk.
    8576 
    8577       Differencing hard disks can be distinguished from base hard disks by
    8578       querying the <link to="#parent"/> attribute: base hard disks do not have
    8579       parents they would depend on, so the value of this attribute is always
    8580       @c null for them. Using this attribute, it is possible to walk up
    8581       the hard disk tree (from the child hard disk to its parent). It is also
    8582       possible to walk down the tree using the <link to="#children"/>
    8583       attribute.
    8584 
    8585       Note that the type of all differencing hard disks is
    8586       <link to="MediumType_Normal" />; all other values are
    8587       meaningless for them. Base hard disks may be of any type.
     8561      attached medium is taken. At the moment DVD and floppy media are always
     8562      of type "writethrough".
     8563
     8564      All media can be also divided in two groups: <i>base</i> media and
     8565      <i>differencing</i> media. A base medium contains all sectors of the
     8566      medium data in its own storage and therefore can be used independently.
     8567      In contrast, a differencing mediun is a "delta" to some other medium and
     8568      contains only those sectors which differ from that other medium, which is
     8569      then called a <i>parent</i>. The differencing medium is said to be
     8570      <i>linked to</i> that parent. The parent may be itself a differencing
     8571      medium, thus forming a chain of linked media. The last element in that
     8572      chain must always be a base medium. Note that several differencing
     8573      media may be linked to the same parent medium.
     8574
     8575      Differencing media can be distinguished from base media by querying the
     8576      <link to="#parent"/> attribute: base media do not have parents they would
     8577      depend on, so the value of this attribute is always @c null for them.
     8578      Using this attribute, it is possible to walk up the medium tree (from the
     8579      child medium to its parent). It is also possible to walk down the tree
     8580      using the <link to="#children"/> attribute.
     8581
     8582      Note that the type of all differencing media is
     8583      <link to="MediumType_Normal" />; all other values are meaningless for
     8584      them. Base media may be of any type.
    85888585
    85898586      <h3>Creating hard disks</h3>
    … …  
    89168913        Storage format of this medium.
    89178914
    8918         The value of this attribute is a string that specifies a backend used to
    8919         store hard disk data. The storage format is defined when you create a
    8920         new hard disk or automatically detected when you open an existing hard
    8921         disk medium, and cannot be changed later.
     8915        The value of this attribute is a string that specifies a backend used
     8916        to store medium data. The storage format is defined when you create a
     8917        new medium or automatically detected when you open an existing medium,
     8918        and cannot be changed later.
    89228919
    89238920        The list of all storage formats supported by this VirtualBox
    … …  
    89298926    <attribute name="type" type="MediumType">
    89308927      <desc>
    8931         Type (role) of this hard disk.
     8928        Type (role) of this medium.
    89328929
    89338930        The following constraints apply when changing the value of this
    89348931        attribute:
    89358932        <ul>
    8936           <li>If a hard disk is attached to a virtual machine (either in the
     8933          <li>If a medium is attached to a virtual machine (either in the
    89378934              current state or in one of the snapshots), its type cannot be
    89388935              changed.
    89398936          </li>
    8940           <li>As long as the hard disk has children, its type cannot be set
     8937          <li>As long as the medium has children, its type cannot be set
    89418938              to <link to="MediumType_Writethrough"/>.
    89428939          </li>
    8943           <li>The type of all differencing hard disks is
     8940          <li>The type of all differencing media is
    89448941              <link to="MediumType_Normal"/> and cannot be changed.
    89458942          </li>
    89468943        </ul>
    89478944
    8948         The type of a newly created or opened hard disk is set to
    8949         <link to="MediumType_Normal"/>.
     8945        The type of a newly created or opened medium is set to
     8946        <link to="MediumType_Normal"/>, except for DVD and floppy media,
     8947        which have a type of <link to="MediumType_Writethrough"/>.
    89508948      </desc>
    89518949    </attribute>
    … …  
    89538951    <attribute name="parent" type="IMedium" readonly="yes">
    89548952      <desc>
    8955         Parent of this hard disk (a hard disk this hard disk is directly based
     8953        Parent of this medium (the medium this medium is directly based
    89568954        on).
    89578955
    8958         Only differencing hard disks have parents. For base (non-differencing)
    8959         hard disks, @c null is returned.
     8956        Only differencing media have parents. For base (non-differencing)
     8957        media, @c null is returned.
    89608958      </desc>
    89618959    </attribute>
    … …  
    89638961    <attribute name="children" type="IMedium" safearray="yes" readonly="yes">
    89648962      <desc>
    8965         Children of this hard disk (all differencing hard disks directly based
    8966         on this hard disk). A @c null array is returned if this hard disk
     8963        Children of this medium (all differencing media directly based
     8964        on this medium). A @c null array is returned if this medium
    89678965        does not have any children.
    89688966      </desc>
    … …  
    89738971        Base medium of this medium.
    89748972
    8975         If this is a differencing medium, its base hard disk is the medium
    8976         the given hard disk branch starts from. For all other types of hard
    8977         disks, this property returns the hard disk object itself (i.e. the same
    8978         object this property is read on).
     8973        If this is a differencing medium, its base medium is the medium
     8974        the given medium branch starts from. For all other types of media, this
     8975        property returns the medium object itself (i.e. the same object this
     8976        property is read on).
    89798977      </desc>
    89808978    </attribute>
    … …  
    89828980    <attribute name="readOnly" type="boolean" readonly="yes">
    89838981      <desc>
    8984         Returns @c true if this hard disk is read-only and @c false otherwise.
    8985 
    8986         A hard disk is considered to be read-only when its contents cannot be
     8982        Returns @c true if this medium is read-only and @c false otherwise.
     8983
     8984        A medium is considered to be read-only when its contents cannot be
    89878985        modified without breaking the integrity of other parties that depend on
    8988         this hard disk such as its child hard disks or snapshots of virtual
    8989         machines where this hard disk is attached to these machines. If there
    8990         are no children and no such snapshots then there is no dependency and
    8991         the hard disk is not read-only.
     8986        this medium such as its child media or snapshots of virtual machines
     8987        where this medium is attached to these machines. If there are no
     8988        children and no such snapshots then there is no dependency and the
     8989        medium is not read-only.
    89928990
    89938991        The value of this attribute can be used to determine the kind of the
    8994         attachment that will take place when attaching this hard disk to a
    8995         virtual machine. If the value is @c false then the hard disk will
    8996         be attached directly. If the value is @c true then the hard disk
    8997         will be attached indirectly by creating a new differencing child hard
    8998         disk for that. See the interface description for more information.
    8999 
    9000         Note that all <link to="MediumType_Immutable">Immutable</link> hard
    9001         disks are always read-only while all
    9002         <link to="MediumType_Writethrough">Writethrough</link> hard disks are
     8992        attachment that will take place when attaching this medium to a
     8993        virtual machine. If the value is @c false then the medium will
     8994        be attached directly. If the value is @c true then the medium
     8995        will be attached indirectly by creating a new differencing child
     8996        medium for that. See the interface description for more information.
     8997
     8998        Note that all <link to="MediumType_Immutable">Immutable</link> media
     8999        are always read-only while all
     9000        <link to="MediumType_Writethrough">Writethrough</link> media are
    90039001        always not.
    90049002
    90059003        <note>
    90069004          The read-only condition represented by this attribute is related to
    9007           the hard disk type and usage, not to the current
     9005          the medium type and usage, not to the current
    90089006          <link to="IMedium::state">medium state</link> and not to the read-only
    90099007          state of the storage unit.
    … …  
    90149012    <attribute name="logicalSize" type="unsigned long long" readonly="yes">
    90159013      <desc>
    9016         Logical size of this hard disk (in megabytes), as reported to the
    9017         guest OS running inside the virtual machine this disk is
    9018         attached to. The logical size is defined when the hard disk is created
     9014        Logical size of this medium (in megabytes), as reported to the
     9015        guest OS running inside the virtual machine this medium is
     9016        attached to. The logical size is defined when the medium is created
    90199017        and cannot be changed later.
    90209018
    90219019        <note>
    9022           Reading this property on a differencing hard disk will return the size
     9020          Reading this property on a differencing medium will return the size
    90239021          of its <link to="#base"/> medium.
    90249022        </note>
    90259023        <note>
    9026           For hard disks whose state is <link to="#state"/> is <link
     9024          For media whose state is <link to="#state"/> is <link
    90279025          to="MediumState_Inaccessible"/>, the value of this property is the
    9028           last known logical size. For <link to="MediumaState_NotCreated"/> hard
    9029           disks, the returned value is zero.
     9026          last known logical size. For <link to="MediumaState_NotCreated"/>
     9027          media, the returned value is zero.
    90309028        </note>
    90319029      </desc>
    … …  
    90349032    <attribute name="autoReset" type="boolean">
    90359033      <desc>
    9036         Whether this differencing hard disk will be automatically reset each
     9034        Whether this differencing medium will be automatically reset each
    90379035        time a virtual machine it is attached to is powered up.
    90389036
    90399037        See <link to="#reset()"/> for more information about resetting
    9040         differencing hard disks.
     9038        differencing media.
    90419039
    90429040        <note>
    9043           Reading this property on a base (non-differencing) hard disk will
     9041          Reading this property on a base (non-differencing) medium will
    90449042          always @c false. Changing the value of this property in this
    90459043          case is not supported.
    … …  
    90479045
    90489046        <result name="VBOX_E_NOT_SUPPORTED">
    9049           This is not a differencing hard disk (when changing the attribute
     9047          This is not a differencing medium (when changing the attribute
    90509048          value).
    90519049        </result>
    … …  
    92929290    <method name="getProperty">
    92939291      <desc>
    9294         Returns the value of the custom hard disk property with the given name.
    9295 
    9296         The list of all properties supported by the given hard disk format can
     9292        Returns the value of the custom medium property with the given name.
     9293
     9294        The list of all properties supported by the given medium format can
    92979295        be obtained with <link to="IMediumFormat::describeProperties"/>.
    92989296
    … …  
    93159313    <method name="setProperty">
    93169314      <desc>
    9317         Sets the value of the custom hard disk property with the given name.
    9318 
    9319         The list of all properties supported by the given hard disk format can
     9315        Sets the value of the custom medium property with the given name.
     9316
     9317        The list of all properties supported by the given medium format can
    93209318        be obtained with <link to="IMediumFormat::describeProperties"/>.
    93219319
    … …  
    93489346        existing properties.
    93499347
    9350         The list of all properties supported by the given hard disk format can
     9348        The list of all properties supported by the given medium format can
    93519349        be obtained with <link to="IMediumFormat::describeProperties"/>.
    93529350
    … …  
    93939391        IPC calls.
    93949392
    9395         The list of all properties supported by the given hard disk format can
     9393        The list of all properties supported by the given medium format can
    93969394        be obtained with <link to="IMediumFormat::describeProperties"/>.
    93979395
    … …  
    94189416        <link to="#deleteStorage"/>, otherwise the operation will fail.
    94199417
    9420         Before the operation starts, the hard disk is placed in
     9418        Before the operation starts, the medium is placed in
    94219419        <link to="MediumState_Creating"/> state. If the create operation
    94229420        fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
    … …  
    94259423        After the returned progress object reports that the operation has
    94269424        successfully completed, the medium state will be set to <link
    9427         to="MediumState_Created"/>, the hard disk will be remembered by this
     9425        to="MediumState_Created"/>, the medium will be remembered by this
    94289426        VirtualBox installation and may be attached to virtual machines.
    94299427
    … …  
    94349432      </desc>
    94359433      <param name="logicalSize" type="unsigned long long" dir="in">
    9436         <desc>Maximum logical size of the hard disk in megabytes.</desc>
     9434        <desc>Maximum logical size of the medium in megabytes.</desc>
    94379435      </param>
    94389436      <param name="variant" type="MediumVariant" dir="in">
    … …  
    94469444    <method name="deleteStorage">
    94479445      <desc>
    9448         Starts deleting the storage unit of this hard disk.
    9449 
    9450         The hard disk must not be attached to any known virtual machine and must
    9451         not have any known child hard disks, otherwise the operation will fail.
     9446        Starts deleting the storage unit of this medium.
     9447
     9448        The medium must not be attached to any known virtual machine and must
     9449        not have any known child media, otherwise the operation will fail.
    94529450        It will also fail if there is no storage unit to delete or if deletion
    9453         is already in progress, or if the hard disk is being in use (locked for
     9451        is already in progress, or if the medium is being in use (locked for
    94549452        read or for write) or inaccessible. Therefore, the only valid state for
    94559453        this operation to succeed is <link to="MediumState_Created"/>.
    94569454
    9457         Before the operation starts, the hard disk is placed to
     9455        Before the operation starts, the medium is placed in
    94589456        <link to="MediumState_Deleting"/> state and gets removed from the list
    94599457        of remembered hard disks (media registry). If the delete operation
    … …  
    94699467
    94709468        <result name="VBOX_E_OBJECT_IN_USE">
    9471           Hard disk is attached to a virtual machine.
     9469          Medium is attached to a virtual machine.
    94729470        </result>
    94739471        <result name="VBOX_E_NOT_SUPPORTED">
    … …  
    94929490    <method name="createDiffStorage">
    94939491      <desc>
    9494         Starts creating an empty differencing storage unit based on this hard
    9495         disk in the format and at the location defined by the @a target
     9492        Starts creating an empty differencing storage unit based on this
     9493        medium in the format and at the location defined by the @a target
    94969494        argument.
    94979495
    9498         The target hard disk must be in <link to="MediumState_NotCreated"/>
     9496        The target medium must be in <link to="MediumState_NotCreated"/>
    94999497        state (i.e. must not have an existing storage unit). Upon successful
    9500         completion, this operation will set the type of the target hard disk to
     9498        completion, this operation will set the type of the target medium to
    95019499        <link to="MediumType_Normal"/> and create a storage unit necessary to
    9502         represent the differencing hard disk data in the given format (according
     9500        represent the differencing medium data in the given format (according
    95039501        to the storage format of the target object).
    95049502
    95059503        After the returned progress object reports that the operation is
    9506         successfully complete, the target hard disk gets remembered by this
     9504        successfully complete, the target medium gets remembered by this
    95079505        VirtualBox installation and may be attached to virtual machines.
    95089506
    95099507        <note>
    9510           The hard disk will be set to <link to="MediumState_LockedRead"/>
     9508          The medium will be set to <link to="MediumState_LockedRead"/>
    95119509          state for the duration of this operation.
    95129510        </note>
    95139511        <result name="VBOX_E_OBJECT_IN_USE">
    9514           Hard disk not in @c NotCreated state.
     9512          Medium not in @c NotCreated state.
    95159513        </result>
    95169514      </desc>
    95179515      <param name="target" type="IMedium" dir="in">
    9518         <desc>Target hard disk.</desc>
     9516        <desc>Target medium.</desc>
    95199517      </param>
    95209518      <param name="variant" type="MediumVariant" dir="in">
    … …  
    95289526    <method name="mergeTo">
    95299527      <desc>
    9530         Starts merging the contents of this hard disk and all intermediate
    9531         differencing hard disks in the chain to the given target hard disk.
    9532 
    9533         The target hard disk must be either a descendant of this hard disk or
     9528        Starts merging the contents of this medium and all intermediate
     9529        differencing media in the chain to the given target medium.
     9530
     9531        The target medium must be either a descendant of this medium or
    95349532        its ancestor (otherwise this method will immediately return a failure).
    95359533        It follows that there are two logical directions of the merge operation:
    95369534        from ancestor to descendant (<i>forward merge</i>) and from descendant to
    9537         ancestor (<i>backward merge</i>). Let us consider the following hard disk
     9535        ancestor (<i>backward merge</i>). Let us consider the following medium
    95389536        chain:
    95399537
    95409538        <pre>Base &lt;- Diff_1 &lt;- Diff_2</pre>
    95419539
    9542         Here, calling this method on the <tt>Base</tt> hard disk object with
     9540        Here, calling this method on the <tt>Base</tt> medium object with
    95439541        <tt>Diff_2</tt> as an argument will be a forward merge; calling it on
    95449542        <tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
    9545         merge. Note that in both cases the contents of the resulting hard disk
    9546         will be the same, the only difference is the hard disk object that takes
     9543        merge. Note that in both cases the contents of the resulting medium
     9544        will be the same, the only difference is the medium object that takes
    95479545        the result of the merge operation. In case of the forward merge in the
    95489546        above example, the result will be written to <tt>Diff_2</tt>; in case of
    95499547        the backward merge, the result will be written to <tt>Base</tt>. In
    95509548        other words, the result of the operation is always stored in the target
    9551         hard disk.
    9552 
    9553         Upon successful operation completion, the storage units of all hard
    9554         disks in the chain between this (source) hard disk and the target hard
    9555         disk, including the source hard disk itself, will be automatically
    9556         deleted and the relevant hard disk objects (including this hard disk)
    9557         will become uninitialized. This means that any attempt to call any of
     9549        medium.
     9550
     9551        Upon successful operation completion, the storage units of all media in
     9552        the chain between this (source) medium and the target medium, including
     9553        the source medium itself, will be automatically deleted and the
     9554        relevant medium objects (including this medium) will become
     9555        uninitialized. This means that any attempt to call any of
    95589556        their methods or attributes will fail with the
    95599557        <tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
    95609558        example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
    9561         delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> hard
    9562         disks. Note that <tt>Diff_2</tt> in this case will become a base hard
    9563         disk itself since it will no longer be based on any other hard disk.
     9559        delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
     9560        Note that <tt>Diff_2</tt> in this case will become a base medium
     9561        itself since it will no longer be based on any other medium.
    95649562
    95659563        Considering the above, all of the following conditions must be met in
    … …  
    95679565        <ul>
    95689566          <li>
    9569             Neither this (source) hard disk nor any intermediate
    9570             differencing hard disk in the chain between it and the target
    9571             hard disk is attached to any virtual machine.
     9567            Neither this (source) medium nor any intermediate
     9568            differencing medium in the chain between it and the target
     9569            medium is attached to any virtual machine.
    95729570          </li>
    95739571          <li>
    9574             Neither the source hard disk nor the target hard disk is an
    9575             <link to="MediumType_Immutable"/> hard disk.
     9572            Neither the source medium nor the target medium is an
     9573            <link to="MediumType_Immutable"/> medium.
    95769574          </li>
    95779575          <li>
    9578             The part of the hard disk tree from the source hard disk to the
    9579             target hard disk is a linear chain, i.e. all hard disks in this
    9580             chain have exactly one child which is the next hard disk in this
    9581             chain. The only exception from this rule is the target hard disk in
     9576            The part of the medium tree from the source medium to the
     9577            target medium is a linear chain, i.e. all medium in this
     9578            chain have exactly one child which is the next medium in this
     9579            chain. The only exception from this rule is the target medium in
    95829580            the forward merge operation; it is allowed to have any number of
    9583             child hard disks because the merge operation will hot change its
     9581            child media because the merge operation will not change its
    95849582            logical contents (as it is seen by the guest OS or by children).
    95859583          </li>
    95869584          <li>
    9587             None of the involved hard disks are in
     9585            None of the involved media are in
    95889586            <link to="MediumState_LockedRead"/> or
    95899587            <link to="MediumState_LockedWrite"/> state.
    … …  
    95929590
    95939591        <note>
    9594           This (source) hard disk and all intermediates will be placed to <link
    9595           to="MediumState_Deleting"/> state and the target hard disk will be
     9592          This (source) medium and all intermediates will be placed to <link
     9593          to="MediumState_Deleting"/> state and the target medium will be
    95969594          placed to <link to="MediumState_LockedWrite"/> state and for the
    95979595          duration of this operation.
    … …  
    95999597      </desc>
    96009598      <param name="targetId" type="uuid" mod="string" dir="in">
    9601         <desc>UUID of the target ancestor or descendant hard disk.</desc>
     9599        <desc>UUID of the target ancestor or descendant medium.</desc>
    96029600      </param>
    96039601      <param name="progress" type="IProgress" dir="return">
    … …  
    96109608    <method name="cloneTo">
    96119609      <desc>
    9612         Starts creating a clone of this hard disk in the format and at the
     9610        Starts creating a clone of this medium in the format and at the
    96139611        location defined by the @a target argument.
    96149612
    9615         The target hard disk must be either in <link to="MediumState_NotCreated"/>
     9613        The target medium must be either in <link to="MediumState_NotCreated"/>
    96169614        state (i.e. must not have an existing storage unit) or in
    96179615        <link to="MediumState_Created"/> state (i.e. created and not locked, and
    96189616        big enough to hold the data or else the copy will be partial). Upon
    9619         successful completion, the cloned hard disk will contain exactly the
    9620         same sector data as the hard disk being cloned, except that in the
     9617        successful completion, the cloned medium will contain exactly the
     9618        same sector data as the medium being cloned, except that in the
    96219619        first case a new UUID for the clone will be randomly generated, and in
    96229620        the second case the UUID will remain unchanged.
    96239621
    9624         The @a parent argument defines which hard disk will be the parent
     9622        The @a parent argument defines which medium will be the parent
    96259623        of the clone. Passing a @c null reference indicates that the clone will
    96269624        be a base image, i.e. completely independent. It is possible to specify
    9627         an arbitrary hard disk for this parameter, including the parent of the
    9628         hard disk which is being cloned. Even cloning to a child of the source
    9629         hard disk is possible. Note that when cloning to an existing image, the
     9625        an arbitrary medium for this parameter, including the parent of the
     9626        medium which is being cloned. Even cloning to a child of the source
     9627        medium is possible. Note that when cloning to an existing image, the
    96309628        @a parent irgument is ignored.
    96319629
    96329630        After the returned progress object reports that the operation is
    9633         successfully complete, the target hard disk gets remembered by this
     9631        successfully complete, the target medium gets remembered by this
    96349632        VirtualBox installation and may be attached to virtual machines.
    96359633
    96369634        <note>
    9637           This hard disk will be placed to <link to="MediumState_LockedRead"/>
     9635          This medium will be placed to <link to="MediumState_LockedRead"/>
    96389636          state for the duration of this operation.
    96399637        </note>
    … …  
    96439641      </desc>
    96449642      <param name="target" type="IMedium" dir="in">
    9645         <desc>Target hard disk.</desc>
     9643        <desc>Target medium.</desc>
    96469644      </param>
    96479645      <param name="variant" type="MediumVariant" dir="in">
    … …  
    96499647      </param>
    96509648      <param name="parent" type="IMedium" dir="in">
    9651         <desc>Parent of the cloned hard disk.</desc>
     9649        <desc>Parent of the cloned medium.</desc>
    96529650      </param>
    96539651      <param name="progress" type="IProgress" dir="return">
    … …  
    96609658    <method name="compact">
    96619659      <desc>
    9662         Starts compacting of this hard disk. This means that the disk is
     9660        Starts compacting of this medium. This means that the medium is
    96639661        transformed into a possibly more compact storage representation.
    96649662        This potentially creates temporary images, which can require a
    96659663        substantial amount of additional disk space.
    96669664
    9667         This hard disk will be placed to <link to="MediumState_LockedWrite"/>
    9668         state and all its parent hard disks (if any) will be placed to
     9665        This medium will be placed to <link to="MediumState_LockedWrite"/>
     9666        state and all its parent media (if any) will be placed to
    96699667        <link to="MediumState_LockedRead"/> state for the duration of this
    96709668        operation.
    … …  
    96759673
    96769674        <result name="VBOX_E_NOT_SUPPORTED">
    9677           Hard disk format does not support compacting (but potentially
     9675          Medium format does not support compacting (but potentially
    96789676          needs it).
    96799677        </result>
    … …  
    96869684    <method name="reset">
    96879685      <desc>
    9688         Starts erasing the contents of this differencing hard disk.
    9689 
    9690         This operation will reset the differencing hard disk to its initial
     9686        Starts erasing the contents of this differencing medium.
     9687
     9688        This operation will reset the differencing medium to its initial
    96919689        state when it does not contain any sector data and any read operation is
    9692         redirected to its parent hard disk.
    9693 
    9694         This hard disk will be placed to <link to="MediumState_LockedWrite"/>
     9690        redirected to its parent medium.
     9691
     9692        This medium will be placed to <link to="MediumState_LockedWrite"/>
    96959693        for the duration of this operation.
    96969694
    96979695        <result name="VBOX_E_NOT_SUPPORTED">
    9698           This is not a differencing hard disk.
     9696          This is not a differencing medium.
    96999697        </result>
    97009698        <result name="VBOX_E_INVALID_OBJECT_STATE">
    9701           Hard disk is not in <link to="MediumState_Created"/> or
     9699          Medium is not in <link to="MediumState_Created"/> or
    97029700          <link to="MediumState_Inaccessible"/> state.
    97039701        </result>
    … …  
    97419739  >
    97429740    <desc>
    9743        Hard disk format capability flags.
     9741       Medium format capability flags.
    97449742    </desc>
    97459743
    … …  
    1261612614    <desc>
    1261712615        Represents a storage controller that is attached to a virtual machine
    12618         (<link to="IMachine" />). Just as disks (hard disks, DVDs, FDs) are
    12619         attached to storage controllers in a real computer, virtual media
    12620         (represented by <link to="IMedium" />) are attached to virtual
     12616        (<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
     12617        attached to storage controllers in a real computer, virtual drives
     12618        (represented by <link to="IMediumAttachment" />) are attached to virtual
    1262112619        storage controllers, represented by this interface.
    1262212620
Note: See TracChangeset for help on using the changeset viewer.

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