VirtualBox

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


Ignore:
Timestamp:
Dec 10, 2008 11:35:43 PM (16 years ago)
Author:
vboxsync
Message:

Main/XIDL: Added MachineState_FirstOnline and LastOnline pseudo-states. Added MachineState diagrams and detailed description. Fixed enum references.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r15235 r15282  
    371371  >
    372372    <desc>
    373       Virtual machine execution state. This enumeration represents possible
    374       values of the <link to="IMachine::state"/> attribute.
     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 a temporary condition of the virtual machine that will not last
     426      too long.
     427
     428      The Stuck state is a special one. 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 whan 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.
    375484    </desc>
    376485
    377486    <const name="Null"                  value="0">
    378       <desc><tt>null</tt> value. Never used by the API.</desc>
     487      <desc>Null value (nver used by the API).</desc>
    379488    </const>
    380489    <const name="PoweredOff"            value="1">
    … …  
    385494    <const name="Saved"                 value="2">
    386495      <desc>
    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>
     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.
    394498      </desc>
    395499    </const>
    396500    <const name="Aborted"               value="3">
    397501      <desc>
    398         A process running the machine has terminated abnormally.
    399         Other than that, this value is equivalent to #PoweredOff.
     502        The process running the machine has terminated abnormally.
    400503      </desc>
    401504    </const>
    … …  
    403506      <desc>
    404507        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>
    411508        <note internal="yes">
    412509          For whoever decides to touch this enum: In order to keep the
    413           aforementioned comparisons valid, this state must immediately
     510          comparisons in the source code valid, this state must immediately
    414511          precede the Paused state.
    415512        </note>
    … …  
    419516      <desc>
    420517        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>
    427518        <note internal="yes">
    428519          For whoever decides to touch this enum: In order to keep the
    429           aforementioned comparisons valid, this state must immediately
     520          comparisons in the source code valid, this state must immediately
    430521          follow the Running state.
    431522        </note>
    … …  
    435526      <desc>
    436527        Execution of the machine has reached the "Guru Meditation"
    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).
     528        condition.
    441529      </desc>
    442530    </const>
    443531    <const name="Starting"              value="7">
    444532      <desc>
    445         Machine is being started after
    446         <link to="IConsole::powerUp">powering it on</link> from a
     533        Machine is being started after powering it on from a
    447534        zero execution state.
    448535      </desc>
    … …  
    450537    <const name="Stopping"              value="8">
    451538      <desc>
    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).
     539        Machine is being normally stopped powering it off, or after the guest OS
     540        has initiated a shutdown sequence.
    455541      </desc>
    456542    </const>
    457543    <const name="Saving"                value="9">
    458544      <desc>
    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"/>.
     545        Machine is saving its execution state to a file or an online
     546        snapshot of the machine is being taken.
    463547      </desc>
    464548    </const>
    … …  
    466550      <desc>
    467551        Execution state of the machine is being restored from a file
    468         after <link to="IConsole::powerUp">powering it on</link> from
    469         a saved execution state.
     552        after powering it on from the saved execution state.
    470553      </desc>
    471554    </const>
    472555    <const name="Discarding"            value="11">
    473556      <desc>
    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"/>.
     557        Snapshot of the machine is being discarded.
    477558      </desc>
    478559    </const>
    479560    <const name="SettingUp"             value="12">
    480561      <desc>
    481         Lengthy setup operation is in progress (e.g.
    482         <link to="IMachine::attachHardDisk2"/>).
     562        Lengthy setup operation is in progress.
    483563      </desc>
    484564    </const>
     565
     566    <const name="FirstOnline"           value="4"> <!-- 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"> <!-- 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
    485593  </enum>
    486594
    … …  
    492600      Session state. This enumeration represents possible values of
    493601      <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
    494       attributes. Individual value descriptions contain the appropriate
    495       meaning for every case.
     602      attributes. See individual enumerator descriptions for the meaning for
     603      every value.
    496604    </desc>
    497605
    498606    <const name="Null"                  value="0">
    499       <desc><tt>null</tt> value. Never used by the API.</desc>
     607      <desc>Null value (never used by the API).</desc>
    500608    </const>
    501609    <const name="Closed"                value="1">
    … …  
    539647
    540648    <const name="Null"                  value="0">
    541       <desc><tt>null</tt> value. Never used by the API.</desc>
     649      <desc>Null value (never used by the API).</desc>
    542650    </const>
    543651    <const name="Direct"                value="1">
    … …  
    570678    <const name="Null"              value="0">
    571679      <desc>
    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>
     680        Null value, may also mean "no device" (not allowed for
     681        <link to="IConsole::getDeviceActivity"/>).
    577682      </desc>
    578683    </const>
    … …  
    618723
    619724    <const name="Null"              value="0">
    620       <desc><tt>null</tt> value. Never used by the API.</desc>
     725      <desc>Null value (never used by the API).</desc>
    621726    </const>
    622727
    … …  
    773878
    774879    <const name="Null"            value="0">
    775       <desc><tt>null</tt> value. Never used by the API.</desc>
     880      <desc>Null value (never used by the API).</desc>
    776881    </const>
    777882    <const name="PIIX3"           value="1"/>
    … …  
    784889  >
    785890    <const name="Null"              value="0">
    786       <desc><tt>null</tt> value. Never used by the API.</desc>
     891      <desc>Null value (never used by the API).</desc>
    787892    </const>
    788893    <const name="NotMounted"        value="1"/>
    … …  
    10051110
    10061111        <ul>
    1007         <li><link to="DeviceType::HardDisk"/>: the media is a hard disk
     1112        <li><link to="DeviceType_HardDisk"/>: the media is a hard disk
    10081113        that, if registered, can be obtained using the
    10091114        <link to="IVirtualBox::getHardDisk2()"/> call.</li>
    1010         <li><link to="DeviceType::DVD"/>: the media is a CD/DVD image
     1115        <li><link to="DeviceType_DVD"/>: the media is a CD/DVD image
    10111116        that, if registered, can be obtained using the
    10121117        <link to="IVirtualBox::getDVDImage()"/> call.</li>
    1013         <li><link to="DeviceType::Floppy"/>: the media is a Floppy image
     1118        <li><link to="DeviceType_Floppy"/>: the media is a Floppy image
    10141119        that, if registered, can be obtained using the
    10151120        <link to="IVirtualBox::getFloppyImage()"/> call.</li>
    … …  
    16351740        </ul>
    16361741
    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.
     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.
    16401745
    16411746        After the storage unit is successfully created, the hard disk gets
    … …  
    34623567      <desc>
    34633568        Full path to the file that stores the execution state of
    3464         the machine when it is in the <link to="MachineState::Saved"/>
    3465         state.
     3569        the machine when it is in the <link to="MachineState_Saved"/> state.
    34663570        <note>
    34673571          When the machine is not in the Saved state, this attribute
    … …  
    35673671
    35683672        To indicate that no device is associated with the given position,
    3569         <link to="DeviceType::Null"/> should be used.
     3673        <link to="DeviceType_Null"/> should be used.
    35703674
    35713675        @todo setHardDiskBootOrder(), setNetworkBootOrder()
    … …  
    36043708
    36053709        If here are no devices at the given position, then
    3606         <link to="DeviceType::Null"/> is returned.
     3710        <link to="DeviceType_Null"/> is returned.
    36073711
    36083712        @todo getHardDiskBootOrder(), getNetworkBootOrder()
    … …  
    46294733        The @a scope argument defines one of three scopes:
    46304734        <link to="IVirtualBox::sharedFolders">global shared folders</link>
    4631         (<link to="Scope::Global">Global</link>),
     4735        (<link to="Scope_Global">Global</link>),
    46324736        <link to="IMachine::sharedFolders">permanent shared folders</link> of
    4633         the machine (<link to="Scope::Machine">Machine</link>) or <link
     4737        the machine (<link to="Scope_Machine">Machine</link>) or <link
    46344738        to="IConsole::sharedFolders">transient shared folders</link> of the
    4635         machine (<link to="Scope::Session">Session</link>). Interested callees
     4739        machine (<link to="Scope_Session">Session</link>). Interested callees
    46364740        should use query the corresponding collections to find out what has
    46374741        changed.
    … …  
    50245128        powered on).
    50255129
    5026         If the machine is in the <link to="MachineState::Saved"/> state,
     5130        If the machine is in the <link to="MachineState_Saved"/> state,
    50275131        it will continue its execution the point where the state has
    50285132        been saved.
    … …  
    50595163      <desc>
    50605164        Identical to powerUp except that the VM will enter the
    5061         <link to="MachineState::Paused"/> state, instead of
    5062         <link to="MachineState::Running"/>.
     5165        <link to="MachineState_Paused"/> state, instead of
     5166        <link to="MachineState_Running"/>.
    50635167
    50645168        <see>#powerUp</see>
    … …  
    52985402
    52995403        The device needs to be in one of the following states:
    5300         <link to="USBDeviceState::Busy">Busy</link>,
    5301         <link to="USBDeviceState::Available">Available</link> or
    5302         <link to="USBDeviceState::Held">Held</link>,
     5404        <link to="USBDeviceState_Busy"/>,
     5405        <link to="USBDeviceState_Available"/> or
     5406        <link to="USBDeviceState_Held"/>,
    53035407        otherwise an error is immediately returned.
    53045408
    53055409        When the device state is
    5306         <link to="USBDeviceState::Busy">Busy</link>, an error may also
     5410        <link to="USBDeviceState_Busy">Busy</link>, an error may also
    53075411        be returned if the host computer refuses to release it for some reason.
    53085412
    … …  
    54565560
    54575561        You cannot discard the snapshot if it
    5458         stores <link to="HardDiskType::Normal">normal</link> (non-differencing)
     5562        stores <link to="HardDiskType_Normal">normal</link> (non-differencing)
    54595563        hard disks that have differencing hard disks based on them. Snapshots of
    54605564        such kind can be discarded only when every normal hard disk has either
    … …  
    54815585
    54825586        The virtual machine is put to
    5483         the <link to="MachineState::Discarding">Discarding</link> state until
     5587        the <link to="MachineState_Discarding">Discarding</link> state until
    54845588        the discard operation is completed.
    54855589
    … …  
    55325636
    55335637        If the current snapshot of the machine is an online snapshot, the
    5534         machine will go to the <link to="MachineState::Saved"> saved
     5638        machine will go to the <link to="MachineState_Saved"> saved
    55355639        state</link>, so that the next time it is powered on, the execution
    55365640        state will be restored from the current snapshot.
    … …  
    55415645
    55425646        <note>
    5543           If the machine state is <link to="MachineState::Saved">Saved</link>
     5647          If the machine state is <link to="MachineState_Saved">Saved</link>
    55445648          prior to this operation, the saved state file will be implicitly
    55455649          discarded (as if <link to="IConsole::discardSavedState()"/> were
    … …  
    55875691
    55885692        <note>
    5589           If the machine state is <link to="MachineState::Saved">Saved</link>
     5693          If the machine state is <link to="MachineState_Saved">Saved</link>
    55905694          prior to this operation, the saved state file will be implicitly
    55915695          discarded (as if <link to="#discardSavedState()"/> were
    … …  
    63576461
    63586462        The list of supported hard disk formats may be obtained by the
    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
     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
    63626466        unexpectedly.
    63636467
    … …  
    63726476        <see>
    63736477          <link to="#hardDiskFormats"/>,
    6374           <link to="IHardDiskFormat:id"/>,
     6478          <link to="IHardDiskFormat::id"/>,
    63756479          <link to="IVirtualBox::createHardDisk2()"/>
    63766480        </see>
    … …  
    68896993      The current machine state also includes the current execution state.
    68906994      If the machine is being currently executed
    6891       (<link to="IMachine::state"/> is <link to="MachineState::Running"/>
     6995      (<link to="IMachine::state"/> is <link to="MachineState_Running"/>
    68926996      and above), its execution state is just what's happening now.
    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
     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
    68967000      execution state is what saved in the execution state file
    68977001      (<link to="IMachine::stateFilePath"/>).
    … …  
    71397243      The given medium (with the created storage unit) is considered to be
    71407244      <i>accessible</i> when its storage unit can be successfully read from.
    7141       Accessible media are indicated by the <link to="MediaState::Created"/>
     7245      Accessible media are indicated by the <link to="MediaState_Created"/>
    71427246      value of the <link to="#state"/> attribute. When the storage unit cannot
    71437247      be read (for example, because it is located on a disconnected network
    71447248      resource, or was accidentally deleted outside VirtualBox), the medium is
    71457249      considered to be <i>inaccessible</i> which is indicated by the
    7146       <link to="MediaState::Inaccessible"/> state. The details about the reason
     7250      <link to="MediaState_Inaccessible"/> state. The details about the reason
    71477251      of being inaccessible can be obtained using the
    71487252      <link to="#lastAccessError"/> attribute.
    … …  
    71577261      Note that when VirtualBox starts up (e.g. the VirtualBox object gets
    71587262      created for the first time), all known media are in the
    7159       <link to="MediaState::Inaccessible"/> state but the value of the <link
     7263      <link to="MediaState_Inaccessible"/> state but the value of the <link
    71607264      to="#lastAccessError"/> attribute is <tt>null</tt> because no actual
    71617265      accessibility check is made on startup. This is done to make the
    … …  
    71717275
    71727276        <note>
    7173           For media in one of MediaState::NotCreated, MediaState::Creating or
    7174           MediaState::Deleting states, the value of this property is undefined
     7277          For media in one of MediaState_NotCreated, MediaState_Creating or
     7278          MediaState_Deleting states, the value of this property is undefined
    71757279          and will most likely be an empty UUID.
    71767280        </note>
    … …  
    71897293          For some storage types, reading this attribute may return an outdated
    71907294          (last known) value when <link to="#state"/> is <link
    7191           to="MediaState::Inaccessible"/> or <link
    7192           to="MediaState::LockedWrite"/> because the value of this attribute is
     7295          to="MediaState_Inaccessible"/> or <link
     7296          to="MediaState_LockedWrite"/> because the value of this attribute is
    71937297          stored within the storage unit itself. Also note that changing the
    71947298          attribute value is not possible in such case, as well as when the
    7195           medium is the <link to="MediaState::LockedRead"/> state.
     7299          medium is the <link to="MediaState_LockedRead"/> state.
    71967300        </note>
    71977301      </desc>
    … …  
    72107314        operation expires.
    72117315
    7212         If the last known state of the medium is <link to="MediaState::Created"/>
     7316        If the last known state of the medium is <link to="MediaState_Created"/>
    72137317        and the accessibility check fails then the state would be set to
    7214         <link to="MediaState::Inaccessible"/> and <link to="#lastAccessError"/>
     7318        <link to="MediaState_Inaccessible"/> and <link to="#lastAccessError"/>
    72157319        may be used to get more details about the failure. If the state of the
    7216         medium is <link to="MediaState::LockedRead"/> or
    7217         <link to="MediaState::LockedWrite"/> then it remains the same, and a
     7320        medium is <link to="MediaState_LockedRead"/> or
     7321        <link to="MediaState_LockedWrite"/> then it remains the same, and a
    72187322        non-null value of <link to="#lastAccessError"/> will indicate a failed
    72197323        accessibility check in this case.
    72207324
    72217325        Note that not all media states are applicable to certain media types.
    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
     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
    72257329        IFloppyImage2 media.
    72267330      </desc>
    … …  
    72757379        <note>
    72767380          For media whose <link to="#state"/> is <link
    7277           to="MediaState::Inaccessible"/>, the value of this property is the
    7278           last known size. For <link to="MediaState::NotCreated"/> media,
     7381          to="MediaState_Inaccessible"/>, the value of this property is the
     7382          last known size. For <link to="MediaState_NotCreated"/> media,
    72797383          the returned value is zero.
    72807384        </note>
    … …  
    73657469
    73667470        This method sets the media state to <link
    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
     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
    73717475        media can be locked too. This is not an error; this method
    73727476        performs a logical lock that prevents modifications of this
    … …  
    74377541
    74387542        This method sets the media state to <link
    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
     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
    74427546        media can be locked too. This is not an error; this method
    74437547        performs a logical lock that prevents modifications of this
    … …  
    76097713
    76107714      There are three types of hard disks:
    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
     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
    76147718      hard disk defines how the hard disk is attached to a virtual machine and
    76157719      what happens when a <link to="ISnapshot">snapshot</link> of the virtual
    … …  
    76417745
    76427746      Note that the type of all differencing hard disks is
    7643       <link to="HardDiskType::Normal">Normal</link>; all other values are
     7747      <link to="HardDiskType_Normal">Normal</link>; all other values are
    76447748      meaningless for them. Base hard disks may be of any type.
    76457749
    … …  
    76787782      there is a possibility to cause VirtualBox to compose a unique value for
    76797783      the file name part of the location using the UUID of the hard disk. This
    7680       applies only to hard disks in <link to="MediaState::NotCreated"/> state,
     7784      applies only to hard disks in <link to="MediaState_NotCreated"/> state,
    76817785      e.g. before the storage unit is created, and works as follows. You set the
    76827786      value of the <link to="IMedium::location"/> attribute to a location
    … …  
    78998003          </li>
    79008004          <li>As long as the hard disk has children, its type cannot be set
    7901               to <link to="HardDiskType::Writethrough"/>.
     8005              to <link to="HardDiskType_Writethrough"/>.
    79028006          </li>
    79038007          <li>The type of all differencing hard disks is
    7904               <link to="HardDiskType::Normal"/> and cannot be changed.
     8008              <link to="HardDiskType_Normal"/> and cannot be changed.
    79058009          </li>
    79068010        </ul>
    79078011
    79088012        The type of a newly created or opened hard disk is set to
    7909         <link to="HardDiskType::Normal"/>.
     8013        <link to="HardDiskType_Normal"/>.
    79108014      </desc>
    79118015    </attribute>
    … …  
    79598063        disk for that. See the interface description for more information.
    79608064
    7961         Note that all <link to="HardDiskType::Immutable">Immutable</link> hard
     8065        Note that all <link to="HardDiskType_Immutable">Immutable</link> hard
    79628066        disks are always read-only while all
    7963         <link to="HardDiskType::Writethrough">Writethrough</link> hard disks are
     8067        <link to="HardDiskType_Writethrough">Writethrough</link> hard disks are
    79648068        always not.
    79658069
    … …  
    79868090        <note>
    79878091          For hard disks whose state is <link to="#state"/> is <link
    7988           to="MediaState::Inaccessible"/>, the value of this property is the
    7989           last known logical size. For <link to="MediaState::NotCreated"/> hard
     8092          to="MediaState_Inaccessible"/>, the value of this property is the
     8093          last known logical size. For <link to="MediaState_NotCreated"/> hard
    79908094          disks, the returned value is zero.
    79918095        </note>
    … …  
    81228226
    81238227        Before the operation starts, the hard disk is placed in
    8124         <link to="MediaState::Creating"/> state. If the create operation
    8125         fails, the media will be placed back in <link to="MediaState::NotCreated"/>
     8228        <link to="MediaState_Creating"/> state. If the create operation
     8229        fails, the media will be placed back in <link to="MediaState_NotCreated"/>
    81268230        state.
    81278231
    81288232        After the returned progress object reports that the operation has
    81298233        successfully completed, the media state will be set to <link
    8130         to="MediaState::Created"/>, the hard disk will be remembered by this
     8234        to="MediaState_Created"/>, the hard disk will be remembered by this
    81318235        VirtualBox installation and may be attached to virtual machines.
    81328236
    … …  
    81528256
    81538257        Before the operation starts, the hard disk is placed to
    8154         <link to="MediaState::Creating"/> state. If the create operation
    8155         fails, the media will placed back to <link to="MediaState::NotCreated"/>
     8258        <link to="MediaState_Creating"/> state. If the create operation
     8259        fails, the media will placed back to <link to="MediaState_NotCreated"/>
    81568260        state.
    81578261
    81588262        After the returned progress object reports that the operation is
    81598263        successfully complete, the media state will be set to <link
    8160         to="MediaState::Created"/>, the hard disk will be remembered by this
     8264        to="MediaState_Created"/>, the hard disk will be remembered by this
    81618265        VirtualBox installation and may be attached to virtual machines.
    81628266
    … …  
    81838287        is already in progress, or if the hard disk is being in use (locked for
    81848288        read or for write) or inaccessible. Therefore, the only valid state for
    8185         this operation to succeed is <link to="MediaState::Created"/>.
     8289        this operation to succeed is <link to="MediaState_Created"/>.
    81868290
    81878291        Before the operation starts, the hard disk is placed to
    8188         <link to="MediaState::Deleting"/> state and gets removed from the list
     8292        <link to="MediaState_Deleting"/> state and gets removed from the list
    81898293        of remembered hard disks (media registry). If the delete operation
    81908294        fails, the media will be remembered again and placed back to
    8191         <link to="MediaState::Created"/> state.
     8295        <link to="MediaState_Created"/> state.
    81928296
    81938297        After the returned progress object reports that the operation is
    81948298        complete, the media state will be set to
    8195         <link to="MediaState::NotCreated"/> and you will be able to use one of
     8299        <link to="MediaState_NotCreated"/> and you will be able to use one of
    81968300        the storage creation methods to create it again.
    81978301
    … …  
    82268330        argument.
    82278331
    8228         The target hard disk must be in <link to="MediaState::NotCreated"/>
     8332        The target hard disk must be in <link to="MediaState_NotCreated"/>
    82298333        state (i.e. must not have an existing storage unit). Upon successful
    82308334        completion, this operation will set the type of the target hard disk to
    8231         <link to="HardDiskType::Normal"/> and create a storage unit necessary to
     8335        <link to="HardDiskType_Normal"/> and create a storage unit necessary to
    82328336        represent the differencing hard disk data in the given format (according
    82338337        to the storage format of the target object).
    … …  
    82388342
    82398343        <note>
    8240           The hard disk will be set to <link to="MediaState::LockedRead"/>
     8344          The hard disk will be set to <link to="MediaState_LockedRead"/>
    82418345          state for the duration of this operation.
    82428346        </note>
    … …  
    83008404          <li>
    83018405            Neither the source hard disk nor the target hard disk is an
    8302             <link to="HardDiskType::Immutable"/> hard disk.
     8406            <link to="HardDiskType_Immutable"/> hard disk.
    83038407          </li>
    83048408          <li>
    … …  
    83138417          <li>
    83148418            None of the involved hard disks are in
    8315             <link to="MediaState::LockedRead"/> or
    8316             <link to="MediaState::LockedWrite"/> state.
     8419            <link to="MediaState_LockedRead"/> or
     8420            <link to="MediaState_LockedWrite"/> state.
    83178421          </li>
    83188422        </ul>
    … …  
    83208424        <note>
    83218425          This (source) hard disk and all intermediates will be placed to <link
    8322           to="MediaState::Deleting"/> state and the target hard disk will be
    8323           placed to <link to="MediaState::LockedWrite"/> state and for the
     8426          to="MediaState_Deleting"/> state and the target hard disk will be
     8427          placed to <link to="MediaState_LockedWrite"/> state and for the
    83248428          duration of this operation.
    83258429        </note>
    … …  
    83408444        location defined by the @a target argument.
    83418445
    8342         The target hard disk must be in <link to="MediaState::NotCreated"/>
     8446        The target hard disk must be in <link to="MediaState_NotCreated"/>
    83438447        state (i.e. must not have an existing storage unit). Upon successful
    83448448        completion, the cloned hard disk will contain exactly the same sector
    … …  
    83558459        </note>
    83568460        <note>
    8357           This hard disk will be placed to <link to="MediaState::LockedRead"/>
     8461          This hard disk will be placed to <link to="MediaState_LockedRead"/>
    83588462          state for the duration of this operation.
    83598463        </note>
    … …  
    83888492        <note>
    83898493          This hard disk and all its parent hard disks will be placed to <link
    8390           to="MediaState::LockedRead"/> state for the duration of this
     8494          to="MediaState_LockedRead"/> state for the duration of this
    83918495          operation.
    83928496        </note>
    … …  
    84768580    <const name="File" value="0x40">
    84778581      <desc>
    8478         The format backend operates on files. The <link to="IMedium::location"/>
     8582        The format backend operates on files (the <link to="IMedium::location"/>
    84798583        attribute of the hard disk specifies a file used to store hard disk
    8480         data. For a list of supported file extensions see
    8481         <link to="IHardDiskFormat::fileExtensions"/>.
     8584        data; for a list of supported file extensions see
     8585        <link to="IHardDiskFormat::fileExtensions"/>).
    84828586      </desc>
    84838587    </const>
    … …  
    84868590      <desc>
    84878591        The format backend uses the property interface to configure the storage
    8488         location and properties. The <link to="IHardDiskFormat::describeProperties"/>
     8592        location and properties (the <link to="IHardDiskFormat::describeProperties"/>
    84898593        method is used to get access to properties supported by the given hard
    8490         disk format.
     8594        disk format).
    84918595      </desc>
    84928596    </const>
    … …  
    85708674
    85718675        The returned arrays are not empty only if the
    8572         <link to="HardDiskFormatCapabilities::Properties"/> flag is set.
     8676        <link to="HardDiskFormatCapabilities_Properties"/> flag is set.
    85738677
    85748678        <see>DataType</see>
    … …  
    89479051    <const name="Opaque"                  value="0xFFFFFFFF">
    89489052      <desc>
    8949         Unknown buffer format. The user may not assume any particular
    8950         format of the buffer.
     9053        Unknown buffer format (the user may not assume any particular format of
     9054        the buffer).
    89519055      </desc>
    89529056    </const>
    89539057    <const name="FOURCC_RGB"              value="0x32424752">
    89549058      <desc>
    8955         Basic RGB format. <link to="IFramebuffer::bitsPerPixel"/> determines
    8956         the bit layout.
     9059        Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
     9060        bit layout).
    89579061      </desc>
    89589062    </const>
    … …  
    89799083      <desc>
    89809084        Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
    8981         to="FramebufferPixelFormat::FOURCC_RGB">FOURCC_RGB</link>, valid values
     9085        to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
    89829086        are: 8, 15, 16, 24 and 32.
    89839087      </desc>
    … …  
    89879091      <desc>
    89889092        Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
    8989         to="FramebufferPixelFormat::FOURCC_RGB">FOURCC_RGB</link>, the
     9093        to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
    89909094        size of the scan line must be aligned to 32 bits.
    89919095      </desc>
    … …  
    89989102        <note>
    89999103          This attribute must never return <link
    9000           to="PixelFormat::Opaque"/> -- the format of the buffer
     9104          to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
    90019105          <link to="#address"/> points to must be always known.
    90029106        </note>
    … …  
    91059209        The @a pixelFormat parameter defines whether the direct mode is
    91069210        available or not. If @a pixelFormat is <link
    9107         to="PixelFormat::Opaque"/> then direct access to the guest
     9211        to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
    91089212        VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and @a
    91099213        bytesPerLine parameters must be ignored and the implementation must use
    … …  
    91469250        value must always correlate with <link to="#pixelFormat"/>. Note that
    91479251        the <link to="#pixelFormat"/> attribute must never return <link
    9148         to="PixelFormat::Opaque"/> regardless of the selected mode.
     9252        to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
    91499253
    91509254        <note>
    … …  
    95259629
    95269630    <const name="Null"                  value="0">
    9527       <desc><tt>null</tt> value. Also means "not attached".</desc>
     9631      <desc>Null value, also means "not attached".</desc>
    95289632    </const>
    95299633    <const name="NAT"                   value="1"/>
    … …  
    95419645
    95429646    <const name="Null"                  value="0">
    9543       <desc><tt>null</tt> value. Never used by the API.</desc>
     9647      <desc>Null value (never used by the API).</desc>
    95449648    </const>
    95459649    <const name="Am79C970A"             value="1"/>
    … …  
    97849888        Flag whether this serial port acts as a server (creates a new pipe on
    97859889        the host) or as a client (uses the existing pipe). This attribute is
    9786         used only when <link to="#hostMode"/> is PortMode::HostPipe.
     9890        used only when <link to="#hostMode"/> is PortMode_HostPipe.
    97879891      </desc>
    97889892    </attribute>
    … …  
    97919895      <desc>
    97929896        Path to the serial port's pipe on the host when <link to="#hostMode"/> is
    9793         PortMode::HostPipe, or the host serial device name when
    9794         <link to="#hostMode"/> is PortMode::HostDevice. In either of the above
     9897        PortMode_HostPipe, or the host serial device name when
     9898        <link to="#hostMode"/> is PortMode_HostDevice. In either of the above
    97959899        cases, setting a @c  null or an empty string as the attribute's value
    97969900        will result into an error. Otherwise, the value of this property is
    … …  
    1002810132        They are run against a list of all currently available USB
    1002910133        devices (in states
    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
     10134        <link to="USBDeviceState_Available"/>,
     10135        <link to="USBDeviceState_Busy"/>,
     10136        <link to="USBDeviceState_Held"/>) that were not previously
    1003310137        ignored by global filters.
    1003410138
    … …  
    1044910553      Once a supported USB device is attached to the host, global USB
    1045010554      filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
    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.
     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.
    1045510559
    1045610560      If the device was ignored by global filters, or didn't match
    1045710561      any filters at all (including guest ones), it is handled by the host
    1045810562      in a normal way. In this case, the device state is determined by
    10459       the host and can be one of #Unavailable, #Busy or #Available, depending on
    10460       the current device usage.
     10563      the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
     10564      or USBDeviceState_Available, depending on the current device usage.
    1046110565
    1046210566      Besides auto-capturing based on filters, the device can be manually
    1046310567      captured by guests (<link to="IConsole::attachUSBDevice()"/>) if its
    10464       state is #Busy, #Available or #Held.
     10568      state is USBDeviceState_Busy, USBDeviceState_Available or
     10569      USBDeviceState_Held.
    1046510570
    1046610571      <note>
    1046710572        Due to differences in USB stack implementations in Linux and Win32,
    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.
     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.
    1047210577      </note>
    1047310578
    … …  
    1049310598    <const name="Available"             value="3">
    1049410599      <desc>
    10495         Not used by the host computer, available to guests.
    10496         The host computer can also start using the device at any time.
     10600        Not used by the host computer, available to guests (the host computer
     10601        can also start using the device at any time).
    1049710602      </desc>
    1049810603    </const>
    … …  
    1060410709
    1060510710    <const name="Null"          value="0">
    10606       <desc><tt>null</tt> value. Never used by the API.</desc>
     10711      <desc>Null value (never used by the API).</desc>
    1060710712    </const>
    1060810713    <const name="Ignore"        value="1">
    … …  
    1067210777
    1067310778    <const name="Null"          value="0">
    10674       <desc><tt>null</tt> value. Also means "dummy audio driver".</desc>
     10779      <desc>Null value, also means "dummy audio driver".</desc>
    1067510780    </const>
    1067610781    <const name="WinMM"         value="1"/>
    … …  
    1074010845
    1074110846    <const name="Null"            value="0">
    10742       <desc><tt>null</tt> value. Also means "no authentication".</desc>
     10847      <desc>Null value, also means "no authentication".</desc>
    1074310848    </const>
    1074410849    <const name="External"        value="1"/>
    … …  
    1121511320      <desc>
    1121611321        Type of this session. The value of this attribute is valid only
    11217         if the session is currently open (i.e. its #state is SessionType::SessionOpen),
    11218         otherwise an error will be returned.
     11322        if the session is currently open (i.e. its #state is
     11323        SessionType_SessionOpen), otherwise an error will be returned.
    1121911324      </desc>
    1122011325    </attribute>
    … …  
    1124411349        <link to="IVirtualBox::openSession()"/> is not explicitly closed
    1124511350        when the application terminates, the state of the machine will
    11246         be set to <link to="MachineState::Aborted" /> on the server.
     11351        be set to <link to="MachineState_Aborted" /> on the server.
    1124711352
    1124811353        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