VirtualBox

Changeset 15290 in vbox for trunk/src/VBox/Main/idl


Ignore:
Timestamp:
Dec 11, 2008 8:08:13 AM (16 years ago)
Author:
vboxsync
Message:

backed out r40701 and r40702 (core dumps)

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r15283 r15290  
    371371  >
    372372    <desc>
    373       Virtual machine execution state.
    374 
    375       This enumeration represents possible values of the <link
    376       to="IMachine::state"/> attribute.
    377 
    378       Below is the basic virtual machine state diagram. It shows how the state
    379       changes during virtual machine execution. The text in square braces shows
    380       a method of the IConsole interface that performs the given state
    381       transition.
    382 
    383       <pre>
    384             +---------[powerDown()] &lt;- Stuck &lt;--[failure]-+
    385             V                                             |
    386     +-&gt; PoweredOff --+--&gt;[powerUp()]--&gt; Starting --+      | +-----[resume()]-----+
    387     |                |                             |      | V                    |
    388     |   Aborted -----+                             +--&gt; Running --[pause()]--&gt; Paused
    389     |                                              |      ^ |                   ^ |
    390     |   Saved -----------[powerUp()]--&gt; Restoring -+      | |                   | |
    391     |     ^                                               | |                   | |
    392     |     |     +-----------------------------------------+-|-------------------+ +
    393     |     |     |                                           |                     |
    394     |     |     +-- Saving &lt;--------[takeSnapshot()]&lt;-------+---------------------+
    395     |     |                                                 |                     |
    396     |     +-------- Saving &lt;--------[saveState()]&lt;----------+---------------------+
    397     |                                                       |                     |
    398     +-------------- Stopping -------[powerDown()]&lt;----------+---------------------+
    399       </pre>
    400 
    401       Note that states to the left from PoweredOff, Aborted and Saved in the
    402       above diagram are called <i>online VM states</i>. These states
    403       represent the virtual machine which is being executed in a dedicated
    404       process (usually with a GUI window attached to it where you can see the
    405       activity of the virtual machine and interact with it). There are two
    406       special pseudo-states, FirstOnline and LastOnline, that can be used in
    407       relational expressions to detect if the given machine state is online or
    408       not:
    409 
    410       <pre>
    411         if (machine.GetState() &gt;= MachineState_FirstOnline &amp;&amp;
    412             machine.GetState() &lt;= MachineState_LastOnline)
    413         {
    414             ...the machine is being executed...
    415         }
    416       </pre>
    417 
    418       When the virtual machine is on one of the online VM states (that is, being
    419       executed), only a few machine settings can be modified. Methods working
    420       with such settings contain an explicit note about that. An attempt to
    421       change any oter setting or perform a modifying operation during this time
    422       will result in the <link to="VBOX_E_INVALID_VM_STATE"/> error.
    423 
    424       All online states except Running, Paused and Stuck are transitional: they
    425       represent temporary conditions of the virtual machine that will last as
    426       long as the operation that initiated such a condition.
    427 
    428       The Stuck state is a special case. It means that execution of the machine
    429       has reached the "Guru Meditation" condition. This condition indicates an
    430       internal VMM (virtual machine manager) failure which may happen as a
    431       result of either an unhandled low-level virtual hardware exception or one
    432       of the recompiler exceptions (such as the <i>too-many-traps</i>
    433       condition).
    434 
    435       Note also that any online VM state may transit to the Aborted state. This
    436       happens if the process that is executing the virtual machine terminates
    437       unexpectedly (for example, crashes). Other than that, the Aborted state is
    438       equivalent to PoweredOff.
    439 
    440       There are also a few additional state diagrams that do not deal with
    441       virtual machine execution and therefore are shown separately. The states
    442       shown on these diagrams are called <i>offline VM states</i> (this includes
    443       PoweredOff, Aborted and Saved too).
    444 
    445       The first diagram shows what happens when a lengthy setup operation is
    446       being executed (such as <link to="IMachine::attachHardDisk2()"/>).
    447 
    448       <pre>
    449     +-----------------------------------(same sate as before the call)------+
    450     |                                                                       |
    451     +-&gt; PoweredOff --+                                                      |
    452     |                |                                                      |
    453     |-&gt; Aborted -----+--&gt;[lengthy VM configuration call] --&gt; SettingUp -----+
    454     |                |
    455     +-&gt; Saved -------+
    456       </pre>
    457 
    458       The next two diagrams demonstrate the process of taking a snapshot of a
    459       powered off virtual machine and performing one of the "discard..."
    460       operations, respectively.
    461 
    462       <pre>
    463     +-----------------------------------(same sate as before the call)------+
    464     |                                                                       |
    465     +-&gt; PoweredOff --+                                                      |
    466     |                +--&gt;[takeSnapshot()] -------------------&gt; Saving ------+
    467     +-&gt; Aborted -----+
    468 
    469     +-&gt; PoweredOff --+
    470     |                |
    471     |   Aborted -----+--&gt;[discardSnapshot()    ]-------------&gt; Discarding --+
    472     |                |   [discardCurrentState()]                            |
    473     +-&gt; Saved -------+   [discardCurrentSnapshotAndState()]                 |
    474     |                                                                       |
    475     +---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
    476       </pre>
    477 
    478       Note that the Saving state is present in both the offline state group and
    479       online state group. Currently, the only way to determine what group is
    480       assumed in a particular case is to remember the previous machine state: if
    481       it was Running or Paused, then Saving is an online state, otherwise it is
    482       an offline state. This inconsistency may be removed in one of the future
    483       versions of VirtualBox by adding a new state.
     373      Virtual machine execution state. This enumeration represents possible
     374      values of the <link to="IMachine::state"/> attribute.
    484375    </desc>
    485376
    486377    <const name="Null"                  value="0">
    487       <desc>Null value (nver used by the API).</desc>
     378      <desc><tt>null</tt> value. Never used by the API.</desc>
    488379    </const>
    489380    <const name="PoweredOff"            value="1">
    … …  
    494385    <const name="Saved"                 value="2">
    495386      <desc>
    496         The machine is not currently running, but the execution state of the machine
    497         has been saved to an external file when it was running.
     387        The machine is not currently running, but the execution state
     388        of the machine has been saved to an external file when it
     389        was running.
     390        <note>
     391          Only a few machine settings can be altered when the machine
     392          is in this state.
     393        </note>
    498394      </desc>
    499395    </const>
    500396    <const name="Aborted"               value="3">
    501397      <desc>
    502         The process running the machine has terminated abnormally.
     398        A process running the machine has terminated abnormally.
     399        Other than that, this value is equivalent to #PoweredOff.
    503400      </desc>
    504401    </const>
    … …  
    506403      <desc>
    507404        The machine is currently being executed.
     405        <note>
     406          This value can be used in relational expressions:
     407          all state values less than Running describe a virtual machine that is
     408          not currently being executed (i.e., it is completely out of
     409          action).
     410        </note>
    508411        <note internal="yes">
    509412          For whoever decides to touch this enum: In order to keep the
    510           comparisons in the source code valid, this state must immediately
     413          aforementioned comparisons valid, this state must immediately
    511414          precede the Paused state.
    512415        </note>
    … …  
    516419      <desc>
    517420        Execution of the machine has been paused.
     421        <note>
     422          This value can be used in relational expressions: all state values
     423          greater than Paused represent unstable states of the running virtual
     424          machine. Unless explicitly stated otherwise, no machine settings can
     425          be altered when it is in one of the unstable states.
     426        </note>
    518427        <note internal="yes">
    519428          For whoever decides to touch this enum: In order to keep the
    520           comparisons in the source code valid, this state must immediately
     429          aforementioned comparisons valid, this state must immediately
    521430          follow the Running state.
    522431        </note>
    … …  
    526435      <desc>
    527436        Execution of the machine has reached the "Guru Meditation"
    528         condition.
     437        condition. This condition indicates an internal VMM failure which may
     438        happen as a result of either an unhandled low-level virtual hardware
     439        exception or one of the recompiler exceptions (such as
     440        the <i>too-many-traps</i> condition).
    529441      </desc>
    530442    </const>
    531443    <const name="Starting"              value="7">
    532444      <desc>
    533         Machine is being started after powering it on from a
     445        Machine is being started after
     446        <link to="IConsole::powerUp">powering it on</link> from a
    534447        zero execution state.
    535448      </desc>
    … …  
    537450    <const name="Stopping"              value="8">
    538451      <desc>
    539         Machine is being normally stopped powering it off, or after the guest OS
    540         has initiated a shutdown sequence.
     452        Machine is being normally stopped
     453        (after explicitly <link to="IConsole::powerDown">powering it off</link>,
     454        or after the guest OS has initiated a shutdown sequence).
    541455      </desc>
    542456    </const>
    543457    <const name="Saving"                value="9">
    544458      <desc>
    545         Machine is saving its execution state to a file or an online
    546         snapshot of the machine is being taken.
     459        Machine is saving its execution state to a file as a
     460        result of calling <link to="IConsole::saveState"/> or an online
     461        snapshot of the machine is being taken using
     462        <link to="IConsole::takeSnapshot"/>.
    547463      </desc>
    548464    </const>
    … …  
    550466      <desc>
    551467        Execution state of the machine is being restored from a file
    552         after powering it on from the saved execution state.
     468        after <link to="IConsole::powerUp">powering it on</link> from
     469        a saved execution state.
    553470      </desc>
    554471    </const>
    555472    <const name="Discarding"            value="11">
    556473      <desc>
    557         Snapshot of the machine is being discarded.
     474        Snapshot of the machine is being discarded after calling
     475        <link to="IConsole::discardSnapshot"/> or its current state is
     476        being discarded after <link to="IConsole::discardCurrentState"/>.
    558477      </desc>
    559478    </const>
    560479    <const name="SettingUp"             value="12">
    561480      <desc>
    562         Lengthy setup operation is in progress.
     481        Lengthy setup operation is in progress (e.g.
     482        <link to="IMachine::attachHardDisk2"/>).
    563483      </desc>
    564484    </const>
    565 
    566     <const name="FirstOnline" value="4" wsmap="suppress"> <!-- Running -->
    567       <desc>
    568         Pseudo-state: first online state (for use in relational expressions).
    569         <note internal="yes">
    570           For whoever decides to touch this enum: In order to keep the
    571           comparisons involving FirstOnline and LastOnline pseudo-states valid,
    572           the numeric values of these states must be correspondingly updated if
    573           needed: for any online VM state, the condition
    574           <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be
    575           <tt>true</tt>.
    576         </note>
    577       </desc>
    578     </const>
    579     <const name="LastOnline"  value="10" wsmap="suppress"> <!-- Restoring -->
    580       <desc>
    581         Pseudo-state: last online state (for use in relational expressions).
    582         <note internal="yes">
    583           For whoever decides to touch this enum: In order to keep the
    584           comparisons involving FirstOnline and LastOnline pseudo-states valid,
    585           the numeric values of these states must be correspondingly updated if
    586           needed: for any online VM state, the condition
    587           <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be
    588           <tt>true</tt>.
    589         </note>
    590       </desc>
    591     </const>
    592 
    593485  </enum>
    594486
    … …  
    600492      Session state. This enumeration represents possible values of
    601493      <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
    602       attributes. See individual enumerator descriptions for the meaning for
    603       every value.
     494      attributes. Individual value descriptions contain the appropriate
     495      meaning for every case.
    604496    </desc>
    605497
    606498    <const name="Null"                  value="0">
    607       <desc>Null value (never used by the API).</desc>
     499      <desc><tt>null</tt> value. Never used by the API.</desc>
    608500    </const>
    609501    <const name="Closed"                value="1">
    … …  
    647539
    648540    <const name="Null"                  value="0">
    649       <desc>Null value (never used by the API).</desc>
     541      <desc><tt>null</tt> value. Never used by the API.</desc>
    650542    </const>
    651543    <const name="Direct"                value="1">
    … …  
    678570    <const name="Null"              value="0">
    679571      <desc>
    680         Null value, may also mean "no device" (not allowed for
    681         <link to="IConsole::getDeviceActivity"/>).
     572        <tt>null</tt> value which may also mean "no device".
     573        <note>
     574          This value is not allowed for
     575          <link to="IConsole::getDeviceActivity"/>
     576        </note>
    682577      </desc>
    683578    </const>
    … …  
    723618
    724619    <const name="Null"              value="0">
    725       <desc>Null value (never used by the API).</desc>
     620      <desc><tt>null</tt> value. Never used by the API.</desc>
    726621    </const>
    727622
    … …  
    878773
    879774    <const name="Null"            value="0">
    880       <desc>Null value (never used by the API).</desc>
     775      <desc><tt>null</tt> value. Never used by the API.</desc>
    881776    </const>
    882777    <const name="PIIX3"           value="1"/>
    … …  
    889784  >
    890785    <const name="Null"              value="0">
    891       <desc>Null value (never used by the API).</desc>
     786      <desc><tt>null</tt> value. Never used by the API.</desc>
    892787    </const>
    893788    <const name="NotMounted"        value="1"/>
    … …  
    11101005
    11111006        <ul>
    1112         <li><link to="DeviceType_HardDisk"/>: the media is a hard disk
     1007        <li><link to="DeviceType::HardDisk"/>: the media is a hard disk
    11131008        that, if registered, can be obtained using the
    11141009        <link to="IVirtualBox::getHardDisk2()"/> call.</li>
    1115         <li><link to="DeviceType_DVD"/>: the media is a CD/DVD image
     1010        <li><link to="DeviceType::DVD"/>: the media is a CD/DVD image
    11161011        that, if registered, can be obtained using the
    11171012        <link to="IVirtualBox::getDVDImage()"/> call.</li>
    1118         <li><link to="DeviceType_Floppy"/>: the media is a Floppy image
     1013        <li><link to="DeviceType::Floppy"/>: the media is a Floppy image
    11191014        that, if registered, can be obtained using the
    11201015        <link to="IVirtualBox::getFloppyImage()"/> call.</li>
    … …  
    17401635        </ul>
    17411636
    1742         Some hard disk attributes, such as <link to="IHardDisk2::id"/>, may
    1743         remain uninitialized until the hard disk storage unit is successfully
    1744         created by one of the above methods.
     1637        Some hard disk attributes, such as <link to="#id"/>, may remain
     1638        uninitialized until the hard disk storage unit is successfully created
     1639        by one of the above methods.
    17451640
    17461641        After the storage unit is successfully created, the hard disk gets
    … …  
    35673462      <desc>
    35683463        Full path to the file that stores the execution state of
    3569         the machine when it is in the <link to="MachineState_Saved"/> state.
     3464        the machine when it is in the <link to="MachineState::Saved"/>
     3465        state.
    35703466        <note>
    35713467          When the machine is not in the Saved state, this attribute
    … …  
    36713567
    36723568        To indicate that no device is associated with the given position,
    3673         <link to="DeviceType_Null"/> should be used.
     3569        <link to="DeviceType::Null"/> should be used.
    36743570
    36753571        @todo setHardDiskBootOrder(), setNetworkBootOrder()
    … …  
    37083604
    37093605        If here are no devices at the given position, then
    3710         <link to="DeviceType_Null"/> is returned.
     3606        <link to="DeviceType::Null"/> is returned.
    37113607
    37123608        @todo getHardDiskBootOrder(), getNetworkBootOrder()
    … …  
    47334629        The @a scope argument defines one of three scopes:
    47344630        <link to="IVirtualBox::sharedFolders">global shared folders</link>
    4735         (<link to="Scope_Global">Global</link>),
     4631        (<link to="Scope::Global">Global</link>),
    47364632        <link to="IMachine::sharedFolders">permanent shared folders</link> of
    4737         the machine (<link to="Scope_Machine">Machine</link>) or <link
     4633        the machine (<link to="Scope::Machine">Machine</link>) or <link
    47384634        to="IConsole::sharedFolders">transient shared folders</link> of the
    4739         machine (<link to="Scope_Session">Session</link>). Interested callees
     4635        machine (<link to="Scope::Session">Session</link>). Interested callees
    47404636        should use query the corresponding collections to find out what has
    47414637        changed.
    … …  
    51285024        powered on).
    51295025
    5130         If the machine is in the <link to="MachineState_Saved"/> state,
     5026        If the machine is in the <link to="MachineState::Saved"/> state,
    51315027        it will continue its execution the point where the state has
    51325028        been saved.
    … …  
    51635059      <desc>
    51645060        Identical to powerUp except that the VM will enter the
    5165         <link to="MachineState_Paused"/> state, instead of
    5166         <link to="MachineState_Running"/>.
     5061        <link to="MachineState::Paused"/> state, instead of
     5062        <link to="MachineState::Running"/>.
    51675063
    51685064        <see>#powerUp</see>
    … …  
    54025298
    54035299        The device needs to be in one of the following states:
    5404         <link to="USBDeviceState_Busy"/>,
    5405         <link to="USBDeviceState_Available"/> or
    5406         <link to="USBDeviceState_Held"/>,
     5300        <link to="USBDeviceState::Busy">Busy</link>,
     5301        <link to="USBDeviceState::Available">Available</link> or
     5302        <link to="USBDeviceState::Held">Held</link>,
    54075303        otherwise an error is immediately returned.
    54085304
    54095305        When the device state is
    5410         <link to="USBDeviceState_Busy">Busy</link>, an error may also
     5306        <link to="USBDeviceState::Busy">Busy</link>, an error may also
    54115307        be returned if the host computer refuses to release it for some reason.
    54125308
    … …  
    55605456
    55615457        You cannot discard the snapshot if it
    5562         stores <link to="HardDiskType_Normal">normal</link> (non-differencing)
     5458        stores <link to="HardDiskType::Normal">normal</link> (non-differencing)
    55635459        hard disks that have differencing hard disks based on them. Snapshots of
    55645460        such kind can be discarded only when every normal hard disk has either
    … …  
    55855481
    55865482        The virtual machine is put to
    5587         the <link to="MachineState_Discarding">Discarding</link> state until
     5483        the <link to="MachineState::Discarding">Discarding</link> state until
    55885484        the discard operation is completed.
    55895485
    … …  
    56365532
    56375533        If the current snapshot of the machine is an online snapshot, the
    5638         machine will go to the <link to="MachineState_Saved"> saved
     5534        machine will go to the <link to="MachineState::Saved"> saved
    56395535        state</link>, so that the next time it is powered on, the execution
    56405536        state will be restored from the current snapshot.
    … …  
    56455541
    56465542        <note>
    5647           If the machine state is <link to="MachineState_Saved">Saved</link>
     5543          If the machine state is <link to="MachineState::Saved">Saved</link>
    56485544          prior to this operation, the saved state file will be implicitly
    56495545          discarded (as if <link to="IConsole::discardSavedState()"/> were
    … …  
    56915587
    56925588        <note>
    5693           If the machine state is <link to="MachineState_Saved">Saved</link>
     5589          If the machine state is <link to="MachineState::Saved">Saved</link>
    56945590          prior to this operation, the saved state file will be implicitly
    56955591          discarded (as if <link to="#discardSavedState()"/> were
    … …  
    64616357
    64626358        The list of supported hard disk formats may be obtained by the
    6463         <link  to="#hardDiskFormats"/> call. Note that the default hard disk
    6464         format must have a capability to create differencing hard disks;
    6465         otherwise opeartions that create hard disks implicitly may fail
     6359        <link  to="#defaultHardDiskFormats"/> call. Note that the default
     6360        hard disk format must have a capability to create differencing hard
     6361        disks; otherwise opeartions that create hard disks implicitly may fail
    64666362        unexpectedly.
    64676363
    … …  
    64766372        <see>
    64776373          <link to="#hardDiskFormats"/>,
    6478           <link to="IHardDiskFormat::id"/>,
     6374          <link to="IHardDiskFormat:id"/>,
    64796375          <link to="IVirtualBox::createHardDisk2()"/>
    64806376        </see>
    … …  
    69936889      The current machine state also includes the current execution state.
    69946890      If the machine is being currently executed
    6995       (<link to="IMachine::state"/> is <link to="MachineState_Running"/>
     6891      (<link to="IMachine::state"/> is <link to="MachineState::Running"/>
    69966892      and above), its execution state is just what's happening now.
    6997       If it is powered off (<link to="MachineState_PoweredOff"/> or
    6998       <link to="MachineState_Aborted"/>), it has a zero execution state.
    6999       If the machine is saved (<link to="MachineState_Saved"/>), its
     6893      If it is powered off (<link to="MachineState::PoweredOff"/> or
     6894      <link to="MachineState::Aborted"/>), it has a zero execution state.
     6895      If the machine is saved (<link to="MachineState::Saved"/>), its
    70006896      execution state is what saved in the execution state file
    70016897      (<link to="IMachine::stateFilePath"/>).
    … …  
    72437139      The given medium (with the created storage unit) is considered to be
    72447140      <i>accessible</i> when its storage unit can be successfully read from.
    7245       Accessible media are indicated by the <link to="MediaState_Created"/>
     7141      Accessible media are indicated by the <link to="MediaState::Created"/>
    72467142      value of the <link to="#state"/> attribute. When the storage unit cannot
    72477143      be read (for example, because it is located on a disconnected network
    72487144      resource, or was accidentally deleted outside VirtualBox), the medium is
    72497145      considered to be <i>inaccessible</i> which is indicated by the
    7250       <link to="MediaState_Inaccessible"/> state. The details about the reason
     7146      <link to="MediaState::Inaccessible"/> state. The details about the reason
    72517147      of being inaccessible can be obtained using the
    72527148      <link to="#lastAccessError"/> attribute.
    … …  
    72617157      Note that when VirtualBox starts up (e.g. the VirtualBox object gets
    72627158      created for the first time), all known media are in the
    7263       <link to="MediaState_Inaccessible"/> state but the value of the <link
     7159      <link to="MediaState::Inaccessible"/> state but the value of the <link
    72647160      to="#lastAccessError"/> attribute is <tt>null</tt> because no actual
    72657161      accessibility check is made on startup. This is done to make the
    … …  
    72757171
    72767172        <note>
    7277           For media in one of MediaState_NotCreated, MediaState_Creating or
    7278           MediaState_Deleting states, the value of this property is undefined
     7173          For media in one of MediaState::NotCreated, MediaState::Creating or
     7174          MediaState::Deleting states, the value of this property is undefined
    72797175          and will most likely be an empty UUID.
    72807176        </note>
    … …  
    72937189          For some storage types, reading this attribute may return an outdated
    72947190          (last known) value when <link to="#state"/> is <link
    7295           to="MediaState_Inaccessible"/> or <link
    7296           to="MediaState_LockedWrite"/> because the value of this attribute is
     7191          to="MediaState::Inaccessible"/> or <link
     7192          to="MediaState::LockedWrite"/> because the value of this attribute is
    72977193          stored within the storage unit itself. Also note that changing the
    72987194          attribute value is not possible in such case, as well as when the
    7299           medium is the <link to="MediaState_LockedRead"/> state.
     7195          medium is the <link to="MediaState::LockedRead"/> state.
    73007196        </note>
    73017197      </desc>
    … …  
    73147210        operation expires.
    73157211
    7316         If the last known state of the medium is <link to="MediaState_Created"/>
     7212        If the last known state of the medium is <link to="MediaState::Created"/>
    73177213        and the accessibility check fails then the state would be set to
    7318         <link to="MediaState_Inaccessible"/> and <link to="#lastAccessError"/>
     7214        <link to="MediaState::Inaccessible"/> and <link to="#lastAccessError"/>
    73197215        may be used to get more details about the failure. If the state of the
    7320         medium is <link to="MediaState_LockedRead"/> or
    7321         <link to="MediaState_LockedWrite"/> then it remains the same, and a
     7216        medium is <link to="MediaState::LockedRead"/> or
     7217        <link to="MediaState::LockedWrite"/> then it remains the same, and a
    73227218        non-null value of <link to="#lastAccessError"/> will indicate a failed
    73237219        accessibility check in this case.
    73247220
    73257221        Note that not all media states are applicable to certain media types.
    7326         For example, states <link to="MediaState_NotCreated"/>,
    7327         <link to="MediaState_LockedWrite"/>, <link to="MediaState_Creating"/>,
    7328         <link to="MediaState_Deleting"/> are meaningless for IDVDImage2 and
     7222        For example, states <link to="MediaState::NotCreated"/>,
     7223        <link to="MediaState::LockedWrite"/>, <link to="MediaState::Creating"/>,
     7224        <link to="MediaState::Deleting"/> are meaningless for IDVDImage2 and
    73297225        IFloppyImage2 media.
    73307226      </desc>
    … …  
    73797275        <note>
    73807276          For media whose <link to="#state"/> is <link
    7381           to="MediaState_Inaccessible"/>, the value of this property is the
    7382           last known size. For <link to="MediaState_NotCreated"/> media,
     7277          to="MediaState::Inaccessible"/>, the value of this property is the
     7278          last known size. For <link to="MediaState::NotCreated"/> media,
    73837279          the returned value is zero.
    73847280        </note>
    … …  
    74697365
    74707366        This method sets the media state to <link
    7471         to="MediaState_LockedRead"/> on success. The state prior to
    7472         this call must be <link to="MediaState_Created"/>, <link
    7473         to="MediaState_Inaccessible"/> or <link
    7474         to="MediaState_LockedRead"/>. As you can see, inaccessible
     7367        to="MediaState::LockedRead"/> on success. The state prior to
     7368        this call must be <link to="MediaState::Created"/>, <link
     7369        to="MediaState::Inaccessible"/> or <link
     7370        to="MediaState::LockedRead"/>. As you can see, inaccessible
    74757371        media can be locked too. This is not an error; this method
    74767372        performs a logical lock that prevents modifications of this
    … …  
    75417437
    75427438        This method sets the media state to <link
    7543         to="MediaState_LockedWrite"/> on success. The state prior to
    7544         this call must be <link to="MediaState_Created"/> or <link
    7545         to="MediaState_Inaccessible"/>. As you can see, inaccessible
     7439        to="MediaState::LockedWrite"/> on success. The state prior to
     7440        this call must be <link to="MediaState::Created"/> or <link
     7441        to="MediaState::Inaccessible"/>. As you can see, inaccessible
    75467442        media can be locked too. This is not an error; this method
    75477443        performs a logical lock that prevents modifications of this
    … …  
    77137609
    77147610      There are three types of hard disks:
    7715       <link to="HardDiskType_Normal">Normal</link>,
    7716       <link to="HardDiskType_Immutable">Immutable</link> and
    7717       <link to="HardDiskType_Writethrough">Writethrough</link>. The type of the
     7611      <link to="HardDiskType::Normal">Normal</link>,
     7612      <link to="HardDiskType::Immutable">Immutable</link> and
     7613      <link to="HardDiskType::Writethrough">Writethrough</link>. The type of the
    77187614      hard disk defines how the hard disk is attached to a virtual machine and
    77197615      what happens when a <link to="ISnapshot">snapshot</link> of the virtual
    … …  
    77457641
    77467642      Note that the type of all differencing hard disks is
    7747       <link to="HardDiskType_Normal">Normal</link>; all other values are
     7643      <link to="HardDiskType::Normal">Normal</link>; all other values are
    77487644      meaningless for them. Base hard disks may be of any type.
    77497645
    … …  
    77827678      there is a possibility to cause VirtualBox to compose a unique value for
    77837679      the file name part of the location using the UUID of the hard disk. This
    7784       applies only to hard disks in <link to="MediaState_NotCreated"/> state,
     7680      applies only to hard disks in <link to="MediaState::NotCreated"/> state,
    77857681      e.g. before the storage unit is created, and works as follows. You set the
    77867682      value of the <link to="IMedium::location"/> attribute to a location
    … …  
    80037899          </li>
    80047900          <li>As long as the hard disk has children, its type cannot be set
    8005               to <link to="HardDiskType_Writethrough"/>.
     7901              to <link to="HardDiskType::Writethrough"/>.
    80067902          </li>
    80077903          <li>The type of all differencing hard disks is
    8008               <link to="HardDiskType_Normal"/> and cannot be changed.
     7904              <link to="HardDiskType::Normal"/> and cannot be changed.
    80097905          </li>
    80107906        </ul>
    80117907
    80127908        The type of a newly created or opened hard disk is set to
    8013         <link to="HardDiskType_Normal"/>.
     7909        <link to="HardDiskType::Normal"/>.
    80147910      </desc>
    80157911    </attribute>
    … …  
    80637959        disk for that. See the interface description for more information.
    80647960
    8065         Note that all <link to="HardDiskType_Immutable">Immutable</link> hard
     7961        Note that all <link to="HardDiskType::Immutable">Immutable</link> hard
    80667962        disks are always read-only while all
    8067         <link to="HardDiskType_Writethrough">Writethrough</link> hard disks are
     7963        <link to="HardDiskType::Writethrough">Writethrough</link> hard disks are
    80687964        always not.
    80697965
    … …  
    80907986        <note>
    80917987          For hard disks whose state is <link to="#state"/> is <link
    8092           to="MediaState_Inaccessible"/>, the value of this property is the
    8093           last known logical size. For <link to="MediaState_NotCreated"/> hard
     7988          to="MediaState::Inaccessible"/>, the value of this property is the
     7989          last known logical size. For <link to="MediaState::NotCreated"/> hard
    80947990          disks, the returned value is zero.
    80957991        </note>
    … …  
    82268122
    82278123        Before the operation starts, the hard disk is placed in
    8228         <link to="MediaState_Creating"/> state. If the create operation
    8229         fails, the media will be placed back in <link to="MediaState_NotCreated"/>
     8124        <link to="MediaState::Creating"/> state. If the create operation
     8125        fails, the media will be placed back in <link to="MediaState::NotCreated"/>
    82308126        state.
    82318127
    82328128        After the returned progress object reports that the operation has
    82338129        successfully completed, the media state will be set to <link
    8234         to="MediaState_Created"/>, the hard disk will be remembered by this
     8130        to="MediaState::Created"/>, the hard disk will be remembered by this
    82358131        VirtualBox installation and may be attached to virtual machines.
    82368132
    … …  
    82568152
    82578153        Before the operation starts, the hard disk is placed to
    8258         <link to="MediaState_Creating"/> state. If the create operation
    8259         fails, the media will placed back to <link to="MediaState_NotCreated"/>
     8154        <link to="MediaState::Creating"/> state. If the create operation
     8155        fails, the media will placed back to <link to="MediaState::NotCreated"/>
    82608156        state.
    82618157
    82628158        After the returned progress object reports that the operation is
    82638159        successfully complete, the media state will be set to <link
    8264         to="MediaState_Created"/>, the hard disk will be remembered by this
     8160        to="MediaState::Created"/>, the hard disk will be remembered by this
    82658161        VirtualBox installation and may be attached to virtual machines.
    82668162
    … …  
    82878183        is already in progress, or if the hard disk is being in use (locked for
    82888184        read or for write) or inaccessible. Therefore, the only valid state for
    8289         this operation to succeed is <link to="MediaState_Created"/>.
     8185        this operation to succeed is <link to="MediaState::Created"/>.
    82908186
    82918187        Before the operation starts, the hard disk is placed to
    8292         <link to="MediaState_Deleting"/> state and gets removed from the list
     8188        <link to="MediaState::Deleting"/> state and gets removed from the list
    82938189        of remembered hard disks (media registry). If the delete operation
    82948190        fails, the media will be remembered again and placed back to
    8295         <link to="MediaState_Created"/> state.
     8191        <link to="MediaState::Created"/> state.
    82968192
    82978193        After the returned progress object reports that the operation is
    82988194        complete, the media state will be set to
    8299         <link to="MediaState_NotCreated"/> and you will be able to use one of
     8195        <link to="MediaState::NotCreated"/> and you will be able to use one of
    83008196        the storage creation methods to create it again.
    83018197
    … …  
    83308226        argument.
    83318227
    8332         The target hard disk must be in <link to="MediaState_NotCreated"/>
     8228        The target hard disk must be in <link to="MediaState::NotCreated"/>
    83338229        state (i.e. must not have an existing storage unit). Upon successful
    83348230        completion, this operation will set the type of the target hard disk to
    8335         <link to="HardDiskType_Normal"/> and create a storage unit necessary to
     8231        <link to="HardDiskType::Normal"/> and create a storage unit necessary to
    83368232        represent the differencing hard disk data in the given format (according
    83378233        to the storage format of the target object).
    … …  
    83428238
    83438239        <note>
    8344           The hard disk will be set to <link to="MediaState_LockedRead"/>
     8240          The hard disk will be set to <link to="MediaState::LockedRead"/>
    83458241          state for the duration of this operation.
    83468242        </note>
    … …  
    84048300          <li>
    84058301            Neither the source hard disk nor the target hard disk is an
    8406             <link to="HardDiskType_Immutable"/> hard disk.
     8302            <link to="HardDiskType::Immutable"/> hard disk.
    84078303          </li>
    84088304          <li>
    … …  
    84178313          <li>
    84188314            None of the involved hard disks are in
    8419             <link to="MediaState_LockedRead"/> or
    8420             <link to="MediaState_LockedWrite"/> state.
     8315            <link to="MediaState::LockedRead"/> or
     8316            <link to="MediaState::LockedWrite"/> state.
    84218317          </li>
    84228318        </ul>
    … …  
    84248320        <note>
    84258321          This (source) hard disk and all intermediates will be placed to <link
    8426           to="MediaState_Deleting"/> state and the target hard disk will be
    8427           placed to <link to="MediaState_LockedWrite"/> state and for the
     8322          to="MediaState::Deleting"/> state and the target hard disk will be
     8323          placed to <link to="MediaState::LockedWrite"/> state and for the
    84288324          duration of this operation.
    84298325        </note>
    … …  
    84448340        location defined by the @a target argument.
    84458341
    8446         The target hard disk must be in <link to="MediaState_NotCreated"/>
     8342        The target hard disk must be in <link to="MediaState::NotCreated"/>
    84478343        state (i.e. must not have an existing storage unit). Upon successful
    84488344        completion, the cloned hard disk will contain exactly the same sector
    … …  
    84598355        </note>
    84608356        <note>
    8461           This hard disk will be placed to <link to="MediaState_LockedRead"/>
     8357          This hard disk will be placed to <link to="MediaState::LockedRead"/>
    84628358          state for the duration of this operation.
    84638359        </note>
    … …  
    84928388        <note>
    84938389          This hard disk and all its parent hard disks will be placed to <link
    8494           to="MediaState_LockedRead"/> state for the duration of this
     8390          to="MediaState::LockedRead"/> state for the duration of this
    84958391          operation.
    84968392        </note>
    … …  
    85808476    <const name="File" value="0x40">
    85818477      <desc>
    8582         The format backend operates on files (the <link to="IMedium::location"/>
     8478        The format backend operates on files. The <link to="IMedium::location"/>
    85838479        attribute of the hard disk specifies a file used to store hard disk
    8584         data; for a list of supported file extensions see
    8585         <link to="IHardDiskFormat::fileExtensions"/>).
     8480        data. For a list of supported file extensions see
     8481        <link to="IHardDiskFormat::fileExtensions"/>.
    85868482      </desc>
    85878483    </const>
    … …  
    85908486      <desc>
    85918487        The format backend uses the property interface to configure the storage
    8592         location and properties (the <link to="IHardDiskFormat::describeProperties"/>
     8488        location and properties. The <link to="IHardDiskFormat::describeProperties"/>
    85938489        method is used to get access to properties supported by the given hard
    8594         disk format).
     8490        disk format.
    85958491      </desc>
    85968492    </const>
    … …  
    86748570
    86758571        The returned arrays are not empty only if the
    8676         <link to="HardDiskFormatCapabilities_Properties"/> flag is set.
     8572        <link to="HardDiskFormatCapabilities::Properties"/> flag is set.
    86778573
    86788574        <see>DataType</see>
    … …  
    90518947    <const name="Opaque"                  value="0xFFFFFFFF">
    90528948      <desc>
    9053         Unknown buffer format (the user may not assume any particular format of
    9054         the buffer).
     8949        Unknown buffer format. The user may not assume any particular
     8950        format of the buffer.
    90558951      </desc>
    90568952    </const>
    90578953    <const name="FOURCC_RGB"              value="0x32424752">
    90588954      <desc>
    9059         Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
    9060         bit layout).
     8955        Basic RGB format. <link to="IFramebuffer::bitsPerPixel"/> determines
     8956        the bit layout.
    90618957      </desc>
    90628958    </const>
    … …  
    90838979      <desc>
    90848980        Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
    9085         to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
     8981        to="FramebufferPixelFormat::FOURCC_RGB">FOURCC_RGB</link>, valid values
    90868982        are: 8, 15, 16, 24 and 32.
    90878983      </desc>
    … …  
    90918987      <desc>
    90928988        Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
    9093         to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
     8989        to="FramebufferPixelFormat::FOURCC_RGB">FOURCC_RGB</link>, the
    90948990        size of the scan line must be aligned to 32 bits.
    90958991      </desc>
    … …  
    91028998        <note>
    91038999          This attribute must never return <link
    9104           to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
     9000          to="PixelFormat::Opaque"/> -- the format of the buffer
    91059001          <link to="#address"/> points to must be always known.
    91069002        </note>
    … …  
    92099105        The @a pixelFormat parameter defines whether the direct mode is
    92109106        available or not. If @a pixelFormat is <link
    9211         to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
     9107        to="PixelFormat::Opaque"/> then direct access to the guest
    92129108        VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and @a
    92139109        bytesPerLine parameters must be ignored and the implementation must use
    … …  
    92509146        value must always correlate with <link to="#pixelFormat"/>. Note that
    92519147        the <link to="#pixelFormat"/> attribute must never return <link
    9252         to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
     9148        to="PixelFormat::Opaque"/> regardless of the selected mode.
    92539149
    92549150        <note>
    … …  
    96299525
    96309526    <const name="Null"                  value="0">
    9631       <desc>Null value, also means "not attached".</desc>
     9527      <desc><tt>null</tt> value. Also means "not attached".</desc>
    96329528    </const>
    96339529    <const name="NAT"                   value="1"/>
    … …  
    96459541
    96469542    <const name="Null"                  value="0">
    9647       <desc>Null value (never used by the API).</desc>
     9543      <desc><tt>null</tt> value. Never used by the API.</desc>
    96489544    </const>
    96499545    <const name="Am79C970A"             value="1"/>
    … …  
    98889784        Flag whether this serial port acts as a server (creates a new pipe on
    98899785        the host) or as a client (uses the existing pipe). This attribute is
    9890         used only when <link to="#hostMode"/> is PortMode_HostPipe.
     9786        used only when <link to="#hostMode"/> is PortMode::HostPipe.
    98919787      </desc>
    98929788    </attribute>
    … …  
    98959791      <desc>
    98969792        Path to the serial port's pipe on the host when <link to="#hostMode"/> is
    9897         PortMode_HostPipe, or the host serial device name when
    9898         <link to="#hostMode"/> is PortMode_HostDevice. In either of the above
     9793        PortMode::HostPipe, or the host serial device name when
     9794        <link to="#hostMode"/> is PortMode::HostDevice. In either of the above
    98999795        cases, setting a @c  null or an empty string as the attribute's value
    99009796        will result into an error. Otherwise, the value of this property is
    … …  
    1013210028        They are run against a list of all currently available USB
    1013310029        devices (in states
    10134         <link to="USBDeviceState_Available"/>,
    10135         <link to="USBDeviceState_Busy"/>,
    10136         <link to="USBDeviceState_Held"/>) that were not previously
     10030        <link to="USBDeviceState::Available">Available</link>,
     10031        <link to="USBDeviceState::Busy">Busy</link>,
     10032        <link to="USBDeviceState::Held">Held</link>) that were not previously
    1013710033        ignored by global filters.
    1013810034
    … …  
    1055310449      Once a supported USB device is attached to the host, global USB
    1055410450      filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
    10555       either ignore the device, or put it to USBDeviceState_Held state, or do
    10556       nothing. Unless the device is ignored by global filters, filters of all
    10557       currently running guests (<link to="IUSBController::deviceFilters"/>) are
    10558       activated that can put it to USBDeviceState_Captured state.
     10451      either ignore the device, or put it to #Held state, or do nothing. Unless
     10452      the device is ignored by global filters, filters of all currently running
     10453      guests (<link to="IUSBController::deviceFilters"/>) are activated that can
     10454      put it to #Captured state.
    1055910455
    1056010456      If the device was ignored by global filters, or didn't match
    1056110457      any filters at all (including guest ones), it is handled by the host
    1056210458      in a normal way. In this case, the device state is determined by
    10563       the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
    10564       or USBDeviceState_Available, depending on the current device usage.
     10459      the host and can be one of #Unavailable, #Busy or #Available, depending on
     10460      the current device usage.
    1056510461
    1056610462      Besides auto-capturing based on filters, the device can be manually
    1056710463      captured by guests (<link to="IConsole::attachUSBDevice()"/>) if its
    10568       state is USBDeviceState_Busy, USBDeviceState_Available or
    10569       USBDeviceState_Held.
     10464      state is #Busy, #Available or #Held.
    1057010465
    1057110466      <note>
    1057210467        Due to differences in USB stack implementations in Linux and Win32,
    10573         states USBDeviceState_Busy and USBDeviceState_vailable are applicable
    10574         only to the Linux version of the product. This also means that (<link
    10575         to="IConsole::attachUSBDevice()"/>) can only succeed on Win32 if the
    10576         device state is USBDeviceState_Held.
     10468        states #Busy and #Available are applicable only to the Linux version of
     10469        the product. This also means that (<link
     10470        to="IConsole::attachUSBDevice()"/>) can only succeed on Win32 if
     10471        the device state is #Held.
    1057710472      </note>
    1057810473
    … …  
    1059810493    <const name="Available"             value="3">
    1059910494      <desc>
    10600         Not used by the host computer, available to guests (the host computer
    10601         can also start using the device at any time).
     10495        Not used by the host computer, available to guests.
     10496        The host computer can also start using the device at any time.
    1060210497      </desc>
    1060310498    </const>
    … …  
    1070910604
    1071010605    <const name="Null"          value="0">
    10711       <desc>Null value (never used by the API).</desc>
     10606      <desc><tt>null</tt> value. Never used by the API.</desc>
    1071210607    </const>
    1071310608    <const name="Ignore"        value="1">
    … …  
    1077710672
    1077810673    <const name="Null"          value="0">
    10779       <desc>Null value, also means "dummy audio driver".</desc>
     10674      <desc><tt>null</tt> value. Also means "dummy audio driver".</desc>
    1078010675    </const>
    1078110676    <const name="WinMM"         value="1"/>
    … …  
    1084510740
    1084610741    <const name="Null"            value="0">
    10847       <desc>Null value, also means "no authentication".</desc>
     10742      <desc><tt>null</tt> value. Also means "no authentication".</desc>
    1084810743    </const>
    1084910744    <const name="External"        value="1"/>
    … …  
    1132011215      <desc>
    1132111216        Type of this session. The value of this attribute is valid only
    11322         if the session is currently open (i.e. its #state is
    11323         SessionType_SessionOpen), otherwise an error will be returned.
     11217        if the session is currently open (i.e. its #state is SessionType::SessionOpen),
     11218        otherwise an error will be returned.
    1132411219      </desc>
    1132511220    </attribute>
    … …  
    1134911244        <link to="IVirtualBox::openSession()"/> is not explicitly closed
    1135011245        when the application terminates, the state of the machine will
    11351         be set to <link to="MachineState_Aborted" /> on the server.
     11246        be set to <link to="MachineState::Aborted" /> on the server.
    1135211247
    1135311248        Generally, it is recommended to close all open sessions explicitly
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