VirtualBox

Changeset 3297 in vbox


Ignore:
Timestamp:
Jun 26, 2007 2:41:31 PM (18 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
22400
Message:

Main: Changed indent from 4 to 2 chars.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r3191 r3297  
    22
    33<!--
     4 * :tabSize=2:indentSize=2:noTabs=true:
     5 * :folding=explicit:collapseFolds=1:
     6 *
    47 * Master declaration for VirtualBox's Main API, represented
    58 * by COM/XPCOM and web service interfaces.
    … …  
    4144
    4245<if target="midl">
    43     <cpp line="enum {"/>
    44     <cpp line="    kTypeLibraryMajorVersion = 1,"/>
    45     <cpp line="    kTypeLibraryMinorVersion = 0"/>
    46     <cpp line="};"/>
     46  <cpp line="enum {"/>
     47  <cpp line="    kTypeLibraryMajorVersion = 1,"/>
     48  <cpp line="    kTypeLibraryMinorVersion = 0"/>
     49  <cpp line="};"/>
    4750</if>
    4851
    4952<if target="xpidl">
    50     <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
    51     <cpp>
     53  <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
     54  <cpp>
    5255// currenty, nsISupportsImpl.h lacks the below-like macros
    5356#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
    … …  
    6568  NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
    6669#endif
    67     </cpp>
     70  </cpp>
    6871</if>
    6972
    7073<module
    71     name="VirtualBox"
    72     uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
    73     version="1.3"
    74     desc="innotek VirtualBox Type Library"
    75     supportsErrorInfo="yes"
     74   name="VirtualBox"
     75   uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
     76   version="1.3"
     77   desc="innotek VirtualBox Type Library"
     78   supportsErrorInfo="yes"
    7679>
    7780
    78     <!--
    79     // all common enums
    80     /////////////////////////////////////////////////////////////////////////
    81     -->
    82 
    83     <enum
    84         name="TriStateBool"
    85         uuid="523ff64d-842a-4b1a-80e7-c311b028cb3a"
    86     >
     81  <!--
     82  // all common enums
     83  /////////////////////////////////////////////////////////////////////////
     84  -->
     85
     86  <enum
     87     name="TriStateBool"
     88     uuid="523ff64d-842a-4b1a-80e7-c311b028cb3a"
     89     >
     90    <desc>
     91      This represents a boolean variable having a third state, default.
     92    </desc>
     93
     94    <const name="False"   value="0"/>
     95    <const name="True"    value="1"/>
     96    <const name="Default" value="2"/>
     97  </enum>
     98
     99  <enum
     100     name="MachineState"
     101     uuid="b8bb15f7-4fa2-4e84-87a8-b4677dd87deb"
     102     >
     103    <desc>
     104      Virtual machine execution state. This enumeration represents possible
     105      values of the <link to="IMachine::state"/> attribute.
     106    </desc>
     107
     108    <const name="InvalidMachineState"   value="0"/>
     109    <const name="PoweredOff"            value="1">
     110      <desc>
     111        The machine is not running.
     112      </desc>
     113    </const>
     114    <const name="Saved"                 value="2">
     115      <desc>
     116        The machine is not currently running, but the execution state
     117        of the machine has been saved to an external file when it
     118        was running.
     119        <note>
     120          No any machine settings can be altered when the machine
     121          is in this state.
     122        </note>
     123      </desc>
     124    </const>
     125    <const name="Aborted"               value="3">
     126      <desc>
     127        A process that run the machine has abnormally terminated.
     128        Other than that, this value is equivalent to #PoweredOff.
     129      </desc>
     130    </const>
     131    <const name="Running"               value="4">
     132      <desc>
     133        The machine is currently being executed.
     134        <note>
     135          This value can be used in comparison expressions:
     136          all state values below it describe a virtual machine that is
     137          not currently being executed (i.e., it is completely out of
     138          action).
     139        </note>
     140      </desc>
     141    </const>
     142    <const name="Paused"                value="5">
     143      <desc>
     144        The execution of the machine has been paused.
     145        <note>
     146          This value can be used in comparison expressions:
     147          all state values above it represent unstable states of the
     148          virtual machine. No any settings can be altered when the
     149          VM is in one of the unstable sates.
     150        </note>
     151      </desc>
     152    </const>
     153    <const name="Starting"              value="6">
     154      <desc>
     155        The machine is being started after
     156        <link to="IConsole::powerUp">powering it on</link> from a
     157        zero execution state.
     158      </desc>
     159    </const>
     160    <const name="Stopping"              value="7">
     161      <desc>
     162        The machine is being normally stopped
     163        (after explicitly <link to="IConsole::powerDown">powering it off</link>,
     164        or after the guest OS has initiated a shutdown sequence).
     165      </desc>
     166    </const>
     167    <const name="Saving"                value="8">
     168      <desc>
     169        The machine is saving its execution state to a file as a
     170        result of calling <link to="IConsole::saveState"/> or an online
     171        snapshot of the machine is being taken using
     172        <link to="IConsole::takeSnapshot"/>.
     173      </desc>
     174    </const>
     175    <const name="Restoring"             value="9">
     176      <desc>
     177        The execution state of the machine is being restored from a file
     178        after <link to="IConsole::powerUp">powering it on</link> from
     179        a saved execution state.
     180      </desc>
     181    </const>
     182    <const name="Discarding"            value="10">
     183      <desc>
     184        A snapshot of the machine is being discarded after calling
     185        <link to="IConsole::discardSnapshot"/> or its current state is
     186        being discarded after <link to="IConsole::discardCurrentState"/>.
     187      </desc>
     188    </const>
     189  </enum>
     190
     191  <enum
     192     name="SessionState"
     193     uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
     194     >
     195    <desc>
     196      Session state. This enumeration represents possible values of
     197      <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
     198      attributes. Idividual value descriptions contain the appropriate
     199      meaning for every case.
     200    </desc>
     201
     202    <const name="InvalidSessionState"   value="0"/>
     203    <const name="SessionClosed"         value="1">
     204      <desc>
     205        The machine has no open sessions (<link to="IMachine::sessionState"/>);
     206        the session is closed (<link to="ISession::state"/>)
     207      </desc>
     208    </const>
     209    <const name="SessionOpen"           value="2">
     210      <desc>
     211        The machine has an open direct session (<link to="IMachine::sessionState"/>);
     212        the session is open (<link to="ISession::state"/>)
     213      </desc>
     214    </const>
     215    <const name="SessionSpawning"       value="3">
     216      <desc>
     217        A new (direct) session is being opened for the machine
     218        as a result of <link to="IVirtualBox::openRemoteSession()"/>
     219        call (<link to="IMachine::sessionState"/>);
     220        the session is currently being opened
     221        as a result of <link to="IVirtualBox::openRemoteSession()"/>
     222        call (<link to="ISession::state"/>)
     223      </desc>
     224    </const>
     225    <const name="SessionClosing"       value="4">
     226      <desc>
     227        The direct session is being closed (<link to="IMachine::sessionState"/>);
     228        the session is being closed (<link to="ISession::state"/>)
     229      </desc>
     230    </const>
     231  </enum>
     232
     233  <enum
     234     name="SessionType"
     235     uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
     236     >
     237    <desc>
     238      Session type. This enumeration represents possible values of the
     239      <link to="ISession::type"/> attribute.
     240    </desc>
     241
     242    <const name="InvalidSessionType"    value="0"/>
     243    <const name="DirectSession"         value="1">
     244      <desc>
     245        Direct session
     246        (opened by <link to="IVirtualBox::openSession()"/>)
     247      </desc>
     248    </const>
     249    <const name="RemoteSession"         value="2">
     250      <desc>
     251        Remote session
     252        (opened by <link to="IVirtualBox::openRemoteSession()"/>)
     253      </desc>
     254    </const>
     255    <const name="ExistingSession"       value="3">
     256      <desc>
     257        Existing session
     258        (opened by <link to="IVirtualBox::openExistingSession()"/>)
     259      </desc>
     260    </const>
     261  </enum>
     262
     263  <enum
     264     name="DeviceType"
     265     uuid="8B7F8ADE-E8F7-42a4-9661-9F5092C4DB4C"
     266     >
     267    <desc>
     268      Device type.
     269    </desc>
     270    <const name="NoDevice"          value="0">
     271      <desc>
     272        No Device. This value is not used by
     273        <link to="IConsole::getDeviceActivity"/>
     274      </desc>
     275    </const>
     276    <const name="FloppyDevice"      value="1">
     277      <desc>Floppy device.</desc>
     278    </const>
     279    <const name="DVDDevice"         value="2">
     280      <desc>CD/DVD-ROM device.</desc>
     281    </const>
     282    <const name="HardDiskDevice"    value="3">
     283      <desc>Hard disk device.</desc>
     284    </const>
     285    <const name="NetworkDevice"     value="4">
     286      <desc>Network device.</desc>
     287    </const>
     288    <const name="USBDevice"         value="5">
     289      <desc>USB device.</desc>
     290    </const>
     291  </enum>
     292
     293  <enum
     294     name="DeviceActivity"
     295     uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
     296     >
     297    <const name="InvalidActivity"   value="0"/>
     298    <const name="DeviceIdle"        value="1"/>
     299    <const name="DeviceReading"     value="2"/>
     300    <const name="DeviceWriting"     value="3"/>
     301  </enum>
     302
     303  <enum
     304     name="ResourceUsage"
     305     uuid="FC56E4B6-B195-48e2-A5E1-A667B0D9F809"
     306     >
     307    <desc>
     308      Usage type constants for
     309      <link to="IVirtualBox::getDVDImageUsage"/> and
     310      <link to="IVirtualBox::getFloppyImageUsage"/>.
     311    </desc>
     312    <const name="InvalidUsage"      value="0"/>
     313    <const name="PermanentUsage"    value="1">
     314      <desc>
     315        Scopes the VMs that use the resource permanently
     316        (the information about this usage is stored in the VM
     317        settings file).
     318      </desc>
     319    </const>
     320    <const name="TemporaryUsage"    value="2">
     321      <desc>
     322        Scopes the VMs that are temporarily using the resource
     323        (the information about the usage is not yet saved in the VM
     324        settings file). Temporary usage can take place only in the
     325        context of an open session.
     326      </desc>
     327    </const>
     328    <const name="AllUsage"          value="3">
     329      <desc>
     330        Combines PermanentUsage and TemporaryUsage.
     331      </desc>
     332    </const>
     333  </enum>
     334
     335  <enum
     336     name="DiskControllerType"
     337     uuid="1115b810-2ee7-4ebd-8b39-92e98c9a2b48"
     338     >
     339    <const name="InvalidController"  value="0"/>
     340    <const name="IDE0Controller"     value="1"/>
     341    <const name="IDE1Controller"     value="2"/>
     342  </enum>
     343
     344  <enum
     345     name="ClipboardMode"
     346     uuid="33364716-4008-4701-8f14-be0fa3d62950"
     347     >
     348    <const name="ClipDisabled"         value="0"/>
     349    <const name="ClipHostToGuest"      value="1"/>
     350    <const name="ClipGuestToHost"      value="2"/>
     351    <const name="ClipBidirectional"    value="3"/>
     352  </enum>
     353
     354  <!--
     355  // IVirtualBoxErrorInfo
     356  /////////////////////////////////////////////////////////////////////////
     357  -->
     358
     359  <interface
     360     name="IVirtualBoxErrorInfo" extends="$errorinfo"
     361     uuid="e98b5376-8eb4-4eea-812a-3964bf3bb26f"
     362     supportsErrorInfo="no"
     363     wsmap="suppress"
     364     >
     365    <desc>
     366      The IVirtualBoxErrorInfo interface represents extended error information
     367      that can be set by components after unsuccessful method invocation and
     368      returned to the client in addition to the result code.
     369
     370      In MS COM, this interface extends the IErrorInfo interface,
     371      in XPCOM, it extends the nsIException interface. In both cases,
     372      it provides a set of common attributes to retrieve error
     373      information.
     374
     375      Sometimes invocation of some component's method may involve
     376      methods of other components that may also fail (independently of
     377      this method's failure), or a series of non-fatal errors may
     378      precede a fatal error that causes method failure. In cases like
     379      that, it may be desirable to preserve information about all errors
     380      happened during method invocation and deliver it to the
     381      caller. The <link to="#next"/> attribute is intended specifically
     382      for this purpose and allows to represent a chain of errors through
     383      a single IVirtualBoxErrorInfo instance set after method
     384      invocation. Note that errors are stored to a chain in the reverse
     385      order, i.e. the initial error object you query right after method
     386      invocation is the last error set by the callee, the object it
     387      points to in the @a next attribute is the previous error and so
     388      on, up to the first error (which is the last in the chain).
     389    </desc>
     390
     391    <attribute name="resultCode" type="result" readonly="yes">
     392      <desc>
     393        Result code of the error.
     394        Usually, it will be the same as the result code returned
     395        by the method that provided this error information, but not
     396        always. For example, on Win32, CoCreateInstance() will most
     397        likely return E_NOINTERFACE upon unsuccessful component
     398        instantiation attempt, but not the value the component factory
     399        returned.
     400        <note>
     401          In MS COM, there is no equivalent.
     402          In XPCOM, it is the same as nsIException::result.
     403        </note>
     404      </desc>
     405    </attribute>
     406
     407    <attribute name="interfaceID" type="uuid" readonly="yes">
     408      <desc>
     409        UUID of the interface that defined the error.
     410        <note>
     411          In MS COM, it is the same as IErrorInfo::GetGUID.
     412          In XPCOM, there is no equivalent.
     413        </note>
     414      </desc>
     415    </attribute>
     416
     417    <attribute name="component" type="wstring" readonly="yes">
     418      <desc>
     419        Name of the component that generated the error.
     420        <note>
     421          In MS COM, it is the same as IErrorInfo::GetSource.
     422          In XPCOM, there is no equivalent.
     423        </note>
     424      </desc>
     425    </attribute>
     426
     427    <attribute name="text" type="wstring" readonly="yes">
     428      <desc>
     429        Text description of the error.
     430        <note>
     431          In MS COM, it is the same as IErrorInfo::GetDescription.
     432          In XPCOM, it is the same as nsIException::message.
     433        </note>
     434      </desc>
     435    </attribute>
     436
     437    <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
     438      <desc>
     439        Next error object if there is any, or @c null otherwise.
     440        <note>
     441          In MS COM, there is no equivalent.
     442          In XPCOM, it is the same as nsIException::inner.
     443        </note>
     444      </desc>
     445    </attribute>
     446
     447  </interface>
     448
     449
     450  <!--
     451  // IVirtualBox
     452  /////////////////////////////////////////////////////////////////////////
     453  -->
     454
     455  <interface
     456     name="IVirtualBoxCallback" extends="$unknown"
     457     uuid="ee95ffc2-b6c6-4ce8-9e9e-ceadbb5019fe"
     458     wsmap="suppress"
     459     >
     460    <method name="onMachineStateChange">
     461      <desc>
     462        The execution state of the given machine has changed.
     463        <see>IMachine::state</see>
     464      </desc>
     465      <param name="machineId" type="uuid" dir="in">
     466        <desc>ID of the machine this event relates to.</desc>
     467      </param>
     468      <param name="state" type="MachineState" dir="in">
     469        <desc>New execution state.</desc>
     470      </param>
     471    </method>
     472
     473    <method name="onMachineDataChange">
     474      <desc>
     475        Any of the settings of the given machine has changed.
     476      </desc>
     477      <param name="machineId" type="uuid" dir="in">
     478        <desc>ID of the machine this event relates to.</desc>
     479      </param>
     480    </method>
     481
     482    <method name="onExtraDataCanChange">
     483      <desc>
     484        Notification when someone tries to change extra data for
     485        either the given machine or (if null) global extra data.
     486        This gives the chance to veto against changes.
     487      </desc>
     488      <param name="machineId" type="uuid" dir="in">
    87489        <desc>
    88             This represents a boolean variable having a third state, default.
     490          ID of the machine this event relates to
     491          (null ID for global extra data change requests).
    89492        </desc>
    90 
    91         <const name="False"   value="0"/>
    92         <const name="True"    value="1"/>
    93         <const name="Default" value="2"/>
    94     </enum>
    95 
    96     <enum
    97         name="MachineState"
    98         uuid="b8bb15f7-4fa2-4e84-87a8-b4677dd87deb"
    99     >
     493      </param>
     494      <param name="key" type="wstring" dir="in">
    100495        <desc>
    101             Virtual machine execution state. This enumeration represents possible
    102             values of the <link to="IMachine::state"/> attribute.
     496          Extra data key for the attempted write.
    103497        </desc>
    104 
    105         <const name="InvalidMachineState"   value="0"/>
    106         <const name="PoweredOff"            value="1">
    107             <desc>
    108                 The machine is not running.
    109             </desc>
    110         </const>
    111         <const name="Saved"                 value="2">
    112             <desc>
    113                 The machine is not currently running, but the execution state
    114                 of the machine has been saved to an external file when it
    115                 was running.
    116                 <note>
    117                     No any machine settings can be altered when the machine
    118                     is in this state.
    119                 </note>
    120             </desc>
    121         </const>
    122         <const name="Aborted"               value="3">
    123             <desc>
    124                 A process that run the machine has abnormally terminated.
    125                 Other than that, this value is equivalent to #PoweredOff.
    126             </desc>
    127         </const>
    128         <const name="Running"               value="4">
    129             <desc>
    130                 The machine is currently being executed.
    131                 <note>
    132                     This value can be used in comparison expressions:
    133                     all state values below it describe a virtual machine that is
    134                     not currently being executed (i.e., it is completely out of
    135                     action).
    136                 </note>
    137             </desc>
    138         </const>
    139         <const name="Paused"                value="5">
    140             <desc>
    141                 The execution of the machine has been paused.
    142                 <note>
    143                     This value can be used in comparison expressions:
    144                     all state values above it represent unstable states of the
    145                     virtual machine. No any settings can be altered when the
    146                     VM is in one of the unstable sates.
    147                 </note>
    148             </desc>
    149         </const>
    150         <const name="Starting"              value="6">
    151             <desc>
    152                 The machine is being started after
    153                 <link to="IConsole::powerUp">powering it on</link> from a
    154                 zero execution state.
    155             </desc>
    156         </const>
    157         <const name="Stopping"              value="7">
    158             <desc>
    159                 The machine is being normally stopped
    160                 (after explicitly <link to="IConsole::powerDown">powering it off</link>,
    161                 or after the guest OS has initiated a shutdown sequence).
    162             </desc>
    163         </const>
    164         <const name="Saving"                value="8">
    165             <desc>
    166                 The machine is saving its execution state to a file as a
    167                 result of calling <link to="IConsole::saveState"/> or an online
    168                 snapshot of the machine is being taken using
    169                 <link to="IConsole::takeSnapshot"/>.
    170             </desc>
    171         </const>
    172         <const name="Restoring"             value="9">
    173             <desc>
    174                 The execution state of the machine is being restored from a file
    175                 after <link to="IConsole::powerUp">powering it on</link> from
    176                 a saved execution state.
    177             </desc>
    178         </const>
    179         <const name="Discarding"            value="10">
    180             <desc>
    181                 A snapshot of the machine is being discarded after calling
    182                 <link to="IConsole::discardSnapshot"/> or its current state is
    183                 being discarded after <link to="IConsole::discardCurrentState"/>.
    184             </desc>
    185         </const>
    186     </enum>
    187 
    188     <enum
    189         name="SessionState"
    190         uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
    191     >
     498      </param>
     499      <param name="value" type="wstring" dir="in">
    192500        <desc>
    193             Session state. This enumeration represents possible values of
    194             <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
    195             attributes. Idividual value descriptions contain the appropriate
    196             meaning for every case.
     501          Extra data value for the given key.
    197502        </desc>
    198 
    199         <const name="InvalidSessionState"   value="0"/>
    200         <const name="SessionClosed"         value="1">
    201             <desc>
    202                 The machine has no open sessions (<link to="IMachine::sessionState"/>);
    203                 the session is closed (<link to="ISession::state"/>)
    204             </desc>
    205         </const>
    206         <const name="SessionOpen"           value="2">
    207             <desc>
    208                 The machine has an open direct session (<link to="IMachine::sessionState"/>);
    209                 the session is open (<link to="ISession::state"/>)
    210             </desc>
    211         </const>
    212         <const name="SessionSpawning"       value="3">
    213             <desc>
    214                 A new (direct) session is being opened for the machine
    215                 as a result of <link to="IVirtualBox::openRemoteSession()"/>
    216                 call (<link to="IMachine::sessionState"/>);
    217                 the session is currently being opened
    218                 as a result of <link to="IVirtualBox::openRemoteSession()"/>
    219                 call (<link to="ISession::state"/>)
    220             </desc>
    221         </const>
    222         <const name="SessionClosing"       value="4">
    223             <desc>
    224                 The direct session is being closed (<link to="IMachine::sessionState"/>);
    225                 the session is being closed (<link to="ISession::state"/>)
    226             </desc>
    227         </const>
    228     </enum>
    229 
    230     <enum
    231         name="SessionType"
    232         uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
    233     >
     503      </param>
     504      <param name="error" type="wstring" dir="out">
    234505        <desc>
    235             Session type. This enumeration represents possible values of the
    236             <link to="ISession::type"/> attribute.
     506          Optional error message describing the reason of the
     507          veto (ignored if this notification returns @c true).
    237508        </desc>
    238 
    239         <const name="InvalidSessionType"    value="0"/>
    240         <const name="DirectSession"         value="1">
    241             <desc>
    242                 Direct session
    243                 (opened by <link to="IVirtualBox::openSession()"/>)
    244             </desc>
    245         </const>
    246         <const name="RemoteSession"         value="2">
    247             <desc>
    248                 Remote session
    249                 (opened by <link to="IVirtualBox::openRemoteSession()"/>)
    250             </desc>
    251         </const>
    252         <const name="ExistingSession"       value="3">
    253             <desc>
    254                 Existing session
    255                 (opened by <link to="IVirtualBox::openExistingSession()"/>)
    256             </desc>
    257         </const>
    258     </enum>
    259 
    260     <enum
    261         name="DeviceType"
    262         uuid="8B7F8ADE-E8F7-42a4-9661-9F5092C4DB4C"
    263     >
     509      </param>
     510      <param name="allowChange" type="boolean" dir="return">
    264511        <desc>
    265             Device type.
     512          Flag to indicate whether the callee agrees (@ true)
     513          or vetoes against the change (@ false).
    266514        </desc>
    267         <const name="NoDevice"          value="0">
    268             <desc>
    269                 No Device. This value is not used by
    270                 <link to="IConsole::getDeviceActivity"/>
    271             </desc>
    272         </const>
    273         <const name="FloppyDevice"      value="1">
    274             <desc>Floppy device.</desc>
    275         </const>
    276         <const name="DVDDevice"         value="2">
    277             <desc>CD/DVD-ROM device.</desc>
    278         </const>
    279         <const name="HardDiskDevice"    value="3">
    280             <desc>Hard disk device.</desc>
    281         </const>
    282         <const name="NetworkDevice"     value="4">
    283             <desc>Network device.</desc>
    284         </const>
    285         <const name="USBDevice"         value="5">
    286             <desc>USB device.</desc>
    287         </const>
    288     </enum>
    289 
    290     <enum
    291         name="DeviceActivity"
    292         uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
    293     >
    294         <const name="InvalidActivity"   value="0"/>
    295         <const name="DeviceIdle"        value="1"/>
    296         <const name="DeviceReading"     value="2"/>
    297         <const name="DeviceWriting"     value="3"/>
    298     </enum>
    299 
    300     <enum
    301         name="ResourceUsage"
    302         uuid="FC56E4B6-B195-48e2-A5E1-A667B0D9F809"
    303     >
     515      </param>
     516    </method>
     517
     518    <method name="onExtraDataChange">
     519      <desc>
     520        Notification when machine specific or global extra data
     521        has changed.
     522      </desc>
     523      <param name="machineId" type="uuid" dir="in">
    304524        <desc>
    305             Usage type constants for
    306             <link to="IVirtualBox::getDVDImageUsage"/> and
    307             <link to="IVirtualBox::getFloppyImageUsage"/>.
     525          ID of the machine this event relates to.
     526          Null for global extra data changes.
    308527        </desc>
    309         <const name="InvalidUsage"      value="0"/>
    310         <const name="PermanentUsage"    value="1">
    311             <desc>
    312                 Scopes the VMs that use the resource permanently
    313                 (the information about this usage is stored in the VM
    314                 settings file).
    315             </desc>
    316         </const>
    317         <const name="TemporaryUsage"    value="2">
    318             <desc>
    319                 Scopes the VMs that are temporarily using the resource
    320                 (the information about the usage is not yet saved in the VM
    321                 settings file). Temporary usage can take place only in the
    322                 context of an open session.
    323             </desc>
    324         </const>
    325         <const name="AllUsage"          value="3">
    326             <desc>
    327                 Combines PermanentUsage and TemporaryUsage.
    328             </desc>
    329         </const>
    330     </enum>
    331 
    332     <enum
    333         name="DiskControllerType"
    334         uuid="1115b810-2ee7-4ebd-8b39-92e98c9a2b48"
    335     >
    336         <const name="InvalidController"  value="0"/>
    337         <const name="IDE0Controller"     value="1"/>
    338         <const name="IDE1Controller"     value="2"/>
    339     </enum>
    340 
    341     <enum
    342         name="ClipboardMode"
    343         uuid="33364716-4008-4701-8f14-be0fa3d62950"
    344     >
    345         <const name="ClipDisabled"         value="0"/>
    346         <const name="ClipHostToGuest"      value="1"/>
    347         <const name="ClipGuestToHost"      value="2"/>
    348         <const name="ClipBidirectional"    value="3"/>
    349     </enum>
    350 
    351     <!--
    352     // IVirtualBoxErrorInfo
    353     /////////////////////////////////////////////////////////////////////////
    354     -->
    355 
    356     <interface
    357         name="IVirtualBoxErrorInfo" extends="$errorinfo"
    358         uuid="e98b5376-8eb4-4eea-812a-3964bf3bb26f"
    359         supportsErrorInfo="no"
    360         wsmap="suppress"
    361     >
     528      </param>
     529      <param name="key" type="wstring" dir="in">
    362530        <desc>
    363             The IVirtualBoxErrorInfo interface represents extended error information
    364             that can be set by components after unsuccessful method invocation and
    365             returned to the client in addition to the result code.
    366 
    367             In MS COM, this interface extends the IErrorInfo interface,
    368             in XPCOM, it extends the nsIException interface. In both cases,
    369             it provides a set of common attributes to retrieve error
    370             information.
    371 
    372             Sometimes invocation of some component's method may involve
    373             methods of other components that may also fail (independently of
    374             this method's failure), or a series of non-fatal errors may
    375             precede a fatal error that causes method failure. In cases like
    376             that, it may be desirable to preserve information about all errors
    377             happened during method invocation and deliver it to the
    378             caller. The <link to="#next"/> attribute is intended specifically
    379             for this purpose and allows to represent a chain of errors through
    380             a single IVirtualBoxErrorInfo instance set after method
    381             invocation. Note that errors are stored to a chain in the reverse
    382             order, i.e. the initial error object you query right after method
    383             invocation is the last error set by the callee, the object it
    384             points to in the @a next attribute is the previous error and so
    385             on, up to the first error (which is the last in the chain).
     531          Extra data key that has changed.
    386532        </desc>
    387 
    388         <attribute name="resultCode" type="result" readonly="yes">
    389             <desc>
    390                 Result code of the error.
    391                 Usually, it will be the same as the result code returned
    392                 by the method that provided this error information, but not
    393                 always. For example, on Win32, CoCreateInstance() will most
    394                 likely return E_NOINTERFACE upon unsuccessful component
    395                 instantiation attempt, but not the value the component factory
    396                 returned.
    397                 <note>
    398                     In MS COM, there is no equivalent.
    399                     In XPCOM, it is the same as nsIException::result.
    400                 </note>
    401             </desc>
    402         </attribute>
    403 
    404         <attribute name="interfaceID" type="uuid" readonly="yes">
    405             <desc>
    406                 UUID of the interface that defined the error.
    407                 <note>
    408                     In MS COM, it is the same as IErrorInfo::GetGUID.
    409                     In XPCOM, there is no equivalent.
    410                 </note>
    411             </desc>
    412         </attribute>
    413 
    414         <attribute name="component" type="wstring" readonly="yes">
    415             <desc>
    416                 Name of the component that generated the error.
    417                 <note>
    418                     In MS COM, it is the same as IErrorInfo::GetSource.
    419                     In XPCOM, there is no equivalent.
    420                 </note>
    421             </desc>
    422         </attribute>
    423 
    424         <attribute name="text" type="wstring" readonly="yes">
    425             <desc>
    426                 Text description of the error.
    427                 <note>
    428                     In MS COM, it is the same as IErrorInfo::GetDescription.
    429                     In XPCOM, it is the same as nsIException::message.
    430                 </note>
    431             </desc>
    432         </attribute>
    433 
    434         <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
    435             <desc>
    436                 Next error object if there is any, or @c null otherwise.
    437                 <note>
    438                     In MS COM, there is no equivalent.
    439                     In XPCOM, it is the same as nsIException::inner.
    440                 </note>
    441             </desc>
    442         </attribute>
    443 
    444     </interface>
    445 
    446 
    447     <!--
    448     // IVirtualBox
    449     /////////////////////////////////////////////////////////////////////////
    450     -->
    451 
    452     <interface
    453         name="IVirtualBoxCallback" extends="$unknown"
    454         uuid="ee95ffc2-b6c6-4ce8-9e9e-ceadbb5019fe"
    455         wsmap="suppress"
    456     >
    457         <method name="onMachineStateChange">
    458             <desc>
    459                 The execution state of the given machine has changed.
    460                 <see>IMachine::state</see>
    461             </desc>
    462             <param name="machineId" type="uuid" dir="in">
    463                 <desc>ID of the machine this event relates to.</desc>
    464             </param>
    465             <param name="state" type="MachineState" dir="in">
    466                 <desc>New execution state.</desc>
    467             </param>
    468         </method>
    469 
    470         <method name="onMachineDataChange">
    471             <desc>
    472                 Any of the settings of the given machine has changed.
    473             </desc>
    474             <param name="machineId" type="uuid" dir="in">
    475                 <desc>ID of the machine this event relates to.</desc>
    476             </param>
    477         </method>
    478 
    479         <method name="onExtraDataCanChange">
    480             <desc>
    481                 Notification when someone tries to change extra data for
    482                 either the given machine or (if null) global extra data.
    483                 This gives the chance to veto against changes.
    484             </desc>
    485             <param name="machineId" type="uuid" dir="in">
    486                 <desc>
    487                     ID of the machine this event relates to
    488                     (null ID for global extra data change requests).
    489                 </desc>
    490             </param>
    491             <param name="key" type="wstring" dir="in">
    492                 <desc>
    493                     Extra data key for the attempted write.
    494                 </desc>
    495             </param>
    496             <param name="value" type="wstring" dir="in">
    497                 <desc>
    498                     Extra data value for the given key.
    499                 </desc>
    500             </param>
    501             <param name="error" type="wstring" dir="out">
    502                 <desc>
    503                     Optional error message describing the reason of the
    504                     veto (ignored if this notification returns @c true).
    505                 </desc>
    506             </param>
    507             <param name="allowChange" type="boolean" dir="return">
    508                 <desc>
    509                     Flag to indicate whether the callee agrees (@ true)
    510                     or vetoes against the change (@ false).
    511                 </desc>
    512             </param>
    513         </method>
    514 
    515         <method name="onExtraDataChange">
    516             <desc>
    517                 Notification when machine specific or global extra data
    518                 has changed.
    519             </desc>
    520             <param name="machineId" type="uuid" dir="in">
    521                 <desc>
    522                     ID of the machine this event relates to.
    523                     Null for global extra data changes.
    524                 </desc>
    525             </param>
    526             <param name="key" type="wstring" dir="in">
    527                 <desc>
    528                     Extra data key that has changed.
    529                 </desc>
    530             </param>
    531             <param name="value" type="wstring" dir="in">
    532                 <desc>
    533                     Extra data value for the given key.
    534                 </desc>
    535             </param>
    536         </method>
    537 
    538         <method name="onMediaRegistered">
    539             <desc>
    540                 The given media was registered or unregistered
    541                 within this VirtualBox installation.
    542 
    543                 The @a mediaType parameter describes what type of
    544                 media the specified @a mediaId refers to. Possible
    545                 values are:
    546 
    547                 - <link to="HardDiskDevice"/>: the media is a hard disk
    548                   that, if registered, can be obtained using the
    549                   <link to="IVirtualBox::getHardDisk"/> call.
    550                 - <link to="DVDDevice"/>: the media is a CD/DVD image
    551                   that, if registered, can be obtained using the
    552                   <link to="IVirtualBox::getDVDImage"/> call.
    553                 - <link to="FloppyDevice"/>: the media is a Floppy image
    554                   that, if registered, can be obtained using the
    555                   <link to="IVirtualBox::getFloppyImage"/> call.
    556 
    557                 Note that if this is a deregistration notification,
    558                 there is no way to access the object representing the
    559                 unregistered media. It is supposed that the
    560                 application will do required cleanup based on the @a
    561                 mediaId value.
    562             </desc>
    563             <param name="mediaId" type="uuid" dir="in">
    564                 <desc>ID of the media this event relates to.</desc>
    565             </param>
    566             <param name="mediaType" type="DeviceType" dir="in">
    567                 <desc>Type of the media this event relates to.</desc>
    568             </param>
    569             <param name="registered" type="boolean" dir="in">
    570                 <desc>
    571                     If true, the media was registered, otherwise it was
    572                     unregistered.
    573                 </desc>
    574             </param>
    575         </method>
    576 
    577         <method name="onMachineRegistered">
    578             <desc>
    579                 The given machine was registered or unregistered
    580                 within this VirtualBox installation.
    581             </desc>
    582             <param name="machineId" type="uuid" dir="in">
    583                 <desc>ID of the machine this event relates to.</desc>
    584             </param>
    585             <param name="registered" type="boolean" dir="in">
    586                 <desc>
    587                     If true, the machine was registered, otherwise it was
    588                     unregistered.
    589                 </desc>
    590             </param>
    591         </method>
    592 
    593         <method name="onSessionStateChange">
    594             <desc>
    595                 The state of the session for the given machine was changed.
    596                 <see>IMachine::sessionState</see>
    597             </desc>
    598             <param name="machineId" type="uuid" dir="in">
    599                 <desc>ID of the machine this event relates to.</desc>
    600             </param>
    601             <param name="state" type="SessionState" dir="in">
    602                 <desc>New session state.</desc>
    603             </param>
    604         </method>
    605 
    606         <method name="onSnapshotTaken">
    607             <desc>
    608                 A new snapshot of the machine has been taken.
    609                 <see>ISnapshot</see>
    610             </desc>
    611             <param name="machineId" type="uuid" dir="in">
    612                 <desc>ID of the machine this event relates to.</desc>
    613             </param>
    614             <param name="snapshotId" type="uuid" dir="in">
    615                 <desc>ID of the new snapshot.</desc>
    616             </param>
    617         </method>
    618 
    619         <method name="onSnapshotDiscarded">
    620             <desc>
    621                 Snapshot of the given machine has been discarded.
    622 
    623                 <note>
    624                     This notification is delivered <b>after</b> the snapshot
    625                     object has been uninitialized on the server (so that any
    626                     attempt to call its methods will return an error).
    627                 </note>
    628 
    629                 <see>ISnapshot</see>
    630             </desc>
    631             <param name="machineId" type="uuid" dir="in">
    632                 <desc>ID of the machine this event relates to.</desc>
    633             </param>
    634             <param name="snapshotId" type="uuid" dir="in">
    635                 <desc>
    636                     ID of the discarded snapshot. <tt>null</tt> means the
    637                     current machine state has been discarded (restored from
    638                     the current snapshot).
    639                 </desc>
    640             </param>
    641         </method>
    642 
    643         <method name="onSnapshotChange">
    644             <desc>
    645                 Snapshot properties (name and/or description) have been changed.
    646                 <see>ISnapshot</see>
    647             </desc>
    648             <param name="machineId" type="uuid" dir="in">
    649                 <desc>ID of the machine this event relates to.</desc>
    650             </param>
    651             <param name="snapshotId" type="uuid" dir="in">
    652                 <desc>ID of the changed snapshot.</desc>
    653             </param>
    654         </method>
    655 
    656     </interface>
    657 
    658     <interface
    659         name="IVirtualBox" extends="$dispatched"
    660         uuid="d1a2295c-d257-4a4c-a9a6-843d87db6f45"
    661         wsmap="global"
    662     >
    663       <desc> The main interface exposed by the product that provides virtual
     533      </param>
     534      <param name="value" type="wstring" dir="in">
     535        <desc>
     536          Extra data value for the given key.
     537        </desc>
     538      </param>
     539    </method>
     540
     541    <method name="onMediaRegistered">
     542      <desc>
     543        The given media was registered or unregistered
     544        within this VirtualBox installation.
     545
     546        The @a mediaType parameter describes what type of
     547        media the specified @a mediaId refers to. Possible
     548        values are:
     549
     550        - <link to="HardDiskDevice"/>: the media is a hard disk
     551        that, if registered, can be obtained using the
     552        <link to="IVirtualBox::getHardDisk"/> call.
     553        - <link to="DVDDevice"/>: the media is a CD/DVD image
     554        that, if registered, can be obtained using the
     555        <link to="IVirtualBox::getDVDImage"/> call.
     556        - <link to="FloppyDevice"/>: the media is a Floppy image
     557        that, if registered, can be obtained using the
     558        <link to="IVirtualBox::getFloppyImage"/> call.
     559
     560        Note that if this is a deregistration notification,
     561        there is no way to access the object representing the
     562        unregistered media. It is supposed that the
     563        application will do required cleanup based on the @a
     564        mediaId value.
     565      </desc>
     566      <param name="mediaId" type="uuid" dir="in">
     567        <desc>ID of the media this event relates to.</desc>
     568      </param>
     569      <param name="mediaType" type="DeviceType" dir="in">
     570        <desc>Type of the media this event relates to.</desc>
     571      </param>
     572      <param name="registered" type="boolean" dir="in">
     573        <desc>
     574          If true, the media was registered, otherwise it was
     575          unregistered.
     576        </desc>
     577      </param>
     578    </method>
     579
     580    <method name="onMachineRegistered">
     581      <desc>
     582        The given machine was registered or unregistered
     583        within this VirtualBox installation.
     584      </desc>
     585      <param name="machineId" type="uuid" dir="in">
     586        <desc>ID of the machine this event relates to.</desc>
     587      </param>
     588      <param name="registered" type="boolean" dir="in">
     589        <desc>
     590          If true, the machine was registered, otherwise it was
     591          unregistered.
     592        </desc>
     593      </param>
     594    </method>
     595
     596    <method name="onSessionStateChange">
     597      <desc>
     598        The state of the session for the given machine was changed.
     599        <see>IMachine::sessionState</see>
     600      </desc>
     601      <param name="machineId" type="uuid" dir="in">
     602        <desc>ID of the machine this event relates to.</desc>
     603      </param>
     604      <param name="state" type="SessionState" dir="in">
     605        <desc>New session state.</desc>
     606      </param>
     607    </method>
     608
     609    <method name="onSnapshotTaken">
     610      <desc>
     611        A new snapshot of the machine has been taken.
     612        <see>ISnapshot</see>
     613      </desc>
     614      <param name="machineId" type="uuid" dir="in">
     615        <desc>ID of the machine this event relates to.</desc>
     616      </param>
     617      <param name="snapshotId" type="uuid" dir="in">
     618        <desc>ID of the new snapshot.</desc>
     619      </param>
     620    </method>
     621
     622    <method name="onSnapshotDiscarded">
     623      <desc>
     624        Snapshot of the given machine has been discarded.
     625
     626        <note>
     627          This notification is delivered <b>after</b> the snapshot
     628          object has been uninitialized on the server (so that any
     629          attempt to call its methods will return an error).
     630        </note>
     631
     632        <see>ISnapshot</see>
     633      </desc>
     634      <param name="machineId" type="uuid" dir="in">
     635        <desc>ID of the machine this event relates to.</desc>
     636      </param>
     637      <param name="snapshotId" type="uuid" dir="in">
     638        <desc>
     639          ID of the discarded snapshot. <tt>null</tt> means the
     640          current machine state has been discarded (restored from
     641          the current snapshot).
     642        </desc>
     643      </param>
     644    </method>
     645
     646    <method name="onSnapshotChange">
     647      <desc>
     648        Snapshot properties (name and/or description) have been changed.
     649        <see>ISnapshot</see>
     650      </desc>
     651      <param name="machineId" type="uuid" dir="in">
     652        <desc>ID of the machine this event relates to.</desc>
     653      </param>
     654      <param name="snapshotId" type="uuid" dir="in">
     655        <desc>ID of the changed snapshot.</desc>
     656      </param>
     657    </method>
     658
     659  </interface>
     660
     661  <interface
     662     name="IVirtualBox" extends="$dispatched"
     663     uuid="d1a2295c-d257-4a4c-a9a6-843d87db6f45"
     664     wsmap="global"
     665     >
     666    <desc> The main interface exposed by the product that provides virtual
    664667      machine management.
    665668
    … …  
    674677      attribute.</desc>
    675678
    676         <attribute name="version" type="wstring" readonly="yes">
    677             <desc>
    678                 A string representing the version number of the product. The
    679                 format is 3 integer numbers divided by dots (e.g. 1.0.1). The
    680                 last number represents the build number and will frequently change.
    681             </desc>
    682         </attribute>
    683 
    684         <attribute name="homeFolder" type="wstring" readonly="yes">
    685             <desc>
    686                 Full path to the directory where the global settings file,
    687                 <tt>VirtualBox.xml</tt>, is stored.
    688 
    689                 In this version of VirtualBox, the value of this property is
    690                 always <tt>&lt;user_dir&gt;/.VirtualBox</tt> (where
    691                 <tt>&lt;user_dir&gt;</tt> is the path to the user directory,
    692                 as determined by the host OS), and cannot be changed.
    693 
    694                 This path is also used as the base to resolve relative paths in
    695                 places where relative paths are allowed (unless otherwise
    696                 expressly indicated).
    697             </desc>
    698         </attribute>
    699 
    700         <attribute name="host" type="IHost" readonly="yes">
    701             <desc>Associated host object.</desc>
    702         </attribute>
    703 
    704         <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
    705             <desc>Associated system information object.</desc>
    706         </attribute>
    707 
    708         <attribute name="machines" type="IMachineCollection" readonly="yes"/>
    709 
    710         <attribute name="hardDisks" type="IHardDiskCollection" readonly="yes">
    711             <desc>
    712                 A collection of hard disk objects registered within this
    713                 VirtualBox instance.
    714                 This collection contains only "top-level" (basic or independent)
    715                 hard disk images, but not differencing ones. All differencing
    716                 images of the given top-level image (i.e. all its children) can
    717                 be enumerated using <link to="IHardDisk::children"/>.
    718             </desc>
    719         </attribute>
    720 
    721         <attribute name="DVDImages" type="IDVDImageCollection" readonly="yes"/>
    722 
    723         <attribute name="FloppyImages" type="IFloppyImageCollection" readonly="yes"/>
    724 
    725         <attribute name="progressOperations" type="IProgressCollection" readonly="yes"/>
    726 
    727         <attribute name="guestOSTypes" type="IGuestOSTypeCollection" readonly="yes"/>
    728 
    729         <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
    730             <desc>
    731                 Collection of globally shared folders. These folders
    732                 are shared automatically upon VirtualBox server startup and
    733                 available only to every virtual machine.
    734 
    735                 New folders to share are added to the collection using
    736                 <link to="#createSharedFolder"/>. An existing shared folder can
    737                 be removed using <link to="#removeSharedFolder"/>.
    738             </desc>
    739         </attribute>
    740 
    741         <method name="createMachine">
    742             <desc>
    743                 Creates a new virtual machine.
    744 
    745                 Every machine has a <i>settings file</i> that is used to store
    746                 the machine configuration. This file is stored in the directory
    747                 called <i>machine settings subfolder</i>. Both the subfolder
    748                 and the settings file have the same name that corresponds to the
    749                 name of the virtual machine. You can specify where
    750                 to create the machine settings subfolder using the @a
    751                 baseFolder argument. The base folder can be absolute (full path)
    752                 or relative to the <link to="IVirtualBox::homeFolder">
    753                 VirtualBox home directory</link>.
    754 
    755                 If a null or empty string is given as the base folder (which is
    756                 recommended), the <link to="ISystemProperties::defaultMachineFolder">
    757                 default machine settings folder</link> will be used as the base
    758                 folder to create the machine settings subfolder and file. In
    759                 any case, the full path to the settings file will look like:
    760                 <pre>
    761     &lt;base_folder&gt;/&lt;machine_name&gt;/&lt;machine_name&gt;.xml</pre>
    762 
    763                 Note that the configuration of the newly created machine is not
    764                 saved to disk (and therefore no settings subfolder and file are
    765                 created) until <link to="IMachine::saveSettings()"/> is called.
    766 
    767                 You should also specify a valid name for the machine.
    768                 See the <link to="IMachine::name"/> property
    769                 description for more details about the machine name.
    770 
    771                 The created machine remains
    772                 unregistered until you call <link to="#registerMachine()"/>.
    773 
    774                 <note>
    775                     There is no way to change the name of the settings file or
    776                     subfolder of the created machine directly.
    777                 </note>
    778             </desc>
    779             <param name="baseFolder" type="wstring" dir="in">
    780                 <desc>
    781                     Name of the folder where to create the machine settings
    782                     subfolder containing the settings file.
    783                 </desc>
    784             </param>
    785             <param name="name" type="wstring" dir="in">
    786                 <desc>Machine name.</desc>
    787             </param>
    788             <param name="machine" type="IMachine" dir="return">
    789                 <desc>Created machine object.</desc>
    790             </param>
    791         </method>
    792 
    793         <method name="createLegacyMachine">
    794             <desc>
    795                 Creates a new virtual machine in "legacy" mode, using the
    796                 specified settings file to store machine settings.
    797 
    798                 As opposed to machines created by <link to="#createMachine()"/>,
    799                 the settings file of the machine created in "legacy" mode
    800                 is not automatically renamed when the machine name is
    801                 changed -- it will always remain the same as specified in this
    802                 method call.
    803 
    804                 The specified settings file name can be absolute
    805                 (full path) or relative to the <link to="IVirtualBox::homeFolder">
    806                 VirtualBox home directory</link>. If the file name doesn't
    807                 contain an extension, the default extension (.xml) will be
    808                 appended.
    809 
    810                 Note that the configuration of the newly created machine is not
    811                 saved to disk (and therefore no settings file is created)
    812                 until <link to="IMachine::saveSettings()"/> is called. If the
    813                 specified settings file already exists,
    814                 <link to="IMachine::saveSettings()"/> will return an error.
    815 
    816                 You should also specify a valid name for the machine.
    817                 See the <link to="IMachine::name"/> property
    818                 description for more details about the machine name.
    819 
    820                 The created machine remains
    821                 unregistered until you call <link to="#registerMachine()"/>.
    822 
    823                 @deprecated This method may be removed later. It is better
    824                 to use <link to="IVirtualBox::createMachine()"/>.
    825 
    826                 <note>
    827                     There is no way to change the name of the settings file
    828                     of the created machine.
    829                 </note>
    830             </desc>
    831             <param name="settingsFile" type="wstring" dir="in">
    832                 <desc>
    833                     Name of the file where to store machine settings.
    834                 </desc>
    835             </param>
    836             <param name="name" type="wstring" dir="in">
    837                 <desc>Machine name.</desc>
    838             </param>
    839             <param name="machine" type="IMachine" dir="return">
    840                 <desc>Created machine object.</desc>
    841             </param>
    842         </method>
    843 
    844         <method name="openMachine">
    845             <desc>
    846                 Opens a virtual machine from the existing settings file.
    847                 The opened machine remains unregistered until you call
    848                 <link to="#registerMachine()"/>.
    849 
    850                 The specified settings file name can be absolute
    851                 (full path) or relative to the <link to="IVirtualBox::homeFolder">
    852                 VirtualBox home directory</link>. This file must exist
    853                 and must be a valid machine settings file whose contents
    854                 will be used to construct the machine object.
    855 
    856                 @deprecated Will be removed soon.
    857             </desc>
    858             <param name="settingsFile" type="wstring" dir="in">
    859                 <desc>
    860                     Name of the machine settings file.
    861                 </desc>
    862             </param>
    863             <param name="machine" type="IMachine" dir="return">
    864                 <desc>Opened machine object.</desc>
    865             </param>
    866             <note>
    867                 <link to="IMachine::settingsModified"/> will return
    868                 false for the created machine, until any of machine settigs
    869                 are changed.
    870             </note>
    871         </method>
    872 
    873         <method name="registerMachine">
    874             <desc>
    875 
    876                 Registers the machine previously created using <link
    877                 to="#createMachine()"/> or opened using <link to="#openMachine()"/>
    878                 within this VirtualBox installation. After successful method
    879                 invocation, the <link
    880                 to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
    881                 to all registered callbacks.
    882 
    883                 <note>This method implicitly calls <link
    884                 to="IMachine::saveSettings"/> to save all current machine
    885                 settings before registering it.</note>
    886 
    887             </desc>
    888             <param name="machine" type="IMachine" dir="in"/>
    889         </method>
    890 
    891         <method name="getMachine">
    892             <param name="id" type="uuid" dir="in"/>
    893             <param name="machine" type="IMachine" dir="return"/>
    894         </method>
    895 
    896         <method name="findMachine">
    897             <param name="name" type="wstring" dir="in"/>
    898             <param name="machine" type="IMachine" dir="return"/>
    899         </method>
    900 
    901         <method name="unregisterMachine">
    902             <desc>
    903 
    904                 Unregisters the machine previously registered using <link
    905                 to="#registerMachine"/>. After successful method invocation, the
    906                 <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is
    907                 sent to all registered callbacks.
    908 
    909                 <note> The specified machine must not be in the Saved state,
    910                 have an open (or a spawning) direct session associated with it,
    911                 have snapshots or have hard disks attached.</note>
    912 
    913                 <note>This method implicitly calls <link
    914                 to="IMachine::saveSettings"/> to save all current machine
    915                 settings before unregistering it.</note>
    916 
    917                 <note>If the given machine is inaccessible (see
    918                 <link to="IMachine::accessible"/>), it will be unregistered
    919                 and fully uninitialized right afterwards. As a result, the
    920                 returned machine object will be unusable and an attempt to call
    921                 <b>any</b> method will return the "Object not ready" error.
    922                 </note>
    923 
    924             </desc>
    925             <param name="id" type="uuid" dir="in">
    926                 <desc>UUID of the machine to unregister.</desc>
    927             </param>
    928             <param name="machine" type="IMachine" dir="return">
    929                 <desc>Unregistered machine object.</desc>
    930             </param>
    931         </method>
    932 
    933         <method name="createHardDisk">
    934             <desc>
    935 
    936                 Creates a new unregistered hard disk that will use the given
    937                 storage type.
    938 
    939                 Most properties of the created hard disk object are
    940                 uninitialized. Valid values must be assigned to them (and
    941                 probalby some actions performed) to make the actual usage of
    942                 this hard disk (<link to="#registerHardDisk()">register</link>,
    943                 attach to a virtual machine, etc.). See the description of <link
    944                 to="IHardDisk"/> and descriptions of storage type specific
    945                 interfaces for more information.
    946 
    947                 <note>For hard disks using the <link
    948                 to="HardDiskStorageType::VirtualDiskImage">VirtualDiskImage</link>
    949                 storage type, an image file is not actually created until you
    950                 call <link to="IVirtualDiskImage::createDynamicImage()"/> or
    951                 <link to="IVirtualDiskImage::createFixedImage()"/>.</note>
    952 
    953             </desc>
    954 
    955             <param name="storageType" type="HardDiskStorageType" dir="in">
    956                 <desc>Storage type of the hard disk image to create.</desc>
    957             </param>
    958             <param name="hardDisk" type="IHardDisk" dir="return">
    959                 <desc>Created hard disk object of the given storage type.</desc>
    960             </param>
    961 
    962         </method>
    963 
    964         <method name="openHardDisk">
    965             <desc>
    966 
    967                 Opens a hard disk from an existing location.
    968 
    969                 This method tries to guess the
    970                 <link to="HardDiskStorageType">hard disk storage
    971                 type</link>
    972                 from the format of the location string and from the
    973                 contens of the resource the location points
    974                 to. Currently, a <i>file path</i> is the only supported
    975                 format for the location string which must point to
    976                 either a VDI file or to a VMDK file. On success,
    977                 an IHardDisk object will be returned that also
    978                 implements the corresponding interface (IVirtualDiskImage
    979                 or IVMDKImage, respectively). The <link
    980                 to="IHardDisk::storageType"/> property may also be
    981                 used to determine the storage type of the returned
    982                 object (instead of trying to query one of these interfaces).
    983 
    984                 <note>The specified file path can be absolute (full path) or
    985                 relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
    986                 home directory</link>. If only a file name without any path is
    987                 given, the <link to="ISystemProperties::defaultVDIFolder">
    988                 default VDI folder</link> will be used as a path to the image
    989                 file.</note>
    990 
    991                 The opened hard disk remains unregistered
    992                 until <link to="#registerHardDisk()"/> is called.
    993 
    994             </desc>
    995 
    996             <param name="location" type="wstring" dir="in">
    997                 <desc>
    998                     Location of the resource that contains a valid hard disk.
    999                 </desc>
    1000             </param>
    1001             <param name="hardDisk" type="IHardDisk" dir="return">
    1002                 <desc>Opened hard disk object.</desc>
    1003             </param>
    1004         </method>
    1005 
    1006         <method name="openVirtualDiskImage">
    1007             <desc>
    1008 
    1009                 Opens a hard disk from an existing Virtual Disk Image file.
    1010                 The opened hard disk remains unregistered
    1011                 until <link to="#registerHardDisk()"/> is called.
    1012 
    1013                 @deprecated Use <link to="IVirtualBox::openHardDisk()"/> instead.
    1014 
    1015                 <note>Opening differencing images is not supported.</note>
    1016 
    1017                 <note>The specified file path can be absolute (full path) or
    1018                 relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
    1019                 home directory</link>. If only a file name without any path is
    1020                 given, the <link to="ISystemProperties::defaultVDIFolder">
    1021                 default VDI folder</link> will be used as a path to the image
    1022                 file.</note>
    1023 
    1024             </desc>
    1025 
    1026             <param name="filePath" type="wstring" dir="in">
    1027                 <desc>
    1028                     Name of the file that contains a valid Virtual Disk Image.
    1029                 </desc>
    1030             </param>
    1031             <param name="image" type="IVirtualDiskImage" dir="return">
    1032                 <desc>Opened hard disk object.</desc>
    1033             </param>
    1034         </method>
    1035 
    1036         <method name="registerHardDisk">
    1037             <desc>
    1038 
    1039                 Registers the given hard disk within this VirtualBox
    1040                 installation. The hard disk must not be registered, must be
    1041                 <link to="IHardDisk::accessible"/> and must not be a
    1042                 differencing hard disk, otherwise the registration will fail.
    1043 
    1044             </desc>
    1045             <param name="hardDisk" type="IHardDisk" dir="in">
    1046                 <desc>Hard disk object to register.</desc>
    1047             </param>
    1048         </method>
    1049 
    1050         <method name="getHardDisk" const="yes">
    1051             <desc>
    1052                 Returns the registered hard disk with the given UUID.
    1053             </desc>
    1054             <param name="id" type="uuid" dir="in">
    1055                 <desc>UUID of the hard disk to look for.</desc>
    1056             </param>
    1057             <param name="hardDisk" type="IHardDisk" dir="return">
    1058                 <desc>Found hard disk object.</desc>
    1059             </param>
    1060         </method>
    1061 
    1062         <method name="findHardDisk">
    1063             <desc>
    1064 
    1065                 Returns a registered hard disk that uses the given location to
    1066                 store data. The search is done by comparing the
    1067                 value of the @a location argument to the
    1068                 <link to="IHardDisk::location"/> attribute of each registered
    1069                 hard disk.
    1070 
    1071                 For locations repesented by file paths (such as VDI and VMDK
    1072                 images), the specified location can be either an absolute file
    1073                 path or a path relative to
    1074                 the <link to="IVirtualBox::homeFolder"> VirtualBox home
    1075                 directory</link>. If only a file name without any path is
    1076                 given, the <link to="ISystemProperties::defaultVDIFolder">
    1077                 default VDI folder</link> will be used as a path to construct
    1078                 the absolute image file name to search for. Note that on host
    1079                 systems with case sensitive filesystems, a case sensitive
    1080                 comparison is performed, otherwise the case of symbols in the
    1081                 file path is ignored.
    1082 
    1083             </desc>
    1084             <param name="location" type="wstring" dir="in">
    1085                 <desc>Hard disk location specification to search for.</desc>
    1086             </param>
    1087             <param name="hardDisk" type="IHardDisk" dir="return">
    1088                 <desc>Found hard disk object.</desc>
    1089             </param>
    1090         </method>
    1091 
    1092         <method name="findVirtualDiskImage">
    1093             <desc>
    1094 
    1095                 Returns a registered hard disk that uses the given image file.
    1096 
    1097                 @deprecated Use <link to="IVirtualBox::findHardDisk()"/> instead.
    1098 
    1099                 <note>The specified file path can be absolute (full path) or
    1100                 relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
    1101                 home directory</link>. If only a file name without any path is
    1102                 given, the <link to="ISystemProperties::defaultVDIFolder">
    1103                 default VDI folder</link> will be used as a path to the image
    1104                 file.</note>
    1105 
    1106                 <note>On host systems with case sensitive filesystems, a case
    1107                 sensitive comparison is performed, otherwise the case of symbols
    1108                 in the file path is ignored.</note>
    1109 
    1110             </desc>
    1111             <param name="filePath" type="wstring" dir="in">
    1112                 <desc>Virtual Disk Image file path to look for.</desc>
    1113             </param>
    1114             <param name="image" type="IVirtualDiskImage" dir="return">
    1115                 <desc>Found hard disk object.</desc>
    1116             </param>
    1117         </method>
    1118 
    1119         <method name="unregisterHardDisk">
    1120             <desc>
    1121                 Unregisters a hard disk previously registered using
    1122                 <link to="#registerHardDisk()"/>.
    1123                 <note>
    1124                     The specified hard disk must not be attached to any of
    1125                     the existing virtual machines and must not have children
    1126                     (differencing) hard disks.
    1127                 </note>
    1128             </desc>
    1129             <param name="id" type="uuid" dir="in">
    1130                 <desc>UUID of the hard disk to unregister.</desc>
    1131             </param>
    1132             <param name="hardDisk" type="IHardDisk" dir="return">
    1133                 <desc>Unregistered hard disk object.</desc>
    1134             </param>
    1135         </method>
    1136 
    1137         <method name="openDVDImage">
    1138             <desc>
    1139                 Opens the CD/DVD image contained in the specified file of
    1140                 the supported format and assigns it the given UUID. The opened
    1141                 image remains unregistered
    1142                 until <link to="#registerDVDImage()"/> is called.
    1143             </desc>
    1144             <param name="filePath" type="wstring" dir="in">
    1145                 <desc>
    1146                     Full name of the file that contains a valid
    1147                     CD/DVD image. Currently, only ISO images are supported.
    1148                     <note>
    1149                         The specified file name can be absolute or relative
    1150                         to the <link to="IVirtualBox::homeFolder">
    1151                         VirtualBox home directory</link>.
    1152                     </note>
    1153                 </desc>
    1154             </param>
    1155             <param name="id" type="uuid" dir="in">
    1156                 <desc>
    1157                     UUID to assign to the given image file within this
    1158                     VirtualBox installation. If an empty (null) UUID is
    1159                     specified, the system will randomly generate an UUID.
    1160                 </desc>
    1161             </param>
    1162             <param name="image" type="IDVDImage" dir="return">
    1163                 <desc>Opened CD/DVD image object.</desc>
    1164             </param>
    1165         </method>
    1166 
    1167         <method name="registerDVDImage">
    1168             <desc>
    1169                 Registers a CD/DVD image within this VirtualBox
    1170                 installation. The image must not be registered and must not
    1171                 be associated with the same image file as any of the already
    1172                 registered images, otherwise the registration will fail.
    1173             </desc>
    1174             <param name="image" type="IDVDImage" dir="in">
    1175                 <desc>CD/DVD image object to register.</desc>
    1176             </param>
    1177         </method>
    1178 
    1179         <method name="getDVDImage">
    1180             <desc>
    1181                 Returns a registered CD/DVD image with the given UUID.
    1182             </desc>
    1183             <param name="id" type="uuid" dir="in">
    1184                 <desc>UUID of the image to look for.</desc>
    1185             </param>
    1186             <param name="image" type="IDVDImage" dir="return">
    1187                 <desc>Found CD/DVD image object.</desc>
    1188             </param>
    1189         </method>
    1190 
    1191         <method name="findDVDImage">
    1192             <desc>
    1193                 Returns a registered CD/DVD image with the given image file.
    1194                 <note>
    1195                     On host systems with case sensitive filesystems, a case
    1196                     sensitive comparison is performed, otherwise the case of
    1197                     symbols in the file path is ignored.
    1198                 </note>
    1199             </desc>
    1200             <param name="filePath" type="wstring" dir="in">
    1201                 <desc>CD/DVD image file path to look for.</desc>
    1202             </param>
    1203             <param name="image" type="IDVDImage" dir="return">
    1204                 <desc>Found CD/DVD image object.</desc>
    1205             </param>
    1206         </method>
    1207 
    1208         <method name="getDVDImageUsage">
    1209             <desc>
    1210                 Returns the list of of UUIDs of all virtual machines that use
    1211                 the given CD/DVD image.
    1212             </desc>
    1213             <param name="id" type="uuid" dir="in">
    1214                 <desc>UUID of the image to get the usage information for.</desc>
    1215             </param>
    1216             <param name="usage" type="ResourceUsage" dir="in">
    1217                 <desc>Type of the usage (permanent, temporary or all).</desc>
    1218             </param>
    1219             <param name="machineIDs" type="wstring" dir="return">
    1220                 <desc>
    1221                     List of UUIDs of all machines that use the given image
    1222                     in the way specified by the usage parameter.
    1223                     The list is returned as a string containing UUIDs separated
    1224                     by spaces. A null string means that the image is not used.
    1225                     <note>
    1226                         When the usage type is <link to="ResourceUsage::AllUsage"/>
    1227                         and the image is used by the VM both permanently
    1228                         and temporarily, the VM's UUID will be present only
    1229                         once in the list.
    1230                     </note>
    1231                 </desc>
    1232             </param>
    1233         </method>
    1234 
    1235         <method name="unregisterDVDImage">
    1236             <desc>
    1237                 Unregisters the CD/DVD image previously registered using
    1238                 <link to="#registerDVDImage()"/>.
    1239                 <note>
    1240                     The specified image must not be mounted to any of
    1241                     the existing virtual machines.
    1242                 </note>
    1243             </desc>
    1244             <param name="id" type="uuid" dir="in">
    1245                 <desc>UUID of the CD/DVD image to unregister.</desc>
    1246             </param>
    1247             <param name="image" type="IDVDImage" dir="return">
    1248                 <desc>Unregistered image object.</desc>
    1249             </param>
    1250         </method>
    1251 
    1252         <method name="openFloppyImage">
    1253             <desc>
    1254                 Opens a floppy image contained in the specified file of
    1255                 the supported format and assigns it the given UUID. The opened
    1256                 image remains unregistered
    1257                 until <link to="#registerFloppyImage()"/> is called.
    1258             </desc>
    1259             <param name="filePath" type="wstring" dir="in">
    1260                 <desc>
    1261                     Full name of the file that contains a valid
    1262                     floppy image.
    1263                     <note>
    1264                         The specified file name can be absolute or relative
    1265                         to the <link to="IVirtualBox::homeFolder">
    1266                         VirtualBox home directory</link>.
    1267                     </note>
    1268                 </desc>
    1269             </param>
    1270             <param name="id" type="uuid" dir="in">
    1271                 <desc>
    1272                     UUID to assign to the given image file within this
    1273                     VirtualBox installation. If an empty (null) UUID is
    1274                     specified, the system will randomly generate an UUID.
    1275                 </desc>
    1276             </param>
    1277             <param name="image" type="IFloppyImage" dir="return">
    1278                 <desc>Opened CD/DVD image object.</desc>
    1279             </param>
    1280         </method>
    1281 
    1282         <method name="registerFloppyImage">
    1283             <desc>
    1284                 Registers a floppy image within this VirtualBox
    1285                 installation. The image must not be registered and must not
    1286                 be associated with the same image file as any of the already
    1287                 registered images, otherwise the registration will fail.
    1288             </desc>
    1289             <param name="image" type="IFloppyImage" dir="in">
    1290                 <desc>Floppy image object to register.</desc>
    1291             </param>
    1292         </method>
    1293 
    1294         <method name="getFloppyImage">
    1295             <desc>
    1296                 Returns a registered floppy image with the given UUID.
    1297             </desc>
    1298             <param name="id" type="uuid" dir="in">
    1299                 <desc>UUID of the image to look for.</desc>
    1300             </param>
    1301             <param name="image" type="IFloppyImage" dir="return">
    1302                 <desc>Found floppy image object.</desc>
    1303             </param>
    1304         </method>
    1305 
    1306         <method name="findFloppyImage">
    1307             <desc>
    1308                 Returns a registered floppy image with the given image file.
    1309                 <note>
    1310                     On host systems with case sensitive filesystems, a case
    1311                     sensitive comparison is performed, otherwise the case of
    1312                     symbols in the file path is ignored.
    1313                 </note>
    1314             </desc>
    1315             <param name="filePath" type="wstring" dir="in">
    1316                 <desc>Floppy image file path to look for.</desc>
    1317             </param>
    1318             <param name="image" type="IFloppyImage" dir="return">
    1319                 <desc>Found floppy image object.</desc>
    1320             </param>
    1321         </method>
    1322 
    1323         <method name="getFloppyImageUsage">
    1324             <desc>
    1325                 Returns the list of of UUIDs of all virtual machines that use
    1326                 the given floppy image.
    1327             </desc>
    1328             <param name="id" type="uuid" dir="in">
    1329                 <desc>UUID of the image to get the usage information for.</desc>
    1330             </param>
    1331             <param name="usage" type="ResourceUsage" dir="in">
    1332                 <desc>Type of the usage (permanent, temporary or all).</desc>
    1333             </param>
    1334             <param name="machineIDs" type="wstring" dir="return">
    1335                 <desc>
    1336                     List of UUIDs of all machines that use the given image
    1337                     in the way specified by the usage parameter.
    1338                     The list is returned as a string containing UUIDs separated
    1339                     by spaces. A null string means that the image is not used.
    1340                     <note>
    1341                         When the usage type is <link to="ResourceUsage::AllUsage"/>
    1342                         and the image is used by the VM both permanently
    1343                         and temporarily, the VM's UUID will be present only
    1344                         once in the list.
    1345                     </note>
    1346                 </desc>
    1347             </param>
    1348         </method>
    1349 
    1350         <method name="unregisterFloppyImage">
    1351             <desc>
    1352                 Unregisters the floppy image previously registered using
    1353                 <link to="#registerFloppyImage()"/>.
    1354                 <note>
    1355                     The specified image must not be mounted to any of
    1356                     the existing virtual machines.
    1357                 </note>
    1358             </desc>
    1359             <param name="id" type="uuid" dir="in">
    1360                 <desc>UUID of the floppy image to unregister.</desc>
    1361             </param>
    1362             <param name="image" type="IFloppyImage" dir="return">
    1363                 <desc>Unregistered image object.</desc>
    1364             </param>
    1365         </method>
    1366 
    1367         <method name="getGuestOSType">
    1368             <param name="id" type="wstring" dir="in"/>
    1369             <param name="type" type="IGuestOSType" dir="return"/>
    1370         </method>
    1371 
    1372         <method name="createSharedFolder">
    1373             <desc>
    1374                 Creates a new shared folder by associating the given logical
    1375                 name with the given host path, adds it to the collection of
    1376                 shared folders and starts sharing it.
    1377                 Refer to the description of <link to="ISharedFolder"/> to read
    1378                 about logical name unicity.
    1379             </desc>
    1380             <param name="name" type="wstring" dir="in">
    1381                 <desc>Unique logical name of the shared folder.</desc>
    1382             </param>
    1383             <param name="hostPath" type="wstring" dir="in">
    1384                 <desc>Full path to the shared folder in the host file system.</desc>
    1385             </param>
    1386         </method>
    1387 
    1388         <method name="removeSharedFolder">
    1389             <desc>
    1390                 Removes a shared folder with the given name previously created
    1391                 by <link to="#createSharedFolder"/> from the collection of
    1392                 shared folders and stops sharing it.
    1393             </desc>
    1394             <param name="name" type="wstring" dir="in">
    1395                 <desc>Logical name of the shared folder to remove.</desc>
    1396             </param>
    1397         </method>
    1398 
    1399         <method name="getNextExtraDataKey">
    1400             <desc>
    1401                 Returns the extra data key name following the supplied key.
    1402                 An error is returned if the supplied key does not exist.
    1403                 @c NULL is returned if the supplied key is the last key.
    1404                 When supplying @c NULL for the key, the first item is returned.
    1405                 @a nextValue is an optional parameter and if supplied, the next
    1406                 key's value is returned in it.
    1407             </desc>
    1408             <param name="key" type="wstring" dir="in">
    1409                 <desc>Name of the data key to follow.</desc>
    1410             </param>
    1411             <param name="nextKey" type="wstring" dir="out">
    1412                 <desc>Name of the next data key.</desc>
    1413             </param>
    1414             <param name="nextValue" type="wstring" dir="out">
    1415                 <desc>Value of the next data key.</desc>
    1416             </param>
    1417         </method>
    1418 
    1419         <method name="getExtraData">
    1420             <desc>
    1421                 Returns associated extra data.
    1422                 If the reuqested key does not exist, this function will
    1423                 succeed and return @c null in the @a value argument.
    1424             </desc>
    1425             <param name="key" type="wstring" dir="in">
    1426                 <desc>Name of the data key to get.</desc>
    1427             </param>
    1428             <param name="value" type="wstring" dir="return">
    1429                 <desc>Value of the requested data key.</desc>
    1430             </param>
    1431         </method>
    1432 
    1433         <method name="setExtraData">
    1434             <desc>
    1435                 Sets associated extra data.
    1436                 If you pass @c NULL as a key @a vaule, the given key will be
    1437                 deleted.
    1438                 <note>
    1439                     This method can be called outside a machine session and
    1440                     therefore it's a caller's responsibility to handle race
    1441                     condition when several clients change the same key at the
    1442                     same time.
    1443                 </note>
    1444             </desc>
    1445             <param name="key" type="wstring" dir="in">
    1446                 <desc>Name of the data key to set.</desc>
    1447             </param>
    1448             <param name="value" type="wstring" dir="in">
    1449                 <desc>Value to assign to the key.</desc>
    1450             </param>
    1451         </method>
    1452 
    1453         <method name="openSession">
    1454             <desc>
    1455                 <p>Opens a new direct session with the given virtual machine.
    1456                 Within the direct session context, it is possible to change
    1457                 all VM settings, as well as to execute the VM in the process
    1458                 space of the session object. There can be only one direct
    1459                 session open at a time for every virtual machine.</p>
    1460                 <p>Upon successful return, the session object can be used to
    1461                 get access to the machine and to the VM console.
    1462                 </p>
    1463             </desc>
    1464             <param name="session" type="ISession" dir="in">
    1465                 <desc>
    1466                     Session object that will represent the opened session after
    1467                     successful method invocation. This object must not represent
    1468                     the already open session.
    1469                     <note>
    1470                         This session will be automatically closed if the
    1471                         VirtualBox server is terminated for some reason.
    1472                     </note>
    1473                 </desc>
    1474             </param>
    1475             <param name="machineId" type="uuid" dir="in">
    1476                 <desc>ID of the virtual machine to open a session with.</desc>
    1477             </param>
    1478         </method>
    1479 
    1480         <method name="openRemoteSession">
    1481             <desc>
    1482                 <p>Opens a new remote session with the given virtual
    1483                 machine. Opening the remote session causes the server to start
    1484                 a new process that opens a direct session with the given VM.
    1485                 The remote session provides some level of control over the VM
    1486                 execution (using the IConsole interface) to the caller. Within
    1487                 the remote session context, it is not possible to change any
    1488                 static VM settings (such as name, HDD configuration, etc.).</p>
    1489                 <p>This operation can take some time, so the progress object
    1490                 is returned to let the caller be informed when the session is
    1491                 actually open. Until then, the remote session object remains in
    1492                 the closed state and accessing the machine or its console through
    1493                 it is invalid.
    1494                 </p>
    1495 
    1496                 Currently supported session types (values of the @a type
    1497                 parameter) are:
    1498                 <ul>
    1499                     <li><tt>gui</tt>: VirtualBox Qt GUI session</li>
    1500                     <li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
    1501                 </ul>
    1502 
    1503                 <note>
    1504                     It is impossible to open a remote session with the machine
    1505                     that already has an open direct session or waits until the
    1506                     previous request to open the remote session is completed
    1507                     (see <link to="IMachine::sessionState"/>).
    1508                 </note>
    1509 
    1510                 <note>
    1511                     The opened @a session will be automatically closed when
    1512                     the corresponding direct session dies or gets closed.
    1513                 </note>
    1514 
    1515                 <see>openExistingSession</see>
    1516             </desc>
    1517             <param name="session" type="ISession" dir="in">
    1518                 <desc>
    1519                     Session object that will represent the opened remote session
    1520                     after successful method invocation (this object must not
    1521                     represent an already open session).
    1522                 </desc>
    1523             </param>
    1524             <param name="machineId" type="uuid" dir="in">
    1525                 <desc>ID of the virtual machine to open a session with.</desc>
    1526             </param>
    1527             <param name="type" type="wstring" dir="in">
    1528                 <desc>
    1529                     Type of the remote session (case sensitive).
    1530                 </desc>
    1531             </param>
    1532             <param name="progress" type="IProgress" dir="return">
    1533                 <desc>Progress object to track the operation completion.</desc>
    1534             </param>
    1535         </method>
    1536 
    1537         <method name="openExistingSession">
    1538             <desc>
    1539                 <p>Opens a new remote session with the virtual machine for
    1540                 which a direct session is already open.
    1541                 The remote session provides some level of control over the VM
    1542                 execution (using the IConsole interface) to the caller. Within
    1543                 the remote session context, it is not possible to change any
    1544                 static VM settings (such as name, HDD configuration, etc.).</p>
    1545                 <p>As opposed to <link to="#openRemoteSession()"/>, the number of
    1546                 remote sessions opened this way is not limited by the API.</p>
    1547                 <note>
    1548                     It is impossible to open a remote session with the machine
    1549                     that doesn't have an open direct session.
    1550                 </note>
    1551                 <see>openRemoteSession</see>
    1552             </desc>
    1553             <param name="session" type="ISession" dir="in">
    1554                 <desc>
    1555                     Session object that will represent the open remote session
    1556                     after successful method invocation. This object must not
    1557                     represent an already open session.
    1558                     <note>
    1559                         This session will be automatically closed when the peer
    1560                         (direct) session dies or gets closed.
    1561                     </note>
    1562                 </desc>
    1563             </param>
    1564             <param name="machineId" type="uuid" dir="in">
    1565                 <desc>ID of the virtual machine to open a session with.</desc>
    1566             </param>
    1567         </method>
    1568 
    1569         <method name="registerCallback">
    1570             <param name="callback" type="IVirtualBoxCallback" dir="in"/>
    1571         </method>
    1572 
    1573         <method name="unregisterCallback">
    1574             <param name="callback" type="IVirtualBoxCallback" dir="in"/>
    1575         </method>
    1576 
    1577     </interface>
    1578 
    1579     <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
    1580            namespace="virtualbox.org">
    1581         <interface name="IVirtualBox" default="yes"/>
    1582     </class>
    1583 
    1584     <!--
    1585     // IMachine
    1586     /////////////////////////////////////////////////////////////////////////
    1587     -->
    1588 
    1589     <enumerator
    1590         name="IMachineEnumerator" type="IMachine"
    1591         uuid="1b554149-be0a-4465-9252-9ff8f420af55"
    1592     />
    1593 
    1594     <collection
    1595         name="IMachineCollection" type="IMachine" enumerator="IMachineEnumerator"
    1596         uuid="FD443EC1-3007-4F5B-9282-D72760A66916"
    1597         readonly="yes"
    1598     />
    1599 
    1600     <interface
    1601         name="IInternalMachineControl" extends="$unknown"
    1602         uuid="67ef427d-5f01-4791-a45e-ae5e646ed7c6"
    1603         internal="yes"
    1604         wsmap="suppress"
    1605     >
    1606         <method name="updateState">
    1607             <desc>
    1608                 Updates the VM state.
    1609                 <note>
    1610                     This operation will also update the settings file with
    1611                     the correct information about the saved state file
    1612                     and delete this file from disk when appropriate.
    1613                 </note>
    1614             </desc>
    1615             <param name="state" type="MachineState" dir="in"/>
    1616         </method>
    1617 
    1618         <method name="getIPCId">
    1619             <param name="id" type="wstring" dir="return"/>
    1620         </method>
    1621 
    1622         <method name="runUSBDeviceFilters">
    1623             <desc>
    1624                 Asks the server to run USB devices filters of the associated
    1625                 machine against the given USB device and tell if there is
    1626                 a match.
    1627                 <note>
    1628                     Intended to be used only for remote USB devices. Local
    1629                     ones don't require to call this method (this is done
    1630                     implicitly by the Host and USBProxyService).
    1631                 </note>
    1632             </desc>
    1633             <param name="device" type="IUSBDevice" dir="in"/>
    1634             <param name="matched" type="boolean" dir="return"/>
    1635         </method>
    1636 
    1637         <method name="captureUSBDevice">
    1638             <desc>
    1639                 Requests a capture of the given host USB device.
    1640                 When the request is completed, the VM process will
    1641                 get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
    1642                 notification.
    1643             </desc>
    1644             <param name="id" type="uuid" dir="in"/>
    1645         </method>
    1646 
    1647         <method name="releaseUSBDevice">
    1648             <desc>
    1649                 Requests to release the given USB device.
    1650                 When the request is completed, the VM process will
    1651                 get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
    1652                 notification.
    1653                 <note>
    1654                     The server must run its own filters and filters of all VMs
    1655                     but this one on all released devices as if they were just
    1656                     attached to the host computer.
    1657                 </note>
    1658             </desc>
    1659             <param name="id" type="uuid" dir="in"/>
    1660         </method>
    1661 
    1662         <method name="autoCaptureUSBDevices">
    1663             <desc>
    1664                 Requests a capture all matching USB devices attached to the host.
    1665                 When the request is completed, the VM process will
    1666                 get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
    1667                 notification per every captured device.
    1668             </desc>
    1669         </method>
    1670 
    1671         <method name="releaseAllUSBDevices">
    1672             <desc>
    1673                 Releases all USB devices that are captured by this VM because
    1674                 the VM has been terminated.
    1675                 <note>
    1676                     The server must run its own filters and filters of all VMs
    1677                     but this one on all released devices as if they were just
    1678                     attached to the host computer.
    1679                 </note>
    1680             </desc>
    1681         </method>
    1682 
    1683         <method name="onSessionEnd">
    1684             <desc>
    1685                 Triggered by the given session object when the session is about
    1686                 to close normally.
    1687             </desc>
    1688             <param name="session" type="ISession" dir="in">
    1689                 <desc>Session that is being closed</desc>
    1690             </param>
    1691             <param name="progress" type="IProgress" dir="return">
    1692                 <desc>
    1693                     Used to wait until the corresponding machine is actually
    1694                     deassociated from the given session on the server.
    1695                     Returned only when this session is a direct one.
    1696                 </desc>
    1697             </param>
    1698         </method>
    1699 
    1700         <method name="beginSavingState">
    1701             <desc>
    1702                 Called by the VM process to inform the server it wants to
    1703                 save the current state and stop the VM execution.
    1704             </desc>
    1705             <param name="progress" type="IProgress" dir="in">
    1706                 <desc>
    1707                     Progress object created by the VM process to wait until
    1708                     the state is saved.
    1709                 </desc>
    1710             </param>
    1711             <param name="stateFilePath" type="wstring" dir="out">
    1712                 <desc>
    1713                     File path the VM process must save the execution state to.
    1714                 </desc>
    1715             </param>
    1716         </method>
    1717 
    1718         <method name="endSavingState">
    1719             <desc>
    1720                 Called by the VM process to inform the server that saving
    1721                 the state previously requested by #beginSavingState is either
    1722                 successfully finished or there was a failure.
    1723             </desc>
    1724 
    1725             <param name="success" type="boolean" dir="in">
    1726                 <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
    1727             </param>
    1728         </method>
    1729 
    1730         <method name="beginTakingSnapshot">
    1731             <desc>
    1732                 Called by the VM process to inform the server it wants to
    1733                 take a snapshot.
    1734             </desc>
    1735             <param name="initiator" type="IConsole" dir="in">
    1736                 <desc>The console object that initiated this call.</desc>
    1737             </param>
    1738             <param name="name" type="wstring" dir="in">
    1739                 <desc>Snapshot name</desc>
    1740             </param>
    1741             <param name="description" type="wstring" dir="in">
    1742                 <desc>Snapshot description</desc>
    1743             </param>
    1744             <param name="progress" type="IProgress" dir="in">
    1745                 <desc>
    1746                     Progress object created by the VM process to wait until
    1747                     the state is saved (only for online snapshots).
    1748                 </desc>
    1749             </param>
    1750             <param name="stateFilePath" type="wstring" dir="out">
    1751                 <desc>
    1752                     File path the VM process must save the execution state to.
    1753                 </desc>
    1754             </param>
    1755             <param name="serverProgress" type="IProgress" dir="out">
    1756                 <desc>
    1757                     Progress object created by the server process to wait until
    1758                     the snapshot is taken (VDI diff creation, etc.).
    1759                 </desc>
    1760             </param>
    1761         </method>
    1762 
    1763         <method name="endTakingSnapshot">
    1764             <desc>
    1765                 Called by the VM process to inform the server that the snapshot
    1766                 previously requested by #beginTakingSnapshot is either
    1767                 successfully taken or there was a failure.
    1768             </desc>
    1769 
    1770             <param name="success" type="boolean" dir="in">
    1771                 <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
    1772             </param>
    1773         </method>
    1774 
    1775         <method name="discardSnapshot">
    1776             <desc>
    1777                 Gets called by IConsole::discardSnapshot.
    1778             </desc>
    1779             <param name="initiator" type="IConsole" dir="in">
    1780                 <desc>The console object that initiated this call.</desc>
    1781             </param>
    1782             <param name="id" type="uuid" dir="in">
    1783                 <desc>UUID of the snapshot to discard.</desc>
    1784             </param>
    1785             <param name="machineState" type="MachineState" dir="out">
    1786                 <desc>New machine state after this operation is started.</desc>
    1787             </param>
    1788             <param name="progress" type="IProgress" dir="return">
    1789                 <desc>Progress object to track the operation completion.</desc>
    1790             </param>
    1791         </method>
    1792 
    1793         <method name="discardCurrentState">
    1794             <desc>
    1795                 Gets called by IConsole::discardCurrentState.
    1796             </desc>
    1797             <param name="initiator" type="IConsole" dir="in">
    1798                 <desc>The console object that initiated this call.</desc>
    1799             </param>
    1800             <param name="machineState" type="MachineState" dir="out">
    1801                 <desc>New machine state after this operation is started.</desc>
    1802             </param>
    1803             <param name="progress" type="IProgress" dir="return">
    1804                 <desc>Progress object to track the operation completion.</desc>
    1805             </param>
    1806         </method>
    1807 
    1808         <method name="discardCurrentSnapshotAndState">
    1809             <desc>
    1810                 Gets called by IConsole::discardCurrentSnapshotAndState.
    1811             </desc>
    1812             <param name="initiator" type="IConsole" dir="in">
    1813                 <desc>The console object that initiated this call.</desc>
    1814             </param>
    1815             <param name="machineState" type="MachineState" dir="out">
    1816                 <desc>New machine state after this operation is started.</desc>
    1817             </param>
    1818             <param name="progress" type="IProgress" dir="return">
    1819                 <desc>Progress object to track the operation completion.</desc>
    1820             </param>
    1821         </method>
    1822 
    1823     </interface>
    1824 
    1825     <enum
    1826         name="BIOSBootMenuMode"
    1827         uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
    1828     >
     679    <attribute name="version" type="wstring" readonly="yes">
     680      <desc>
     681        A string representing the version number of the product. The
     682        format is 3 integer numbers divided by dots (e.g. 1.0.1). The
     683        last number represents the build number and will frequently change.
     684      </desc>
     685    </attribute>
     686
     687    <attribute name="homeFolder" type="wstring" readonly="yes">
     688      <desc>
     689        Full path to the directory where the global settings file,
     690        <tt>VirtualBox.xml</tt>, is stored.
     691
     692        In this version of VirtualBox, the value of this property is
     693        always <tt>&lt;user_dir&gt;/.VirtualBox</tt> (where
     694        <tt>&lt;user_dir&gt;</tt> is the path to the user directory,
     695        as determined by the host OS), and cannot be changed.
     696
     697        This path is also used as the base to resolve relative paths in
     698        places where relative paths are allowed (unless otherwise
     699        expressly indicated).
     700      </desc>
     701    </attribute>
     702
     703    <attribute name="host" type="IHost" readonly="yes">
     704      <desc>Associated host object.</desc>
     705    </attribute>
     706
     707    <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
     708      <desc>Associated system information object.</desc>
     709    </attribute>
     710
     711    <attribute name="machines" type="IMachineCollection" readonly="yes"/>
     712
     713    <attribute name="hardDisks" type="IHardDiskCollection" readonly="yes">
     714      <desc>
     715        A collection of hard disk objects registered within this
     716        VirtualBox instance.
     717        This collection contains only "top-level" (basic or independent)
     718        hard disk images, but not differencing ones. All differencing
     719        images of the given top-level image (i.e. all its children) can
     720        be enumerated using <link to="IHardDisk::children"/>.
     721      </desc>
     722    </attribute>
     723
     724    <attribute name="DVDImages" type="IDVDImageCollection" readonly="yes"/>
     725
     726    <attribute name="FloppyImages" type="IFloppyImageCollection" readonly="yes"/>
     727
     728    <attribute name="progressOperations" type="IProgressCollection" readonly="yes"/>
     729
     730    <attribute name="guestOSTypes" type="IGuestOSTypeCollection" readonly="yes"/>
     731
     732    <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
     733      <desc>
     734        Collection of globally shared folders. These folders
     735        are shared automatically upon VirtualBox server startup and
     736        available only to every virtual machine.
     737
     738        New folders to share are added to the collection using
     739        <link to="#createSharedFolder"/>. An existing shared folder can
     740        be removed using <link to="#removeSharedFolder"/>.
     741      </desc>
     742    </attribute>
     743
     744    <method name="createMachine">
     745      <desc>
     746        Creates a new virtual machine.
     747
     748        Every machine has a <i>settings file</i> that is used to store
     749        the machine configuration. This file is stored in the directory
     750        called <i>machine settings subfolder</i>. Both the subfolder
     751        and the settings file have the same name that corresponds to the
     752        name of the virtual machine. You can specify where
     753        to create the machine settings subfolder using the @a
     754        baseFolder argument. The base folder can be absolute (full path)
     755        or relative to the <link to="IVirtualBox::homeFolder">
     756          VirtualBox home directory</link>.
     757
     758        If a null or empty string is given as the base folder (which is
     759        recommended), the <link to="ISystemProperties::defaultMachineFolder">
     760          default machine settings folder</link> will be used as the base
     761        folder to create the machine settings subfolder and file. In
     762        any case, the full path to the settings file will look like:
     763        <pre>
     764          &lt;base_folder&gt;/&lt;machine_name&gt;/&lt;machine_name&gt;.xml</pre>
     765
     766        Note that the configuration of the newly created machine is not
     767        saved to disk (and therefore no settings subfolder and file are
     768        created) until <link to="IMachine::saveSettings()"/> is called.
     769
     770        You should also specify a valid name for the machine.
     771        See the <link to="IMachine::name"/> property
     772        description for more details about the machine name.
     773
     774        The created machine remains
     775        unregistered until you call <link to="#registerMachine()"/>.
     776
     777        <note>
     778          There is no way to change the name of the settings file or
     779          subfolder of the created machine directly.
     780        </note>
     781      </desc>
     782      <param name="baseFolder" type="wstring" dir="in">
    1829783        <desc>
    1830             This represents the BIOS boot menu state.
     784          Name of the folder where to create the machine settings
     785          subfolder containing the settings file.
    1831786        </desc>
    1832 
    1833         <const name="Disabled"       value="0"/>
    1834         <const name="MenuOnly"       value="1"/>
    1835         <const name="MessageAndMenu" value="2"/>
    1836     </enum>
    1837 
    1838     <interface
    1839         name="IBIOSSettings" extends="$unknown"
    1840         uuid="946b83be-c5aa-4089-859d-db694f57d5ef"
    1841         wsmap="struct"
    1842     >
    1843         <attribute name="LogoFadeIn" type="boolean">
    1844             <desc>Fade in flag for BIOS logo animation.</desc>
    1845         </attribute>
    1846 
    1847         <attribute name="LogoFadeOut" type="boolean">
    1848             <desc>Fade out flag for BIOS logo animation.</desc>
    1849         </attribute>
    1850 
    1851         <attribute name="LogoDisplayTime" type="unsigned long">
    1852             <desc>BIOS logo display time in milliseconds (0 = default).</desc>
    1853         </attribute>
    1854 
    1855         <attribute name="LogoImagePath" type="wstring">
    1856             <desc>Local file system path for external BIOS image.</desc>
    1857         </attribute>
    1858 
    1859         <attribute name="BootMenuMode" type="BIOSBootMenuMode">
    1860             <desc>Mode of the BIOS boot device menu.</desc>
    1861         </attribute>
    1862 
    1863         <attribute name="ACPIEnabled" type="boolean">
    1864             <desc>ACPI support flag.</desc>
    1865         </attribute>
    1866 
    1867         <attribute name="IOAPICEnabled" type="boolean">
    1868             <desc>
    1869                 IO APIC support flag. If set, VirtualBox will provide an IO APIC
    1870                 and support IRQs above 15.
    1871             </desc>
    1872         </attribute>
    1873 
    1874         <attribute name="TimeOffset" type="long long">
    1875             <desc>
    1876                 Offset in milliseconds from the host system time. This allows for
    1877                 guests running with a different system date/time than the host.
    1878                 It is equivalent to setting the system date/time in the BIOS other
    1879                 than it's not an absolute value but a relative one. Guest Additions
    1880                 time synchronization also honors this offset.
    1881             </desc>
    1882         </attribute>
    1883 
    1884     </interface>
    1885 
    1886     <interface
    1887         name="IMachine" extends="$unknown"
    1888         uuid="0332de0e-ce75-461f-8c6f-0fa42616404a"
    1889         wsmap="managed"
    1890     >
    1891         <attribute name="parent" type="IVirtualBox" readonly="yes">
    1892             <desc>Associated parent obect.</desc>
    1893         </attribute>
    1894 
    1895         <attribute name="accessible" type="boolean" readonly="yes">
    1896             <desc>
    1897                 Whether this virtual machine is currently accessible or not.
    1898 
    1899                 The machine is considered to be inaccessible when:
    1900                 <ul>
    1901                     <li>It is a registered virtual machine, and
    1902                     </li>
    1903                     <li>Its settings file is inaccessible (for example, it is
    1904                     located on a network share that is not accessible during
    1905                     VirtualBox startup, or becomes inaccessible later, or if
    1906                     the settings file can be read but is invalid).
    1907                     </li>
    1908                 </ul>
    1909 
    1910                 Otherwise, the value of this property is always <tt>true</tt>.
    1911 
    1912                 Every time this property is read, the accessibility state of
    1913                 this machine is re-evaluated. If the returned value is |false|,
    1914                 the <link to="#accessError"/> property may be used to get the
    1915                 detailed error information describing the reason of
    1916                 inaccessibility.
    1917 
    1918                 When the machine is inaccessible, only the following properties
    1919                 can be used on it:
    1920                 <ul>
    1921                     <li><link to="#parent"/></li>
    1922                     <li><link to="#id"/></li>
    1923                     <li><link to="#settingsFilePath"/></li>
    1924                     <li><link to="#accessible"/></li>
    1925                     <li><link to="#accessError"/></li>
    1926                 </ul>
    1927 
    1928                 An attempt to access any other property or method will return
    1929                 an error.
    1930 
    1931                 The only possible action you can perform on an inaccessible
    1932                 machine is to unregister it using the
    1933                 <link to="IVirtualBox::unregisterMachine"/> call (or, to check
    1934                 for the accessibility state once more by querying this
    1935                 property).
    1936 
    1937                 <note>
    1938                     In the current implementation, once this property returns
    1939                     <tt>true</tt>, the machine will never become inaccessible
    1940                     later, even if its settings file cannot be successfully
    1941                     read/written any more (at least, until the VirtualBox
    1942                     server is restarted). This limitation may be removed in
    1943                     future releases.
    1944                 </note>
    1945             </desc>
    1946         </attribute>
    1947 
    1948         <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
    1949             <desc>
    1950                 Error information describing the reason of machine
    1951                 inaccessibility.
    1952 
    1953                 Reading this property is only valid after the last call to
    1954                 <link to="#accessible"/> returned <tt>false</tt> (i.e. the
    1955                 machine is currently unaccessible). Otherwise, a null
    1956                 IVirtualBoxErrorInfo object will be returned.
    1957             </desc>
    1958         </attribute>
    1959 
    1960         <attribute name="name" type="wstring">
    1961             <desc>
    1962                 Name of the virtual machine.
    1963 
    1964                 Besides being used for human-readable identification purposes
    1965                 everywhere in VirtualBox, the virtual machine name is also used
    1966                 as a name of the machine's settings file and as a name of the
    1967                 subdirectory this settings file resides in. Thus, every time you
    1968                 change the value of this property, the settings file will be
    1969                 renamed once you call <link to="#saveSettings()"/> to confirm the
    1970                 change. The containing subdirectory will be also renamed, but
    1971                 only if it has exactly the same name as the settings file
    1972                 itself prior to changing this property (for backward compatibility
    1973                 with previous API releases). The above implies the following
    1974                 limitations:
    1975                 <ul>
    1976                 <li>The machine name cannot be empty.</li>
    1977                 <li>The machine name can contain only characters that are valid
    1978                     file name characters according to the rules of the file
    1979                     system used to store VirtualBox configuration.</li>
    1980                 <li>You cannot have two or more machines with the same name
    1981                     if they use the same subdirectory for storing the machine
    1982                     settings files.</li>
    1983                 <li>You cannot change the name of the machine if it is running,
    1984                     or if any file in the directory containing the settings file
    1985                     is being used by another running machine or by any other
    1986                     process in the host operating system at a time when
    1987                     <link to="#saveSettings()"/> is called.
    1988                 </li>
    1989                 </ul>
    1990                 If any of the above limitations are hit, <link to="#saveSettings()"/>
    1991                 will return an appropriate error message explaining the exact
    1992                 reason and the changes you made to this machine will not be
    1993                 saved.
    1994                 <note>
    1995                     For "legacy" machines created using the
    1996                     <link to="IVirtualBox::createLegacyMachine()"/> call,
    1997                     the above naming limitations do not apply because the
    1998                     machine name does not affect the settings file name.
    1999                     The settings file name remains the same as it was specified
    2000                     during machine creation and never changes.
    2001                 </note>
    2002             </desc>
    2003         </attribute>
    2004 
    2005         <attribute name="description" type="wstring">
    2006             <desc>
    2007                 Description of the virtual machine.
    2008 
    2009                 The description attribute can contain any text and is
    2010                 typically used to describe the hardware and software
    2011                 configuration of the virtual machine in detail (i.e. network
    2012                 settings, versions of the installed software and so on).
    2013             </desc>
    2014         </attribute>
    2015 
    2016         <attribute name="id" type="uuid" readonly="yes">
    2017             <desc>UUID of the virtual machine.</desc>
    2018         </attribute>
    2019 
    2020         <attribute name="OSTypeId" type="wstring">
    2021             <desc>
    2022                 User-defined identifier of the Guest OS type.
    2023                 You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
    2024                 an IGuestOSType object representing details about the given
    2025                 Guest OS type.
    2026                 <note>
    2027                     This value may differ from the value returned by
    2028                     <link to="IGuest::OSTypeId"/> if Guest Additions are
    2029                     installed to the guest OS.
    2030                 </note>
    2031             </desc>
    2032         </attribute>
    2033 
    2034         <attribute name="memorySize" type="unsigned long">
    2035             <desc>Sytem memory size in megabytes.</desc>
    2036         </attribute>
    2037 
    2038         <attribute name="VRAMSize" type="unsigned long">
    2039             <desc>Video memory size in megabytes.</desc>
    2040         </attribute>
    2041 
    2042         <attribute name="MonitorCount" type="unsigned long">
    2043             <desc>
    2044                 Number of virtual monitors.
    2045                 <note>
    2046                     Only effective on Windows XP and later guests with
    2047                     Guest Additions installed.
    2048                 </note>
    2049             </desc>
    2050         </attribute>
    2051 
    2052         <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
    2053             <desc>Object containing all BIOS settings.</desc>
    2054         </attribute>
    2055 
    2056         <attribute name="HWVirtExEnabled" type="TriStateBool">
    2057             <desc>
    2058                 This setting determines whether VirtualBox will try to make use of
    2059                 the host CPU's hardware virtualization extensions such as Intel VT-x
    2060                 and AMD SVM. Note that in case such extensions are not available,
    2061                 they will not be used.
    2062             </desc>
    2063         </attribute>
    2064 
    2065         <attribute name="snapshotFolder" type="wstring">
    2066             <desc>
    2067                 Full path to the directory used to store snapshot data
    2068                 (difrerencing hard disks and saved state files) of this machine.
    2069 
    2070                 The initial value of this property is
    2071                 <tt>&lt;</tt><link to="#settingsFilePath">
    2072                 path_to_settings_file</link><tt>&gt;/&lt;</tt>
    2073                 <link to="#id">machine_uuid</link>
    2074                 <tt>&gt;</tt>.
    2075 
    2076                 Currently, it is an error to try to change this property on
    2077                 a machine that has snapshots (because this would require to
    2078                 move possibly large files to a different location).
    2079                 A separate method will be available for this purpose later.
    2080 
    2081                 <note>
    2082                     Setting this property to <tt>null</tt> will restore the
    2083                     initial value.
    2084                 </note>
    2085                 <note>
    2086                     When setting this property, the specified path can be
    2087                     absolute (full path) or relative to the directory where the
    2088                     <link to="#settingsFilePath">machine settings file</link>
    2089                     is located. When reading this property, a full path is
    2090                     always returned.
    2091                 </note>
    2092                 <note>
    2093                     The specified path may not exist, it will be created
    2094                     when necessary.
    2095                 </note>
    2096             </desc>
    2097         </attribute>
    2098 
    2099         <attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
    2100             <desc>VRDP server object.</desc>
    2101         </attribute>
    2102 
    2103         <attribute name="hardDiskAttachments" type="IHardDiskAttachmentCollection" readonly="yes">
    2104             <desc>Collection of hard disks attached to the machine.</desc>
    2105         </attribute>
    2106 
    2107         <attribute name="DVDDrive" type="IDVDDrive" readonly="yes">
    2108             <desc>Associated DVD drive object.</desc>
    2109         </attribute>
    2110 
    2111         <attribute name="FloppyDrive" type="IFloppyDrive" readonly="yes">
    2112             <desc>Associated floppy drive object.</desc>
    2113         </attribute>
    2114 
    2115         <attribute name="USBController" type="IUSBController" readonly="yes">
    2116             <desc>Associated USB controller object.</desc>
    2117         </attribute>
    2118 
    2119         <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
    2120             <desc>Associated audio adapter, always present.</desc>
    2121         </attribute>
    2122 
    2123         <attribute name="settingsFilePath" type="wstring" readonly="yes">
    2124             <desc>
    2125                 Full name of the file containing machine settings data.
    2126             </desc>
    2127         </attribute>
    2128 
    2129         <attribute name="settingsModified" type="boolean" readonly="yes">
    2130             <desc>
    2131                 Whether the settings of this machine have been modified
    2132                 (but neither yet saved nor discarded).
    2133                 <note>
    2134                     Reading this property is only valid on instances returned
    2135                     by <link to="ISession::machine"/> and on new machines
    2136                     created by <link to="IVirtualBox::createMachine"/> or opened
    2137                     by <link to="IVirtualBox::openMachine"/> but not
    2138                     yet registered, or on unregistered machines after calling
    2139                     <link to="IVirtualBox::unregisterMachine"/>. For all other
    2140                     cases, the settigs can never be modified.
    2141                 </note>
    2142                 <note>
    2143                     For newly created unregistered machines, the value of this
    2144                     property is always TRUE until <link to="#saveSettings"/>
    2145                     is called (no matter if any machine settings have been
    2146                     changed after the creation or not). For opened machines
    2147                     the value is set to FALSE (and then follows to normal rules).
    2148                 </note>
    2149             </desc>
    2150         </attribute>
    2151 
    2152         <attribute name="sessionState" type="SessionState" readonly="yes">
    2153             <desc>Current session state for this machine.</desc>
    2154         </attribute>
    2155 
    2156         <attribute name="sessionType" type="wstring" readonly="yes">
    2157             <desc>
    2158                 Type of the session.  If <link to="#sessionState"/> is
    2159                 SessionSpawning or SessionOpen, this attribute contains the
    2160                 same value as passed to the
    2161                 <link to="IVirtualBox::openRemoteSession()"/> method in the @a
    2162                 type parameter. If the session was opened directly using
    2163                 <link to="IVirtualBox::openSession()"/>, or if
    2164                 <link to="#sessionState"/> is SessionClosed, the value of this
    2165                 attribute is @c null.
    2166             </desc>
    2167         </attribute>
    2168 
    2169         <attribute name="sessionPid" type="unsigned long" readonly="yes">
    2170             <desc>
    2171                 Identifier of the session process. This attribute contains the
    2172                 platform-dependent identifier of the process that has opened a
    2173                 direct session for this machine using the
    2174                 <link to="IVirtualBox::openSession()"/> call. The returned value
    2175                 is only valid if <link to="#sessionState"/> is SessionOpen or
    2176                 SessionClosing (i.e. a session is currently open or being
    2177                 closed) by the time this property is read.
    2178             </desc>
    2179         </attribute>
    2180 
    2181         <attribute name="state" type="MachineState" readonly="yes">
    2182             <desc>Current execution state of this machine.</desc>
    2183         </attribute>
    2184 
    2185         <attribute name="lastStateChange" type="long long" readonly="yes">
    2186             <desc>
    2187                 Time stamp of the last execution state change,
    2188                 in milliseconds since 1970-01-01 UTC.
    2189             </desc>
    2190         </attribute>
    2191 
    2192         <attribute name="stateFilePath" type="wstring" readonly="yes">
    2193             <desc>
    2194                 Full path to the file that stores the execution state of
    2195                 the machine when it is in the <link to="MachineState::Saved"/>
    2196                 state.
    2197                 <note>
    2198                     When the machine is not in the Saved state, this attribute
    2199                     <tt>null</tt>.
    2200                 </note>
    2201             </desc>
    2202         </attribute>
    2203 
    2204         <attribute name="logFolder" type="wstring" readonly="yes">
    2205             <desc>
    2206                 Full path to the folder that stores a set of rotated log files
    2207                 recorded during machine execution. The most recent log file is
    2208                 named <tt>VBox.log</tt>, the previous log file is
    2209                 named <tt>VBox.log.1</tt> and so on (upto <tt>VBox.log.3</tt>
    2210                 in the current version).
    2211             </desc>
    2212         </attribute>
    2213 
    2214         <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
    2215             <desc>
    2216                 Current snapshot of this machine.
    2217                 <note>
    2218                     A <tt>null</tt> object is returned if the machine doesn't
    2219                     have snapshots.
    2220                 </note>
    2221                 <see><link to="ISnapshot"/></see>
    2222             </desc>
    2223         </attribute>
    2224 
    2225         <attribute name="snapshotCount" type="unsigned long" readonly="yes">
    2226             <desc>
    2227                 Number of snapshots taken on this machine. Zero means the
    2228                 machine doesn't have any snapshots.
    2229             </desc>
    2230         </attribute>
    2231 
    2232         <attribute name="currentStateModified" type="boolean" readonly="yes">
    2233             <desc>
    2234                 Returns <tt>true</tt> if the current state of the machine is not
    2235                 identical to the state stored in the current snapshot.
    2236 
    2237                 The current state is identical to the current snapshot right
    2238                 after one of the following calls are made:
    2239                 <ul>
    2240                     <li><link to="IConsole::discardCurrentState"/> or
    2241                         <link to="IConsole::discardCurrentSnapshotAndState"/>
    2242                     </li>
    2243                     <li><link to="IConsole::takeSnapshot"/> (issued on a
    2244                          powered off or saved machine, for which
    2245                          <link to="#settingsModified"/> returns <tt>false</tt>)
    2246                     </li>
    2247                     <li><link to="IMachine::setCurrentSnapshot"/>
    2248                     </li>
    2249                 </ul>
    2250 
    2251                 The current state remains identical until one of the following
    2252                 happens:
    2253                 <ul>
    2254                     <li>settings of the machine are changed</li>
    2255                     <li>the saved state is discarded</li>
    2256                     <li>the current snapshot is discarded</li>
    2257                     <li>an attempt to execute the machine is made</li>
    2258                 </ul>
    2259 
    2260                 <note>
    2261                    For machines that don't have snapshots, this property is
    2262                    always <tt>false</tt>.
    2263                 </note>
    2264             </desc>
    2265         </attribute>
    2266 
    2267         <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
    2268             <desc>
    2269                 Collection of shared folders for this machine. These folders
    2270                 are shared automatically upon machine startup and available only
    2271                 to the guest OS installed within this machine.
    2272 
    2273                 New folders to share are added to the collection using
    2274                 <link to="#createSharedFolder"/>. An existing shared folder can
    2275                 be removed using <link to="#removeSharedFolder"/>.
    2276             </desc>
    2277         </attribute>
    2278 
    2279         <attribute name="clipboardMode" type="ClipboardMode">
    2280             <desc>
    2281                 Synchronization mode between the host OS clipboard
    2282                 and the guest OS clipboard.
    2283             </desc>
    2284         </attribute>
    2285 
    2286         <method name="setBootOrder">
    2287             <desc>
    2288                 Puts the given device to the specified position in
    2289                 the boot order.
    2290 
    2291                 @todo [remove?]
    2292                 If the machine can have more than one device of the given type
    2293                 (such as hard disks), then a separate method should be used to
    2294                 specify the boot order for individual devices. Using this method
    2295                 in such cases will put the first device in the group
    2296                 (for example, a hard disk attached as Master on the primary
    2297                 IDE controller) to the given position.
    2298 
    2299                 To indicate that no any device is associated with the
    2300                 given position, <link to="DeviceType::NoDevice"/> should be used.
    2301 
    2302                 @todo setHardDiskBootOrder(), setNetworkBootOrder()
    2303             </desc>
    2304             <param name="position" type="unsigned long" dir="in">
    2305                 <desc>
    2306                     Position in the boot order (<tt>1</tt> to the total number of
    2307                     devices the machine can boot from, as returned by
    2308                     <link to="ISystemProperties::maxBootPosition"/>).
    2309                 </desc>
    2310             </param>
    2311             <param name="device" type="DeviceType" dir="in">
    2312                 <desc>
    2313                     The type of the device used to boot at the given position.
    2314                 </desc>
    2315             </param>
    2316         </method>
    2317 
    2318         <method name="getBootOrder" const="yes">
    2319             <desc>
    2320                 Returns the device type that occupies the specified
    2321                 position in the boot order.
    2322 
    2323                 @todo [remove?]
    2324                 If the machine can have more than one device of the returned type
    2325                 (such as hard disks), then a separate method should be used to
    2326                 retrieve the individual device that occupies the given position.
    2327 
    2328                 If here are no devices at the given position, then
    2329                 <link to="DeviceType::NoDevice"/> is returned.
    2330 
    2331                 @todo getHardDiskBootOrder(), getNetworkBootOrder()
    2332             </desc>
    2333             <param name="order" type="unsigned long" dir="in">
    2334                 <desc>
    2335                     Position in the boot order (<tt>1</tt> to the total number of
    2336                     devices the machine can boot from, as returned by
    2337                     <link to="ISystemProperties::maxBootPosition"/>).
    2338                 </desc>
    2339             </param>
    2340             <param name="device" type="DeviceType" dir="return">
    2341                 <desc>
    2342                     Device at the given position.
    2343                 </desc>
    2344             </param>
    2345         </method>
    2346 
    2347         <method name="attachHardDisk">
    2348             <desc>
    2349 
    2350                 Attaches a virtual hard disk identified by the given UUID to the
    2351                 given device slot of the given controller. The specified device
    2352                 must not have another disk attached and the given hard disk must
    2353                 not be already attached to this machine.
    2354 
    2355                 See <link to="IHardDisk"/> for detailed information about
    2356                 attaching hard disks.
    2357 
    2358                 <note>You cannot attach a hard disk to a running machine. Also,
    2359                 you cannot attach a hard disk to a newly created machine until
    2360                 it is registered.</note>
    2361 
    2362                 <note>Attaching a hard disk to a machine creates a <i>lazy</i>
    2363                 attachment. In particular, no differeincing images are
    2364                 actually created until <link to="#saveSettings"/> is called to
    2365                 commit all changed settings.</note>
    2366 
    2367             </desc>
    2368             <param name="diskID" type="uuid" dir="in">
    2369                 <desc>UUID of the hard disk to attach.</desc>
    2370             </param>
    2371             <param name="controller" type="DiskControllerType" dir="in">
    2372                 <desc>Controller to attach the hard disk to.</desc>
    2373             </param>
    2374             <param name="device" type="long" dir="in">
    2375                 <desc>Device slot to attach the hard disk to.</desc>
    2376             </param>
    2377         </method>
    2378 
    2379         <method name="getHardDisk" const="yes">
    2380             <desc>
    2381                 Returns the hard disk attached to the
    2382                 given controller under the specified device number.
    2383             </desc>
    2384             <param name="controller" type="DiskControllerType" dir="in"/>
    2385             <param name="deviceNumber" type="long" dir="in"/>
    2386             <param name="hardDisk" type="IHardDisk" dir="return"/>
    2387         </method>
    2388 
    2389         <method name="detachHardDisk">
    2390             <desc>
    2391 
    2392                 Detaches the hard disk drive attached to the given device slot
    2393                 of the given controller.
    2394 
    2395                 See <link to="IHardDisk"/> for detailed information about
    2396                 attaching hard disks.
    2397 
    2398                 <note>You cannot detach a hard disk from a running
    2399                 machine.</note>
    2400 
    2401                 <note>Detaching a hard disk from a machine creates a <i>lazy</i>
    2402                 detachment. In particular, if the detached hard disk is a
    2403                 differencing hard disk, it is not actually deleted until <link
    2404                 to="#saveSettings"/> is called to commit all changed settings.
    2405                 Keep in mind, that doing <link to="#saveSettings"/> will
    2406                 <b>physically delete</b> all detached differencing hard disks,
    2407                 so be careful.</note>
    2408 
    2409             </desc>
    2410             <param name="controller" type="DiskControllerType" dir="in">
    2411                 <desc>Controller to dettach the hard disk from.</desc>
    2412             </param>
    2413             <param name="device" type="long" dir="in">
    2414                 <desc>Device slot to dettach the hard disk from.</desc>
    2415             </param>
    2416         </method>
    2417 
    2418         <method name="getNetworkAdapter" const="yes">
    2419             <desc>
    2420                 Returns the network adapter associated with the given slot.
    2421                 Slots are numbered sequentially, starting with zero. The total
    2422                 number of adapters per every machine is defined by the
    2423                 <link to="ISystemProperties::networkAdapterCount"/> property,
    2424                 so the maximum slot number is one less than that property's value.
    2425             </desc>
    2426             <param name="slot" type="unsigned long" dir="in"/>
    2427             <param name="adapter" type="INetworkAdapter" dir="return"/>
    2428         </method>
    2429 
    2430         <method name="getNextExtraDataKey">
    2431             <desc>
    2432                 Returns the extra data key name following the supplied key.
    2433                 An error is returned if the supplied key does not exist.
    2434                 NULL is returned if the supplied key is the last key.
    2435                 When supplying NULL for the key, the first item is returned.
    2436                 NextValue is an optional parameter and if supplied, the next
    2437                 key's value is returned as well.
    2438             </desc>
    2439             <param name="key" type="wstring" dir="in"/>
    2440             <param name="nextKey" type="wstring" dir="out"/>
    2441             <param name="nextValue" type="wstring" dir="out"/>
    2442         </method>
    2443 
    2444         <method name="getExtraData">
    2445             <desc>Returns associated extra data.</desc>
    2446             <param name="key" type="wstring" dir="in"/>
    2447             <param name="value" type="wstring" dir="return"/>
    2448         </method>
    2449 
    2450         <method name="setExtraData">
    2451             <desc>Sets associated extra data.</desc>
    2452             <param name="key" type="wstring" dir="in"/>
    2453             <param name="value" type="wstring" dir="in"/>
    2454         </method>
    2455 
    2456         <method name="saveSettings">
    2457             <desc>
    2458                 Saves any changes to machine settings made since the session
    2459                 has been opened or a new machine has been created, or since the
    2460                 last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
    2461                 For registered machines, new settings become visible to all
    2462                 other VirtualBox clients after successful invocation of this
    2463                 method.
    2464                 <note>
    2465                     The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
    2466                     notification event after the configuration has been successfully
    2467                     saved (only for registered machines).
    2468                 </note>
    2469                 <note>
    2470                     Calling this method is only valid on instances returned
    2471                     by <link to="ISession::machine"/> and on new machines
    2472                     created by <link to="IVirtualBox::createMachine"/> but not
    2473                     yet registered, or on unregistered machines after calling
    2474                     <link to="IVirtualBox::unregisterMachine"/>.
    2475                 </note>
    2476             </desc>
    2477         </method>
    2478 
    2479         <method name="discardSettings">
    2480             <desc>
    2481                 Discards any changes to the machine settings made since the session
    2482                 has been opened or since the last call to <link to="#saveSettings"/>
    2483                 or <link to="#discardSettings"/>.
    2484                 <note>
    2485                     Calling this method is only valid on instances returned
    2486                     by <link to="ISession::machine"/> and on new machines
    2487                     created by <link to="IVirtualBox::createMachine"/> or
    2488                     opened by <link to="IVirtualBox::openMachine"/> but not
    2489                     yet registered, or on unregistered machines after calling
    2490                     <link to="IVirtualBox::unregisterMachine"/>.
    2491                 </note>
    2492             </desc>
    2493         </method>
    2494 
    2495         <method name="deleteSettings">
    2496             <desc>
    2497                 Deletes the settings file of this machine from disk.
    2498                 The machine must not be registered in order for this operation
    2499                 to succeed.
    2500                 <note>
    2501                     <link to="#settingsModified"/> will return TRUE after this
    2502                     method successfully returns.
    2503                 </note>
    2504                 <note>
    2505                     Calling this method is only valid on instances returned
    2506                     by <link to="ISession::machine"/> and on new machines
    2507                     created by <link to="IVirtualBox::createMachine"/> or
    2508                     opened by <link to="IVirtualBox::openMachine"/> but not
    2509                     yet registered, or on unregistered machines after calling
    2510                     <link to="IVirtualBox::unregisterMachine"/>.
    2511                 </note>
    2512                 <note>
    2513                     The deleted machine settings file can be restored (saved again)
    2514                     by calling <link to="#saveSettings"/>.
    2515                 </note>
    2516             </desc>
    2517         </method>
    2518 
    2519         <method name="getSnapshot">
    2520             <desc>
    2521                 Returns a snapshot of this machine with the given UUID.
    2522                 A <tt>null</tt> UUID can be used to obtain the first snapshot
    2523                 taken on this machine. This is useful if you want to traverse
    2524                 the whole tree of snapshots starting from the root.
    2525             </desc>
    2526             <param name="id" type="uuid" dir="in">
    2527                 <desc>UUID of the snapshot to get</desc>
    2528             </param>
    2529             <param name="snapshot" type="ISnapshot" dir="return">
    2530                 <desc>Snapshot object with the given UUID.</desc>
    2531             </param>
    2532         </method>
    2533 
    2534         <method name="findSnapshot">
    2535             <desc>
    2536                 Returns a snapshot of this machine with the given name.
    2537             </desc>
    2538             <param name="name" type="wstring" dir="in">
    2539                 <desc>Name of the snapshot to find</desc>
    2540             </param>
    2541             <param name="snapshot" type="ISnapshot" dir="return">
    2542                 <desc>Snapshot object with the given name.</desc>
    2543             </param>
    2544         </method>
    2545 
    2546         <method name="setCurrentSnapshot">
    2547             <desc>
    2548                 Sets the current snapshot of this machine.
    2549                 <note>
    2550                     In the current implementation, this operation is not
    2551                     implemented.
    2552                 </note>
    2553             </desc>
    2554             <param name="id" type="uuid" dir="in">
    2555                 <desc>UUID of the snapshot to set as the current snapshot.</desc>
    2556             </param>
    2557         </method>
    2558 
    2559         <method name="createSharedFolder">
    2560             <desc>
    2561                 Creates a new shared folder by associating the given logical
    2562                 name with the given host path, adds it to the collection of
    2563                 shared folders and starts sharing it.
    2564                 Refer to the description of <link to="ISharedFolder"/> to read
    2565                 about logical name unicity.
    2566             </desc>
    2567             <param name="name" type="wstring" dir="in">
    2568                 <desc>Unique logical name of the shared folder.</desc>
    2569             </param>
    2570             <param name="hostPath" type="wstring" dir="in">
    2571                 <desc>Full path to the shared folder in the host file system.</desc>
    2572             </param>
    2573         </method>
    2574 
    2575         <method name="removeSharedFolder">
    2576             <desc>
    2577                 Removes a shared folder with the given name previously created
    2578                 by <link to="#createSharedFolder"/> from the collection of
    2579                 shared folders and stops sharing it.
    2580             </desc>
    2581             <param name="name" type="wstring" dir="in">
    2582                 <desc>Logical name of the shared folder to remove.</desc>
    2583             </param>
    2584         </method>
    2585 
    2586         <method name="canShowConsoleWindow">
    2587             <desc>
    2588                 Returns @c true if the VM console process can activate the
    2589                 console window and bring it to foreground on the desktop of
    2590                 the host PC.
    2591                 <note>
    2592                     This method will fail if a session for this machine is not
    2593                     currently open.
    2594                 </note>
    2595             </desc>
    2596             <param name="canShow" type="boolean" dir="return">
    2597                 <desc>
    2598                     @c true if the console window can be shown and @c
    2599                     false otherwise.
    2600                 </desc>
    2601             </param>
    2602         </method>
    2603 
    2604         <method name="showConsoleWindow">
    2605             <desc>
    2606                 Activates the console window and brings it to foreground on
    2607                 the desktop of the host PC. Many modern window managers on
    2608                 many platforms implement some sort of focus stealing
    2609                 prevention logic, so that it may be impossible to activate
    2610                 a window without the help of the currently active
    2611                 application. In this case, this method will return a non-zero
    2612                 identifier that represents the top-level window of the VM
    2613                 console process. The caller, if it represents a currently
    2614                 active process, is responsible to use this identifier (in a
    2615                 platform-dependent manner) to perform actual window
    2616                 activation.
    2617                 <note>
    2618                     This method will fail if a session for this machine is not
    2619                     currently open.
    2620                 </note>
    2621             </desc>
    2622             <param name="winId" type="unsigned long long" dir="return">
    2623                 <desc>
    2624                   Platform-dependent identifier of the top-level VM console
    2625                   window, or zero if this method has performed all actions
    2626                   necessary to implement the <i>show window</i> semantics for
    2627                   the given platform and/or VirtualBox front-end.
    2628                 </desc>
    2629             </param>
    2630         </method>
    2631 
    2632     </interface>
    2633 
    2634     <!--
    2635     // IConsole
    2636     /////////////////////////////////////////////////////////////////////////
    2637     -->
    2638 
    2639     <interface
    2640         name="IConsoleCallback" extends="$unknown"
    2641         uuid="ebd0c5f2-7b11-4508-803f-012099caee03"
    2642         wsmap="suppress"
    2643     >
    2644 
    2645         <method name="onMousePointerShapeChange">
    2646             <desc>
    2647                 Notification when the guest mouse pointer shape has
    2648                 changed. The new shape data is given.
    2649             </desc>
    2650             <param name="visible" type="boolean" dir="in">
    2651                 <desc>
    2652                     Flag whether the pointer is visible.
    2653                 </desc>
    2654             </param>
    2655             <param name="alpha" type="boolean" dir="in">
    2656                 <desc>
    2657                     Flag whether the pointer has an alpha channel.
    2658                 </desc>
    2659             </param>
    2660             <param name="xHot" type="unsigned long" dir="in">
    2661                 <desc>
    2662                     The pointer hot spot x coordinate.
    2663                 </desc>
    2664             </param>
    2665             <param name="yHot" type="unsigned long" dir="in">
    2666                 <desc>
    2667                     The pointer hot spot y coordinate.
    2668                 </desc>
    2669             </param>
    2670             <param name="width" type="unsigned long" dir="in">
    2671                 <desc>
    2672                     Width of the pointer shape in pixels.
    2673                 </desc>
    2674             </param>
    2675             <param name="height" type="unsigned long" dir="in">
    2676                 <desc>
    2677                     Height of the pointer shape in pixels.
    2678                 </desc>
    2679             </param>
    2680             <param name="shape" type="octet" mod="ptr" dir="in">
    2681                 <desc>
    2682                     Address of the shape buffer.
    2683 
    2684                     The buffer contains 1 bpp (bits per pixel) AND mask followed by 32 bpp XOR (color) mask.
    2685 
    2686                     For pointers without alpha channel the XOR mask pixels are 32 bit values: (lsb)BGR0(msb).
    2687                     For pointers with alpha channel the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
    2688 
    2689                     AND mask presents for pointers with alpha channel, so if the callback does not
    2690                     support alpha, the pointer could be displayed as a normal color pointer.
    2691 
    2692                     The AND mask is 1 bpp bitmap with byte aligned scanlines. Size of AND mask,
    2693                     therefore, is <tt>cbAnd = (width + 7) / 8 * height</tt>. The padding bits at the
    2694                     end of any scanline are undefined.
    2695 
    2696                     The XOR mask follows the AND mask on the next 4 bytes aligned offset:
    2697                     <tt>uint8_t *pXor = pAnd + (cbAnd + 3) &amp; ~3</tt>
    2698                     Bytes in the gap between the AND and the XOR mask are undefined.
    2699                     XOR mask scanlines have no gap between them and size of XOR mask is:
    2700                     <tt>cXor = width * 4 * height</tt>.
    2701 
    2702                     <note>
    2703                         If 'shape' is equal to 0, only pointer visibility is being changed.
    2704                     </note>
    2705                 </desc>
    2706             </param>
    2707         </method>
    2708 
    2709         <method name="onMouseCapabilityChange">
    2710             <desc>
    2711                 Notification when the mouse capabilities reported by the
    2712                 guest have changed. The new capabilities are passed.
    2713             </desc>
    2714             <param name="supportsAbsolute" type="boolean" dir="in"/>
    2715             <param name="needsHostCursor" type="boolean" dir="in"/>
    2716         </method>
    2717 
    2718         <method name="onKeyboardLedsChange">
    2719             <desc>
    2720                 Notification of the host if the guest executed the KBD_CMD_SET_LEDS
    2721                 command to alter the state of the keyboard LEDs.
    2722             </desc>
    2723             <param name="numLock" type="boolean" dir="in"/>
    2724             <param name="capsLock" type="boolean" dir="in"/>
    2725             <param name="scrollLock" type="boolean" dir="in"/>
    2726         </method>
    2727 
    2728         <method name="onStateChange">
    2729             <desc>
    2730                 Notification when the execution state of the machine has changed.
    2731                 The new state will be given.
    2732             </desc>
    2733             <param name="state" type="MachineState" dir="in"/>
    2734         </method>
    2735 
    2736         <method name="onAdditionsStateChange">
    2737             <desc>
    2738                 Notification when a Guest Additions property changes.
    2739                 Interested callees should query IGuest's properties to
    2740                 find out what has changed.
    2741             </desc>
    2742         </method>
    2743 
    2744         <method name="onUSBDeviceStateChange">
    2745             <desc>
    2746                 Notification when a USB device is attached to or detached from
    2747                 the virtual USB controller.
    2748 
    2749                 This notification is sent as a result of the indirect
    2750                 request to attach the device because it matches one of the
    2751                 machine USB filters, or as a result of the direct request
    2752                 issued by <link to="IConsole::attachUSBDevice"/> or
    2753                 <link to="IConsole::detachUSBDevice"/>.
    2754 
    2755                 This notification is sent in case of both a succeeded and a
    2756                 failed request completion. When the request succeeds, the @a
    2757                 error parameter is @c null, and the given device has been
    2758                 already added to (when @a attached is @c true) or removed from
    2759                 (when @a attached is @c false) the collection represented by
    2760                 <link to="IConsole::USBDevices"/>. On failure, the collection
    2761                 doesn't change and the @a error perameter represents the error
    2762                 message describing the failure.
    2763 
    2764             </desc>
    2765             <param name="device" type="IUSBDevice" dir="in">
    2766                 <desc>Device that is subject to state change.</desc>
    2767             </param>
    2768             <param name="attached" type="boolean" dir="in">
    2769                 <desc>
    2770                     <tt>true</tt> if the device was attached
    2771                     and <tt>false</tt> otherwise.
    2772                 </desc>
    2773             </param>
    2774             <param name="error" type="IVirtualBoxErrorInfo" dir="in">
    2775                 <desc>
    2776                    <tt>null</tt> on success or an error message object on
    2777                    failure.
    2778                 </desc>
    2779             </param>
    2780         </method>
    2781 
    2782         <method name="onRuntimeError">
    2783             <desc>
    2784                 Notification when an error happens during the virtual
    2785                 machine execution.
    2786 
    2787                 There are three kinds of runtime errors:
    2788                 <ul>
    2789                     <li><i>fatal</i></li>
    2790                     <li><i>non-fatal with retry</i></li>
    2791                     <li><i>non-fatal warnings</i></li>
    2792                 </ul>
    2793 
    2794                 <b>Fatal</b> errors are indicated by the @a fatal parameter set
    2795                 to <tt>true</tt>. In case of fatal errors, the virtual machine
    2796                 execution is always paused before calling this notification, and
    2797                 the notification handler is supposed either to immediately save
    2798                 the virtual machine state using <link to="IConsole::saveState()"/>
    2799                 or power it off using <link to="IConsole::powerDown()"/>.
    2800                 Resuming the execution can lead to unpredictable results.
    2801 
    2802                 <b>Non-fatal</b> errors and warnings are indicated by the
    2803                 @a fatal parameter set to <tt>false</tt>. If the virtual machine
    2804                 is in the Paused state by the time the error notification is
    2805                 received, it means that the user can <i>try to resume</i> the machine
    2806                 execution after attempting to solve the probem that caused the
    2807                 error. In this case, the notification handler is supposed
    2808                 to show an appropriate message to the user (depending on the
    2809                 value of the @a id parameter) that offers several actions such
    2810                 as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
    2811                 wants to retry, the notification handler should continue
    2812                 the machine execution using the <link to="IConsole::resume()"/>
    2813                 call. If the machine execution is not Paused during this
    2814                 notification, then it means this notification is a <i>warning</i>
    2815                 (for example, about a fatal condition that can happen very soon);
    2816                 no immediate action is required from the user, the machine
    2817                 continues its normal execution.
    2818 
    2819                 Note that in either case the notification handler
    2820                 <b>must not</b> perform any action directly on a thread
    2821                 where this notification is called. Everything it is allowed to
    2822                 do is to post a message to another thread that will then talk
    2823                 to the user and take the corresponding action.
    2824 
    2825                 Currently, the following error identificators are known:
    2826                 <ul>
    2827                 <li><tt>"HostMemoryLow"</tt></li>
    2828                 <li><tt>"HostAudioNotResponding"</tt></li>
    2829                 <li><tt>"VDIStorageFull"</tt></li>
    2830                 </ul>
    2831 
    2832                 <note>
    2833                     This notification is not designed to be implemented by
    2834                     more than one callback at a time. If you have multiple
    2835                     IConsoleCallback instances registered on the given
    2836                     IConsole object, make sure you simply do nothing but
    2837                     return @c S_OK from all but one of them that does actual
    2838                     user notification and performs necessary actions.
    2839                 </note>
    2840 
    2841             </desc>
    2842             <param name="fatal" type="boolean" dir="in">
    2843                 <desc>Whether the error is fatal or not</desc>
    2844             </param>
    2845             <param name="id" type="wstring" dir="in">
    2846                 <desc>Error identificator</desc>
    2847             </param>
    2848             <param name="message" type="wstring" dir="in">
    2849                 <desc>Optional error message</desc>
    2850             </param>
    2851         </method>
    2852 
    2853         <method name="onCanShowWindow">
    2854             <desc>
    2855                 Notification when a call to
    2856                 <link to="IMachine::canShowConsoleWindow()"/> is made by a
    2857                 front-end to check if a subsequent call to
    2858                 <link to="IMachine::showConsoleWindow()"/> can succeed.
    2859 
    2860                 The callee should give an answer appropriate to the current
    2861                 machine state in the @a canShow argument. This answer must
    2862                 remain valid at least until the next
    2863                 <link to="IConsole::state">machine state</link> change.
    2864 
    2865                 <note>
    2866                     This notification is not designed to be implemented by
    2867                     more than one callback at a time. If you have multiple
    2868                     IConsoleCallback instances registered on the given
    2869                     IConsole object, make sure you simply do nothing but
    2870                     return @c true and @c S_OK from all but one of them that
    2871                     actually manages console window activation.
    2872                 </note>
    2873             </desc>
    2874             <param name="canShow" type="boolean" dir="return">
    2875                 <desc>
    2876                     @c true if the console window can be shown and @c
    2877                     false otherwise.
    2878                 </desc>
    2879             </param>
    2880         </method>
    2881 
    2882         <method name="onShowWindow">
    2883             <desc>
    2884                 Notification when a call to
    2885                 <link to="IMachine::showConsoleWindow()"/>
    2886                 requests the console window to be activated and brought to
    2887                 foreground on the desktop of the host PC.
    2888 
    2889                 This notification should cause the VM console process to
    2890                 perform the requested action as described above. If it is
    2891                 impossible to do it at a time of this notification, this
    2892                 method should return a failure.
    2893 
    2894                 Note that many modern window managers on many platforms
    2895                 implement some sort of focus stealing prevention logic, so
    2896                 that it may be impossible to activate a window without the
    2897                 help of the currently active application (which is supposedly
    2898                 an initiator of this notification). In this case, this method
    2899                 must return a non-zero identifier that represents the
    2900                 top-level window of the VM console process. The caller, if it
    2901                 represents a currently active process, is responsible to use
    2902                 this identifier (in a platform-dependent manner) to perform
    2903                 actual window activation.
    2904 
    2905                 This method must set @a winId to zero if it has performed all
    2906                 actions necessary to complete the request and the console
    2907                 window is now active and in foreground, to indicate that no
    2908                 further action is required on the caller's side.
    2909 
    2910                 <note>
    2911                     This notification is not designed to be implemented by
    2912                     more than one callback at a time. If you have multiple
    2913                     IConsoleCallback instances registered on the given
    2914                     IConsole object, make sure you simply do nothing but
    2915                     return@c S_OK from all but one of them that actually
    2916                     manages console window activation.
    2917                 </note>
    2918             </desc>
    2919             <param name="winId" type="unsigned long long" dir="return">
    2920                 <desc>
    2921                     Platform-dependent identifier of the top-level VM console
    2922                     window, or zero if this method has performed all actions
    2923                     necessary to implement the <i>show window</i> semantics for
    2924                     the given platform and/or this VirtualBox front-end.
    2925                 </desc>
    2926             </param>
    2927         </method>
    2928 
    2929     </interface>
    2930 
    2931     <interface
    2932         name="IRemoteDisplayInfo" extends="$unknown"
    2933         uuid="550104cd-2dfd-4a6c-857d-f6f8e088e62c"
    2934         wsmap="struct"
    2935     >
    2936         <attribute name="active" type="boolean" readonly="yes">
    2937             <desc>
    2938                 Whether the remote display connection is active.
    2939             </desc>
    2940         </attribute>
    2941 
    2942         <attribute name="numberOfClients" type="unsigned long" readonly="yes">
    2943             <desc>
    2944                 How many times a client connected.
    2945             </desc>
    2946         </attribute>
    2947 
    2948         <attribute name="beginTime" type="long long" readonly="yes">
    2949             <desc>
    2950                 When the last connection was established, in milliseconds since 1970-01-01 UTC.
    2951             </desc>
    2952         </attribute>
    2953 
    2954         <attribute name="endTime" type="long long" readonly="yes">
    2955             <desc>
    2956                 When the last connection was terminated or the current time, if
    2957                 connection is still active, in milliseconds since 1970-01-01 UTC.
    2958             </desc>
    2959         </attribute>
    2960 
    2961         <attribute name="bytesSent" type="unsigned long long" readonly="yes">
    2962             <desc>
    2963                 How many bytes were sent in last or current, if still active, connection.
    2964             </desc>
    2965         </attribute>
    2966 
    2967         <attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
    2968             <desc>
    2969                 How many bytes were sent in all connections.
    2970             </desc>
    2971         </attribute>
    2972 
    2973         <attribute name="bytesReceived" type="unsigned long long" readonly="yes">
    2974             <desc>
    2975                 How many bytes were received in last or current, if still active, connection.
    2976             </desc>
    2977         </attribute>
    2978 
    2979         <attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
    2980             <desc>
    2981                 How many bytes were received in all connections.
    2982             </desc>
    2983         </attribute>
    2984 
    2985         <attribute name="user" type="wstring" readonly="yes">
    2986             <desc>
    2987                 Login user name supplied by the client.
    2988             </desc>
    2989         </attribute>
    2990 
    2991         <attribute name="domain" type="wstring" readonly="yes">
    2992             <desc>
    2993                 Login domain name supplied by the client.
    2994             </desc>
    2995         </attribute>
    2996 
    2997         <attribute name="clientName" type="wstring" readonly="yes">
    2998             <desc>
    2999                 The client name supplied by the client.
    3000             </desc>
    3001         </attribute>
    3002 
    3003         <attribute name="clientIP" type="wstring" readonly="yes">
    3004             <desc>
    3005                 The IP address of the client.
    3006             </desc>
    3007         </attribute>
    3008 
    3009         <attribute name="clientVersion" type="unsigned long" readonly="yes">
    3010             <desc>
    3011                 The client software version number.
    3012             </desc>
    3013         </attribute>
    3014 
    3015         <attribute name="encryptionStyle" type="unsigned long" readonly="yes">
    3016             <desc>
    3017                 Public key exchange method used when connection was established.
    3018                 Values: 0 - RDP4 public key exchange scheme.
    3019                         1 - X509 sertificates were sent to client.
    3020             </desc>
    3021         </attribute>
    3022 
    3023     </interface>
    3024 
    3025     <interface
    3026         name="IConsole" extends="$unknown"
    3027         uuid="1DEA5C4B-0753-4193-B909-22330F64EC45"
    3028         wsmap="managed"
    3029     >
    3030         <attribute name="machine" type="IMachine" readonly="yes">
    3031             <desc>
    3032                 Machine object this console is sessioned with.
    3033                 <note>
    3034                     This is a convenience property, it has the same value as
    3035                     <link to="ISession::machine"/> of the corresponding session
    3036                     object.
    3037                 </note>
    3038             </desc>
    3039         </attribute>
    3040 
    3041         <attribute name="state" type="MachineState" readonly="yes">
    3042             <desc>
    3043                 Current execution state of the machine.
    3044                 <note>
    3045                     This property always returns the same value as the corresponding
    3046                     property of the IMachine object this console is sessioned with.
    3047                     For the process, that owns (executes) the VM, this is the
    3048                     preferrable way of quierying the VM state, because no IPC
    3049                     calls are made.
    3050                 </note>
    3051             </desc>
    3052         </attribute>
    3053 
    3054         <attribute name="guest" type="IGuest" readonly="yes">
    3055             <desc>Guest object.</desc>
    3056         </attribute>
    3057 
    3058         <attribute name="keyboard" type="IKeyboard" readonly="yes">
    3059             <desc>
    3060                 Virtual keyboard object.
    3061                 <note>
    3062                     If the machine is not running, any attempt to use
    3063                     the returned object will result in an error.
    3064                 </note>
    3065             </desc>
    3066         </attribute>
    3067 
    3068         <attribute name="mouse" type="IMouse" readonly="yes">
    3069             <desc>
    3070                 Virtual mouse object.
    3071                 <note>
    3072                     If the machine is not running, any attempt to use
    3073                     the returned object will result in an error.
    3074                 </note>
    3075             </desc>
    3076         </attribute>
    3077 
    3078         <attribute name="display" type="IDisplay" readonly="yes">
    3079             <desc>Virtual display object.
    3080                 <note>
    3081                     If the machine is not running, any attempt to use
    3082                     the returned object will result in an error.
    3083                 </note>
    3084             </desc>
    3085         </attribute>
    3086 
    3087         <attribute name="debugger" type="IMachineDebugger" readonly="yes">
    3088             <desc>Debugging interface.</desc>
    3089         </attribute>
    3090 
    3091         <attribute name="USBDevices" type="IUSBDeviceCollection" readonly="yes">
    3092             <desc>
    3093                 Collection of USB devices currently attached to the virtual
    3094                 USB controller.
    3095                 <note>
    3096                     The collection is empty if the machine is not running.
    3097                 </note>
    3098             </desc>
    3099         </attribute>
    3100 
    3101         <attribute name="remoteUSBDevices" type="IHostUSBDeviceCollection" readonly="yes">
    3102             <desc>
    3103                 List of USB devices currently attached to the remote VRDP client.
    3104                 Once a new device is physically attached to the remote host computer,
    3105                 it appears in this list and remains there until detached.
    3106             </desc>
    3107         </attribute>
    3108 
    3109         <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
    3110             <desc>
    3111                 Collection of shared folders for the current session.
    3112                 This collection is initially empty and is cleared once the
    3113                 session is closed. On other words, this collection represents
    3114                 transient shares (as opposed to <link to="IMachine::sharedFolders"/>
    3115                 that stores permanent shares stored in the settings file).
    3116 
    3117                 New folders to share are added to the collection using
    3118                 <link to="#createSharedFolder"/>. An existing shared folder can
    3119                 be removed using <link to="#removeSharedFolder"/>.
    3120             </desc>
    3121         </attribute>
    3122 
    3123         <attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
    3124             <desc>
    3125                 Interface that provides information on Remote Display (VRDP) connection.
    3126             </desc>
    3127         </attribute>
    3128 
    3129         <method name="powerUp">
    3130             <desc>
    3131                 Starts the virtual machine execution using the current machine
    3132                 state (i.e. its current execution state, current settings and
    3133                 current hard disks).
    3134 
    3135                 If the machine is powered off or aborted, the execution will
    3136                 start from the beginning (as if the real hardware were just
    3137                 powered on).
    3138 
    3139                 If the machine is in the <link to="MachineState::Saved"/> state,
    3140                 it will continue its execution the point where the state has
    3141                 beem saved.
    3142 
    3143                 <see>#saveState</see>
    3144             </desc>
    3145             <param name="progress" type="IProgress" dir="return">
    3146                 <desc>Progress object to track the operation completion.</desc>
    3147             </param>
    3148         </method>
    3149 
    3150         <method name="powerDown">
    3151             <desc>
    3152                 Stops the virtual machine execution.
    3153                 After this operation completes, the machine will go to the
    3154                 PoweredOff state.
    3155             </desc>
    3156         </method>
    3157 
    3158         <method name="reset">
    3159             <desc>Resets the virtual machine.</desc>
    3160         </method>
    3161 
    3162         <method name="pause">
    3163             <desc>Pauses the virtual machine execution.</desc>
    3164         </method>
    3165 
    3166         <method name="resume">
    3167             <desc>Resumes the virtual machine execution.</desc>
    3168         </method>
    3169 
    3170         <method name="powerButton">
    3171             <desc>Send the ACPI power button event to the guest.</desc>
    3172         </method>
    3173 
    3174         <method name="saveState">
    3175             <desc>
    3176                 Saves the current execution state of a running virtual machine
    3177                 and stops its executiuon.
    3178 
    3179                 After this operation completes, the machine will go to the
    3180                 Saved state. Next time it is powered up, this state will
    3181                 be restored and the machine will continue its execution from
    3182                 the place where it was saved.
    3183 
    3184                 This operation differs from taking a snapshot to the effect
    3185                 that it doesn't create new differencing hard disks. Also, once
    3186                 the machine is powered up from the state saved using this method,
    3187                 the saved state is deleted, so it will be impossible to return
    3188                 to this state later.
    3189 
    3190                 <note>On success, this method implicitly calls <link
    3191                 to="IMachine::saveSettings"/> to save all current machine
    3192                 settings (including runtime changes to the DVD drive, etc.).
    3193                 Together with the impossibility to change any VM settings when
    3194                 it is in the Saved state, this guarantees the adequate hardware
    3195                 configuration of the machine when it is restored from the saved
    3196                 state file.</note>
    3197 
    3198                 <note>
    3199                     The machine must be in the Running or Paused state, otherwise
    3200                     the operation will fail.
    3201                 </note>
    3202 
    3203                 <see><link to="#takeSnapshot"/></see>
    3204             </desc>
    3205             <param name="progress" type="IProgress" dir="return">
    3206                 <desc>Progress object to track the operation completion.</desc>
    3207             </param>
    3208         </method>
    3209 
    3210         <method name="discardSavedState">
    3211             <desc>
    3212                 Discards (deletes) the saved state of the virtual machine
    3213                 previously created by <link to="#saveState"/>. Next time the
    3214                 machine is powered up, a clean boot will occur.
    3215                 <note>
    3216                     This operation is equivalent to resetting or powering off
    3217                     the machine without doing a proper shutdown in the guest OS.
    3218                 </note>
    3219             </desc>
    3220         </method>
    3221 
    3222         <method name="getDeviceActivity">
    3223             <desc>
    3224                 Gets the current activity type of a given device or device group.
    3225             </desc>
    3226             <param name="type" type="DeviceType" dir="in"/>
    3227             <param name="activity" type="DeviceActivity" dir="return"/>
    3228         </method>
    3229 
    3230         <method name="attachUSBDevice">
    3231             <desc>
    3232                 Attaches a host USB device with the given UUID to the
    3233                 USB controller of the virtual machine.
    3234 
    3235                 The device needs to be in one of the following states:
    3236                 <link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,
    3237                 <link to="USBDeviceState::USBDeviceAvailable">USBDeviceAvailable</link> or
    3238                 <link to="USBDeviceState::USBDeviceHeld">USBDeviceHeld</link>,
    3239                 otherwise an error is immediately returned.
    3240 
    3241                 When the device state is
    3242                 <link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,
    3243                 an error may also be returned if the host computer
    3244                 refuses to release it for some reason.
    3245 
    3246                 <see>IUSBController::DeviceFilters, USBDeviceState</see>
    3247             </desc>
    3248             <param name="id" type="uuid" dir="in">
    3249                 <desc>UUID of the host USB device to attach.</desc>
    3250             </param>
    3251         </method>
    3252 
    3253         <method name="detachUSBDevice">
    3254             <desc>
    3255                 Detaches an USB device with the given UUID from the USB controller
    3256                 oif the virtual machine.
    3257 
    3258                 After this method succeeds, the VirtualBox server reinitiates
    3259                 all USB filters as if the device were just physically attached
    3260                 to the host, but filters of this machine are ignored to avoid
    3261                 a possible automatic reattachment.
    3262 
    3263                 <see>IUSBController::DeviceFilters, USBDeviceState</see>
    3264             </desc>
    3265             <param name="id" type="uuid" dir="in">
    3266                 <desc>UUID of the USB device to detach.</desc>
    3267             </param>
    3268             <param name="device" type="IUSBDevice" dir="return">
    3269                 <desc>Detached USB device.</desc>
    3270             </param>
    3271         </method>
    3272 
    3273         <method name="createSharedFolder">
    3274             <desc>
    3275                 Creates a new shared folder by associating the given logical
    3276                 name with the given host path, adds it to the collection of
    3277                 shared folders and starts sharing it.
    3278                 Refer to the description of <link to="ISharedFolder"/> to read
    3279                 about logical name unicity.
    3280             </desc>
    3281             <param name="name" type="wstring" dir="in">
    3282                 <desc>Unique logical name of the shared folder.</desc>
    3283             </param>
    3284             <param name="hostPath" type="wstring" dir="in">
    3285                 <desc>Full path to the shared folder in the host file system.</desc>
    3286             </param>
    3287         </method>
    3288 
    3289         <method name="removeSharedFolder">
    3290             <desc>
    3291                 Removes a shared folder with the given name previously created
    3292                 by <link to="#createSharedFolder"/> from the collection of
    3293                 shared folders and stops sharing it.
    3294             </desc>
    3295             <param name="name" type="wstring" dir="in">
    3296                 <desc>Logical name of the shared folder to remove.</desc>
    3297             </param>
    3298         </method>
    3299 
    3300         <method name="takeSnapshot">
    3301             <desc>
    3302                 Saves the current execution state and all settings of the
    3303                 machine and creates differencing images for all
    3304                 normal (non-independent) hard disks.
    3305 
    3306                 This method can be called for a PoweredOff, Saved, Running or
    3307                 Paused virtual machine. When the machine is PoweredOff, an
    3308                 offline <link to="ISnapshot">snapshot</link> is created,
    3309                 in all other cases -- an online snapshot.
    3310 
    3311                 The taken snapshot is always based on the
    3312                 <link to="IMachine::currentSnapshot">current
    3313                 snapshot</link> of the associated virtual machine and becomes
    3314                 a new current snapshot.
    3315 
    3316                 <note>This method implicitly calls <link
    3317                 to="IMachine::saveSettings"/> to save all current machine
    3318                 settings before taking an offline snapshot.</note>
    3319 
    3320                 <see>ISnapshot, <link to="#saveState"/></see>
    3321             </desc>
    3322             <param name="name" type="wstring" dir="in">
    3323                 <desc>Short name for the snapshot.</desc>
    3324             </param>
    3325             <param name="description" type="wstring" dir="in">
    3326                 <desc>Optional description of the snapshot.</desc>
    3327             </param>
    3328             <param name="progress" type="IProgress" dir="return">
    3329                 <desc>Progress object to track the operation completion.</desc>
    3330             </param>
    3331         </method>
    3332 
    3333         <method name="discardSnapshot">
    3334             <desc>
    3335 
    3336                 Starts discarding the specified snapshot. The execution state
    3337                 and settings of the associated machine stored in the snapshot
    3338                 will be deleted. The contents of all differencing hard disks of
    3339                 this snapshot will be merged with the contents of their
    3340                 dependent child hard disks to keep the, disks valid (in other
    3341                 words, all changes represented by hard disks being discarded
    3342                 will be propagated to their child hard disks). After that, this
    3343                 snapshot's differencing hard disks will be deleted. The parent
    3344                 of this snapshot will become a new parent for all its child
    3345                 snapshots.
    3346 
    3347                 If the discarded snapshot is the current one, its parent
    3348                 snapshot will become a new current snapshot. The current machine
    3349                 state is not directly affected in this case, except that
    3350                 currently attached differencing hard disks based on hard disks
    3351                 of the discarded snapshot will be also merged as described
    3352                 above.
    3353 
    3354                 If the discarded snapshot is the first one (the root snapshot)
    3355                 and it has exactly one child snapshot, this child snapshot will
    3356                 become the first snapshot after discarding. If there are no
    3357                 children at all (i.e. the first snapshot is the only snapshot of
    3358                 the machine), both the current and the first snapshot of the
    3359                 machine will be set to null. In all other cases, the first
    3360                 snapshot cannot be discarded.
    3361 
    3362                 You cannot discard the snapshot if it stores <link
    3363                 to="HardDiskType::NormalHardDisk">normal</link>
    3364                 (non-differencing) hard disks that have differencing hard disks
    3365                 based on them. Snapshots of such kind can be discarded only when
    3366                 every normal hard disk has either no children at all or exactly
    3367                 one child. In the former case, the normal hard disk simply
    3368                 becomes unused (i.e. not attached to any VM). In the latter
    3369                 case, it receives all the changes strored in the child hard
    3370                 disk, and then it replaces the child hard disk in the
    3371                 configuration of the corresponding snapshot or machine.
    3372 
    3373                 Also, you cannot discard the snapshot if it stores hard disks
    3374                 (of any type) having differencing child hard disks that belong
    3375                 to other machines. Such snapshots can be only discarded after
    3376                 you discard all snapshots of other machines containing "foreign"
    3377                 child disks, or detach these "foreign" child disks from machines
    3378                 they are attached to.
    3379 
    3380                 One particular example of the snapshot storing normal hard disks
    3381                 is the first snapshot of a virtual machine that had normal hard
    3382                 disks attached when taking the snapshot. Be careful when
    3383                 discarding such snapshots because this implicitly commits
    3384                 changes (made since the snapshot being discarded has been taken)
    3385                 to normal hard disks (as described above), which may be not what
    3386                 you want.
    3387 
    3388                 The virtual machine is put to the <link
    3389                 to="MachineState::Discarding">Discarding</link> state until the
    3390                 discard operation is completed.
    3391 
    3392                 <note>The machine must not be running, otherwise the operation
    3393                 will fail.</note>
    3394 
    3395                 <note>
    3396                     Child hard disks of all normal hard disks of the
    3397                     discarded snapshot must be <link to="IHardDisk::accessible">
    3398                     accessible</link> for this operation to succeed.
    3399                     In particular, this means that all virtual machines,
    3400                     whose hard disks are directly or indirectly based on
    3401                     the hard disks of discarded snapshot, must be powered off.
    3402                 </note>
    3403                 <note>
    3404                     Merging hard disk contents can be very time and disk space
    3405                     consuming, if these disks are big in size and have many
    3406                     children. However, if the snapshot being discarded is the last
    3407                     (head) snapshot on the branch, the operation will be rather
    3408                     quick.
    3409                 </note>
    3410                 <note>
    3411                     Note that discarding the current snapshot
    3412                     will imlicitly call <link to="IMachine::saveSettings()"/> to
    3413                     make all current machine settings permanent.
    3414                 </note>
    3415             </desc>
    3416             <param name="id" type="uuid" dir="in">
    3417                 <desc>UUID of the snapshot to discard.</desc>
    3418             </param>
    3419             <param name="progress" type="IProgress" dir="return">
    3420                 <desc>Progress object to track the operation completion.</desc>
    3421             </param>
    3422         </method>
    3423 
    3424         <method name="discardCurrentState">
    3425             <desc>
    3426                 This operation is similar to <link to="#discardSnapshot()"/> but
    3427                 affects the current machine state. This means that the state stored
    3428                 in the current snapshot will become a new current state, and
    3429                 all current settings of the machine and changes stored in
    3430                 differencing hard disks will be lost.
    3431 
    3432                 After this operation is successfully completed, new empty
    3433                 differencing hard disks are created for all normal hard disks
    3434                 of the machine.
    3435 
    3436                 If the current snapshot of the machine is an online snapshot,
    3437                 the machine will go to the <link to="MachineState::Saved">
    3438                 saved state</link>, so that the next time it is powered on,
    3439                 the execution state will be restored from the current snapshot.
    3440 
    3441                 <note>The machine must not be running, otherwise the operation
    3442                 will fail.</note>
    3443 
    3444                 <note>If the machine state is <link
    3445                 to="MachineState::Saved">Saved</link> prior to this operation,
    3446                 the saved state file will be implicitly discarded (as if <link
    3447                 to="IConsole::discardSavedState()"/> were called).</note>
    3448 
    3449             </desc>
    3450             <param name="progress" type="IProgress" dir="return">
    3451                 <desc>Progress object to track the operation completion.</desc>
    3452             </param>
    3453         </method>
    3454 
    3455         <method name="discardCurrentSnapshotAndState">
    3456             <desc>
    3457 
    3458                 This method is equivalent to doing <link
    3459                 to="#discardSnapshot">discardSnapshot</link> (<link
    3460                 to="IMachine::currentSnapshot">currentSnapshot</link>.<link
    3461                 to="ISnapshot::id">id()</link>, ...) followed by <link
    3462                 to="#discardCurrentState()"/>.
    3463 
    3464                 As a result, the machine will be fully restored from the
    3465                 snapshot preceeding the current snapshot, while both the current
    3466                 snapshot and the current machine state will be discarded.
    3467 
    3468                 If the current snapshot is the first snapshot of the machine
    3469                 (i.e. it has the only snapshot), the current machine state will
    3470                 be discarded <b>before</b> discarding the snapshot. In other
    3471                 words, the machine will be restored from its last snapshot,
    3472                 before discarding it. This differs from performing a single
    3473                 <link to="#discardSnapshot()"/> call (note that no <link
    3474                 to="#discardCurrentState()"/> will be possible after it) to the
    3475                 effect that the latter will preserve the current state instead
    3476                 of discarding it.
    3477 
    3478                 Unless explicitly mentioned otherwise, all remarks and
    3479                 limitations of the above two methods also apply to this method.
    3480 
    3481                 <note>The machine must not be running, otherwise the operation
    3482                 will fail.</note>
    3483 
    3484                 <note>If the machine state is <link
    3485                 to="MachineState::Saved">Saved</link> prior to this operation,
    3486                 the saved state file will be implicitly discarded (as if <link
    3487                 to="IConsole::discardSavedState()"/> were called).</note>
    3488 
    3489                 <note>
    3490                     This method is more efficient than calling two above
    3491                     methods separately: it requires less IPC calls and provides
    3492                     a single progress object.
    3493                 </note>
    3494 
    3495             </desc>
    3496             <param name="progress" type="IProgress" dir="return">
    3497                 <desc>Progress object to track the operation completion.</desc>
    3498             </param>
    3499         </method>
    3500 
    3501         <method name="registerCallback">
    3502             <desc>
    3503                 Registers a new console callback on this instance. The methods of the
    3504                 callback interface will be called by this instance when the appropriate
    3505                 event occurs.
    3506             </desc>
    3507             <param name="callback" type="IConsoleCallback" dir="in"/>
    3508         </method>
    3509 
    3510         <method name="unregisterCallback">
    3511             <desc>
    3512                 Unregisters the console callback previously registered using
    3513                 <link to="#registerCallback"/>.
    3514             </desc>
    3515             <param name="callback" type="IConsoleCallback" dir="in"/>
    3516         </method>
    3517 
    3518     </interface>
    3519 
    3520     <!--
    3521     // IHost
    3522     /////////////////////////////////////////////////////////////////////////
    3523     -->
    3524 
    3525     <interface
    3526         name="IHostDVDDrive" extends="$unknown"
    3527         uuid="21f86694-202d-4ce4-8b05-a63ff82dbf4c"
    3528         wsmap="managed"
    3529     >
    3530         <attribute name="name" type="wstring" readonly="yes">
    3531             <desc>
    3532                 Returns the platform-specific device identifier.
    3533                 On DOS-like platforms, it is a drive name (e.g. R:).
    3534                 On Unix-like platforms, it is a device name (e.g. /dev/hdc).
    3535             </desc>
    3536         </attribute>
    3537         <attribute name="description" type="wstring" readonly="yes">
    3538             <desc>
    3539                 Returns a human readable description for the drive.  This
    3540                 description usually contains the product and vendor name.  A
    3541                 @c null string is returned if the description is not available.
    3542             </desc>
    3543         </attribute>
    3544         <attribute name="udi" type="wstring" readonly="yes">
    3545             <desc>
    3546                 Returns the unique device identifier for the drive.  This
    3547                 attribute is reserved for future use instead of
    3548                 <link to="#name"/>. Currently it is not used and may return
    3549                 @c null on some platforms.
    3550             </desc>
    3551         </attribute>
    3552 
    3553     </interface>
    3554 
    3555     <enumerator
    3556         name="IHostDVDDriveEnumerator" type="IHostDVDDrive"
    3557         uuid="1ed7cfaf-c363-40df-aa4e-89c1afb7d96b"
    3558     />
    3559 
    3560     <collection
    3561         name="IHostDVDDriveCollection" type="IHostDVDDrive"
    3562         enumerator="IHostDVDDriveEnumerator"
    3563         uuid="1909c533-1a1e-445f-a4e1-a267cffc30ed"
    3564         readonly="yes"
    3565     >
    3566         <method name="findByName">
    3567             <desc>
    3568                 Searches this collection for a host drive with the given name.
    3569                 <note>
    3570                     The method returns an error if the given name does not
    3571                     correspond to any host drive in the collection.
    3572                 </note>
    3573             </desc>
    3574             <param name="name" type="wstring" dir="in">
    3575                 <desc>Name of the host drive to search for</desc>
    3576             </param>
    3577             <param name="drive" type="IHostDVDDrive" dir="return">
    3578                 <desc>Found host drive object</desc>
    3579             </param>
    3580         </method>
    3581     </collection>
    3582 
    3583     <interface
    3584         name="IHostFloppyDrive" extends="$unknown"
    3585         uuid="b6a4d1a9-4221-43c3-bd52-021a5daa9ed2"
    3586         wsmap="managed"
    3587     >
    3588         <attribute name="name" type="wstring" readonly="yes">
    3589             <desc>
    3590                 Returns the platform-specific device identifier.
    3591                 On DOS-like platforms, it is a drive name (e.g. A:).
    3592                 On Unix-like platforms, it is a device name (e.g. /dev/fd0).
    3593             </desc>
    3594         </attribute>
    3595         <attribute name="description" type="wstring" readonly="yes">
    3596             <desc>
    3597                 Returns a human readable description for the drive.  This
    3598                 description usually contains the product and vendor name.  A
    3599                 @c null string is returned if the description is not available.
    3600             </desc>
    3601         </attribute>
    3602         <attribute name="udi" type="wstring" readonly="yes">
    3603             <desc>
    3604                 Returns the unique device identifier for the drive.  This
    3605                 attribute is reserved for future use instead of
    3606                 <link to="#name"/>. Currently it is not used and may return
    3607                 @c null on some platforms.
    3608             </desc>
    3609         </attribute>
    3610     </interface>
    3611 
    3612     <enumerator
    3613         name="IHostFloppyDriveEnumerator" type="IHostFloppyDrive"
    3614         uuid="ce04c924-4f54-432a-9dec-11fddc3ea875"
    3615     />
    3616 
    3617     <collection
    3618         name="IHostFloppyDriveCollection" type="IHostFloppyDrive"
    3619         enumerator="IHostFloppyDriveEnumerator"
    3620         uuid="fd84bb86-c59a-4037-a557-755ff263a460"
    3621         readonly="yes"
    3622     >
    3623         <method name="findByName">
    3624             <desc>
    3625                 Searches this collection for a host drive with the given name.
    3626                 <note>
    3627                     The method returns an error if the given name does not
    3628                     correspond to any host drive in the collection.
    3629                 </note>
    3630             </desc>
    3631             <param name="name" type="wstring" dir="in">
    3632                 <desc>Name of the host drive to search for</desc>
    3633             </param>
    3634             <param name="drive" type="IHostFloppyDrive" dir="return">
    3635                 <desc>Found host drive object</desc>
    3636             </param>
    3637         </method>
    3638     </collection>
     787      </param>
     788      <param name="name" type="wstring" dir="in">
     789        <desc>Machine name.</desc>
     790      </param>
     791      <param name="machine" type="IMachine" dir="return">
     792        <desc>Created machine object.</desc>
     793      </param>
     794    </method>
     795
     796    <method name="createLegacyMachine">
     797      <desc>
     798        Creates a new virtual machine in "legacy" mode, using the
     799        specified settings file to store machine settings.
     800
     801        As opposed to machines created by <link to="#createMachine()"/>,
     802        the settings file of the machine created in "legacy" mode
     803        is not automatically renamed when the machine name is
     804        changed -- it will always remain the same as specified in this
     805        method call.
     806
     807        The specified settings file name can be absolute
     808        (full path) or relative to the <link to="IVirtualBox::homeFolder">
     809          VirtualBox home directory</link>. If the file name doesn't
     810        contain an extension, the default extension (.xml) will be
     811        appended.
     812
     813        Note that the configuration of the newly created machine is not
     814        saved to disk (and therefore no settings file is created)
     815        until <link to="IMachine::saveSettings()"/> is called. If the
     816        specified settings file already exists,
     817        <link to="IMachine::saveSettings()"/> will return an error.
     818
     819        You should also specify a valid name for the machine.
     820        See the <link to="IMachine::name"/> property
     821        description for more details about the machine name.
     822
     823        The created machine remains
     824        unregistered until you call <link to="#registerMachine()"/>.
     825
     826        @deprecated This method may be removed later. It is better
     827        to use <link to="IVirtualBox::createMachine()"/>.
     828
     829        <note>
     830          There is no way to change the name of the settings file
     831          of the created machine.
     832        </note>
     833      </desc>
     834      <param name="settingsFile" type="wstring" dir="in">
     835        <desc>
     836          Name of the file where to store machine settings.
     837        </desc>
     838      </param>
     839      <param name="name" type="wstring" dir="in">
     840        <desc>Machine name.</desc>
     841      </param>
     842      <param name="machine" type="IMachine" dir="return">
     843        <desc>Created machine object.</desc>
     844      </param>
     845    </method>
     846
     847    <method name="openMachine">
     848      <desc>
     849        Opens a virtual machine from the existing settings file.
     850        The opened machine remains unregistered until you call
     851        <link to="#registerMachine()"/>.
     852
     853        The specified settings file name can be absolute
     854        (full path) or relative to the <link to="IVirtualBox::homeFolder">
     855          VirtualBox home directory</link>. This file must exist
     856        and must be a valid machine settings file whose contents
     857        will be used to construct the machine object.
     858
     859        @deprecated Will be removed soon.
     860      </desc>
     861      <param name="settingsFile" type="wstring" dir="in">
     862        <desc>
     863          Name of the machine settings file.
     864        </desc>
     865      </param>
     866      <param name="machine" type="IMachine" dir="return">
     867        <desc>Opened machine object.</desc>
     868      </param>
     869      <note>
     870        <link to="IMachine::settingsModified"/> will return
     871        false for the created machine, until any of machine settigs
     872        are changed.
     873      </note>
     874    </method>
     875
     876    <method name="registerMachine">
     877      <desc>
     878
     879        Registers the machine previously created using
     880        <link to="#createMachine()"/> or opened using
     881        <link to="#openMachine()"/> within this VirtualBox installation. After
     882        successful method invocation, the
     883        <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
     884        to all registered callbacks.
     885
     886        <note>
     887          This method implicitly calls <link to="IMachine::saveSettings"/>
     888          to save all current machine settings before registering it.
     889        </note>
     890
     891      </desc>
     892      <param name="machine" type="IMachine" dir="in"/>
     893    </method>
     894
     895    <method name="getMachine">
     896      <param name="id" type="uuid" dir="in"/>
     897      <param name="machine" type="IMachine" dir="return"/>
     898    </method>
     899
     900    <method name="findMachine">
     901      <param name="name" type="wstring" dir="in"/>
     902      <param name="machine" type="IMachine" dir="return"/>
     903    </method>
     904
     905    <method name="unregisterMachine">
     906      <desc>
     907
     908        Unregisters the machine previously registered using
     909        <link to="#registerMachine"/>. After successful method invocation, the
     910        <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
     911        to all registered callbacks.
     912
     913        <note>
     914          The specified machine must not be in the Saved state, have an open
     915          (or a spawning) direct session associated with it, have snapshots or
     916          have hard disks attached.
     917        </note>
     918
     919        <note>
     920          This method implicitly calls <link to="IMachine::saveSettings"/> to
     921          save all current machine settings before unregistering it.
     922        </note>
     923
     924        <note>
     925          If the given machine is inaccessible (see
     926          <link to="IMachine::accessible"/>), it will be unregistered and
     927          fully uninitialized right afterwards. As a result, the returned
     928          machine object will be unusable and an attempt to call
     929          <b>any</b> method will return the "Object not ready" error.
     930        </note>
     931
     932      </desc>
     933      <param name="id" type="uuid" dir="in">
     934        <desc>UUID of the machine to unregister.</desc>
     935      </param>
     936      <param name="machine" type="IMachine" dir="return">
     937        <desc>Unregistered machine object.</desc>
     938      </param>
     939    </method>
     940
     941    <method name="createHardDisk">
     942      <desc>
     943
     944        Creates a new unregistered hard disk that will use the given
     945        storage type.
     946
     947        Most properties of the created hard disk object are
     948        uninitialized. Valid values must be assigned to them (and probalby
     949        some actions performed) to make the actual usage of this hard disk
     950        (<link to="#registerHardDisk()">register</link>, attach to a virtual
     951        machine, etc.). See the description of <link to="IHardDisk"/> and
     952        descriptions of storage type specific interfaces for more information.
     953
     954        <note>
     955          For hard disks using
     956          the <link
     957          to="HardDiskStorageType::VirtualDiskImage">VirtualDiskImage</link>
     958          storage type, an image file is not actually created until you call
     959          <link to="IVirtualDiskImage::createDynamicImage()"/> or
     960          <link to="IVirtualDiskImage::createFixedImage()"/>.
     961        </note>
     962
     963      </desc>
     964
     965      <param name="storageType" type="HardDiskStorageType" dir="in">
     966        <desc>Storage type of the hard disk image to create.</desc>
     967      </param>
     968      <param name="hardDisk" type="IHardDisk" dir="return">
     969        <desc>Created hard disk object of the given storage type.</desc>
     970      </param>
     971
     972    </method>
     973
     974    <method name="openHardDisk">
     975      <desc>
     976
     977        Opens a hard disk from an existing location.
     978
     979        This method tries to guess the
     980        <link to="HardDiskStorageType">hard disk storage type</link> from the
     981        format of the location string and from the contens of the resource the
     982        location points to. Currently, a <i>file path</i> is the only
     983        supported format for the location string which must point to either a
     984        VDI file or to a VMDK file. On success, an IHardDisk object will be
     985        returned that also implements the corresponding interface
     986        (IVirtualDiskImage or IVMDKImage, respectively). The
     987        <link to="IHardDisk::storageType"/> property may also be used to
     988        determine the storage type of the returned object (instead of trying
     989        to query one of these interfaces).
     990
     991        <note>
     992          The specified file path can be absolute (full path) or relative to
     993          the <link to="IVirtualBox::homeFolder">VirtualBox home
     994          directory</link>. If only a file name without any path is given,
     995          the <link to="ISystemProperties::defaultVDIFolder"> default VDI
     996          folder</link> will be used as a path to the image file.
     997        </note>
     998
     999        The opened hard disk remains unregistered
     1000        until <link to="#registerHardDisk()"/> is called.
     1001
     1002      </desc>
     1003
     1004      <param name="location" type="wstring" dir="in">
     1005        <desc>
     1006          Location of the resource that contains a valid hard disk.
     1007        </desc>
     1008      </param>
     1009      <param name="hardDisk" type="IHardDisk" dir="return">
     1010        <desc>Opened hard disk object.</desc>
     1011      </param>
     1012    </method>
     1013
     1014    <method name="openVirtualDiskImage">
     1015      <desc>
     1016
     1017        Opens a hard disk from an existing Virtual Disk Image file.
     1018        The opened hard disk remains unregistered
     1019        until <link to="#registerHardDisk()"/> is called.
     1020
     1021        @deprecated Use <link to="IVirtualBox::openHardDisk()"/> instead.
     1022
     1023        <note>Opening differencing images is not supported.</note>
     1024
     1025        <note>The specified file path can be absolute (full path) or
     1026          relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
     1027            home directory</link>. If only a file name without any path is
     1028          given, the <link to="ISystemProperties::defaultVDIFolder">
     1029            default VDI folder</link> will be used as a path to the image
     1030          file.</note>
     1031
     1032      </desc>
     1033
     1034      <param name="filePath" type="wstring" dir="in">
     1035        <desc>
     1036          Name of the file that contains a valid Virtual Disk Image.
     1037        </desc>
     1038      </param>
     1039      <param name="image" type="IVirtualDiskImage" dir="return">
     1040        <desc>Opened hard disk object.</desc>
     1041      </param>
     1042    </method>
     1043
     1044    <method name="registerHardDisk">
     1045      <desc>
     1046
     1047        Registers the given hard disk within this VirtualBox
     1048        installation. The hard disk must not be registered, must be
     1049        <link to="IHardDisk::accessible"/> and must not be a
     1050        differencing hard disk, otherwise the registration will fail.
     1051
     1052      </desc>
     1053      <param name="hardDisk" type="IHardDisk" dir="in">
     1054        <desc>Hard disk object to register.</desc>
     1055      </param>
     1056    </method>
     1057
     1058    <method name="getHardDisk" const="yes">
     1059      <desc>
     1060        Returns the registered hard disk with the given UUID.
     1061      </desc>
     1062      <param name="id" type="uuid" dir="in">
     1063        <desc>UUID of the hard disk to look for.</desc>
     1064      </param>
     1065      <param name="hardDisk" type="IHardDisk" dir="return">
     1066        <desc>Found hard disk object.</desc>
     1067      </param>
     1068    </method>
     1069
     1070    <method name="findHardDisk">
     1071      <desc>
     1072
     1073        Returns a registered hard disk that uses the given location to
     1074        store data. The search is done by comparing the
     1075        value of the @a location argument to the
     1076        <link to="IHardDisk::location"/> attribute of each registered
     1077        hard disk.
     1078
     1079        For locations repesented by file paths (such as VDI and VMDK
     1080        images), the specified location can be either an absolute file
     1081        path or a path relative to
     1082        the <link to="IVirtualBox::homeFolder"> VirtualBox home
     1083          directory</link>. If only a file name without any path is
     1084        given, the <link to="ISystemProperties::defaultVDIFolder">
     1085          default VDI folder</link> will be used as a path to construct
     1086        the absolute image file name to search for. Note that on host
     1087        systems with case sensitive filesystems, a case sensitive
     1088        comparison is performed, otherwise the case of symbols in the
     1089        file path is ignored.
     1090
     1091      </desc>
     1092      <param name="location" type="wstring" dir="in">
     1093        <desc>Hard disk location specification to search for.</desc>
     1094      </param>
     1095      <param name="hardDisk" type="IHardDisk" dir="return">
     1096        <desc>Found hard disk object.</desc>
     1097      </param>
     1098    </method>
     1099
     1100    <method name="findVirtualDiskImage">
     1101      <desc>
     1102
     1103        Returns a registered hard disk that uses the given image file.
     1104
     1105        @deprecated Use <link to="IVirtualBox::findHardDisk()"/> instead.
     1106
     1107        <note>The specified file path can be absolute (full path) or
     1108          relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
     1109            home directory</link>. If only a file name without any path is
     1110          given, the <link to="ISystemProperties::defaultVDIFolder">
     1111            default VDI folder</link> will be used as a path to the image
     1112          file.</note>
     1113
     1114        <note>On host systems with case sensitive filesystems, a case
     1115          sensitive comparison is performed, otherwise the case of symbols
     1116          in the file path is ignored.</note>
     1117
     1118      </desc>
     1119      <param name="filePath" type="wstring" dir="in">
     1120        <desc>Virtual Disk Image file path to look for.</desc>
     1121      </param>
     1122      <param name="image" type="IVirtualDiskImage" dir="return">
     1123        <desc>Found hard disk object.</desc>
     1124      </param>
     1125    </method>
     1126
     1127    <method name="unregisterHardDisk">
     1128      <desc>
     1129        Unregisters a hard disk previously registered using
     1130        <link to="#registerHardDisk()"/>.
     1131        <note>
     1132          The specified hard disk must not be attached to any of
     1133          the existing virtual machines and must not have children
     1134          (differencing) hard disks.
     1135        </note>
     1136      </desc>
     1137      <param name="id" type="uuid" dir="in">
     1138        <desc>UUID of the hard disk to unregister.</desc>
     1139      </param>
     1140      <param name="hardDisk" type="IHardDisk" dir="return">
     1141        <desc>Unregistered hard disk object.</desc>
     1142      </param>
     1143    </method>
     1144
     1145    <method name="openDVDImage">
     1146      <desc>
     1147        Opens the CD/DVD image contained in the specified file of
     1148        the supported format and assigns it the given UUID. The opened
     1149        image remains unregistered
     1150        until <link to="#registerDVDImage()"/> is called.
     1151      </desc>
     1152      <param name="filePath" type="wstring" dir="in">
     1153        <desc>
     1154          Full name of the file that contains a valid
     1155          CD/DVD image. Currently, only ISO images are supported.
     1156          <note>
     1157            The specified file name can be absolute or relative
     1158            to the <link to="IVirtualBox::homeFolder">
     1159              VirtualBox home directory</link>.
     1160          </note>
     1161        </desc>
     1162      </param>
     1163      <param name="id" type="uuid" dir="in">
     1164        <desc>
     1165          UUID to assign to the given image file within this
     1166          VirtualBox installation. If an empty (null) UUID is
     1167          specified, the system will randomly generate an UUID.
     1168        </desc>
     1169      </param>
     1170      <param name="image" type="IDVDImage" dir="return">
     1171        <desc>Opened CD/DVD image object.</desc>
     1172      </param>
     1173    </method>
     1174
     1175    <method name="registerDVDImage">
     1176      <desc>
     1177        Registers a CD/DVD image within this VirtualBox
     1178        installation. The image must not be registered and must not
     1179        be associated with the same image file as any of the already
     1180        registered images, otherwise the registration will fail.
     1181      </desc>
     1182      <param name="image" type="IDVDImage" dir="in">
     1183        <desc>CD/DVD image object to register.</desc>
     1184      </param>
     1185    </method>
     1186
     1187    <method name="getDVDImage">
     1188      <desc>
     1189        Returns a registered CD/DVD image with the given UUID.
     1190      </desc>
     1191      <param name="id" type="uuid" dir="in">
     1192        <desc>UUID of the image to look for.</desc>
     1193      </param>
     1194      <param name="image" type="IDVDImage" dir="return">
     1195        <desc>Found CD/DVD image object.</desc>
     1196      </param>
     1197    </method>
     1198
     1199    <method name="findDVDImage">
     1200      <desc>
     1201        Returns a registered CD/DVD image with the given image file.
     1202        <note>
     1203          On host systems with case sensitive filesystems, a case
     1204          sensitive comparison is performed, otherwise the case of
     1205          symbols in the file path is ignored.
     1206        </note>
     1207      </desc>
     1208      <param name="filePath" type="wstring" dir="in">
     1209        <desc>CD/DVD image file path to look for.</desc>
     1210      </param>
     1211      <param name="image" type="IDVDImage" dir="return">
     1212        <desc>Found CD/DVD image object.</desc>
     1213      </param>
     1214    </method>
     1215
     1216    <method name="getDVDImageUsage">
     1217      <desc>
     1218        Returns the list of of UUIDs of all virtual machines that use
     1219        the given CD/DVD image.
     1220      </desc>
     1221      <param name="id" type="uuid" dir="in">
     1222        <desc>UUID of the image to get the usage information for.</desc>
     1223      </param>
     1224      <param name="usage" type="ResourceUsage" dir="in">
     1225        <desc>Type of the usage (permanent, temporary or all).</desc>
     1226      </param>
     1227      <param name="machineIDs" type="wstring" dir="return">
     1228        <desc>
     1229          List of UUIDs of all machines that use the given image
     1230          in the way specified by the usage parameter.
     1231          The list is returned as a string containing UUIDs separated
     1232          by spaces. A null string means that the image is not used.
     1233          <note>
     1234            When the usage type is <link to="ResourceUsage::AllUsage"/>
     1235            and the image is used by the VM both permanently
     1236            and temporarily, the VM's UUID will be present only
     1237            once in the list.
     1238          </note>
     1239        </desc>
     1240      </param>
     1241    </method>
     1242
     1243    <method name="unregisterDVDImage">
     1244      <desc>
     1245        Unregisters the CD/DVD image previously registered using
     1246        <link to="#registerDVDImage()"/>.
     1247        <note>
     1248          The specified image must not be mounted to any of
     1249          the existing virtual machines.
     1250        </note>
     1251      </desc>
     1252      <param name="id" type="uuid" dir="in">
     1253        <desc>UUID of the CD/DVD image to unregister.</desc>
     1254      </param>
     1255      <param name="image" type="IDVDImage" dir="return">
     1256        <desc>Unregistered image object.</desc>
     1257      </param>
     1258    </method>
     1259
     1260    <method name="openFloppyImage">
     1261      <desc>
     1262        Opens a floppy image contained in the specified file of
     1263        the supported format and assigns it the given UUID. The opened
     1264        image remains unregistered
     1265        until <link to="#registerFloppyImage()"/> is called.
     1266      </desc>
     1267      <param name="filePath" type="wstring" dir="in">
     1268        <desc>
     1269          Full name of the file that contains a valid
     1270          floppy image.
     1271          <note>
     1272            The specified file name can be absolute or relative
     1273            to the <link to="IVirtualBox::homeFolder">
     1274              VirtualBox home directory</link>.
     1275          </note>
     1276        </desc>
     1277      </param>
     1278      <param name="id" type="uuid" dir="in">
     1279        <desc>
     1280          UUID to assign to the given image file within this
     1281          VirtualBox installation. If an empty (null) UUID is
     1282          specified, the system will randomly generate an UUID.
     1283        </desc>
     1284      </param>
     1285      <param name="image" type="IFloppyImage" dir="return">
     1286        <desc>Opened CD/DVD image object.</desc>
     1287      </param>
     1288    </method>
     1289
     1290    <method name="registerFloppyImage">
     1291      <desc>
     1292        Registers a floppy image within this VirtualBox
     1293        installation. The image must not be registered and must not
     1294        be associated with the same image file as any of the already
     1295        registered images, otherwise the registration will fail.
     1296      </desc>
     1297      <param name="image" type="IFloppyImage" dir="in">
     1298        <desc>Floppy image object to register.</desc>
     1299      </param>
     1300    </method>
     1301
     1302    <method name="getFloppyImage">
     1303      <desc>
     1304        Returns a registered floppy image with the given UUID.
     1305      </desc>
     1306      <param name="id" type="uuid" dir="in">
     1307        <desc>UUID of the image to look for.</desc>
     1308      </param>
     1309      <param name="image" type="IFloppyImage" dir="return">
     1310        <desc>Found floppy image object.</desc>
     1311      </param>
     1312    </method>
     1313
     1314    <method name="findFloppyImage">
     1315      <desc>
     1316        Returns a registered floppy image with the given image file.
     1317        <note>
     1318          On host systems with case sensitive filesystems, a case
     1319          sensitive comparison is performed, otherwise the case of
     1320          symbols in the file path is ignored.
     1321        </note>
     1322      </desc>
     1323      <param name="filePath" type="wstring" dir="in">
     1324        <desc>Floppy image file path to look for.</desc>
     1325      </param>
     1326      <param name="image" type="IFloppyImage" dir="return">
     1327        <desc>Found floppy image object.</desc>
     1328      </param>
     1329    </method>
     1330
     1331    <method name="getFloppyImageUsage">
     1332      <desc>
     1333        Returns the list of of UUIDs of all virtual machines that use
     1334        the given floppy image.
     1335      </desc>
     1336      <param name="id" type="uuid" dir="in">
     1337        <desc>UUID of the image to get the usage information for.</desc>
     1338      </param>
     1339      <param name="usage" type="ResourceUsage" dir="in">
     1340        <desc>Type of the usage (permanent, temporary or all).</desc>
     1341      </param>
     1342      <param name="machineIDs" type="wstring" dir="return">
     1343        <desc>
     1344          List of UUIDs of all machines that use the given image
     1345          in the way specified by the usage parameter.
     1346          The list is returned as a string containing UUIDs separated
     1347          by spaces. A null string means that the image is not used.
     1348          <note>
     1349            When the usage type is <link to="ResourceUsage::AllUsage"/>
     1350            and the image is used by the VM both permanently
     1351            and temporarily, the VM's UUID will be present only
     1352            once in the list.
     1353          </note>
     1354        </desc>
     1355      </param>
     1356    </method>
     1357
     1358    <method name="unregisterFloppyImage">
     1359      <desc>
     1360        Unregisters the floppy image previously registered using
     1361        <link to="#registerFloppyImage()"/>.
     1362        <note>
     1363          The specified image must not be mounted to any of
     1364          the existing virtual machines.
     1365        </note>
     1366      </desc>
     1367      <param name="id" type="uuid" dir="in">
     1368        <desc>UUID of the floppy image to unregister.</desc>
     1369      </param>
     1370      <param name="image" type="IFloppyImage" dir="return">
     1371        <desc>Unregistered image object.</desc>
     1372      </param>
     1373    </method>
     1374
     1375    <method name="getGuestOSType">
     1376      <param name="id" type="wstring" dir="in"/>
     1377      <param name="type" type="IGuestOSType" dir="return"/>
     1378    </method>
     1379
     1380    <method name="createSharedFolder">
     1381      <desc>
     1382        Creates a new shared folder by associating the given logical
     1383        name with the given host path, adds it to the collection of
     1384        shared folders and starts sharing it.
     1385        Refer to the description of <link to="ISharedFolder"/> to read
     1386        about logical name unicity.
     1387      </desc>
     1388      <param name="name" type="wstring" dir="in">
     1389        <desc>Unique logical name of the shared folder.</desc>
     1390      </param>
     1391      <param name="hostPath" type="wstring" dir="in">
     1392        <desc>Full path to the shared folder in the host file system.</desc>
     1393      </param>
     1394    </method>
     1395
     1396    <method name="removeSharedFolder">
     1397      <desc>
     1398        Removes a shared folder with the given name previously created
     1399        by <link to="#createSharedFolder"/> from the collection of
     1400        shared folders and stops sharing it.
     1401      </desc>
     1402      <param name="name" type="wstring" dir="in">
     1403        <desc>Logical name of the shared folder to remove.</desc>
     1404      </param>
     1405    </method>
     1406
     1407    <method name="getNextExtraDataKey">
     1408      <desc>
     1409        Returns the extra data key name following the supplied key.
     1410        An error is returned if the supplied key does not exist.
     1411        @c NULL is returned if the supplied key is the last key.
     1412        When supplying @c NULL for the key, the first item is returned.
     1413        @a nextValue is an optional parameter and if supplied, the next
     1414        key's value is returned in it.
     1415      </desc>
     1416      <param name="key" type="wstring" dir="in">
     1417        <desc>Name of the data key to follow.</desc>
     1418      </param>
     1419      <param name="nextKey" type="wstring" dir="out">
     1420        <desc>Name of the next data key.</desc>
     1421      </param>
     1422      <param name="nextValue" type="wstring" dir="out">
     1423        <desc>Value of the next data key.</desc>
     1424      </param>
     1425    </method>
     1426
     1427    <method name="getExtraData">
     1428      <desc>
     1429        Returns associated extra data.
     1430        If the reuqested key does not exist, this function will
     1431        succeed and return @c null in the @a value argument.
     1432      </desc>
     1433      <param name="key" type="wstring" dir="in">
     1434        <desc>Name of the data key to get.</desc>
     1435      </param>
     1436      <param name="value" type="wstring" dir="return">
     1437        <desc>Value of the requested data key.</desc>
     1438      </param>
     1439    </method>
     1440
     1441    <method name="setExtraData">
     1442      <desc>
     1443        Sets associated extra data.
     1444        If you pass @c NULL as a key @a vaule, the given key will be
     1445        deleted.
     1446        <note>
     1447          This method can be called outside a machine session and
     1448          therefore it's a caller's responsibility to handle race
     1449          condition when several clients change the same key at the
     1450          same time.
     1451        </note>
     1452      </desc>
     1453      <param name="key" type="wstring" dir="in">
     1454        <desc>Name of the data key to set.</desc>
     1455      </param>
     1456      <param name="value" type="wstring" dir="in">
     1457        <desc>Value to assign to the key.</desc>
     1458      </param>
     1459    </method>
     1460
     1461    <method name="openSession">
     1462      <desc>
     1463        <p>Opens a new direct session with the given virtual machine.
     1464          Within the direct session context, it is possible to change
     1465          all VM settings, as well as to execute the VM in the process
     1466          space of the session object. There can be only one direct
     1467          session open at a time for every virtual machine.</p>
     1468        <p>Upon successful return, the session object can be used to
     1469          get access to the machine and to the VM console.
     1470        </p>
     1471      </desc>
     1472      <param name="session" type="ISession" dir="in">
     1473        <desc>
     1474          Session object that will represent the opened session after
     1475          successful method invocation. This object must not represent
     1476          the already open session.
     1477          <note>
     1478            This session will be automatically closed if the
     1479            VirtualBox server is terminated for some reason.
     1480          </note>
     1481        </desc>
     1482      </param>
     1483      <param name="machineId" type="uuid" dir="in">
     1484        <desc>ID of the virtual machine to open a session with.</desc>
     1485      </param>
     1486    </method>
     1487
     1488    <method name="openRemoteSession">
     1489      <desc>
     1490        <p>Opens a new remote session with the given virtual
     1491          machine. Opening the remote session causes the server to start
     1492          a new process that opens a direct session with the given VM.
     1493          The remote session provides some level of control over the VM
     1494          execution (using the IConsole interface) to the caller. Within
     1495          the remote session context, it is not possible to change any
     1496          static VM settings (such as name, HDD configuration, etc.).</p>
     1497        <p>This operation can take some time, so the progress object
     1498          is returned to let the caller be informed when the session is
     1499          actually open. Until then, the remote session object remains in
     1500          the closed state and accessing the machine or its console through
     1501          it is invalid.
     1502        </p>
     1503
     1504        Currently supported session types (values of the @a type
     1505        parameter) are:
     1506        <ul>
     1507          <li><tt>gui</tt>: VirtualBox Qt GUI session</li>
     1508          <li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
     1509        </ul>
     1510
     1511        <note>
     1512          It is impossible to open a remote session with the machine
     1513          that already has an open direct session or waits until the
     1514          previous request to open the remote session is completed
     1515          (see <link to="IMachine::sessionState"/>).
     1516        </note>
     1517
     1518        <note>
     1519          The opened @a session will be automatically closed when
     1520          the corresponding direct session dies or gets closed.
     1521        </note>
     1522
     1523        <see>openExistingSession</see>
     1524      </desc>
     1525      <param name="session" type="ISession" dir="in">
     1526        <desc>
     1527          Session object that will represent the opened remote session
     1528          after successful method invocation (this object must not
     1529          represent an already open session).
     1530        </desc>
     1531      </param>
     1532      <param name="machineId" type="uuid" dir="in">
     1533        <desc>ID of the virtual machine to open a session with.</desc>
     1534      </param>
     1535      <param name="type" type="wstring" dir="in">
     1536        <desc>
     1537          Type of the remote session (case sensitive).
     1538        </desc>
     1539      </param>
     1540      <param name="progress" type="IProgress" dir="return">
     1541        <desc>Progress object to track the operation completion.</desc>
     1542      </param>
     1543    </method>
     1544
     1545    <method name="openExistingSession">
     1546      <desc>
     1547        <p>Opens a new remote session with the virtual machine for
     1548          which a direct session is already open.
     1549          The remote session provides some level of control over the VM
     1550          execution (using the IConsole interface) to the caller. Within
     1551          the remote session context, it is not possible to change any
     1552          static VM settings (such as name, HDD configuration, etc.).</p>
     1553        <p>As opposed to <link to="#openRemoteSession()"/>, the number of
     1554          remote sessions opened this way is not limited by the API.</p>
     1555        <note>
     1556          It is impossible to open a remote session with the machine
     1557          that doesn't have an open direct session.
     1558        </note>
     1559        <see>openRemoteSession</see>
     1560      </desc>
     1561      <param name="session" type="ISession" dir="in">
     1562        <desc>
     1563          Session object that will represent the open remote session
     1564          after successful method invocation. This object must not
     1565          represent an already open session.
     1566          <note>
     1567            This session will be automatically closed when the peer
     1568            (direct) session dies or gets closed.
     1569          </note>
     1570        </desc>
     1571      </param>
     1572      <param name="machineId" type="uuid" dir="in">
     1573        <desc>ID of the virtual machine to open a session with.</desc>
     1574      </param>
     1575    </method>
     1576
     1577    <method name="registerCallback">
     1578      <param name="callback" type="IVirtualBoxCallback" dir="in"/>
     1579    </method>
     1580
     1581    <method name="unregisterCallback">
     1582      <param name="callback" type="IVirtualBoxCallback" dir="in"/>
     1583    </method>
     1584
     1585  </interface>
     1586
     1587  <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
     1588         namespace="virtualbox.org">
     1589    <interface name="IVirtualBox" default="yes"/>
     1590  </class>
     1591
     1592  <!--
     1593  // IMachine
     1594  /////////////////////////////////////////////////////////////////////////
     1595  -->
     1596
     1597  <enumerator
     1598     name="IMachineEnumerator" type="IMachine"
     1599     uuid="1b554149-be0a-4465-9252-9ff8f420af55"
     1600     />
     1601
     1602  <collection
     1603     name="IMachineCollection" type="IMachine" enumerator="IMachineEnumerator"
     1604     uuid="FD443EC1-3007-4F5B-9282-D72760A66916"
     1605     readonly="yes"
     1606     />
     1607
     1608  <interface
     1609     name="IInternalMachineControl" extends="$unknown"
     1610     uuid="67ef427d-5f01-4791-a45e-ae5e646ed7c6"
     1611     internal="yes"
     1612     wsmap="suppress"
     1613     >
     1614    <method name="updateState">
     1615      <desc>
     1616        Updates the VM state.
     1617        <note>
     1618          This operation will also update the settings file with
     1619          the correct information about the saved state file
     1620          and delete this file from disk when appropriate.
     1621        </note>
     1622      </desc>
     1623      <param name="state" type="MachineState" dir="in"/>
     1624    </method>
     1625
     1626    <method name="getIPCId">
     1627      <param name="id" type="wstring" dir="return"/>
     1628    </method>
     1629
     1630    <method name="runUSBDeviceFilters">
     1631      <desc>
     1632        Asks the server to run USB devices filters of the associated
     1633        machine against the given USB device and tell if there is
     1634        a match.
     1635        <note>
     1636          Intended to be used only for remote USB devices. Local
     1637          ones don't require to call this method (this is done
     1638          implicitly by the Host and USBProxyService).
     1639        </note>
     1640      </desc>
     1641      <param name="device" type="IUSBDevice" dir="in"/>
     1642      <param name="matched" type="boolean" dir="return"/>
     1643    </method>
     1644
     1645    <method name="captureUSBDevice">
     1646      <desc>
     1647        Requests a capture of the given host USB device.
     1648        When the request is completed, the VM process will
     1649        get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
     1650        notification.
     1651      </desc>
     1652      <param name="id" type="uuid" dir="in"/>
     1653    </method>
     1654
     1655    <method name="releaseUSBDevice">
     1656      <desc>
     1657        Requests to release the given USB device.
     1658        When the request is completed, the VM process will
     1659        get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
     1660        notification.
     1661        <note>
     1662          The server must run its own filters and filters of all VMs
     1663          but this one on all released devices as if they were just
     1664          attached to the host computer.
     1665        </note>
     1666      </desc>
     1667      <param name="id" type="uuid" dir="in"/>
     1668    </method>
     1669
     1670    <method name="autoCaptureUSBDevices">
     1671      <desc>
     1672        Requests a capture all matching USB devices attached to the host.
     1673        When the request is completed, the VM process will
     1674        get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
     1675        notification per every captured device.
     1676      </desc>
     1677    </method>
     1678
     1679    <method name="releaseAllUSBDevices">
     1680      <desc>
     1681        Releases all USB devices that are captured by this VM because
     1682        the VM has been terminated.
     1683        <note>
     1684          The server must run its own filters and filters of all VMs
     1685          but this one on all released devices as if they were just
     1686          attached to the host computer.
     1687        </note>
     1688      </desc>
     1689    </method>
     1690
     1691    <method name="onSessionEnd">
     1692      <desc>
     1693        Triggered by the given session object when the session is about
     1694        to close normally.
     1695      </desc>
     1696      <param name="session" type="ISession" dir="in">
     1697        <desc>Session that is being closed</desc>
     1698      </param>
     1699      <param name="progress" type="IProgress" dir="return">
     1700        <desc>
     1701          Used to wait until the corresponding machine is actually
     1702          deassociated from the given session on the server.
     1703          Returned only when this session is a direct one.
     1704        </desc>
     1705      </param>
     1706    </method>
     1707
     1708    <method name="beginSavingState">
     1709      <desc>
     1710        Called by the VM process to inform the server it wants to
     1711        save the current state and stop the VM execution.
     1712      </desc>
     1713      <param name="progress" type="IProgress" dir="in">
     1714        <desc>
     1715          Progress object created by the VM process to wait until
     1716          the state is saved.
     1717        </desc>
     1718      </param>
     1719      <param name="stateFilePath" type="wstring" dir="out">
     1720        <desc>
     1721          File path the VM process must save the execution state to.
     1722        </desc>
     1723      </param>
     1724    </method>
     1725
     1726    <method name="endSavingState">
     1727      <desc>
     1728        Called by the VM process to inform the server that saving
     1729        the state previously requested by #beginSavingState is either
     1730        successfully finished or there was a failure.
     1731      </desc>
     1732
     1733      <param name="success" type="boolean" dir="in">
     1734        <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
     1735      </param>
     1736    </method>
     1737
     1738    <method name="beginTakingSnapshot">
     1739      <desc>
     1740        Called by the VM process to inform the server it wants to
     1741        take a snapshot.
     1742      </desc>
     1743      <param name="initiator" type="IConsole" dir="in">
     1744        <desc>The console object that initiated this call.</desc>
     1745      </param>
     1746      <param name="name" type="wstring" dir="in">
     1747        <desc>Snapshot name</desc>
     1748      </param>
     1749      <param name="description" type="wstring" dir="in">
     1750        <desc>Snapshot description</desc>
     1751      </param>
     1752      <param name="progress" type="IProgress" dir="in">
     1753        <desc>
     1754          Progress object created by the VM process to wait until
     1755          the state is saved (only for online snapshots).
     1756        </desc>
     1757      </param>
     1758      <param name="stateFilePath" type="wstring" dir="out">
     1759        <desc>
     1760          File path the VM process must save the execution state to.
     1761        </desc>
     1762      </param>
     1763      <param name="serverProgress" type="IProgress" dir="out">
     1764        <desc>
     1765          Progress object created by the server process to wait until
     1766          the snapshot is taken (VDI diff creation, etc.).
     1767        </desc>
     1768      </param>
     1769    </method>
     1770
     1771    <method name="endTakingSnapshot">
     1772      <desc>
     1773        Called by the VM process to inform the server that the snapshot
     1774        previously requested by #beginTakingSnapshot is either
     1775        successfully taken or there was a failure.
     1776      </desc>
     1777
     1778      <param name="success" type="boolean" dir="in">
     1779        <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
     1780      </param>
     1781    </method>
     1782
     1783    <method name="discardSnapshot">
     1784      <desc>
     1785        Gets called by IConsole::discardSnapshot.
     1786      </desc>
     1787      <param name="initiator" type="IConsole" dir="in">
     1788        <desc>The console object that initiated this call.</desc>
     1789      </param>
     1790      <param name="id" type="uuid" dir="in">
     1791        <desc>UUID of the snapshot to discard.</desc>
     1792      </param>
     1793      <param name="machineState" type="MachineState" dir="out">
     1794        <desc>New machine state after this operation is started.</desc>
     1795      </param>
     1796      <param name="progress" type="IProgress" dir="return">
     1797        <desc>Progress object to track the operation completion.</desc>
     1798      </param>
     1799    </method>
     1800
     1801    <method name="discardCurrentState">
     1802      <desc>
     1803        Gets called by IConsole::discardCurrentState.
     1804      </desc>
     1805      <param name="initiator" type="IConsole" dir="in">
     1806        <desc>The console object that initiated this call.</desc>
     1807      </param>
     1808      <param name="machineState" type="MachineState" dir="out">
     1809        <desc>New machine state after this operation is started.</desc>
     1810      </param>
     1811      <param name="progress" type="IProgress" dir="return">
     1812        <desc>Progress object to track the operation completion.</desc>
     1813      </param>
     1814    </method>
     1815
     1816    <method name="discardCurrentSnapshotAndState">
     1817      <desc>
     1818        Gets called by IConsole::discardCurrentSnapshotAndState.
     1819      </desc>
     1820      <param name="initiator" type="IConsole" dir="in">
     1821        <desc>The console object that initiated this call.</desc>
     1822      </param>
     1823      <param name="machineState" type="MachineState" dir="out">
     1824        <desc>New machine state after this operation is started.</desc>
     1825      </param>
     1826      <param name="progress" type="IProgress" dir="return">
     1827        <desc>Progress object to track the operation completion.</desc>
     1828      </param>
     1829    </method>
     1830
     1831  </interface>
     1832
     1833  <enum
     1834     name="BIOSBootMenuMode"
     1835     uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
     1836     >
     1837    <desc>
     1838      This represents the BIOS boot menu state.
     1839    </desc>
     1840
     1841    <const name="Disabled"       value="0"/>
     1842    <const name="MenuOnly"       value="1"/>
     1843    <const name="MessageAndMenu" value="2"/>
     1844  </enum>
     1845
     1846  <interface
     1847     name="IBIOSSettings" extends="$unknown"
     1848     uuid="946b83be-c5aa-4089-859d-db694f57d5ef"
     1849     wsmap="struct"
     1850     >
     1851    <attribute name="LogoFadeIn" type="boolean">
     1852      <desc>Fade in flag for BIOS logo animation.</desc>
     1853    </attribute>
     1854
     1855    <attribute name="LogoFadeOut" type="boolean">
     1856      <desc>Fade out flag for BIOS logo animation.</desc>
     1857    </attribute>
     1858
     1859    <attribute name="LogoDisplayTime" type="unsigned long">
     1860      <desc>BIOS logo display time in milliseconds (0 = default).</desc>
     1861    </attribute>
     1862
     1863    <attribute name="LogoImagePath" type="wstring">
     1864      <desc>Local file system path for external BIOS image.</desc>
     1865    </attribute>
     1866
     1867    <attribute name="BootMenuMode" type="BIOSBootMenuMode">
     1868      <desc>Mode of the BIOS boot device menu.</desc>
     1869    </attribute>
     1870
     1871    <attribute name="ACPIEnabled" type="boolean">
     1872      <desc>ACPI support flag.</desc>
     1873    </attribute>
     1874
     1875    <attribute name="IOAPICEnabled" type="boolean">
     1876      <desc>
     1877        IO APIC support flag. If set, VirtualBox will provide an IO APIC
     1878        and support IRQs above 15.
     1879      </desc>
     1880    </attribute>
     1881
     1882    <attribute name="TimeOffset" type="long long">
     1883      <desc>
     1884        Offset in milliseconds from the host system time. This allows for
     1885        guests running with a different system date/time than the host.
     1886        It is equivalent to setting the system date/time in the BIOS other
     1887        than it's not an absolute value but a relative one. Guest Additions
     1888        time synchronization also honors this offset.
     1889      </desc>
     1890    </attribute>
     1891
     1892  </interface>
     1893
     1894  <interface
     1895     name="IMachine" extends="$unknown"
     1896     uuid="0332de0e-ce75-461f-8c6f-0fa42616404a"
     1897     wsmap="managed"
     1898     >
     1899    <attribute name="parent" type="IVirtualBox" readonly="yes">
     1900      <desc>Associated parent obect.</desc>
     1901    </attribute>
     1902
     1903    <attribute name="accessible" type="boolean" readonly="yes">
     1904      <desc>
     1905        Whether this virtual machine is currently accessible or not.
     1906
     1907        The machine is considered to be inaccessible when:
     1908        <ul>
     1909          <li>It is a registered virtual machine, and
     1910          </li>
     1911          <li>Its settings file is inaccessible (for example, it is
     1912            located on a network share that is not accessible during
     1913            VirtualBox startup, or becomes inaccessible later, or if
     1914            the settings file can be read but is invalid).
     1915          </li>
     1916        </ul>
     1917
     1918        Otherwise, the value of this property is always <tt>true</tt>.
     1919
     1920        Every time this property is read, the accessibility state of
     1921        this machine is re-evaluated. If the returned value is |false|,
     1922        the <link to="#accessError"/> property may be used to get the
     1923        detailed error information describing the reason of
     1924        inaccessibility.
     1925
     1926        When the machine is inaccessible, only the following properties
     1927        can be used on it:
     1928        <ul>
     1929          <li><link to="#parent"/></li>
     1930          <li><link to="#id"/></li>
     1931          <li><link to="#settingsFilePath"/></li>
     1932          <li><link to="#accessible"/></li>
     1933          <li><link to="#accessError"/></li>
     1934        </ul>
     1935
     1936        An attempt to access any other property or method will return
     1937        an error.
     1938
     1939        The only possible action you can perform on an inaccessible
     1940        machine is to unregister it using the
     1941        <link to="IVirtualBox::unregisterMachine"/> call (or, to check
     1942        for the accessibility state once more by querying this
     1943        property).
     1944
     1945        <note>
     1946          In the current implementation, once this property returns
     1947          <tt>true</tt>, the machine will never become inaccessible
     1948          later, even if its settings file cannot be successfully
     1949          read/written any more (at least, until the VirtualBox
     1950          server is restarted). This limitation may be removed in
     1951          future releases.
     1952        </note>
     1953      </desc>
     1954    </attribute>
     1955
     1956    <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
     1957      <desc>
     1958        Error information describing the reason of machine
     1959        inaccessibility.
     1960
     1961        Reading this property is only valid after the last call to
     1962        <link to="#accessible"/> returned <tt>false</tt> (i.e. the
     1963        machine is currently unaccessible). Otherwise, a null
     1964        IVirtualBoxErrorInfo object will be returned.
     1965      </desc>
     1966    </attribute>
     1967
     1968    <attribute name="name" type="wstring">
     1969      <desc>
     1970        Name of the virtual machine.
     1971
     1972        Besides being used for human-readable identification purposes
     1973        everywhere in VirtualBox, the virtual machine name is also used
     1974        as a name of the machine's settings file and as a name of the
     1975        subdirectory this settings file resides in. Thus, every time you
     1976        change the value of this property, the settings file will be
     1977        renamed once you call <link to="#saveSettings()"/> to confirm the
     1978        change. The containing subdirectory will be also renamed, but
     1979        only if it has exactly the same name as the settings file
     1980        itself prior to changing this property (for backward compatibility
     1981        with previous API releases). The above implies the following
     1982        limitations:
     1983        <ul>
     1984          <li>The machine name cannot be empty.</li>
     1985          <li>The machine name can contain only characters that are valid
     1986            file name characters according to the rules of the file
     1987            system used to store VirtualBox configuration.</li>
     1988          <li>You cannot have two or more machines with the same name
     1989            if they use the same subdirectory for storing the machine
     1990            settings files.</li>
     1991          <li>You cannot change the name of the machine if it is running,
     1992            or if any file in the directory containing the settings file
     1993            is being used by another running machine or by any other
     1994            process in the host operating system at a time when
     1995            <link to="#saveSettings()"/> is called.
     1996          </li>
     1997        </ul>
     1998        If any of the above limitations are hit, <link to="#saveSettings()"/>
     1999        will return an appropriate error message explaining the exact
     2000        reason and the changes you made to this machine will not be
     2001        saved.
     2002        <note>
     2003          For "legacy" machines created using the
     2004          <link to="IVirtualBox::createLegacyMachine()"/> call,
     2005          the above naming limitations do not apply because the
     2006          machine name does not affect the settings file name.
     2007          The settings file name remains the same as it was specified
     2008          during machine creation and never changes.
     2009        </note>
     2010      </desc>
     2011    </attribute>
     2012
     2013    <attribute name="description" type="wstring">
     2014      <desc>
     2015        Description of the virtual machine.
     2016
     2017        The description attribute can contain any text and is
     2018        typically used to describe the hardware and software
     2019        configuration of the virtual machine in detail (i.e. network
     2020        settings, versions of the installed software and so on).
     2021      </desc>
     2022    </attribute>
     2023
     2024    <attribute name="id" type="uuid" readonly="yes">
     2025      <desc>UUID of the virtual machine.</desc>
     2026    </attribute>
     2027
     2028    <attribute name="OSTypeId" type="wstring">
     2029      <desc>
     2030        User-defined identifier of the Guest OS type.
     2031        You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
     2032        an IGuestOSType object representing details about the given
     2033        Guest OS type.
     2034        <note>
     2035          This value may differ from the value returned by
     2036          <link to="IGuest::OSTypeId"/> if Guest Additions are
     2037          installed to the guest OS.
     2038        </note>
     2039      </desc>
     2040    </attribute>
     2041
     2042    <attribute name="memorySize" type="unsigned long">
     2043      <desc>Sytem memory size in megabytes.</desc>
     2044    </attribute>
     2045
     2046    <attribute name="VRAMSize" type="unsigned long">
     2047      <desc>Video memory size in megabytes.</desc>
     2048    </attribute>
     2049
     2050    <attribute name="MonitorCount" type="unsigned long">
     2051      <desc>
     2052        Number of virtual monitors.
     2053        <note>
     2054          Only effective on Windows XP and later guests with
     2055          Guest Additions installed.
     2056        </note>
     2057      </desc>
     2058    </attribute>
     2059
     2060    <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
     2061      <desc>Object containing all BIOS settings.</desc>
     2062    </attribute>
     2063
     2064    <attribute name="HWVirtExEnabled" type="TriStateBool">
     2065      <desc>
     2066        This setting determines whether VirtualBox will try to make use of
     2067        the host CPU's hardware virtualization extensions such as Intel VT-x
     2068        and AMD SVM. Note that in case such extensions are not available,
     2069        they will not be used.
     2070      </desc>
     2071    </attribute>
     2072
     2073    <attribute name="snapshotFolder" type="wstring">
     2074      <desc>
     2075        Full path to the directory used to store snapshot data
     2076        (difrerencing hard disks and saved state files) of this machine.
     2077
     2078        The initial value of this property is
     2079        <tt>&lt;</tt><link to="#settingsFilePath">
     2080          path_to_settings_file</link><tt>&gt;/&lt;</tt>
     2081        <link to="#id">machine_uuid</link>
     2082        <tt>&gt;</tt>.
     2083
     2084        Currently, it is an error to try to change this property on
     2085        a machine that has snapshots (because this would require to
     2086        move possibly large files to a different location).
     2087        A separate method will be available for this purpose later.
     2088
     2089        <note>
     2090          Setting this property to <tt>null</tt> will restore the
     2091          initial value.
     2092        </note>
     2093        <note>
     2094          When setting this property, the specified path can be
     2095          absolute (full path) or relative to the directory where the
     2096          <link to="#settingsFilePath">machine settings file</link>
     2097          is located. When reading this property, a full path is
     2098          always returned.
     2099        </note>
     2100        <note>
     2101          The specified path may not exist, it will be created
     2102          when necessary.
     2103        </note>
     2104      </desc>
     2105    </attribute>
     2106
     2107    <attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
     2108      <desc>VRDP server object.</desc>
     2109    </attribute>
     2110
     2111    <attribute name="hardDiskAttachments" type="IHardDiskAttachmentCollection" readonly="yes">
     2112      <desc>Collection of hard disks attached to the machine.</desc>
     2113    </attribute>
     2114
     2115    <attribute name="DVDDrive" type="IDVDDrive" readonly="yes">
     2116      <desc>Associated DVD drive object.</desc>
     2117    </attribute>
     2118
     2119    <attribute name="FloppyDrive" type="IFloppyDrive" readonly="yes">
     2120      <desc>Associated floppy drive object.</desc>
     2121    </attribute>
     2122
     2123    <attribute name="USBController" type="IUSBController" readonly="yes">
     2124      <desc>Associated USB controller object.</desc>
     2125    </attribute>
     2126
     2127    <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
     2128      <desc>Associated audio adapter, always present.</desc>
     2129    </attribute>
     2130
     2131    <attribute name="settingsFilePath" type="wstring" readonly="yes">
     2132      <desc>
     2133        Full name of the file containing machine settings data.
     2134      </desc>
     2135    </attribute>
     2136
     2137    <attribute name="settingsModified" type="boolean" readonly="yes">
     2138      <desc>
     2139        Whether the settings of this machine have been modified
     2140        (but neither yet saved nor discarded).
     2141        <note>
     2142          Reading this property is only valid on instances returned
     2143          by <link to="ISession::machine"/> and on new machines
     2144          created by <link to="IVirtualBox::createMachine"/> or opened
     2145          by <link to="IVirtualBox::openMachine"/> but not
     2146          yet registered, or on unregistered machines after calling
     2147          <link to="IVirtualBox::unregisterMachine"/>. For all other
     2148          cases, the settigs can never be modified.
     2149        </note>
     2150        <note>
     2151          For newly created unregistered machines, the value of this
     2152          property is always TRUE until <link to="#saveSettings"/>
     2153          is called (no matter if any machine settings have been
     2154          changed after the creation or not). For opened machines
     2155          the value is set to FALSE (and then follows to normal rules).
     2156        </note>
     2157      </desc>
     2158    </attribute>
     2159
     2160    <attribute name="sessionState" type="SessionState" readonly="yes">
     2161      <desc>Current session state for this machine.</desc>
     2162    </attribute>
     2163
     2164    <attribute name="sessionType" type="wstring" readonly="yes">
     2165      <desc>
     2166        Type of the session.  If <link to="#sessionState"/> is
     2167        SessionSpawning or SessionOpen, this attribute contains the
     2168        same value as passed to the
     2169        <link to="IVirtualBox::openRemoteSession()"/> method in the @a
     2170        type parameter. If the session was opened directly using
     2171        <link to="IVirtualBox::openSession()"/>, or if
     2172        <link to="#sessionState"/> is SessionClosed, the value of this
     2173        attribute is @c null.
     2174      </desc>
     2175    </attribute>
     2176
     2177    <attribute name="sessionPid" type="unsigned long" readonly="yes">
     2178      <desc>
     2179        Identifier of the session process. This attribute contains the
     2180        platform-dependent identifier of the process that has opened a
     2181        direct session for this machine using the
     2182        <link to="IVirtualBox::openSession()"/> call. The returned value
     2183        is only valid if <link to="#sessionState"/> is SessionOpen or
     2184        SessionClosing (i.e. a session is currently open or being
     2185        closed) by the time this property is read.
     2186      </desc>
     2187    </attribute>
     2188
     2189    <attribute name="state" type="MachineState" readonly="yes">
     2190      <desc>Current execution state of this machine.</desc>
     2191    </attribute>
     2192
     2193    <attribute name="lastStateChange" type="long long" readonly="yes">
     2194      <desc>
     2195        Time stamp of the last execution state change,
     2196        in milliseconds since 1970-01-01 UTC.
     2197      </desc>
     2198    </attribute>
     2199
     2200    <attribute name="stateFilePath" type="wstring" readonly="yes">
     2201      <desc>
     2202        Full path to the file that stores the execution state of
     2203        the machine when it is in the <link to="MachineState::Saved"/>
     2204        state.
     2205        <note>
     2206          When the machine is not in the Saved state, this attribute
     2207          <tt>null</tt>.
     2208        </note>
     2209      </desc>
     2210    </attribute>
     2211
     2212    <attribute name="logFolder" type="wstring" readonly="yes">
     2213      <desc>
     2214        Full path to the folder that stores a set of rotated log files
     2215        recorded during machine execution. The most recent log file is
     2216        named <tt>VBox.log</tt>, the previous log file is
     2217        named <tt>VBox.log.1</tt> and so on (upto <tt>VBox.log.3</tt>
     2218        in the current version).
     2219      </desc>
     2220    </attribute>
     2221
     2222    <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
     2223      <desc>
     2224        Current snapshot of this machine.
     2225        <note>
     2226          A <tt>null</tt> object is returned if the machine doesn't
     2227          have snapshots.
     2228        </note>
     2229        <see><link to="ISnapshot"/></see>
     2230      </desc>
     2231    </attribute>
     2232
     2233    <attribute name="snapshotCount" type="unsigned long" readonly="yes">
     2234      <desc>
     2235        Number of snapshots taken on this machine. Zero means the
     2236        machine doesn't have any snapshots.
     2237      </desc>
     2238    </attribute>
     2239
     2240    <attribute name="currentStateModified" type="boolean" readonly="yes">
     2241      <desc>
     2242        Returns <tt>true</tt> if the current state of the machine is not
     2243        identical to the state stored in the current snapshot.
     2244
     2245        The current state is identical to the current snapshot right
     2246        after one of the following calls are made:
     2247        <ul>
     2248          <li><link to="IConsole::discardCurrentState"/> or
     2249            <link to="IConsole::discardCurrentSnapshotAndState"/>
     2250          </li>
     2251          <li><link to="IConsole::takeSnapshot"/> (issued on a
     2252            powered off or saved machine, for which
     2253            <link to="#settingsModified"/> returns <tt>false</tt>)
     2254          </li>
     2255          <li><link to="IMachine::setCurrentSnapshot"/>
     2256          </li>
     2257        </ul>
     2258
     2259        The current state remains identical until one of the following
     2260        happens:
     2261        <ul>
     2262          <li>settings of the machine are changed</li>
     2263          <li>the saved state is discarded</li>
     2264          <li>the current snapshot is discarded</li>
     2265          <li>an attempt to execute the machine is made</li>
     2266        </ul>
     2267
     2268        <note>
     2269          For machines that don't have snapshots, this property is
     2270          always <tt>false</tt>.
     2271        </note>
     2272      </desc>
     2273    </attribute>
     2274
     2275    <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
     2276      <desc>
     2277        Collection of shared folders for this machine. These folders
     2278        are shared automatically upon machine startup and available only
     2279        to the guest OS installed within this machine.
     2280
     2281        New folders to share are added to the collection using
     2282        <link to="#createSharedFolder"/>. An existing shared folder can
     2283        be removed using <link to="#removeSharedFolder"/>.
     2284      </desc>
     2285    </attribute>
     2286
     2287    <attribute name="clipboardMode" type="ClipboardMode">
     2288      <desc>
     2289        Synchronization mode between the host OS clipboard
     2290        and the guest OS clipboard.
     2291      </desc>
     2292    </attribute>
     2293
     2294    <method name="setBootOrder">
     2295      <desc>
     2296        Puts the given device to the specified position in
     2297        the boot order.
     2298
     2299        @todo [remove?]
     2300        If the machine can have more than one device of the given type
     2301        (such as hard disks), then a separate method should be used to
     2302        specify the boot order for individual devices. Using this method
     2303        in such cases will put the first device in the group
     2304        (for example, a hard disk attached as Master on the primary
     2305        IDE controller) to the given position.
     2306
     2307        To indicate that no any device is associated with the
     2308        given position, <link to="DeviceType::NoDevice"/> should be used.
     2309
     2310        @todo setHardDiskBootOrder(), setNetworkBootOrder()
     2311      </desc>
     2312      <param name="position" type="unsigned long" dir="in">
     2313        <desc>
     2314          Position in the boot order (<tt>1</tt> to the total number of
     2315          devices the machine can boot from, as returned by
     2316          <link to="ISystemProperties::maxBootPosition"/>).
     2317        </desc>
     2318      </param>
     2319      <param name="device" type="DeviceType" dir="in">
     2320        <desc>
     2321          The type of the device used to boot at the given position.
     2322        </desc>
     2323      </param>
     2324    </method>
     2325
     2326    <method name="getBootOrder" const="yes">
     2327      <desc>
     2328        Returns the device type that occupies the specified
     2329        position in the boot order.
     2330
     2331        @todo [remove?]
     2332        If the machine can have more than one device of the returned type
     2333        (such as hard disks), then a separate method should be used to
     2334        retrieve the individual device that occupies the given position.
     2335
     2336        If here are no devices at the given position, then
     2337        <link to="DeviceType::NoDevice"/> is returned.
     2338
     2339        @todo getHardDiskBootOrder(), getNetworkBootOrder()
     2340      </desc>
     2341      <param name="order" type="unsigned long" dir="in">
     2342        <desc>
     2343          Position in the boot order (<tt>1</tt> to the total number of
     2344          devices the machine can boot from, as returned by
     2345          <link to="ISystemProperties::maxBootPosition"/>).
     2346        </desc>
     2347      </param>
     2348      <param name="device" type="DeviceType" dir="return">
     2349        <desc>
     2350          Device at the given position.
     2351        </desc>
     2352      </param>
     2353    </method>
     2354
     2355    <method name="attachHardDisk">
     2356      <desc>
     2357
     2358        Attaches a virtual hard disk identified by the given UUID to the
     2359        given device slot of the given controller. The specified device
     2360        must not have another disk attached and the given hard disk must
     2361        not be already attached to this machine.
     2362
     2363        See <link to="IHardDisk"/> for detailed information about
     2364        attaching hard disks.
     2365
     2366        <note>You cannot attach a hard disk to a running machine. Also,
     2367          you cannot attach a hard disk to a newly created machine until
     2368          it is registered.</note>
     2369
     2370        <note>Attaching a hard disk to a machine creates a <i>lazy</i>
     2371          attachment. In particular, no differeincing images are
     2372          actually created until <link to="#saveSettings"/> is called to
     2373          commit all changed settings.</note>
     2374
     2375      </desc>
     2376      <param name="diskID" type="uuid" dir="in">
     2377        <desc>UUID of the hard disk to attach.</desc>
     2378      </param>
     2379      <param name="controller" type="DiskControllerType" dir="in">
     2380        <desc>Controller to attach the hard disk to.</desc>
     2381      </param>
     2382      <param name="device" type="long" dir="in">
     2383        <desc>Device slot to attach the hard disk to.</desc>
     2384      </param>
     2385    </method>
     2386
     2387    <method name="getHardDisk" const="yes">
     2388      <desc>
     2389        Returns the hard disk attached to the
     2390        given controller under the specified device number.
     2391      </desc>
     2392      <param name="controller" type="DiskControllerType" dir="in"/>
     2393      <param name="deviceNumber" type="long" dir="in"/>
     2394      <param name="hardDisk" type="IHardDisk" dir="return"/>
     2395    </method>
     2396
     2397    <method name="detachHardDisk">
     2398      <desc>
     2399
     2400        Detaches the hard disk drive attached to the given device slot
     2401        of the given controller.
     2402
     2403        See <link to="IHardDisk"/> for detailed information about
     2404        attaching hard disks.
     2405
     2406        <note>You cannot detach a hard disk from a running
     2407          machine.</note>
     2408
     2409        <note>
     2410          Detaching a hard disk from a machine creates a <i>lazy</i>
     2411          detachment. In particular, if the detached hard disk is a
     2412          differencing hard disk, it is not actually deleted until
     2413          <link to="#saveSettings"/> is called to commit all changed settings.
     2414          Keep in mind, that doing <link to="#saveSettings"/> will
     2415          <b>physically delete</b> all detached differencing hard disks,
     2416          so be careful.
     2417        </note>
     2418
     2419      </desc>
     2420      <param name="controller" type="DiskControllerType" dir="in">
     2421        <desc>Controller to dettach the hard disk from.</desc>
     2422      </param>
     2423      <param name="device" type="long" dir="in">
     2424        <desc>Device slot to dettach the hard disk from.</desc>
     2425      </param>
     2426    </method>
     2427
     2428    <method name="getNetworkAdapter" const="yes">
     2429      <desc>
     2430        Returns the network adapter associated with the given slot.
     2431        Slots are numbered sequentially, starting with zero. The total
     2432        number of adapters per every machine is defined by the
     2433        <link to="ISystemProperties::networkAdapterCount"/> property,
     2434        so the maximum slot number is one less than that property's value.
     2435      </desc>
     2436      <param name="slot" type="unsigned long" dir="in"/>
     2437      <param name="adapter" type="INetworkAdapter" dir="return"/>
     2438    </method>
     2439
     2440    <method name="getNextExtraDataKey">
     2441      <desc>
     2442        Returns the extra data key name following the supplied key.
     2443        An error is returned if the supplied key does not exist.
     2444        NULL is returned if the supplied key is the last key.
     2445        When supplying NULL for the key, the first item is returned.
     2446        NextValue is an optional parameter and if supplied, the next
     2447        key's value is returned as well.
     2448      </desc>
     2449      <param name="key" type="wstring" dir="in"/>
     2450      <param name="nextKey" type="wstring" dir="out"/>
     2451      <param name="nextValue" type="wstring" dir="out"/>
     2452    </method>
     2453
     2454    <method name="getExtraData">
     2455      <desc>Returns associated extra data.</desc>
     2456      <param name="key" type="wstring" dir="in"/>
     2457      <param name="value" type="wstring" dir="return"/>
     2458    </method>
     2459
     2460    <method name="setExtraData">
     2461      <desc>Sets associated extra data.</desc>
     2462      <param name="key" type="wstring" dir="in"/>
     2463      <param name="value" type="wstring" dir="in"/>
     2464    </method>
     2465
     2466    <method name="saveSettings">
     2467      <desc>
     2468        Saves any changes to machine settings made since the session
     2469        has been opened or a new machine has been created, or since the
     2470        last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
     2471        For registered machines, new settings become visible to all
     2472        other VirtualBox clients after successful invocation of this
     2473        method.
     2474        <note>
     2475          The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
     2476          notification event after the configuration has been successfully
     2477          saved (only for registered machines).
     2478        </note>
     2479        <note>
     2480          Calling this method is only valid on instances returned
     2481          by <link to="ISession::machine"/> and on new machines
     2482          created by <link to="IVirtualBox::createMachine"/> but not
     2483          yet registered, or on unregistered machines after calling
     2484          <link to="IVirtualBox::unregisterMachine"/>.
     2485        </note>
     2486      </desc>
     2487    </method>
     2488
     2489    <method name="discardSettings">
     2490      <desc>
     2491        Discards any changes to the machine settings made since the session
     2492        has been opened or since the last call to <link to="#saveSettings"/>
     2493        or <link to="#discardSettings"/>.
     2494        <note>
     2495          Calling this method is only valid on instances returned
     2496          by <link to="ISession::machine"/> and on new machines
     2497          created by <link to="IVirtualBox::createMachine"/> or
     2498          opened by <link to="IVirtualBox::openMachine"/> but not
     2499          yet registered, or on unregistered machines after calling
     2500          <link to="IVirtualBox::unregisterMachine"/>.
     2501        </note>
     2502      </desc>
     2503    </method>
     2504
     2505    <method name="deleteSettings">
     2506      <desc>
     2507        Deletes the settings file of this machine from disk.
     2508        The machine must not be registered in order for this operation
     2509        to succeed.
     2510        <note>
     2511          <link to="#settingsModified"/> will return TRUE after this
     2512          method successfully returns.
     2513        </note>
     2514        <note>
     2515          Calling this method is only valid on instances returned
     2516          by <link to="ISession::machine"/> and on new machines
     2517          created by <link to="IVirtualBox::createMachine"/> or
     2518          opened by <link to="IVirtualBox::openMachine"/> but not
     2519          yet registered, or on unregistered machines after calling
     2520          <link to="IVirtualBox::unregisterMachine"/>.
     2521        </note>
     2522        <note>
     2523          The deleted machine settings file can be restored (saved again)
     2524          by calling <link to="#saveSettings"/>.
     2525        </note>
     2526      </desc>
     2527    </method>
     2528
     2529    <method name="getSnapshot">
     2530      <desc>
     2531        Returns a snapshot of this machine with the given UUID.
     2532        A <tt>null</tt> UUID can be used to obtain the first snapshot
     2533        taken on this machine. This is useful if you want to traverse
     2534        the whole tree of snapshots starting from the root.
     2535      </desc>
     2536      <param name="id" type="uuid" dir="in">
     2537        <desc>UUID of the snapshot to get</desc>
     2538      </param>
     2539      <param name="snapshot" type="ISnapshot" dir="return">
     2540        <desc>Snapshot object with the given UUID.</desc>
     2541      </param>
     2542    </method>
     2543
     2544    <method name="findSnapshot">
     2545      <desc>
     2546        Returns a snapshot of this machine with the given name.
     2547      </desc>
     2548      <param name="name" type="wstring" dir="in">
     2549        <desc>Name of the snapshot to find</desc>
     2550      </param>
     2551      <param name="snapshot" type="ISnapshot" dir="return">
     2552        <desc>Snapshot object with the given name.</desc>
     2553      </param>
     2554    </method>
     2555
     2556    <method name="setCurrentSnapshot">
     2557      <desc>
     2558        Sets the current snapshot of this machine.
     2559        <note>
     2560          In the current implementation, this operation is not
     2561          implemented.
     2562        </note>
     2563      </desc>
     2564      <param name="id" type="uuid" dir="in">
     2565        <desc>UUID of the snapshot to set as the current snapshot.</desc>
     2566      </param>
     2567    </method>
     2568
     2569    <method name="createSharedFolder">
     2570      <desc>
     2571        Creates a new shared folder by associating the given logical
     2572        name with the given host path, adds it to the collection of
     2573        shared folders and starts sharing it.
     2574        Refer to the description of <link to="ISharedFolder"/> to read
     2575        about logical name unicity.
     2576      </desc>
     2577      <param name="name" type="wstring" dir="in">
     2578        <desc>Unique logical name of the shared folder.</desc>
     2579      </param>
     2580      <param name="hostPath" type="wstring" dir="in">
     2581        <desc>Full path to the shared folder in the host file system.</desc>
     2582      </param>
     2583    </method>
     2584
     2585    <method name="removeSharedFolder">
     2586      <desc>
     2587        Removes a shared folder with the given name previously created
     2588        by <link to="#createSharedFolder"/> from the collection of
     2589        shared folders and stops sharing it.
     2590      </desc>
     2591      <param name="name" type="wstring" dir="in">
     2592        <desc>Logical name of the shared folder to remove.</desc>
     2593      </param>
     2594    </method>
     2595
     2596    <method name="canShowConsoleWindow">
     2597      <desc>
     2598        Returns @c true if the VM console process can activate the
     2599        console window and bring it to foreground on the desktop of
     2600        the host PC.
     2601        <note>
     2602          This method will fail if a session for this machine is not
     2603          currently open.
     2604        </note>
     2605      </desc>
     2606      <param name="canShow" type="boolean" dir="return">
     2607        <desc>
     2608          @c true if the console window can be shown and @c
     2609          false otherwise.
     2610        </desc>
     2611      </param>
     2612    </method>
     2613
     2614    <method name="showConsoleWindow">
     2615      <desc>
     2616        Activates the console window and brings it to foreground on
     2617        the desktop of the host PC. Many modern window managers on
     2618        many platforms implement some sort of focus stealing
     2619        prevention logic, so that it may be impossible to activate
     2620        a window without the help of the currently active
     2621        application. In this case, this method will return a non-zero
     2622        identifier that represents the top-level window of the VM
     2623        console process. The caller, if it represents a currently
     2624        active process, is responsible to use this identifier (in a
     2625        platform-dependent manner) to perform actual window
     2626        activation.
     2627        <note>
     2628          This method will fail if a session for this machine is not
     2629          currently open.
     2630        </note>
     2631      </desc>
     2632      <param name="winId" type="unsigned long long" dir="return">
     2633        <desc>
     2634          Platform-dependent identifier of the top-level VM console
     2635          window, or zero if this method has performed all actions
     2636          necessary to implement the <i>show window</i> semantics for
     2637          the given platform and/or VirtualBox front-end.
     2638        </desc>
     2639      </param>
     2640    </method>
     2641
     2642  </interface>
     2643
     2644  <!--
     2645  // IConsole
     2646  /////////////////////////////////////////////////////////////////////////
     2647  -->
     2648
     2649  <interface
     2650     name="IConsoleCallback" extends="$unknown"
     2651     uuid="ebd0c5f2-7b11-4508-803f-012099caee03"
     2652     wsmap="suppress"
     2653     >
     2654
     2655    <method name="onMousePointerShapeChange">
     2656      <desc>
     2657        Notification when the guest mouse pointer shape has
     2658        changed. The new shape data is given.
     2659      </desc>
     2660      <param name="visible" type="boolean" dir="in">
     2661        <desc>
     2662          Flag whether the pointer is visible.
     2663        </desc>
     2664      </param>
     2665      <param name="alpha" type="boolean" dir="in">
     2666        <desc>
     2667          Flag whether the pointer has an alpha channel.
     2668        </desc>
     2669      </param>
     2670      <param name="xHot" type="unsigned long" dir="in">
     2671        <desc>
     2672          The pointer hot spot x coordinate.
     2673        </desc>
     2674      </param>
     2675      <param name="yHot" type="unsigned long" dir="in">
     2676        <desc>
     2677          The pointer hot spot y coordinate.
     2678        </desc>
     2679      </param>
     2680      <param name="width" type="unsigned long" dir="in">
     2681        <desc>
     2682          Width of the pointer shape in pixels.
     2683        </desc>
     2684      </param>
     2685      <param name="height" type="unsigned long" dir="in">
     2686        <desc>
     2687          Height of the pointer shape in pixels.
     2688        </desc>
     2689      </param>
     2690      <param name="shape" type="octet" mod="ptr" dir="in">
     2691        <desc>
     2692          Address of the shape buffer.
     2693
     2694          The buffer contains 1 bpp (bits per pixel) AND mask followed by 32 bpp XOR (color) mask.
     2695
     2696          For pointers without alpha channel the XOR mask pixels are 32 bit values: (lsb)BGR0(msb).
     2697          For pointers with alpha channel the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
     2698
     2699          AND mask presents for pointers with alpha channel, so if the callback does not
     2700          support alpha, the pointer could be displayed as a normal color pointer.
     2701
     2702          The AND mask is 1 bpp bitmap with byte aligned scanlines. Size of AND mask,
     2703          therefore, is <tt>cbAnd = (width + 7) / 8 * height</tt>. The padding bits at the
     2704          end of any scanline are undefined.
     2705
     2706          The XOR mask follows the AND mask on the next 4 bytes aligned offset:
     2707          <tt>uint8_t *pXor = pAnd + (cbAnd + 3) &amp; ~3</tt>
     2708          Bytes in the gap between the AND and the XOR mask are undefined.
     2709          XOR mask scanlines have no gap between them and size of XOR mask is:
     2710          <tt>cXor = width * 4 * height</tt>.
     2711
     2712          <note>
     2713            If 'shape' is equal to 0, only pointer visibility is being changed.
     2714          </note>
     2715        </desc>
     2716      </param>
     2717    </method>
     2718
     2719    <method name="onMouseCapabilityChange">
     2720      <desc>
     2721        Notification when the mouse capabilities reported by the
     2722        guest have changed. The new capabilities are passed.
     2723      </desc>
     2724      <param name="supportsAbsolute" type="boolean" dir="in"/>
     2725      <param name="needsHostCursor" type="boolean" dir="in"/>
     2726    </method>
     2727
     2728    <method name="onKeyboardLedsChange">
     2729      <desc>
     2730        Notification of the host if the guest executed the KBD_CMD_SET_LEDS
     2731        command to alter the state of the keyboard LEDs.
     2732      </desc>
     2733      <param name="numLock" type="boolean" dir="in"/>
     2734      <param name="capsLock" type="boolean" dir="in"/>
     2735      <param name="scrollLock" type="boolean" dir="in"/>
     2736    </method>
     2737
     2738    <method name="onStateChange">
     2739      <desc>
     2740        Notification when the execution state of the machine has changed.
     2741        The new state will be given.
     2742      </desc>
     2743      <param name="state" type="MachineState" dir="in"/>
     2744    </method>
     2745
     2746    <method name="onAdditionsStateChange">
     2747      <desc>
     2748        Notification when a Guest Additions property changes.
     2749        Interested callees should query IGuest's properties to
     2750        find out what has changed.
     2751      </desc>
     2752    </method>
     2753
     2754    <method name="onUSBDeviceStateChange">
     2755      <desc>
     2756        Notification when a USB device is attached to or detached from
     2757        the virtual USB controller.
     2758
     2759        This notification is sent as a result of the indirect
     2760        request to attach the device because it matches one of the
     2761        machine USB filters, or as a result of the direct request
     2762        issued by <link to="IConsole::attachUSBDevice"/> or
     2763        <link to="IConsole::detachUSBDevice"/>.
     2764
     2765        This notification is sent in case of both a succeeded and a
     2766        failed request completion. When the request succeeds, the @a
     2767        error parameter is @c null, and the given device has been
     2768        already added to (when @a attached is @c true) or removed from
     2769        (when @a attached is @c false) the collection represented by
     2770        <link to="IConsole::USBDevices"/>. On failure, the collection
     2771        doesn't change and the @a error perameter represents the error
     2772        message describing the failure.
     2773
     2774      </desc>
     2775      <param name="device" type="IUSBDevice" dir="in">
     2776        <desc>Device that is subject to state change.</desc>
     2777      </param>
     2778      <param name="attached" type="boolean" dir="in">
     2779        <desc>
     2780          <tt>true</tt> if the device was attached
     2781          and <tt>false</tt> otherwise.
     2782        </desc>
     2783      </param>
     2784      <param name="error" type="IVirtualBoxErrorInfo" dir="in">
     2785        <desc>
     2786          <tt>null</tt> on success or an error message object on
     2787          failure.
     2788        </desc>
     2789      </param>
     2790    </method>
     2791
     2792    <method name="onRuntimeError">
     2793      <desc>
     2794        Notification when an error happens during the virtual
     2795        machine execution.
     2796
     2797        There are three kinds of runtime errors:
     2798        <ul>
     2799          <li><i>fatal</i></li>
     2800          <li><i>non-fatal with retry</i></li>
     2801          <li><i>non-fatal warnings</i></li>
     2802        </ul>
     2803
     2804        <b>Fatal</b> errors are indicated by the @a fatal parameter set
     2805        to <tt>true</tt>. In case of fatal errors, the virtual machine
     2806        execution is always paused before calling this notification, and
     2807        the notification handler is supposed either to immediately save
     2808        the virtual machine state using <link to="IConsole::saveState()"/>
     2809        or power it off using <link to="IConsole::powerDown()"/>.
     2810        Resuming the execution can lead to unpredictable results.
     2811
     2812        <b>Non-fatal</b> errors and warnings are indicated by the
     2813        @a fatal parameter set to <tt>false</tt>. If the virtual machine
     2814        is in the Paused state by the time the error notification is
     2815        received, it means that the user can <i>try to resume</i> the machine
     2816        execution after attempting to solve the probem that caused the
     2817        error. In this case, the notification handler is supposed
     2818        to show an appropriate message to the user (depending on the
     2819        value of the @a id parameter) that offers several actions such
     2820        as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
     2821        wants to retry, the notification handler should continue
     2822        the machine execution using the <link to="IConsole::resume()"/>
     2823        call. If the machine execution is not Paused during this
     2824        notification, then it means this notification is a <i>warning</i>
     2825        (for example, about a fatal condition that can happen very soon);
     2826        no immediate action is required from the user, the machine
     2827        continues its normal execution.
     2828
     2829        Note that in either case the notification handler
     2830        <b>must not</b> perform any action directly on a thread
     2831        where this notification is called. Everything it is allowed to
     2832        do is to post a message to another thread that will then talk
     2833        to the user and take the corresponding action.
     2834
     2835        Currently, the following error identificators are known:
     2836        <ul>
     2837          <li><tt>"HostMemoryLow"</tt></li>
     2838          <li><tt>"HostAudioNotResponding"</tt></li>
     2839          <li><tt>"VDIStorageFull"</tt></li>
     2840        </ul>
     2841
     2842        <note>
     2843          This notification is not designed to be implemented by
     2844          more than one callback at a time. If you have multiple
     2845          IConsoleCallback instances registered on the given
     2846          IConsole object, make sure you simply do nothing but
     2847          return @c S_OK from all but one of them that does actual
     2848          user notification and performs necessary actions.
     2849        </note>
     2850
     2851      </desc>
     2852      <param name="fatal" type="boolean" dir="in">
     2853        <desc>Whether the error is fatal or not</desc>
     2854      </param>
     2855      <param name="id" type="wstring" dir="in">
     2856        <desc>Error identificator</desc>
     2857      </param>
     2858      <param name="message" type="wstring" dir="in">
     2859        <desc>Optional error message</desc>
     2860      </param>
     2861    </method>
     2862
     2863    <method name="onCanShowWindow">
     2864      <desc>
     2865        Notification when a call to
     2866        <link to="IMachine::canShowConsoleWindow()"/> is made by a
     2867        front-end to check if a subsequent call to
     2868        <link to="IMachine::showConsoleWindow()"/> can succeed.
     2869
     2870        The callee should give an answer appropriate to the current
     2871        machine state in the @a canShow argument. This answer must
     2872        remain valid at least until the next
     2873        <link to="IConsole::state">machine state</link> change.
     2874
     2875        <note>
     2876          This notification is not designed to be implemented by
     2877          more than one callback at a time. If you have multiple
     2878          IConsoleCallback instances registered on the given
     2879          IConsole object, make sure you simply do nothing but
     2880          return @c true and @c S_OK from all but one of them that
     2881          actually manages console window activation.
     2882        </note>
     2883      </desc>
     2884      <param name="canShow" type="boolean" dir="return">
     2885        <desc>
     2886          @c true if the console window can be shown and @c
     2887          false otherwise.
     2888        </desc>
     2889      </param>
     2890    </method>
     2891
     2892    <method name="onShowWindow">
     2893      <desc>
     2894        Notification when a call to
     2895        <link to="IMachine::showConsoleWindow()"/>
     2896        requests the console window to be activated and brought to
     2897        foreground on the desktop of the host PC.
     2898
     2899        This notification should cause the VM console process to
     2900        perform the requested action as described above. If it is
     2901        impossible to do it at a time of this notification, this
     2902        method should return a failure.
     2903
     2904        Note that many modern window managers on many platforms
     2905        implement some sort of focus stealing prevention logic, so
     2906        that it may be impossible to activate a window without the
     2907        help of the currently active application (which is supposedly
     2908        an initiator of this notification). In this case, this method
     2909        must return a non-zero identifier that represents the
     2910        top-level window of the VM console process. The caller, if it
     2911        represents a currently active process, is responsible to use
     2912        this identifier (in a platform-dependent manner) to perform
     2913        actual window activation.
     2914
     2915        This method must set @a winId to zero if it has performed all
     2916        actions necessary to complete the request and the console
     2917        window is now active and in foreground, to indicate that no
     2918        further action is required on the caller's side.
     2919
     2920        <note>
     2921          This notification is not designed to be implemented by
     2922          more than one callback at a time. If you have multiple
     2923          IConsoleCallback instances registered on the given
     2924          IConsole object, make sure you simply do nothing but
     2925          return@c S_OK from all but one of them that actually
     2926          manages console window activation.
     2927        </note>
     2928      </desc>
     2929      <param name="winId" type="unsigned long long" dir="return">
     2930        <desc>
     2931          Platform-dependent identifier of the top-level VM console
     2932          window, or zero if this method has performed all actions
     2933          necessary to implement the <i>show window</i> semantics for
     2934          the given platform and/or this VirtualBox front-end.
     2935        </desc>
     2936      </param>
     2937    </method>
     2938
     2939  </interface>
     2940
     2941  <interface
     2942     name="IRemoteDisplayInfo" extends="$unknown"
     2943     uuid="550104cd-2dfd-4a6c-857d-f6f8e088e62c"
     2944     wsmap="struct"
     2945     >
     2946    <attribute name="active" type="boolean" readonly="yes">
     2947      <desc>
     2948        Whether the remote display connection is active.
     2949      </desc>
     2950    </attribute>
     2951
     2952    <attribute name="numberOfClients" type="unsigned long" readonly="yes">
     2953      <desc>
     2954        How many times a client connected.
     2955      </desc>
     2956    </attribute>
     2957
     2958    <attribute name="beginTime" type="long long" readonly="yes">
     2959      <desc>
     2960        When the last connection was established, in milliseconds since 1970-01-01 UTC.
     2961      </desc>
     2962    </attribute>
     2963
     2964    <attribute name="endTime" type="long long" readonly="yes">
     2965      <desc>
     2966        When the last connection was terminated or the current time, if
     2967        connection is still active, in milliseconds since 1970-01-01 UTC.
     2968      </desc>
     2969    </attribute>
     2970
     2971    <attribute name="bytesSent" type="unsigned long long" readonly="yes">
     2972      <desc>
     2973        How many bytes were sent in last or current, if still active, connection.
     2974      </desc>
     2975    </attribute>
     2976
     2977    <attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
     2978      <desc>
     2979        How many bytes were sent in all connections.
     2980      </desc>
     2981    </attribute>
     2982
     2983    <attribute name="bytesReceived" type="unsigned long long" readonly="yes">
     2984      <desc>
     2985        How many bytes were received in last or current, if still active, connection.
     2986      </desc>
     2987    </attribute>
     2988
     2989    <attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
     2990      <desc>
     2991        How many bytes were received in all connections.
     2992      </desc>
     2993    </attribute>
     2994
     2995    <attribute name="user" type="wstring" readonly="yes">
     2996      <desc>
     2997        Login user name supplied by the client.
     2998      </desc>
     2999    </attribute>
     3000
     3001    <attribute name="domain" type="wstring" readonly="yes">
     3002      <desc>
     3003        Login domain name supplied by the client.
     3004      </desc>
     3005    </attribute>
     3006
     3007    <attribute name="clientName" type="wstring" readonly="yes">
     3008      <desc>
     3009        The client name supplied by the client.
     3010      </desc>
     3011    </attribute>
     3012
     3013    <attribute name="clientIP" type="wstring" readonly="yes">
     3014      <desc>
     3015        The IP address of the client.
     3016      </desc>
     3017    </attribute>
     3018
     3019    <attribute name="clientVersion" type="unsigned long" readonly="yes">
     3020      <desc>
     3021        The client software version number.
     3022      </desc>
     3023    </attribute>
     3024
     3025    <attribute name="encryptionStyle" type="unsigned long" readonly="yes">
     3026      <desc>
     3027        Public key exchange method used when connection was established.
     3028        Values: 0 - RDP4 public key exchange scheme.
     3029        1 - X509 sertificates were sent to client.
     3030      </desc>
     3031    </attribute>
     3032
     3033  </interface>
     3034
     3035  <interface
     3036     name="IConsole" extends="$unknown"
     3037     uuid="1DEA5C4B-0753-4193-B909-22330F64EC45"
     3038     wsmap="managed"
     3039     >
     3040    <attribute name="machine" type="IMachine" readonly="yes">
     3041      <desc>
     3042        Machine object this console is sessioned with.
     3043        <note>
     3044          This is a convenience property, it has the same value as
     3045          <link to="ISession::machine"/> of the corresponding session
     3046          object.
     3047        </note>
     3048      </desc>
     3049    </attribute>
     3050
     3051    <attribute name="state" type="MachineState" readonly="yes">
     3052      <desc>
     3053        Current execution state of the machine.
     3054        <note>
     3055          This property always returns the same value as the corresponding
     3056          property of the IMachine object this console is sessioned with.
     3057          For the process, that owns (executes) the VM, this is the
     3058          preferrable way of quierying the VM state, because no IPC
     3059          calls are made.
     3060        </note>
     3061      </desc>
     3062    </attribute>
     3063
     3064    <attribute name="guest" type="IGuest" readonly="yes">
     3065      <desc>Guest object.</desc>
     3066    </attribute>
     3067
     3068    <attribute name="keyboard" type="IKeyboard" readonly="yes">
     3069      <desc>
     3070        Virtual keyboard object.
     3071        <note>
     3072          If the machine is not running, any attempt to use
     3073          the returned object will result in an error.
     3074        </note>
     3075      </desc>
     3076    </attribute>
     3077
     3078    <attribute name="mouse" type="IMouse" readonly="yes">
     3079      <desc>
     3080        Virtual mouse object.
     3081        <note>
     3082          If the machine is not running, any attempt to use
     3083          the returned object will result in an error.
     3084        </note>
     3085      </desc>
     3086    </attribute>
     3087
     3088    <attribute name="display" type="IDisplay" readonly="yes">
     3089      <desc>Virtual display object.
     3090        <note>
     3091          If the machine is not running, any attempt to use
     3092          the returned object will result in an error.
     3093        </note>
     3094      </desc>
     3095    </attribute>
     3096
     3097    <attribute name="debugger" type="IMachineDebugger" readonly="yes">
     3098      <desc>Debugging interface.</desc>
     3099    </attribute>
     3100
     3101    <attribute name="USBDevices" type="IUSBDeviceCollection" readonly="yes">
     3102      <desc>
     3103        Collection of USB devices currently attached to the virtual
     3104        USB controller.
     3105        <note>
     3106          The collection is empty if the machine is not running.
     3107        </note>
     3108      </desc>
     3109    </attribute>
     3110
     3111    <attribute name="remoteUSBDevices" type="IHostUSBDeviceCollection" readonly="yes">
     3112      <desc>
     3113        List of USB devices currently attached to the remote VRDP client.
     3114        Once a new device is physically attached to the remote host computer,
     3115        it appears in this list and remains there until detached.
     3116      </desc>
     3117    </attribute>
     3118
     3119    <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
     3120      <desc>
     3121        Collection of shared folders for the current session.
     3122        This collection is initially empty and is cleared once the
     3123        session is closed. On other words, this collection represents
     3124        transient shares (as opposed to <link to="IMachine::sharedFolders"/>
     3125        that stores permanent shares stored in the settings file).
     3126
     3127        New folders to share are added to the collection using
     3128        <link to="#createSharedFolder"/>. An existing shared folder can
     3129        be removed using <link to="#removeSharedFolder"/>.
     3130      </desc>
     3131    </attribute>
     3132
     3133    <attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
     3134      <desc>
     3135        Interface that provides information on Remote Display (VRDP) connection.
     3136      </desc>
     3137    </attribute>
     3138
     3139    <method name="powerUp">
     3140      <desc>
     3141        Starts the virtual machine execution using the current machine
     3142        state (i.e. its current execution state, current settings and
     3143        current hard disks).
     3144
     3145        If the machine is powered off or aborted, the execution will
     3146        start from the beginning (as if the real hardware were just
     3147        powered on).
     3148
     3149        If the machine is in the <link to="MachineState::Saved"/> state,
     3150        it will continue its execution the point where the state has
     3151        beem saved.
     3152
     3153        <see>#saveState</see>
     3154      </desc>
     3155      <param name="progress" type="IProgress" dir="return">
     3156        <desc>Progress object to track the operation completion.</desc>
     3157      </param>
     3158    </method>
     3159
     3160    <method name="powerDown">
     3161      <desc>
     3162        Stops the virtual machine execution.
     3163        After this operation completes, the machine will go to the
     3164        PoweredOff state.
     3165      </desc>
     3166    </method>
     3167
     3168    <method name="reset">
     3169      <desc>Resets the virtual machine.</desc>
     3170    </method>
     3171
     3172    <method name="pause">
     3173      <desc>Pauses the virtual machine execution.</desc>
     3174    </method>
     3175
     3176    <method name="resume">
     3177      <desc>Resumes the virtual machine execution.</desc>
     3178    </method>
     3179
     3180    <method name="powerButton">
     3181      <desc>Send the ACPI power button event to the guest.</desc>
     3182    </method>
     3183
     3184    <method name="saveState">
     3185      <desc>
     3186        Saves the current execution state of a running virtual machine
     3187        and stops its executiuon.
     3188
     3189        After this operation completes, the machine will go to the
     3190        Saved state. Next time it is powered up, this state will
     3191        be restored and the machine will continue its execution from
     3192        the place where it was saved.
     3193
     3194        This operation differs from taking a snapshot to the effect
     3195        that it doesn't create new differencing hard disks. Also, once
     3196        the machine is powered up from the state saved using this method,
     3197        the saved state is deleted, so it will be impossible to return
     3198        to this state later.
     3199
     3200        <note>
     3201          On success, this method implicitly calls
     3202          <link to="IMachine::saveSettings"/> to save all current machine
     3203          settings (including runtime changes to the DVD drive, etc.).
     3204          Together with the impossibility to change any VM settings when it is
     3205          in the Saved state, this guarantees the adequate hardware
     3206          configuration of the machine when it is restored from the saved
     3207          state file.
     3208        </note>
     3209
     3210        <note>
     3211          The machine must be in the Running or Paused state, otherwise
     3212          the operation will fail.
     3213        </note>
     3214
     3215        <see><link to="#takeSnapshot"/></see>
     3216      </desc>
     3217      <param name="progress" type="IProgress" dir="return">
     3218        <desc>Progress object to track the operation completion.</desc>
     3219      </param>
     3220    </method>
     3221
     3222    <method name="discardSavedState">
     3223      <desc>
     3224        Discards (deletes) the saved state of the virtual machine
     3225        previously created by <link to="#saveState"/>. Next time the
     3226        machine is powered up, a clean boot will occur.
     3227        <note>
     3228          This operation is equivalent to resetting or powering off
     3229          the machine without doing a proper shutdown in the guest OS.
     3230        </note>
     3231      </desc>
     3232    </method>
     3233
     3234    <method name="getDeviceActivity">
     3235      <desc>
     3236        Gets the current activity type of a given device or device group.
     3237      </desc>
     3238      <param name="type" type="DeviceType" dir="in"/>
     3239      <param name="activity" type="DeviceActivity" dir="return"/>
     3240    </method>
     3241
     3242    <method name="attachUSBDevice">
     3243      <desc>
     3244        Attaches a host USB device with the given UUID to the
     3245        USB controller of the virtual machine.
     3246
     3247        The device needs to be in one of the following states:
     3248        <link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,
     3249        <link to="USBDeviceState::USBDeviceAvailable">USBDeviceAvailable</link> or
     3250        <link to="USBDeviceState::USBDeviceHeld">USBDeviceHeld</link>,
     3251        otherwise an error is immediately returned.
     3252
     3253        When the device state is
     3254        <link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,
     3255        an error may also be returned if the host computer
     3256        refuses to release it for some reason.
     3257
     3258        <see>IUSBController::DeviceFilters, USBDeviceState</see>
     3259      </desc>
     3260      <param name="id" type="uuid" dir="in">
     3261        <desc>UUID of the host USB device to attach.</desc>
     3262      </param>
     3263    </method>
     3264
     3265    <method name="detachUSBDevice">
     3266      <desc>
     3267        Detaches an USB device with the given UUID from the USB controller
     3268        oif the virtual machine.
     3269
     3270        After this method succeeds, the VirtualBox server reinitiates
     3271        all USB filters as if the device were just physically attached
     3272        to the host, but filters of this machine are ignored to avoid
     3273        a possible automatic reattachment.
     3274
     3275        <see>IUSBController::DeviceFilters, USBDeviceState</see>
     3276      </desc>
     3277      <param name="id" type="uuid" dir="in">
     3278        <desc>UUID of the USB device to detach.</desc>
     3279      </param>
     3280      <param name="device" type="IUSBDevice" dir="return">
     3281        <desc>Detached USB device.</desc>
     3282      </param>
     3283    </method>
     3284
     3285    <method name="createSharedFolder">
     3286      <desc>
     3287        Creates a new shared folder by associating the given logical
     3288        name with the given host path, adds it to the collection of
     3289        shared folders and starts sharing it.
     3290        Refer to the description of <link to="ISharedFolder"/> to read
     3291        about logical name unicity.
     3292      </desc>
     3293      <param name="name" type="wstring" dir="in">
     3294        <desc>Unique logical name of the shared folder.</desc>
     3295      </param>
     3296      <param name="hostPath" type="wstring" dir="in">
     3297        <desc>Full path to the shared folder in the host file system.</desc>
     3298      </param>
     3299    </method>
     3300
     3301    <method name="removeSharedFolder">
     3302      <desc>
     3303        Removes a shared folder with the given name previously created
     3304        by <link to="#createSharedFolder"/> from the collection of
     3305        shared folders and stops sharing it.
     3306      </desc>
     3307      <param name="name" type="wstring" dir="in">
     3308        <desc>Logical name of the shared folder to remove.</desc>
     3309      </param>
     3310    </method>
     3311
     3312    <method name="takeSnapshot">
     3313      <desc>
     3314        Saves the current execution state and all settings of the
     3315        machine and creates differencing images for all
     3316        normal (non-independent) hard disks.
     3317
     3318        This method can be called for a PoweredOff, Saved, Running or
     3319        Paused virtual machine. When the machine is PoweredOff, an
     3320        offline <link to="ISnapshot">snapshot</link> is created,
     3321        in all other cases -- an online snapshot.
     3322
     3323        The taken snapshot is always based on the
     3324        <link to="IMachine::currentSnapshot">current
     3325          snapshot</link> of the associated virtual machine and becomes
     3326        a new current snapshot.
     3327
     3328        <note>
     3329          This method implicitly calls <link to="IMachine::saveSettings"/> to
     3330          save all current machine settings before taking an offline snapshot.
     3331        </note>
     3332
     3333        <see>ISnapshot, <link to="#saveState"/></see>
     3334      </desc>
     3335      <param name="name" type="wstring" dir="in">
     3336        <desc>Short name for the snapshot.</desc>
     3337      </param>
     3338      <param name="description" type="wstring" dir="in">
     3339        <desc>Optional description of the snapshot.</desc>
     3340      </param>
     3341      <param name="progress" type="IProgress" dir="return">
     3342        <desc>Progress object to track the operation completion.</desc>
     3343      </param>
     3344    </method>
     3345
     3346    <method name="discardSnapshot">
     3347      <desc>
     3348
     3349        Starts discarding the specified snapshot. The execution state
     3350        and settings of the associated machine stored in the snapshot
     3351        will be deleted. The contents of all differencing hard disks of
     3352        this snapshot will be merged with the contents of their
     3353        dependent child hard disks to keep the, disks valid (in other
     3354        words, all changes represented by hard disks being discarded
     3355        will be propagated to their child hard disks). After that, this
     3356        snapshot's differencing hard disks will be deleted. The parent
     3357        of this snapshot will become a new parent for all its child
     3358        snapshots.
     3359
     3360        If the discarded snapshot is the current one, its parent
     3361        snapshot will become a new current snapshot. The current machine
     3362        state is not directly affected in this case, except that
     3363        currently attached differencing hard disks based on hard disks
     3364        of the discarded snapshot will be also merged as described
     3365        above.
     3366
     3367        If the discarded snapshot is the first one (the root snapshot)
     3368        and it has exactly one child snapshot, this child snapshot will
     3369        become the first snapshot after discarding. If there are no
     3370        children at all (i.e. the first snapshot is the only snapshot of
     3371        the machine), both the current and the first snapshot of the
     3372        machine will be set to null. In all other cases, the first
     3373        snapshot cannot be discarded.
     3374
     3375        You cannot discard the snapshot if it
     3376        stores <link to="HardDiskType::NormalHardDisk">normal</link>
     3377        (non-differencing) hard disks that have differencing hard disks based
     3378        on them. Snapshots of such kind can be discarded only when every
     3379        normal hard disk has either no children at all or exactly one
     3380        child. In the former case, the normal hard disk simply becomes unused
     3381        (i.e. not attached to any VM). In the latter case, it receives all the
     3382        changes strored in the child hard disk, and then it replaces the child
     3383        hard disk in the configuration of the corresponding snapshot or
     3384        machine.
     3385
     3386        Also, you cannot discard the snapshot if it stores hard disks
     3387        (of any type) having differencing child hard disks that belong
     3388        to other machines. Such snapshots can be only discarded after
     3389        you discard all snapshots of other machines containing "foreign"
     3390        child disks, or detach these "foreign" child disks from machines
     3391        they are attached to.
     3392
     3393        One particular example of the snapshot storing normal hard disks
     3394        is the first snapshot of a virtual machine that had normal hard
     3395        disks attached when taking the snapshot. Be careful when
     3396        discarding such snapshots because this implicitly commits
     3397        changes (made since the snapshot being discarded has been taken)
     3398        to normal hard disks (as described above), which may be not what
     3399        you want.
     3400
     3401        The virtual machine is put to
     3402        the <link to="MachineState::Discarding">Discarding</link> state until
     3403        the discard operation is completed.
     3404
     3405        <note>
     3406          The machine must not be running, otherwise the operation
     3407          will fail.
     3408        </note>
     3409
     3410        <note>
     3411          Child hard disks of all normal hard disks of the discarded snapshot
     3412          must be <link to="IHardDisk::accessible">accessible</link> for this
     3413          operation to succeed.  In particular, this means that all virtual
     3414          machines, whose hard disks are directly or indirectly based on the
     3415          hard disks of discarded snapshot, must be powered off.
     3416        </note>
     3417        <note>
     3418          Merging hard disk contents can be very time and disk space
     3419          consuming, if these disks are big in size and have many
     3420          children. However, if the snapshot being discarded is the last
     3421          (head) snapshot on the branch, the operation will be rather
     3422          quick.
     3423        </note>
     3424        <note>
     3425          Note that discarding the current snapshot
     3426          will imlicitly call <link to="IMachine::saveSettings()"/> to
     3427          make all current machine settings permanent.
     3428        </note>
     3429      </desc>
     3430      <param name="id" type="uuid" dir="in">
     3431        <desc>UUID of the snapshot to discard.</desc>
     3432      </param>
     3433      <param name="progress" type="IProgress" dir="return">
     3434        <desc>Progress object to track the operation completion.</desc>
     3435      </param>
     3436    </method>
     3437
     3438    <method name="discardCurrentState">
     3439      <desc>
     3440        This operation is similar to <link to="#discardSnapshot()"/> but
     3441        affects the current machine state. This means that the state stored
     3442        in the current snapshot will become a new current state, and
     3443        all current settings of the machine and changes stored in
     3444        differencing hard disks will be lost.
     3445
     3446        After this operation is successfully completed, new empty
     3447        differencing hard disks are created for all normal hard disks
     3448        of the machine.
     3449
     3450        If the current snapshot of the machine is an online snapshot,
     3451        the machine will go to the <link to="MachineState::Saved">
     3452          saved state</link>, so that the next time it is powered on,
     3453        the execution state will be restored from the current snapshot.
     3454
     3455        <note>The machine must not be running, otherwise the operation
     3456          will fail.</note>
     3457
     3458        <note>If the machine state is <link
     3459                                         to="MachineState::Saved">Saved</link> prior to this operation,
     3460          the saved state file will be implicitly discarded (as if <link
     3461                                                                      to="IConsole::discardSavedState()"/> were called).</note>
     3462
     3463      </desc>
     3464      <param name="progress" type="IProgress" dir="return">
     3465        <desc>Progress object to track the operation completion.</desc>
     3466      </param>
     3467    </method>
     3468
     3469    <method name="discardCurrentSnapshotAndState">
     3470      <desc>
     3471
     3472        This method is equivalent to
     3473        doing <link to="#discardSnapshot">discardSnapshot</link>
     3474        (<link
     3475        to="IMachine::currentSnapshot">currentSnapshot</link>.<link
     3476        to="ISnapshot::id">id()</link>, ...) followed by
     3477        <link to="#discardCurrentState()"/>.
     3478
     3479        As a result, the machine will be fully restored from the
     3480        snapshot preceeding the current snapshot, while both the current
     3481        snapshot and the current machine state will be discarded.
     3482
     3483        If the current snapshot is the first snapshot of the machine (i.e. it
     3484        has the only snapshot), the current machine state will be
     3485        discarded <b>before</b> discarding the snapshot. In other words, the
     3486        machine will be restored from its last snapshot, before discarding
     3487        it. This differs from performing a single
     3488        <link to="#discardSnapshot()"/> call (note that no
     3489        <link to="#discardCurrentState()"/> will be possible after it) to the
     3490        effect that the latter will preserve the current state instead of
     3491        discarding it.
     3492
     3493        Unless explicitly mentioned otherwise, all remarks and
     3494        limitations of the above two methods also apply to this method.
     3495
     3496        <note>
     3497          The machine must not be running, otherwise the operation
     3498          will fail.
     3499        </note>
     3500
     3501        <note>
     3502          If the machine state is <link to="MachineState::Saved">Saved</link>
     3503          prior to this operation, the saved state file will be implicitly
     3504          discarded (as if <link to="IConsole::discardSavedState()"/> were
     3505          called).</note>
     3506
     3507        <note>
     3508          This method is more efficient than calling two above
     3509          methods separately: it requires less IPC calls and provides
     3510          a single progress object.
     3511        </note>
     3512
     3513      </desc>
     3514      <param name="progress" type="IProgress" dir="return">
     3515        <desc>Progress object to track the operation completion.</desc>
     3516      </param>
     3517    </method>
     3518
     3519    <method name="registerCallback">
     3520      <desc>
     3521        Registers a new console callback on this instance. The methods of the
     3522        callback interface will be called by this instance when the appropriate
     3523        event occurs.
     3524      </desc>
     3525      <param name="callback" type="IConsoleCallback" dir="in"/>
     3526    </method>
     3527
     3528    <method name="unregisterCallback">
     3529      <desc>
     3530        Unregisters the console callback previously registered using
     3531        <link to="#registerCallback"/>.
     3532      </desc>
     3533      <param name="callback" type="IConsoleCallback" dir="in"/>
     3534    </method>
     3535
     3536  </interface>
     3537
     3538  <!--
     3539  // IHost
     3540  /////////////////////////////////////////////////////////////////////////
     3541  -->
     3542
     3543  <interface
     3544     name="IHostDVDDrive" extends="$unknown"
     3545     uuid="21f86694-202d-4ce4-8b05-a63ff82dbf4c"
     3546     wsmap="managed"
     3547     >
     3548    <attribute name="name" type="wstring" readonly="yes">
     3549      <desc>
     3550        Returns the platform-specific device identifier.
     3551        On DOS-like platforms, it is a drive name (e.g. R:).
     3552        On Unix-like platforms, it is a device name (e.g. /dev/hdc).
     3553      </desc>
     3554    </attribute>
     3555    <attribute name="description" type="wstring" readonly="yes">
     3556      <desc>
     3557        Returns a human readable description for the drive.  This
     3558        description usually contains the product and vendor name.  A
     3559        @c null string is returned if the description is not available.
     3560      </desc>
     3561    </attribute>
     3562    <attribute name="udi" type="wstring" readonly="yes">
     3563      <desc>
     3564        Returns the unique device identifier for the drive.  This
     3565        attribute is reserved for future use instead of
     3566        <link to="#name"/>. Currently it is not used and may return
     3567        @c null on some platforms.
     3568      </desc>
     3569    </attribute>
     3570
     3571  </interface>
     3572
     3573  <enumerator
     3574     name="IHostDVDDriveEnumerator" type="IHostDVDDrive"
     3575     uuid="1ed7cfaf-c363-40df-aa4e-89c1afb7d96b"
     3576     />
     3577
     3578  <collection
     3579     name="IHostDVDDriveCollection" type="IHostDVDDrive"
     3580     enumerator="IHostDVDDriveEnumerator"
     3581     uuid="1909c533-1a1e-445f-a4e1-a267cffc30ed"
     3582     readonly="yes"
     3583     >
     3584    <method name="findByName">
     3585      <desc>
     3586        Searches this collection for a host drive with the given name.
     3587        <note>
     3588          The method returns an error if the given name does not
     3589          correspond to any host drive in the collection.
     3590        </note>
     3591      </desc>
     3592      <param name="name" type="wstring" dir="in">
     3593        <desc>Name of the host drive to search for</desc>
     3594      </param>
     3595      <param name="drive" type="IHostDVDDrive" dir="return">
     3596        <desc>Found host drive object</desc>
     3597      </param>
     3598    </method>
     3599  </collection>
     3600
     3601  <interface
     3602     name="IHostFloppyDrive" extends="$unknown"
     3603     uuid="b6a4d1a9-4221-43c3-bd52-021a5daa9ed2"
     3604     wsmap="managed"
     3605     >
     3606    <attribute name="name" type="wstring" readonly="yes">
     3607      <desc>
     3608        Returns the platform-specific device identifier.
     3609        On DOS-like platforms, it is a drive name (e.g. A:).
     3610        On Unix-like platforms, it is a device name (e.g. /dev/fd0).
     3611      </desc>
     3612    </attribute>
     3613    <attribute name="description" type="wstring" readonly="yes">
     3614      <desc>
     3615        Returns a human readable description for the drive.  This
     3616        description usually contains the product and vendor name.  A
     3617        @c null string is returned if the description is not available.
     3618      </desc>
     3619    </attribute>
     3620    <attribute name="udi" type="wstring" readonly="yes">
     3621      <desc>
     3622        Returns the unique device identifier for the drive.  This
     3623        attribute is reserved for future use instead of
     3624        <link to="#name"/>. Currently it is not used and may return
     3625        @c null on some platforms.
     3626      </desc>
     3627    </attribute>
     3628  </interface>
     3629
     3630  <enumerator
     3631     name="IHostFloppyDriveEnumerator" type="IHostFloppyDrive"
     3632     uuid="ce04c924-4f54-432a-9dec-11fddc3ea875"
     3633     />
     3634
     3635  <collection
     3636     name="IHostFloppyDriveCollection" type="IHostFloppyDrive"
     3637     enumerator="IHostFloppyDriveEnumerator"
     3638     uuid="fd84bb86-c59a-4037-a557-755ff263a460"
     3639     readonly="yes"
     3640     >
     3641    <method name="findByName">
     3642      <desc>
     3643        Searches this collection for a host drive with the given name.
     3644        <note>
     3645          The method returns an error if the given name does not
     3646          correspond to any host drive in the collection.
     3647        </note>
     3648      </desc>
     3649      <param name="name" type="wstring" dir="in">
     3650        <desc>Name of the host drive to search for</desc>
     3651      </param>
     3652      <param name="drive" type="IHostFloppyDrive" dir="return">
     3653        <desc>Found host drive object</desc>
     3654      </param>
     3655    </method>
     3656  </collection>
    36393657
    36403658<if target="midl">
    3641     <interface
    3642         name="IHostNetworkInterface" extends="$unknown"
    3643         uuid="F4512D7C-B074-4e97-99B8-6D2BD27C3F5A"
    3644         wsmap="managed"
    3645     >
    3646         <attribute name="name" type="wstring" readonly="yes">
    3647             <desc>Returns the host network interface name.</desc>
    3648         </attribute>
    3649 
    3650         <attribute name="id" type="uuid" readonly="yes">
    3651             <desc>Returns the interface UUID.</desc>
    3652         </attribute>
    3653     </interface>
    3654 
    3655     <enumerator
    3656         name="IHostNetworkInterfaceEnumerator" type="IHostNetworkInterface"
    3657         uuid="7B52FEF7-56E8-4aec-92F5-15E6D11EC630"
    3658     />
    3659 
    3660     <collection
    3661         name="IHostNetworkInterfaceCollection" type="IHostNetworkInterface"
    3662         enumerator="IHostNetworkInterfaceEnumerator"
    3663         uuid="BF1D41F2-B97B-4314-A0FB-D4823AF42FB5"
    3664         readonly="yes"
    3665     >
    3666         <method name="findByName">
    3667             <desc>
    3668                 Searches this collection for a host network interface with the given name.
    3669                 <note>
    3670                     The method returns an error if the given name does not
    3671                     correspond to any host network interface in the collection.
    3672                 </note>
    3673             </desc>
    3674             <param name="name" type="wstring" dir="in">
    3675                 <desc>Name of the host network interface to search for.</desc>
    3676             </param>
    3677             <param name="networkInterface" type="IHostNetworkInterface" dir="return">
    3678                 <desc>Found host network interface object.</desc>
    3679             </param>
    3680         </method>
    3681         <method name="findById">
    3682             <desc>
    3683                 Searches this collection for a host network interface with the given GUID.
    3684                 <note>
    3685                     The method returns an error if the given GUID does not
    3686                     correspond to any host network interface in the collection.
    3687                 </note>
    3688             </desc>
    3689             <param name="id" type="uuid" dir="in">
    3690                 <desc>GUID of the host network interface to search for.</desc>
    3691             </param>
    3692             <param name="networkInterface" type="IHostNetworkInterface" dir="return">
    3693                 <desc>Found host network interface object.</desc>
    3694             </param>
    3695         </method>
    3696     </collection>
     3659  <interface
     3660     name="IHostNetworkInterface" extends="$unknown"
     3661     uuid="F4512D7C-B074-4e97-99B8-6D2BD27C3F5A"
     3662     wsmap="managed"
     3663     >
     3664    <attribute name="name" type="wstring" readonly="yes">
     3665      <desc>Returns the host network interface name.</desc>
     3666    </attribute>
     3667
     3668    <attribute name="id" type="uuid" readonly="yes">
     3669      <desc>Returns the interface UUID.</desc>
     3670    </attribute>
     3671  </interface>
     3672
     3673  <enumerator
     3674     name="IHostNetworkInterfaceEnumerator" type="IHostNetworkInterface"
     3675     uuid="7B52FEF7-56E8-4aec-92F5-15E6D11EC630"
     3676     />
     3677
     3678  <collection
     3679     name="IHostNetworkInterfaceCollection" type="IHostNetworkInterface"
     3680     enumerator="IHostNetworkInterfaceEnumerator"
     3681     uuid="BF1D41F2-B97B-4314-A0FB-D4823AF42FB5"
     3682     readonly="yes"
     3683     >
     3684    <method name="findByName">
     3685      <desc>
     3686        Searches this collection for a host network interface with the given name.
     3687        <note>
     3688          The method returns an error if the given name does not
     3689          correspond to any host network interface in the collection.
     3690        </note>
     3691      </desc>
     3692      <param name="name" type="wstring" dir="in">
     3693        <desc>Name of the host network interface to search for.</desc>
     3694      </param>
     3695      <param name="networkInterface" type="IHostNetworkInterface" dir="return">
     3696        <desc>Found host network interface object.</desc>
     3697      </param>
     3698    </method>
     3699    <method name="findById">
     3700      <desc>
     3701        Searches this collection for a host network interface with the given GUID.
     3702        <note>
     3703          The method returns an error if the given GUID does not
     3704          correspond to any host network interface in the collection.
     3705        </note>
     3706      </desc>
     3707      <param name="id" type="uuid" dir="in">
     3708        <desc>GUID of the host network interface to search for.</desc>
     3709      </param>
     3710      <param name="networkInterface" type="IHostNetworkInterface" dir="return">
     3711        <desc>Found host network interface object.</desc>
     3712      </param>
     3713    </method>
     3714  </collection>
    36973715</if>
    36983716
    3699     <interface
    3700         name="IHost" extends="$unknown"
    3701         uuid="81729c26-1aec-46f5-b7c0-cc7364738fdb"
    3702         wsmap="managed"
    3703     >
    3704         <attribute name="DVDDrives" type="IHostDVDDriveCollection" readonly="yes">
    3705             <desc>List of DVD drives available on the host.</desc>
    3706         </attribute>
    3707 
    3708         <attribute name="floppyDrives" type="IHostFloppyDriveCollection" readonly="yes">
    3709             <desc>List of floppy drives available on the host.</desc>
    3710         </attribute>
    3711 
    3712         <attribute name="USBDevices" type="IHostUSBDeviceCollection" readonly="yes">
    3713             <desc>
    3714                 List of USB devices currently attached to the host.
    3715                 Once a new device is physically attached to the host computer,
    3716                 it appears in this list and remains there until detached.
    3717             </desc>
    3718         </attribute>
    3719 
    3720         <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilterCollection" readonly="yes">
    3721             <desc>
    3722                 List of USB device filters in action.
    3723                 When a new device is physically attached to the host computer,
    3724                 filters from this list are applied to it (in order they are stored
    3725                 in the list). The first matched filter will determine the
    3726                 <link to="IHostUSBDeviceFilter::action">action</link>
    3727                 performed on the device.
    3728 
    3729                 Unless the device is ignored by these filters, filters of all
    3730                 currently running virtual machines
    3731                 (<link to="IUSBController::DeviceFilters"/>) are applied to it.
    3732 
    3733                 <see>IHostUSBDeviceFilter, USBDeviceState</see>
    3734             </desc>
    3735         </attribute>
     3717  <interface
     3718     name="IHost" extends="$unknown"
     3719     uuid="81729c26-1aec-46f5-b7c0-cc7364738fdb"
     3720     wsmap="managed"
     3721     >
     3722    <attribute name="DVDDrives" type="IHostDVDDriveCollection" readonly="yes">
     3723      <desc>List of DVD drives available on the host.</desc>
     3724    </attribute>
     3725
     3726    <attribute name="floppyDrives" type="IHostFloppyDriveCollection" readonly="yes">
     3727      <desc>List of floppy drives available on the host.</desc>
     3728    </attribute>
     3729
     3730    <attribute name="USBDevices" type="IHostUSBDeviceCollection" readonly="yes">
     3731      <desc>
     3732        List of USB devices currently attached to the host.
     3733        Once a new device is physically attached to the host computer,
     3734        it appears in this list and remains there until detached.
     3735      </desc>
     3736    </attribute>
     3737
     3738    <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilterCollection" readonly="yes">
     3739      <desc>
     3740        List of USB device filters in action.
     3741        When a new device is physically attached to the host computer,
     3742        filters from this list are applied to it (in order they are stored
     3743        in the list). The first matched filter will determine the
     3744        <link to="IHostUSBDeviceFilter::action">action</link>
     3745        performed on the device.
     3746
     3747        Unless the device is ignored by these filters, filters of all
     3748        currently running virtual machines
     3749        (<link to="IUSBController::DeviceFilters"/>) are applied to it.
     3750
     3751        <see>IHostUSBDeviceFilter, USBDeviceState</see>
     3752      </desc>
     3753    </attribute>
    37363754
    37373755<if target="midl">
    3738         <attribute name="networkInterfaces" type="IHostNetworkInterfaceCollection" readonly="yes">
    3739             <desc>List of host network interfaces currently defined on the host.</desc>
    3740         </attribute>
     3756    <attribute name="networkInterfaces" type="IHostNetworkInterfaceCollection" readonly="yes">
     3757      <desc>List of host network interfaces currently defined on the host.</desc>
     3758    </attribute>
    37413759</if>
    37423760
    3743         <attribute name="processorCount" type="unsigned long" readonly="yes">
    3744             <desc>Number of (logical) CPUs installed in the host system.</desc>
    3745         </attribute>
    3746 
    3747         <attribute name="processorSpeed" type="unsigned long" readonly="yes">
    3748             <desc>(Approximate) speed of the host CPU in Megahertz.</desc>
    3749         </attribute>
    3750 
    3751         <attribute name="processorDescription" type="wstring" readonly="yes">
    3752             <desc>Description string of the host CPU.</desc>
    3753         </attribute>
    3754 
    3755         <attribute name="memorySize" type="unsigned long" readonly="yes">
    3756             <desc>Amount of system memory in megabytes installed in the host system.</desc>
    3757         </attribute>
    3758 
    3759         <attribute name="memoryAvailable" type="unsigned long" readonly="yes">
    3760             <desc>Available system memory in the host system.</desc>
    3761         </attribute>
    3762 
    3763         <attribute name="operatingSystem" type="wstring" readonly="yes">
    3764             <desc>Name of the host system's operating system.</desc>
    3765         </attribute>
    3766 
    3767         <attribute name="OSVersion" type="wstring" readonly="yes">
    3768             <desc>Host operating system's version string.</desc>
    3769         </attribute>
    3770 
    3771         <attribute name="UTCTime" type="long long" readonly="yes">
    3772             <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
    3773         </attribute>
     3761    <attribute name="processorCount" type="unsigned long" readonly="yes">
     3762      <desc>Number of (logical) CPUs installed in the host system.</desc>
     3763    </attribute>
     3764
     3765    <attribute name="processorSpeed" type="unsigned long" readonly="yes">
     3766      <desc>(Approximate) speed of the host CPU in Megahertz.</desc>
     3767    </attribute>
     3768
     3769    <attribute name="processorDescription" type="wstring" readonly="yes">
     3770      <desc>Description string of the host CPU.</desc>
     3771    </attribute>
     3772
     3773    <attribute name="memorySize" type="unsigned long" readonly="yes">
     3774      <desc>Amount of system memory in megabytes installed in the host system.</desc>
     3775    </attribute>
     3776
     3777    <attribute name="memoryAvailable" type="unsigned long" readonly="yes">
     3778      <desc>Available system memory in the host system.</desc>
     3779    </attribute>
     3780
     3781    <attribute name="operatingSystem" type="wstring" readonly="yes">
     3782      <desc>Name of the host system's operating system.</desc>
     3783    </attribute>
     3784
     3785    <attribute name="OSVersion" type="wstring" readonly="yes">
     3786      <desc>Host operating system's version string.</desc>
     3787    </attribute>
     3788
     3789    <attribute name="UTCTime" type="long long" readonly="yes">
     3790      <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
     3791    </attribute>
    37743792
    37753793<if target="midl">
    3776         <method name="createHostNetworkInterface">
    3777             <desc>
    3778                 Creates a new adapter for Host Interface Networking.
    3779             </desc>
    3780             <param name="name" type="wstring" dir="in">
    3781                 <desc>
    3782                     Adapter name.
    3783                 </desc>
    3784             </param>
    3785             <param name="hostInterface" type="IHostNetworkInterface" dir="out">
    3786                 <desc>
    3787                     Created host interface object.
    3788                 </desc>
    3789             </param>
    3790             <param name="progress" type="IProgress" dir="return">
    3791                 <desc>
    3792                     Progress object to track the operation completion.
    3793                 </desc>
    3794             </param>
    3795         </method>
    3796         <method name="removeHostNetworkInterface">
    3797             <desc>
    3798                 Removes the given host network interface.
    3799             </desc>
    3800             <param name="id" type="uuid" dir="in">
    3801                 <desc>
    3802                     Adapter GUID.
    3803                 </desc>
    3804             </param>
    3805             <param name="hostInterface" type="IHostNetworkInterface" dir="out">
    3806                 <desc>
    3807                     Removed host interface object.
    3808                 </desc>
    3809             </param>
    3810             <param name="progress" type="IProgress" dir="return">
    3811                 <desc>
    3812                     Progress object to track the operation completion.
    3813                 </desc>
    3814             </param>
    3815         </method>
     3794    <method name="createHostNetworkInterface">
     3795      <desc>
     3796        Creates a new adapter for Host Interface Networking.
     3797      </desc>
     3798      <param name="name" type="wstring" dir="in">
     3799        <desc>
     3800          Adapter name.
     3801        </desc>
     3802      </param>
     3803      <param name="hostInterface" type="IHostNetworkInterface" dir="out">
     3804        <desc>
     3805          Created host interface object.
     3806        </desc>
     3807      </param>
     3808      <param name="progress" type="IProgress" dir="return">
     3809        <desc>
     3810          Progress object to track the operation completion.
     3811        </desc>
     3812      </param>
     3813    </method>
     3814    <method name="removeHostNetworkInterface">
     3815      <desc>
     3816        Removes the given host network interface.
     3817      </desc>
     3818      <param name="id" type="uuid" dir="in">
     3819        <desc>
     3820          Adapter GUID.
     3821        </desc>
     3822      </param>
     3823      <param name="hostInterface" type="IHostNetworkInterface" dir="out">
     3824        <desc>
     3825          Removed host interface object.
     3826        </desc>
     3827      </param>
     3828      <param name="progress" type="IProgress" dir="return">
     3829        <desc>
     3830          Progress object to track the operation completion.
     3831        </desc>
     3832      </param>
     3833    </method>
    38163834</if>
    38173835
    3818         <method name="createUSBDeviceFilter">
    3819             <desc>
    3820                 Creates a new USB device filter. All attributes except
    3821                 the filter name are set to <tt>null</tt> (any match),
    3822                 <i>active</i> is <tt>false</tt> (the filter is not active).
    3823 
    3824                 The created filter can be added to the list of filters using
    3825                 <link to="#insertUSBDeviceFilter()"/>.
    3826 
    3827                 <see>#USBDeviceFilters</see>
    3828             </desc>
    3829             <param name="name" type="wstring" dir="in">
    3830                 <desc>
    3831                     Filter name. See <link to="IHostUSBDeviceFilter::name"/>
    3832                     for more info.
    3833                 </desc>
    3834             </param>
    3835             <param name="filter" type="IHostUSBDeviceFilter" dir="return">
    3836                 <desc>Created filter object.</desc>
    3837             </param>
    3838         </method>
    3839 
    3840         <method name="insertUSBDeviceFilter">
    3841             <desc>
    3842                 Inserts the given USB device to the specified position
    3843                 in the list of filters.
    3844 
    3845                 Positions are numbered starting from <tt>0</tt>. If the specified
    3846                 position is equal to or greater than the number of elements in
    3847                 the list, the filter is added to the end of the collection.
    3848 
    3849                 <note>
    3850                     Duplicates are not allowed, so an attempt to insert a
    3851                     filter that is already in the list, will return an
    3852                     error.
    3853                 </note>
    3854 
    3855                 <see>#USBDeviceFilters</see>
    3856             </desc>
    3857             <param name="position" type="unsigned long" dir="in">
    3858                 <desc>Position to insert the filter to.</desc>
    3859             </param>
    3860             <param name="filter" type="IHostUSBDeviceFilter" dir="in">
    3861                 <desc>USB device filter to insert.</desc>
    3862             </param>
    3863         </method>
    3864 
    3865         <method name="removeUSBDeviceFilter">
    3866             <desc>
    3867                 Removes a USB device filter from the specified position in the
    3868                 list of filters.
    3869 
    3870                 Positions are numbered starting from <tt>0</tt>. Specifying a
    3871                 position equal to or greater than the number of elements in
    3872                 the list will produce an error.
    3873 
    3874                 <see>#USBDeviceFilters</see>
    3875             </desc>
    3876             <param name="position" type="unsigned long" dir="in">
    3877                 <desc>Position to remove the filter from.</desc>
    3878             </param>
    3879             <param name="filter" type="IHostUSBDeviceFilter" dir="return">
    3880                 <desc>Removed USB device filter.</desc>
    3881             </param>
    3882         </method>
    3883 
    3884     </interface>
    3885 
    3886     <!--
    3887     // ISystemProperties
    3888     /////////////////////////////////////////////////////////////////////////
    3889     -->
    3890 
    3891     <interface
    3892         name="ISystemProperties"
    3893         extends="$unknown"
    3894         uuid="6dc28c62-7924-43de-8336-fa754aa531d7"
    3895         wsmap="struct"
    3896     >
     3836    <method name="createUSBDeviceFilter">
     3837      <desc>
     3838        Creates a new USB device filter. All attributes except
     3839        the filter name are set to <tt>null</tt> (any match),
     3840        <i>active</i> is <tt>false</tt> (the filter is not active).
     3841
     3842        The created filter can be added to the list of filters using
     3843        <link to="#insertUSBDeviceFilter()"/>.
     3844
     3845        <see>#USBDeviceFilters</see>
     3846      </desc>
     3847      <param name="name" type="wstring" dir="in">
    38973848        <desc>
    3898             The ISystemProperties interface represents global properties
    3899             of the given VirtualBox installation.
    3900 
    3901             These properties define limits and default values for various
    3902             attributes and parameters.
    3903 
    3904             Most of the properties are read-only, but some can be changed by
    3905             a user.
     3849          Filter name. See <link to="IHostUSBDeviceFilter::name"/>
     3850          for more info.
    39063851        </desc>
    3907 
    3908         <attribute name="minGuestRAM" type="unsigned long" readonly="yes">
    3909             <desc>Minium guest system memory in Megabytes.</desc>
    3910         </attribute>
    3911 
    3912         <attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
    3913             <desc>Maximum guest system memory in Megabytes.</desc>
    3914         </attribute>
    3915 
    3916         <attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
    3917             <desc>Minimum guest video memory in Megabytes.</desc>
    3918         </attribute>
    3919 
    3920         <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
    3921             <desc>Maximum guest video memory in Megabytes.</desc>
    3922         </attribute>
    3923 
    3924         <attribute name="maxVDISize" type="unsigned long long" readonly="yes">
    3925             <desc>Maximum size of a virtual disk image in Megabytes.</desc>
    3926         </attribute>
    3927 
    3928         <attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
    3929             <desc>
    3930                 Number of network adapters associated with every
    3931                 <link to="IMachine"/> instance.
    3932             </desc>
    3933         </attribute>
    3934 
    3935         <attribute name="maxBootPosition" type="unsigned long" readonly="yes">
    3936             <desc>
    3937                 Maximum device position in the boot order. This value corresponds
    3938                 to the total number of devices a machine can boot from, to make it
    3939                 possible to include all possible devices to the boot list.
    3940                 <see><link to="IMachine::setBootOrder()"/></see>
    3941             </desc>
    3942         </attribute>
    3943 
    3944         <attribute name="defaultVDIFolder" type="wstring">
    3945             <desc>
    3946                 Full path to the default directory used to create new or open
    3947                 existing virtual disk images when an image file name contains no
    3948                 path.
    3949 
    3950                 The initial value of this property is
    3951                 <tt>&lt;</tt><link to="IVirtualBox::homeFolder">
    3952                 VirtualBox_home</link><tt>&gt;/VDI</tt>.
    3953 
    3954                 <note>
    3955                     Setting this property to <tt>null</tt> will restore the
    3956                     initial value.
    3957                 </note>
    3958                 <note>
    3959                     When settings this property, the specified path can be
    3960                     absolute (full path) or relative
    3961                     to the <link to="IVirtualBox::homeFolder">
    3962                     VirtualBox home directory</link>.
    3963                     When reading this property, a full path is
    3964                     always returned.
    3965                 </note>
    3966                 <note>
    3967                     The specified path may not exist, it will be created
    3968                     when necessary.
    3969                 </note>
    3970 
    3971                 <see>
    3972                     <link to="IVirtualBox::createHardDisk()"/>,
    3973                     <link to="IVirtualBox::openVirtualDiskImage()"/>
    3974                 </see>
    3975             </desc>
    3976         </attribute>
    3977 
    3978         <attribute name="defaultMachineFolder" type="wstring">
    3979             <desc>
    3980                 Full path to the default directory used to create new or open
    3981                 existing machines when a settings file name contains no
    3982                 path.
    3983 
    3984                 The initial value of this property is
    3985                 <tt>&lt;</tt><link to="IVirtualBox::homeFolder">
    3986                 VirtualBox_home</link><tt>&gt;/Machines</tt>.
    3987 
    3988                 <note>
    3989                     Setting this property to <tt>null</tt> will restore the
    3990                     initial value.
    3991                 </note>
    3992                 <note>
    3993                     When settings this property, the specified path can be
    3994                     absolute (full path) or relative
    3995                     to the <link to="IVirtualBox::homeFolder">
    3996                     VirtualBox home directory</link>.
    3997                     When reading this property, a full path is
    3998                     always returned.
    3999                 </note>
    4000                 <note>
    4001                     The specified path may not exist, it will be created
    4002                     when necessary.
    4003                 </note>
    4004 
    4005                 <see>
    4006                     <link to="IVirtualBox::createMachine()"/>,
    4007                     <link to="IVirtualBox::openMachine()"/>
    4008                 </see>
    4009             </desc>
    4010         </attribute>
    4011 
    4012         <attribute name="remoteDisplayAuthLibrary" type="wstring">
    4013             <desc>
    4014                 Path to the library that provides authentication
    4015                 for VRDP clients. The library is used if authentication
    4016                 type is set to "external" in the VM RemoteDisplay
    4017                 configuration.
    4018 
    4019                 The initial value of this property is <tt>VRDPAuth</tt>.
    4020                 That is library called VRDPAuth in one of default library
    4021                 directories. A full path can be used as well.
    4022 
    4023                 <note>
    4024                     The library name does not include the file extension.
    4025                 </note>
    4026                 <note>
    4027                     Setting this property to <tt>null</tt> will restore the
    4028                     initial value.
    4029                 </note>
    4030             </desc>
    4031         </attribute>
    4032 
    4033         <attribute name="HWVirtExEnabled" type="boolean">
    4034             <desc>
    4035                 This specifies the default value for hardware virtualization
    4036                 extensions. If enabled, virtual machines will make use of
    4037                 hardware virtualization extensions such as Intel VT-x and
    4038                 AMD SVM by default. This value can be overridden by each VM
    4039                 using their <link to="IMachine::HWVirtExEnabled"/> property.
    4040             </desc>
    4041         </attribute>
    4042 
    4043     </interface>
    4044 
    4045     <!--
    4046     // IGuest
    4047     /////////////////////////////////////////////////////////////////////////
    4048     -->
    4049 
    4050     <interface
    4051         name="IGuestOSType" extends="$unknown"
    4052         uuid="da94f478-1f37-4726-b750-2235950dc2fe"
    4053         wsmap="struct"
    4054     >
    4055         <attribute name="id" type="wstring" readonly="yes">
    4056             <desc>Guest OS identifier string.</desc>
    4057         </attribute>
    4058 
    4059         <attribute name="description" type="wstring" readonly="yes">
    4060             <desc>Human readable description of the guest OS.</desc>
    4061         </attribute>
    4062 
    4063         <attribute name="recommendedRAM" type="unsigned long" readonly="yes">
    4064             <desc>Recommended RAM size in Megabytes.</desc>
    4065         </attribute>
    4066 
    4067         <attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
    4068             <desc>Recommended video RAM size in Megabytes.</desc>
    4069         </attribute>
    4070 
    4071         <attribute name="recommendedHDD" type="unsigned long" readonly="yes">
    4072             <desc>Recommended hard disk size in Megabytes.</desc>
    4073         </attribute>
    4074     </interface>
    4075 
    4076 
    4077     <enumerator
    4078         name="IGuestOSTypeEnumerator" type="IGuestOSType"
    4079         uuid="a3335e02-4669-4e3c-80c7-c4dc7056a07c"
    4080     />
    4081 
    4082     <collection
    4083         name="IGuestOSTypeCollection" type="IGuestOSType" enumerator="IGuestOSTypeEnumerator"
    4084         uuid="a5e36749-a610-498b-9f29-2e36c1042d65"
    4085         readonly="yes"
    4086     />
    4087 
    4088     <interface
    4089         name="IGuest" extends="$unknown"
    4090         uuid="4b71ac5f-db5a-4b4f-af6e-a947d4b83dda"
    4091         wsmap="suppress"
    4092     >
     3852      </param>
     3853      <param name="filter" type="IHostUSBDeviceFilter" dir="return">
     3854        <desc>Created filter object.</desc>
     3855      </param>
     3856    </method>
     3857
     3858    <method name="insertUSBDeviceFilter">
     3859      <desc>
     3860        Inserts the given USB device to the specified position
     3861        in the list of filters.
     3862
     3863        Positions are numbered starting from <tt>0</tt>. If the specified
     3864        position is equal to or greater than the number of elements in
     3865        the list, the filter is added to the end of the collection.
     3866
     3867        <note>
     3868          Duplicates are not allowed, so an attempt to insert a
     3869          filter that is already in the list, will return an
     3870          error.
     3871        </note>
     3872
     3873        <see>#USBDeviceFilters</see>
     3874      </desc>
     3875      <param name="position" type="unsigned long" dir="in">
     3876        <desc>Position to insert the filter to.</desc>
     3877      </param>
     3878      <param name="filter" type="IHostUSBDeviceFilter" dir="in">
     3879        <desc>USB device filter to insert.</desc>
     3880      </param>
     3881    </method>
     3882
     3883    <method name="removeUSBDeviceFilter">
     3884      <desc>
     3885        Removes a USB device filter from the specified position in the
     3886        list of filters.
     3887
     3888        Positions are numbered starting from <tt>0</tt>. Specifying a
     3889        position equal to or greater than the number of elements in
     3890        the list will produce an error.
     3891
     3892        <see>#USBDeviceFilters</see>
     3893      </desc>
     3894      <param name="position" type="unsigned long" dir="in">
     3895        <desc>Position to remove the filter from.</desc>
     3896      </param>
     3897      <param name="filter" type="IHostUSBDeviceFilter" dir="return">
     3898        <desc>Removed USB device filter.</desc>
     3899      </param>
     3900    </method>
     3901
     3902  </interface>
     3903
     3904  <!--
     3905  // ISystemProperties
     3906  /////////////////////////////////////////////////////////////////////////
     3907  -->
     3908
     3909  <interface
     3910     name="ISystemProperties"
     3911     extends="$unknown"
     3912     uuid="6dc28c62-7924-43de-8336-fa754aa531d7"
     3913     wsmap="struct"
     3914     >
     3915    <desc>
     3916      The ISystemProperties interface represents global properties
     3917      of the given VirtualBox installation.
     3918
     3919      These properties define limits and default values for various
     3920      attributes and parameters.
     3921
     3922      Most of the properties are read-only, but some can be changed by
     3923      a user.
     3924    </desc>
     3925
     3926    <attribute name="minGuestRAM" type="unsigned long" readonly="yes">
     3927      <desc>Minium guest system memory in Megabytes.</desc>
     3928    </attribute>
     3929
     3930    <attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
     3931      <desc>Maximum guest system memory in Megabytes.</desc>
     3932    </attribute>
     3933
     3934    <attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
     3935      <desc>Minimum guest video memory in Megabytes.</desc>
     3936    </attribute>
     3937
     3938    <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
     3939      <desc>Maximum guest video memory in Megabytes.</desc>
     3940    </attribute>
     3941
     3942    <attribute name="maxVDISize" type="unsigned long long" readonly="yes">
     3943      <desc>Maximum size of a virtual disk image in Megabytes.</desc>
     3944    </attribute>
     3945
     3946    <attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
     3947      <desc>
     3948        Number of network adapters associated with every
     3949        <link to="IMachine"/> instance.
     3950      </desc>
     3951    </attribute>
     3952
     3953    <attribute name="maxBootPosition" type="unsigned long" readonly="yes">
     3954      <desc>
     3955        Maximum device position in the boot order. This value corresponds
     3956        to the total number of devices a machine can boot from, to make it
     3957        possible to include all possible devices to the boot list.
     3958        <see><link to="IMachine::setBootOrder()"/></see>
     3959      </desc>
     3960    </attribute>
     3961
     3962    <attribute name="defaultVDIFolder" type="wstring">
     3963      <desc>
     3964        Full path to the default directory used to create new or open
     3965        existing virtual disk images when an image file name contains no
     3966        path.
     3967
     3968        The initial value of this property is
     3969        <tt>&lt;</tt><link to="IVirtualBox::homeFolder">
     3970          VirtualBox_home</link><tt>&gt;/VDI</tt>.
     3971
     3972        <note>
     3973          Setting this property to <tt>null</tt> will restore the
     3974          initial value.
     3975        </note>
     3976        <note>
     3977          When settings this property, the specified path can be
     3978          absolute (full path) or relative
     3979          to the <link to="IVirtualBox::homeFolder">
     3980            VirtualBox home directory</link>.
     3981          When reading this property, a full path is
     3982          always returned.
     3983        </note>
     3984        <note>
     3985          The specified path may not exist, it will be created
     3986          when necessary.
     3987        </note>
     3988
     3989        <see>
     3990          <link to="IVirtualBox::createHardDisk()"/>,
     3991          <link to="IVirtualBox::openVirtualDiskImage()"/>
     3992        </see>
     3993      </desc>
     3994    </attribute>
     3995
     3996    <attribute name="defaultMachineFolder" type="wstring">
     3997      <desc>
     3998        Full path to the default directory used to create new or open
     3999        existing machines when a settings file name contains no
     4000        path.
     4001
     4002        The initial value of this property is
     4003        <tt>&lt;</tt><link to="IVirtualBox::homeFolder">
     4004          VirtualBox_home</link><tt>&gt;/Machines</tt>.
     4005
     4006        <note>
     4007          Setting this property to <tt>null</tt> will restore the
     4008          initial value.
     4009        </note>
     4010        <note>
     4011          When settings this property, the specified path can be
     4012          absolute (full path) or relative
     4013          to the <link to="IVirtualBox::homeFolder">
     4014            VirtualBox home directory</link>.
     4015          When reading this property, a full path is
     4016          always returned.
     4017        </note>
     4018        <note>
     4019          The specified path may not exist, it will be created
     4020          when necessary.
     4021        </note>
     4022
     4023        <see>
     4024          <link to="IVirtualBox::createMachine()"/>,
     4025          <link to="IVirtualBox::openMachine()"/>
     4026        </see>
     4027      </desc>
     4028    </attribute>
     4029
     4030    <attribute name="remoteDisplayAuthLibrary" type="wstring">
     4031      <desc>
     4032        Path to the library that provides authentication
     4033        for VRDP clients. The library is used if authentication
     4034        type is set to "external" in the VM RemoteDisplay
     4035        configuration.
     4036
     4037        The initial value of this property is <tt>VRDPAuth</tt>.
     4038        That is library called VRDPAuth in one of default library
     4039        directories. A full path can be used as well.
     4040
     4041        <note>
     4042          The library name does not include the file extension.
     4043        </note>
     4044        <note>
     4045          Setting this property to <tt>null</tt> will restore the
     4046          initial value.
     4047        </note>
     4048      </desc>
     4049    </attribute>
     4050
     4051    <attribute name="HWVirtExEnabled" type="boolean">
     4052      <desc>
     4053        This specifies the default value for hardware virtualization
     4054        extensions. If enabled, virtual machines will make use of
     4055        hardware virtualization extensions such as Intel VT-x and
     4056        AMD SVM by default. This value can be overridden by each VM
     4057        using their <link to="IMachine::HWVirtExEnabled"/> property.
     4058      </desc>
     4059    </attribute>
     4060
     4061  </interface>
     4062
     4063  <!--
     4064  // IGuest
     4065  /////////////////////////////////////////////////////////////////////////
     4066  -->
     4067
     4068  <interface
     4069     name="IGuestOSType" extends="$unknown"
     4070     uuid="da94f478-1f37-4726-b750-2235950dc2fe"
     4071     wsmap="struct"
     4072     >
     4073    <attribute name="id" type="wstring" readonly="yes">
     4074      <desc>Guest OS identifier string.</desc>
     4075    </attribute>
     4076
     4077    <attribute name="description" type="wstring" readonly="yes">
     4078      <desc>Human readable description of the guest OS.</desc>
     4079    </attribute>
     4080
     4081    <attribute name="recommendedRAM" type="unsigned long" readonly="yes">
     4082      <desc>Recommended RAM size in Megabytes.</desc>
     4083    </attribute>
     4084
     4085    <attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
     4086      <desc>Recommended video RAM size in Megabytes.</desc>
     4087    </attribute>
     4088
     4089    <attribute name="recommendedHDD" type="unsigned long" readonly="yes">
     4090      <desc>Recommended hard disk size in Megabytes.</desc>
     4091    </attribute>
     4092  </interface>
     4093
     4094
     4095  <enumerator
     4096     name="IGuestOSTypeEnumerator" type="IGuestOSType"
     4097     uuid="a3335e02-4669-4e3c-80c7-c4dc7056a07c"
     4098     />
     4099
     4100  <collection
     4101     name="IGuestOSTypeCollection" type="IGuestOSType" enumerator="IGuestOSTypeEnumerator"
     4102     uuid="a5e36749-a610-498b-9f29-2e36c1042d65"
     4103     readonly="yes"
     4104     />
     4105
     4106  <interface
     4107     name="IGuest" extends="$unknown"
     4108     uuid="4b71ac5f-db5a-4b4f-af6e-a947d4b83dda"
     4109     wsmap="suppress"
     4110     >
     4111    <desc>
     4112      The IGuest interface represents a guest (virtual machine's) operating
     4113      system. It provides information about the Guest Additions and other
     4114      guest OS properties.
     4115
     4116      <see>IConsole::guest</see>
     4117    </desc>
     4118
     4119    <attribute name="OSTypeId" type="wstring" readonly="yes">
     4120      <desc>
     4121        Identifier of the Guest OS type as reported by the Guest
     4122        Additions.
     4123        You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
     4124        an IGuestOSType object representing details about the given
     4125        Guest OS type.
     4126        <note>
     4127          If Guest Additions are not installed, this value will be
     4128          the same as <link to="IMachine::OSTypeId"/>.
     4129        </note>
     4130      </desc>
     4131    </attribute>
     4132
     4133    <attribute name="additionsActive" type="boolean" readonly="yes">
     4134      <desc>
     4135        Flag whether the Guest Additions are installed and active
     4136        in which case their version will be returned by the
     4137        <link to="#additionsVersion"/> property.
     4138      </desc>
     4139    </attribute>
     4140
     4141    <attribute name="additionsVersion" type="wstring" readonly="yes">
     4142      <desc>
     4143        Version of the Guest Additions (3 decimal numbers separated
     4144        by dots) or empty when the Additions are not installed. The
     4145        Additions may also report a version but yet not be active as
     4146        the version might be refused by VirtualBox (incompatible) or
     4147        other failures occured.
     4148      </desc>
     4149    </attribute>
     4150
     4151    <method name="setCredentials">
     4152      <desc>
     4153        Store login credentials that can be queried by guest operating
     4154        systems with Additions installed. The credentials are transient
     4155        to the session and the guest may also choose to erase them. Note
     4156        that the caller cannot determine whether the guest operating system
     4157        has queried or made use of the credentials.
     4158      </desc>
     4159      <param name="userName" type="wstring" dir="in">
     4160        <desc>User name string, can be empty</desc>
     4161      </param>
     4162      <param name="password" type="wstring" dir="in">
     4163        <desc>Password string, can be empty</desc>
     4164      </param>
     4165      <param name="domain" type="wstring" dir="in">
     4166        <desc>Domain name (guest logon scheme specific), can be emtpy</desc>
     4167      </param>
     4168      <param name="allowInteractiveLogon" type="boolean" dir="in">
    40934169        <desc>
    4094             The IGuest interface represents a guest (virtual machine's) operating
    4095             system. It provides information about the Guest Additions and other
    4096             guest OS properties.
    4097 
    4098             <see>IConsole::guest</see>
     4170          Flag whether the guest should alternatively allow the user to
     4171          interactively specify different credentials. This flag might
     4172          not be supported by all versions of the Additions.
    40994173        </desc>
    4100 
    4101         <attribute name="OSTypeId" type="wstring" readonly="yes">
    4102             <desc>
    4103                 Identifier of the Guest OS type as reported by the Guest
    4104                 Additions.
    4105                 You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
    4106                 an IGuestOSType object representing details about the given
    4107                 Guest OS type.
    4108                 <note>
    4109                     If Guest Additions are not installed, this value will be
    4110                     the same as <link to="IMachine::OSTypeId"/>.
    4111                 </note>
    4112             </desc>
    4113         </attribute>
    4114 
    4115         <attribute name="additionsActive" type="boolean" readonly="yes">
    4116             <desc>
    4117                 Flag whether the Guest Additions are installed and active
    4118                 in which case their version will be returned by the
    4119                 <link to="#additionsVersion"/> property.
    4120             </desc>
    4121         </attribute>
    4122 
    4123         <attribute name="additionsVersion" type="wstring" readonly="yes">
    4124             <desc>
    4125                 Version of the Guest Additions (3 decimal numbers separated
    4126                 by dots) or empty when the Additions are not installed. The
    4127                 Additions may also report a version but yet not be active as
    4128                 the version might be refused by VirtualBox (incompatible) or
    4129                 other failures occured.
    4130             </desc>
    4131         </attribute>
    4132 
    4133         <method name="setCredentials">
    4134             <desc>
    4135                 Store login credentials that can be queried by guest operating
    4136                 systems with Additions installed. The credentials are transient
    4137                 to the session and the guest may also choose to erase them. Note
    4138                 that the caller cannot determine whether the guest operating system
    4139                 has queried or made use of the credentials.
    4140             </desc>
    4141             <param name="userName" type="wstring" dir="in">
    4142                 <desc>User name string, can be empty</desc>
    4143             </param>
    4144             <param name="password" type="wstring" dir="in">
    4145                 <desc>Password string, can be empty</desc>
    4146             </param>
    4147             <param name="domain" type="wstring" dir="in">
    4148                 <desc>Domain name (guest logon scheme specific), can be emtpy</desc>
    4149             </param>
    4150             <param name="allowInteractiveLogon" type="boolean" dir="in">
    4151                 <desc>
    4152                     Flag whether the guest should alternatively allow the user to
    4153                     interactively specify different credentials. This flag might
    4154                     not be supported by all versions of the Additions.
    4155                 </desc>
    4156             </param>
    4157         </method>
    4158 
    4159     </interface>
    4160 
    4161 
    4162     <!--
    4163     // IProgress
    4164     /////////////////////////////////////////////////////////////////////////
    4165     -->
    4166 
    4167     <enumerator
    4168         name="IProgressEnumerator" type="IProgress"
    4169         uuid="e0380522-4ef1-48f4-856c-e455177ccb2d"
    4170     />
    4171 
    4172     <collection
    4173         name="IProgressCollection" type="IProgress" enumerator="IProgressEnumerator"
    4174         uuid="78B76A7C-F0F2-467c-9F0E-F089A54EE957"
    4175         readonly="yes"
    4176     />
    4177 
    4178     <interface
    4179         name="IProgress" extends="$unknown"
    4180         uuid="10CC03A1-717E-429b-992D-C67B56175A51"
    4181         wsmap="managed"
    4182     >
     4174      </param>
     4175    </method>
     4176
     4177  </interface>
     4178
     4179
     4180  <!--
     4181  // IProgress
     4182  /////////////////////////////////////////////////////////////////////////
     4183  -->
     4184
     4185  <enumerator
     4186     name="IProgressEnumerator" type="IProgress"
     4187     uuid="e0380522-4ef1-48f4-856c-e455177ccb2d"
     4188     />
     4189
     4190  <collection
     4191     name="IProgressCollection" type="IProgress" enumerator="IProgressEnumerator"
     4192     uuid="78B76A7C-F0F2-467c-9F0E-F089A54EE957"
     4193     readonly="yes"
     4194     />
     4195
     4196  <interface
     4197     name="IProgress" extends="$unknown"
     4198     uuid="10CC03A1-717E-429b-992D-C67B56175A51"
     4199     wsmap="managed"
     4200     >
     4201    <desc>
     4202      The IProgress interface represents a task progress object that allows
     4203      to wait for the completion of some asynchronous task.
     4204
     4205      The task consists of one or more operations that run sequentially,
     4206      one after one. There is an individual percent of completion of the
     4207      current operation and the percent of completion of the task as a
     4208      whole. Similarly, you can wait for the completion of a particular
     4209      operation or for the completion of the whole task.
     4210
     4211      Every operation is identified by a number (starting from 0)
     4212      and has a separate description.
     4213    </desc>
     4214
     4215    <attribute name="id" type="uuid" readonly="yes">
     4216      <desc>ID of the task.</desc>
     4217    </attribute>
     4218
     4219    <attribute name="description" type="wstring" readonly="yes">
     4220      <desc>Description of the task.</desc>
     4221    </attribute>
     4222
     4223    <attribute name="initiator" type="$unknown" readonly="yes">
     4224      <desc>Initiator of the task.</desc>
     4225    </attribute>
     4226
     4227    <attribute name="cancelable" type="boolean" readonly="yes">
     4228      <desc>Whether the task can be interrupted.</desc>
     4229    </attribute>
     4230
     4231    <attribute name="percent" type="long" readonly="yes">
     4232      <desc>
     4233        Current task progress value in percent.
     4234        This value depends on how many operations are already complete.
     4235      </desc>
     4236    </attribute>
     4237
     4238    <attribute name="completed" type="boolean" readonly="yes">
     4239      <desc>Whether the task has been completed.</desc>
     4240    </attribute>
     4241
     4242    <attribute name="canceled" type="boolean" readonly="yes">
     4243      <desc>Whether the task has been canceled.</desc>
     4244    </attribute>
     4245
     4246    <attribute name="resultCode" type="result" readonly="yes">
     4247      <desc>
     4248        Result code of the progress task.
     4249        Valid only if <link to="#completed"/> is true.
     4250      </desc>
     4251    </attribute>
     4252
     4253    <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
     4254      <desc>
     4255        Extended information about the unsuccessful result of the
     4256        progress operation. May be NULL when no extended information
     4257        is available.
     4258        Valid only if <link to="#completed"/> is true and
     4259        <link to="#resultCode"/> indicates a failure.
     4260      </desc>
     4261    </attribute>
     4262
     4263    <attribute name="operationCount" type="unsigned long" readonly="yes">
     4264      <desc>
     4265        Number of operations this task is divided into.
     4266        Every task consists of at least one operation.
     4267      </desc>
     4268    </attribute>
     4269
     4270    <attribute name="operation" type="unsigned long" readonly="yes">
     4271      <desc>Number of the operation being currently executed.</desc>
     4272    </attribute>
     4273
     4274    <attribute name="operationDescription" type="wstring" readonly="yes">
     4275      <desc>
     4276        Description of the operation being currently executed.
     4277      </desc>
     4278    </attribute>
     4279
     4280    <attribute name="operationPercent" type="long" readonly="yes">
     4281      <desc>Current operation progress value in percent.</desc>
     4282    </attribute>
     4283
     4284    <method name="waitForCompletion">
     4285      <desc>
     4286        Waits until the task is done (including all operations) with a
     4287        given timeout.
     4288      </desc>
     4289      <param name="timeout" type="long" dir="in">
    41834290        <desc>
    4184             The IProgress interface represents a task progress object that allows
    4185             to wait for the completion of some asynchronous task.
    4186 
    4187             The task consists of one or more operations that run sequentially,
    4188             one after one. There is an individual percent of completion of the
    4189             current operation and the percent of completion of the task as a
    4190             whole. Similarly, you can wait for the completion of a particular
    4191             operation or for the completion of the whole task.
    4192 
    4193             Every operation is identified by a number (starting from 0)
    4194             and has a separate description.
     4291          Timeout value in milliseconds.
     4292          Specify -1 for an indefinite wait.
    41954293        </desc>
    4196 
    4197         <attribute name="id" type="uuid" readonly="yes">
    4198             <desc>ID of the task.</desc>
    4199         </attribute>
    4200 
    4201         <attribute name="description" type="wstring" readonly="yes">
    4202             <desc>Description of the task.</desc>
    4203         </attribute>
    4204 
    4205         <attribute name="initiator" type="$unknown" readonly="yes">
    4206             <desc>Initiator of the task.</desc>
    4207         </attribute>
    4208 
    4209         <attribute name="cancelable" type="boolean" readonly="yes">
    4210             <desc>Whether the task can be interrupted.</desc>
    4211         </attribute>
    4212 
    4213         <attribute name="percent" type="long" readonly="yes">
    4214             <desc>
    4215                 Current task progress value in percent.
    4216                 This value depends on how many operations are already complete.
    4217             </desc>
    4218         </attribute>
    4219 
    4220         <attribute name="completed" type="boolean" readonly="yes">
    4221             <desc>Whether the task has been completed.</desc>
    4222         </attribute>
    4223 
    4224         <attribute name="canceled" type="boolean" readonly="yes">
    4225             <desc>Whether the task has been canceled.</desc>
    4226         </attribute>
    4227 
    4228         <attribute name="resultCode" type="result" readonly="yes">
    4229             <desc>
    4230                 Result code of the progress task.
    4231                 Valid only if <link to="#completed"/> is true.
    4232             </desc>
    4233         </attribute>
    4234 
    4235         <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
    4236             <desc>
    4237                 Extended information about the unsuccessful result of the
    4238                 progress operation. May be NULL when no extended information
    4239                 is available.
    4240                 Valid only if <link to="#completed"/> is true and
    4241                 <link to="#resultCode"/> indicates a failure.
    4242             </desc>
    4243         </attribute>
    4244 
    4245         <attribute name="operationCount" type="unsigned long" readonly="yes">
    4246             <desc>
    4247                 Number of operations this task is divided into.
    4248                 Every task consists of at least one operation.
    4249             </desc>
    4250         </attribute>
    4251 
    4252         <attribute name="operation" type="unsigned long" readonly="yes">
    4253             <desc>Number of the operation being currently executed.</desc>
    4254         </attribute>
    4255 
    4256         <attribute name="operationDescription" type="wstring" readonly="yes">
    4257             <desc>
    4258                 Description of the operation being currently executed.
    4259             </desc>
    4260         </attribute>
    4261 
    4262         <attribute name="operationPercent" type="long" readonly="yes">
    4263             <desc>Current operation progress value in percent.</desc>
    4264         </attribute>
    4265 
    4266         <method name="waitForCompletion">
    4267             <desc>
    4268                 Waits until the task is done (including all operations) with a
    4269                 given timeout.
    4270             </desc>
    4271             <param name="timeout" type="long" dir="in">
    4272                 <desc>
    4273                     Timeout value in milliseconds.
    4274                     Specify -1 for an indefinite wait.
    4275                 </desc>
    4276             </param>
    4277         </method>
    4278 
    4279         <method name="waitForOperationCompletion">
    4280             <desc>
    4281                 Waits until the given operation is done with a given timeout.
    4282             </desc>
    4283             <param name="operation" type="unsigned long" dir="in">
    4284                 <desc>
    4285                     Number of the operation to wait for.
    4286                     Must be less than <link to="#operationCount"/>.
    4287                 </desc>
    4288             </param>
    4289             <param name="timeout" type="long" dir="in">
    4290                 <desc>
    4291                     Timeout value in milliseconds.
    4292                     Specify -1 for an indefinite wait.
    4293                 </desc>
    4294             </param>
    4295         </method>
    4296 
    4297         <method name="cancel">
    4298             <desc>
    4299                 Cancels the task.
    4300                 <note>
    4301                     If <link to="#cancelable"/> is <tt>false</tt>, then
    4302                     this method will fail.
    4303                 </note>
    4304             </desc>
    4305         </method>
    4306 
    4307     </interface>
    4308 
    4309 
    4310     <!--
    4311     // ISnapshot
    4312     /////////////////////////////////////////////////////////////////////////
    4313     -->
    4314 
    4315     <enumerator
    4316         name="ISnapshotEnumerator" type="ISnapshot"
    4317         uuid="25cfa2a4-1f1d-4f05-9658-b7a5894ef1a3"
    4318     />
    4319 
    4320     <collection
    4321         name="ISnapshotCollection" type="ISnapshot"
    4322         enumerator="ISnapshotEnumerator"
    4323         uuid="23852e3c-94cd-4801-ab05-ed35675b3894"
    4324         readonly="yes"
    4325     />
    4326 
    4327     <interface
    4328         name="ISnapshot" extends="$unknown"
    4329         uuid="9f1bbf79-13b0-4da2-abba-4a992c65c083"
    4330         wsmap="managed"
    4331     >
     4294      </param>
     4295    </method>
     4296
     4297    <method name="waitForOperationCompletion">
     4298      <desc>
     4299        Waits until the given operation is done with a given timeout.
     4300      </desc>
     4301      <param name="operation" type="unsigned long" dir="in">
    43324302        <desc>
    4333             The ISnapshot interface represents a snapshot of the virtual
    4334             machine.
    4335 
    4336             The <i>snapshot</i> stores all the information about a virtual
    4337             machine necessary to bring it to exactly the same state as it was at
    4338             the time of taking the snapshot. The snapshot includes:
    4339 
    4340             <ul>
    4341             <li>all settings of the virtual machine (i.e. its hardware
    4342             configuration: RAM size, attached hard disks, etc.)
    4343             </li>
    4344             <li>the execution state of the virtual machine (memory contents,
    4345             CPU state, etc.).
    4346             </li>
    4347             </ul>
    4348 
    4349             Snapshots can be <i>offline</i> (taken when the VM is powered off)
    4350             or <i>online</i> (taken when the VM is running). The execution
    4351             state of the offline snapshot is called a <i>zero execution state</i>
    4352             (it doesn't actually contain any information about memory contents
    4353             or the CPU state, assuming that all hardware is just powered off).
    4354 
    4355             <h3>Snapshot branches</h3>
    4356 
    4357             Snapshots can be chained. Chained snapshots form a branch where
    4358             every next snapshot is based on the previous one. This chaining is
    4359             mostly related to hard disk branching (see <link to="IHardDisk"/>
    4360             description). This means that every time a new snapshot is created,
    4361             a new differencing hard disk is implicitly created for all normal
    4362             hard disks attached to the given virtual machine. This allows to
    4363             fully restore hard disk contents when the machine is later reverted
    4364             to a particular snapshot.
    4365 
    4366             In the current implelemtation, multiple snapshot branches within one
    4367             virtual machine are not allowed. Every machine has a signle branch,
    4368             and <link to="IConsole::takeSnapshot()"/> operation adds a new
    4369             snapshot to the top of that branch.
    4370 
    4371             Existings snapshots can be discarded using
    4372             <link to="IConsole::discardSnapshot()"/>.
    4373 
    4374             <h3>Current snapshot</h3>
    4375 
    4376             Every virtual machine has a current snapshot, identified by
    4377             <link to="IMachine::currentSnapshot"/>. This snapshot is used as
    4378             a base for the <i>current machine state</i> (see below), to the effect
    4379             that all normal hard disks of the machine and its execution
    4380             state are based on this snapshot.
    4381 
    4382             In the current implementation, the current snapshot is always the
    4383             last taken snapshot (i.e. the head snapshot on the branch) and it
    4384             cannot be changed.
    4385 
    4386             The current snapshot is <tt>null</tt> if the machine doesn't have
    4387             snapshots at all; in this case the current machine state is just
    4388             current settings of this machine plus its current execution state.
    4389 
    4390             <h3>Current machine state</h3>
    4391 
    4392             The current machine state is what represened by IMachine instances
    4393             got directly from IVirtualBox using <link
    4394             to="IVirtualBox::getMachine()">getMachine()</link>, <link
    4395             to="IVirtualBox::findMachine()">findMachine()</link>, etc. (as
    4396             opposed to instances returned by <link to="ISnapshot::machine"/>).
    4397             This state is always used when the machine is <link
    4398             to="IConsole::powerUp"> powered on</link>.
    4399 
    4400             The current machine state also includes the current execution state.
    4401             If the machine is being currently executed
    4402             (<link to="IMachine::state"/> is <link to="MachineState::Running"/>
    4403             and above), its execution state is just what's happening now.
    4404             If it is powered off (<link to="MachineState::PoweredOff"/> or
    4405             <link to="MachineState::Aborted"/>), it has a zero execution state.
    4406             If the machine is saved (<link to="MachineState::Saved"/>), its
    4407             execution state is what saved in the execution state file
    4408             (<link to="IMachine::stateFilePath"/>).
    4409 
    4410             If the machine is in the saved state, then, next time it is powered
    4411             on, its execution state will be fully restored from the saved state
    4412             file and the execution will continue from the point where the state
    4413             was saved.
    4414 
    4415             Similarly to snapshots, the current machine state can be discarded
    4416             using <link to="IConsole::discardCurrentState()"/>.
    4417 
    4418             <h3>Taking and discarding snapshots</h3>
    4419 
    4420             The table below briefly explains the meaning of every snapshot
    4421             operation:
    4422 
    4423             <table>
    4424             <tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr>
    4425 
    4426             <tr><td><link to="IConsole::takeSnapshot()"/></td>
    4427 
    4428             <td>Save the current state of the virtual machine, including all
     4303          Number of the operation to wait for.
     4304          Must be less than <link to="#operationCount"/>.
     4305        </desc>
     4306      </param>
     4307      <param name="timeout" type="long" dir="in">
     4308        <desc>
     4309          Timeout value in milliseconds.
     4310          Specify -1 for an indefinite wait.
     4311        </desc>
     4312      </param>
     4313    </method>
     4314
     4315    <method name="cancel">
     4316      <desc>
     4317        Cancels the task.
     4318        <note>
     4319          If <link to="#cancelable"/> is <tt>false</tt>, then
     4320          this method will fail.
     4321        </note>
     4322      </desc>
     4323    </method>
     4324
     4325  </interface>
     4326
     4327
     4328  <!--
     4329  // ISnapshot
     4330  /////////////////////////////////////////////////////////////////////////
     4331  -->
     4332
     4333  <enumerator
     4334     name="ISnapshotEnumerator" type="ISnapshot"
     4335     uuid="25cfa2a4-1f1d-4f05-9658-b7a5894ef1a3"
     4336     />
     4337
     4338  <collection
     4339     name="ISnapshotCollection" type="ISnapshot"
     4340     enumerator="ISnapshotEnumerator"
     4341     uuid="23852e3c-94cd-4801-ab05-ed35675b3894"
     4342     readonly="yes"
     4343     />
     4344
     4345  <interface
     4346     name="ISnapshot" extends="$unknown"
     4347     uuid="9f1bbf79-13b0-4da2-abba-4a992c65c083"
     4348     wsmap="managed"
     4349     >
     4350    <desc>
     4351      The ISnapshot interface represents a snapshot of the virtual
     4352      machine.
     4353
     4354      The <i>snapshot</i> stores all the information about a virtual
     4355      machine necessary to bring it to exactly the same state as it was at
     4356      the time of taking the snapshot. The snapshot includes:
     4357
     4358      <ul>
     4359        <li>all settings of the virtual machine (i.e. its hardware
     4360          configuration: RAM size, attached hard disks, etc.)
     4361        </li>
     4362        <li>the execution state of the virtual machine (memory contents,
     4363          CPU state, etc.).
     4364        </li>
     4365      </ul>
     4366
     4367      Snapshots can be <i>offline</i> (taken when the VM is powered off)
     4368      or <i>online</i> (taken when the VM is running). The execution
     4369      state of the offline snapshot is called a <i>zero execution state</i>
     4370      (it doesn't actually contain any information about memory contents
     4371      or the CPU state, assuming that all hardware is just powered off).
     4372
     4373      <h3>Snapshot branches</h3>
     4374
     4375      Snapshots can be chained. Chained snapshots form a branch where
     4376      every next snapshot is based on the previous one. This chaining is
     4377      mostly related to hard disk branching (see <link to="IHardDisk"/>
     4378      description). This means that every time a new snapshot is created,
     4379      a new differencing hard disk is implicitly created for all normal
     4380      hard disks attached to the given virtual machine. This allows to
     4381      fully restore hard disk contents when the machine is later reverted
     4382      to a particular snapshot.
     4383
     4384      In the current implelemtation, multiple snapshot branches within one
     4385      virtual machine are not allowed. Every machine has a signle branch,
     4386      and <link to="IConsole::takeSnapshot()"/> operation adds a new
     4387      snapshot to the top of that branch.
     4388
     4389      Existings snapshots can be discarded using
     4390      <link to="IConsole::discardSnapshot()"/>.
     4391
     4392      <h3>Current snapshot</h3>
     4393
     4394      Every virtual machine has a current snapshot, identified by
     4395      <link to="IMachine::currentSnapshot"/>. This snapshot is used as
     4396      a base for the <i>current machine state</i> (see below), to the effect
     4397      that all normal hard disks of the machine and its execution
     4398      state are based on this snapshot.
     4399
     4400      In the current implementation, the current snapshot is always the
     4401      last taken snapshot (i.e. the head snapshot on the branch) and it
     4402      cannot be changed.
     4403
     4404      The current snapshot is <tt>null</tt> if the machine doesn't have
     4405      snapshots at all; in this case the current machine state is just
     4406      current settings of this machine plus its current execution state.
     4407
     4408      <h3>Current machine state</h3>
     4409
     4410      The current machine state is what represened by IMachine instances got
     4411      directly from IVirtualBox
     4412      using <link
     4413      to="IVirtualBox::getMachine()">getMachine()</link>, <link
     4414      to="IVirtualBox::findMachine()">findMachine()</link>, etc. (as opposed
     4415      to instances returned by <link to="ISnapshot::machine"/>).  This state
     4416      is always used when the machine is <link to="IConsole::powerUp"> powered
     4417      on</link>.
     4418
     4419      The current machine state also includes the current execution state.
     4420      If the machine is being currently executed
     4421      (<link to="IMachine::state"/> is <link to="MachineState::Running"/>
     4422      and above), its execution state is just what's happening now.
     4423      If it is powered off (<link to="MachineState::PoweredOff"/> or
     4424      <link to="MachineState::Aborted"/>), it has a zero execution state.
     4425      If the machine is saved (<link to="MachineState::Saved"/>), its
     4426      execution state is what saved in the execution state file
     4427      (<link to="IMachine::stateFilePath"/>).
     4428
     4429      If the machine is in the saved state, then, next time it is powered
     4430      on, its execution state will be fully restored from the saved state
     4431      file and the execution will continue from the point where the state
     4432      was saved.
     4433
     4434      Similarly to snapshots, the current machine state can be discarded
     4435      using <link to="IConsole::discardCurrentState()"/>.
     4436
     4437      <h3>Taking and discarding snapshots</h3>
     4438
     4439      The table below briefly explains the meaning of every snapshot
     4440      operation:
     4441
     4442      <table>
     4443        <tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr>
     4444
     4445        <tr><td><link to="IConsole::takeSnapshot()"/></td>
     4446
     4447          <td>Save the current state of the virtual machine, including all
    44294448            settings, contents of normal hard disks and the current modifications
    44304449            to immutable hard disks (for online snapshots)</td>
    44314450
    4432             <td>The current state is not changed (the machine will continue
     4451          <td>The current state is not changed (the machine will continue
    44334452            execution if it is being executed when the snapshot is
    44344453            taken)</td></tr>
    44354454
    4436             <tr><td><link to="IConsole::discardSnapshot()"/></td>
    4437 
    4438             <td>Forget the state of the virtual machine stored in the snapshot:
     4455        <tr><td><link to="IConsole::discardSnapshot()"/></td>
     4456
     4457          <td>Forget the state of the virtual machine stored in the snapshot:
    44394458            dismiss all saved settings and delete the saved execution state (for
    44404459            online snapshots)</td>
    44414460
    4442             <td>Other snapshots (including child snapshots, if any) and the
     4461          <td>Other snapshots (including child snapshots, if any) and the
    44434462            current state are not directly affected</td></tr>
    44444463
    4445             <tr><td><link to="IConsole::discardCurrentState()"/></td>
    4446 
    4447             <td>Restore the current state of the virtual machine from the state
     4464        <tr><td><link to="IConsole::discardCurrentState()"/></td>
     4465
     4466          <td>Restore the current state of the virtual machine from the state
    44484467            stored in the current snapshot, including all settings and hard disk
    44494468            contents</td>
    44504469
    4451             <td>The current state of the machine existed prior to this operation
     4470          <td>The current state of the machine existed prior to this operation
    44524471            is lost</td></tr>
    44534472
    4454             <tr><td><link to="IConsole::discardCurrentSnapshotAndState()"/></td>
    4455 
    4456             <td>Completely revert the virtual machine to the state it was in
     4473        <tr><td><link to="IConsole::discardCurrentSnapshotAndState()"/></td>
     4474
     4475          <td>Completely revert the virtual machine to the state it was in
    44574476            before the current snapshot has been taken</td>
    44584477
    4459             <td>The current state, as well as the current snapshot, are
     4478          <td>The current state, as well as the current snapshot, are
    44604479            lost</td></tr>
    44614480
    4462             </table>
    4463 
     4481      </table>
     4482
     4483    </desc>
     4484
     4485    <attribute name="id" type="uuid" readonly="yes">
     4486      <desc>UUID of the snapshot.</desc>
     4487    </attribute>
     4488
     4489    <attribute name="name" type="wstring">
     4490      <desc>Short name of the snapshot.</desc>
     4491    </attribute>
     4492
     4493    <attribute name="description" type="wstring">
     4494      <desc>Optional description of the snapshot.</desc>
     4495    </attribute>
     4496
     4497    <attribute name="timeStamp" type="long long" readonly="yes">
     4498      <desc>
     4499        Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
     4500      </desc>
     4501    </attribute>
     4502
     4503    <attribute name="online" type="boolean" readonly="yes">
     4504      <desc>
     4505        <tt>true</tt> if this snapshot is an online snapshot and
     4506        <tt>false</tt> otherwise.
     4507
     4508        <note>
     4509          When this attribute is <tt>true</tt>, the
     4510          <link to="IMachine::stateFilePath"/> attribute of the
     4511          <link to="#machine"/> object associated with this snapshot
     4512          will point to the saved state file. Otherwise, it will be
     4513          <tt>null</tt>.
     4514        </note>
     4515      </desc>
     4516    </attribute>
     4517
     4518    <attribute name="machine" type="IMachine" readonly="yes">
     4519      <desc>
     4520        Virtual machine this snapshot is taken on. This object
     4521        stores all settings the machine had when taking this snapshot.
     4522        <note>
     4523          The returned machine object is immutable, i.e. no
     4524          any settings can be changed.
     4525        </note>
     4526      </desc>
     4527    </attribute>
     4528
     4529    <attribute name="parent" type="ISnapshot" readonly="yes">
     4530      <desc>
     4531        Parent snapshot (a snapshot this one is based on).
     4532        <note>
     4533          It's not an error to read this attribute on a snapshot
     4534          that doesn't have a parent -- a null object will be
     4535          returned to indicate this.
     4536        </note>
     4537      </desc>
     4538    </attribute>
     4539
     4540    <attribute name="children" type="ISnapshotCollection" readonly="yes">
     4541      <desc>
     4542        Child snapshots (all snapshots having this one as a parent).
     4543        <note>
     4544          In the current implementation, there can be only one
     4545          child snapshot, or no children at all, meaning this is the
     4546          last (head) snapshot.
     4547        </note>
     4548      </desc>
     4549    </attribute>
     4550
     4551  </interface>
     4552
     4553  <!--
     4554  // IHardDisk
     4555  /////////////////////////////////////////////////////////////////////////
     4556  -->
     4557
     4558  <enum
     4559     name="HardDiskStorageType"
     4560     uuid="48138584-ad99-479d-a36f-eb82a7663685"
     4561     >
     4562    <desc>
     4563      Virtual hard disk storage type.
     4564      <see>IHardDisk</see>
     4565    </desc>
     4566    <const name="VirtualDiskImage" value="0">
     4567      <desc>
     4568        Virtual Disk Image, VDI (a regular file in the file
     4569        system of the host OS, see <link to="IVirtualDiskImage"/>)
     4570      </desc>
     4571    </const>
     4572    <const name="ISCSIHardDisk" value="1">
     4573      <desc>
     4574        iSCSI Remote Disk (a disk accessed via the Internet
     4575        SCSI protocol over a TCP/IP network, see
     4576        <link to="IISCSIHardDisk"/>)
     4577      </desc>
     4578    </const>
     4579    <const name="VMDKImage" value="2">
     4580      <desc>
     4581        VMware Virtual Machine Disk image (a regular file in the file
     4582        system of the host OS, see <link to="IVMDKImage"/>)
     4583      </desc>
     4584    </const>
     4585  </enum>
     4586
     4587  <enum
     4588     name="HardDiskType"
     4589     uuid="a348fafd-a64e-4643-ba65-eb3896bd7e0a"
     4590     >
     4591    <desc>
     4592      Virtual hard disk type.
     4593      <see>IHardDisk</see>
     4594    </desc>
     4595    <const name="NormalHardDisk" value="0">
     4596      <desc>
     4597        Normal hard disk (attached directly or indirectly, preserved
     4598        when taking snapshots).
     4599      </desc>
     4600    </const>
     4601    <const name="ImmutableHardDisk" value="1">
     4602      <desc>
     4603        Immutable hard disk (attached indirectly, changes are wiped out
     4604        after powering off the virtual machine).
     4605      </desc>
     4606    </const>
     4607    <const name="WritethroughHardDisk" value="2">
     4608      <desc>
     4609        Write through hard disk (attached directly, ignored when
     4610        taking snapshots).
     4611      </desc>
     4612    </const>
     4613  </enum>
     4614
     4615  <interface
     4616     name="IHardDiskAttachment" extends="$unknown"
     4617     uuid="c0ffe596-21c6-4797-8d8a-b47b66881e7a"
     4618     wsmap="struct"
     4619     >
     4620    <attribute name="hardDisk" type="IHardDisk" readonly="yes">
     4621      <desc>Harddisk object this attachment is about.</desc>
     4622    </attribute>
     4623
     4624    <attribute name="controller" type="DiskControllerType" readonly="yes">
     4625      <desc>Disk controller ID of this attachment.</desc>
     4626    </attribute>
     4627
     4628    <attribute name="deviceNumber" type="long" readonly="yes">
     4629      <desc>Device number of the attachment.</desc>
     4630    </attribute>
     4631
     4632  </interface>
     4633
     4634  <enumerator
     4635     name="IHardDiskAttachmentEnumerator" type="IHardDiskAttachment"
     4636     uuid="9955e486-2f0b-432a-99e4-0ebbd338875e"
     4637     />
     4638
     4639  <collection
     4640     name="IHardDiskAttachmentCollection" type="IHardDiskAttachment"
     4641     enumerator="IHardDiskAttachmentEnumerator"
     4642     uuid="8f727842-bb77-45d4-92de-4ec14bf613c9"
     4643     readonly="yes"
     4644     />
     4645
     4646  <enumerator
     4647     name="IHardDiskEnumerator" type="IHardDisk"
     4648     uuid="b976f97b-cdb8-47e3-9860-084031cbd533"
     4649     />
     4650
     4651  <collection
     4652     name="IHardDiskCollection" type="IHardDisk"
     4653     enumerator="IHardDiskEnumerator"
     4654     uuid="43EAC2BC-5C61-40fa-BC38-46DE2C7DB6BB"
     4655     readonly="yes"
     4656     />
     4657
     4658  <interface
     4659     name="IHardDisk" extends="$unknown"
     4660     uuid="FD443EC1-000F-4F5B-9282-D72760A66916"
     4661     wsmap="managed"
     4662     >
     4663    <desc>
     4664      The IHardDisk interface represents a virtual hard disk drive
     4665      used by virtual machines.
     4666
     4667      The virtual hard disk drive virtualizes the hard disk hardware and
     4668      looks like a regular hard disk inside the virtual machine and
     4669      the guest OS.
     4670
     4671      <h3>Storage Types</h3>
     4672
     4673      The <link to="HardDiskStorageType">storage type</link> of the
     4674      virtual hard disk determines where and how it stores its data
     4675      (sectors). Currently, the following storage types are supported:
     4676
     4677      <ul>
     4678
     4679        <li>
     4680          <i>Virtual Disk Image (VDI)</i>, a regular file in the file system
     4681          of the host OS (represented by the <link to="IVirtualDiskImage"/>
     4682          interface). This file has a special format optimized so that unused
     4683          sectors of data occupy much less space than on a physical hard disk.
     4684        </li>
     4685
     4686        <li>
     4687          <i>iSCSI Remote Disk</i>, a disk accessed via the Internet SCSI
     4688          protocol over a TCP/IP network link (represented by the
     4689          <link to="IISCSIHardDisk"/> interface).
     4690        </li>
     4691
     4692        <li>
     4693          <i>VMware VMDK Image</i>, a regular file in the file system of the
     4694          host OS (represented by the <link to="IVMDKImage"/> interface).
     4695        </li>
     4696
     4697      </ul>
     4698
     4699      The storage type of the particular hard disk object is indicated by
     4700      the <link to="#storageType"/> property.
     4701
     4702      Each storage type is represented by its own interface (as shown
     4703      above), that allows to query and set properties and perform
     4704      operations specific to that storage type. When an IHardDisk object
     4705      reports it uses some particular storage type, it also guaranteed to
     4706      support the corresponding interface which you can query. And vice
     4707      versa, every object that supports a storage-specific interface, also
     4708      supports IHardDisk.
     4709
     4710      <h3>Virtual Hard Disk Types</h3>
     4711
     4712      The <link to="HardDiskType">type</link> of the virtual hard disk
     4713      determines how it is attached to the virtual machine when you call
     4714      <link to="IMachine::attachHardDisk()"/> and what happens to it when
     4715      a <link to="ISnapshot">snapshot</link> of the virtual machine is
     4716      taken.
     4717
     4718      There are three types of virtual hard disks:
     4719
     4720      <ul>
     4721        <li><i>Normal</i></li>
     4722        <li><i>Immutable</i></li>
     4723        <li><i>Writethrough</i></li>
     4724      </ul>
     4725
     4726      The virtual disk type is indicated by the <link to="#type"/>
     4727      property. Each of the above types is described in detail further
     4728      down.
     4729
     4730      There is also a forth, "hidden" virtual disk type:
     4731      <i>Differencing</i>. It is "hidden" because you cannot directly
     4732      create hard disks of this type -- they are automatically created by
     4733      VirtualBox when necessary.
     4734
     4735      <b>Differencing Hard Disks</b>
     4736
     4737      Unlike disks of other types (that are similar to real hard disks),
     4738      the differencing hard disk does not store the full range of data
     4739      sectors. Instead, it stores only a subset of sectors of some other
     4740      disk that were changed since the differencing hard disk has been
     4741      created. Thus, every differencing hard disk has a parent hard disk
     4742      it is linked to, and represents the difference between the initial
     4743      and the current hard disk state. A differencing hard disk can be
     4744      linked to another differencing hard disk -- this way, differencing
     4745      hard disks can form a branch of changes. More over, a given virtual
     4746      hard disk can have more than one differencing hard disk linked to
     4747      it.
     4748
     4749      A disk the differencing hard disk is linked to (or, in other words,
     4750      based on) is called a <i>parent</i> hard disk and is accessible through
     4751      the <link to="#parent"/> property. Similarly, all existing differencing
     4752      hard disks for a given parent hard disk are called its <i>child</i> hard
     4753      disks (and accessible through the <link to="#children"/> property).
     4754
     4755      All differencing hard disks use Virtual Disk Image files to store
     4756      changed sectors. They have the <link to="#type"/> property set to
     4757      Normal, but can be easily distinguished from normal hard disks using
     4758      the <link to="#parent"/> property: all differencing hard disks have
     4759      a parent, while all normal hard disks don't.
     4760
     4761      When the virtual machine makes an attempt to read a sector that is
     4762      missing in a differencing hard disk, its parent is accessed to
     4763      resolve the sector in question. This process continues until the
     4764      sector is found, or until the root hard disk is encountered, which
     4765      always contains all sectors. As a consequence,
     4766
     4767      <ul>
     4768
     4769        <li>
     4770          The virtual hard disk geometry seen by the guest OS is
     4771          always defined by the root hard disk.
     4772        </li>
     4773
     4774        <li>
     4775          All hard disks on a branch, up to the root, must be
     4776          <link to="#accessible"/> for a given differencing hard disk in order
     4777          to let it function properly when the virtual machine is
     4778          running.
     4779        </li>
     4780
     4781      </ul>
     4782
     4783      Differencing hard disks can be implicitly created by VirtualBox in
     4784      the following cases:
     4785
     4786      <ul>
     4787
     4788        <li>
     4789          When a hard disk is <i>indirectly</i> attached to the virtual
     4790          machine using <link to="IMachine::attachHardDisk()"/>.  In this
     4791          case, all disk writes performed by the guest OS will go to the
     4792          created diffferencing hard disk, as opposed to the
     4793          <i>direct</i> attachment, where all changes are written to the
     4794          attached hard disk itself.
     4795        </li>
     4796
     4797        <li>
     4798          When a <link to="ISnapshot">snapshot</link> of the virtual machine
     4799          is taken. After that, disk writes to hard disks the differencing
     4800          ones have been created for, will be directed to those differencing
     4801          hard disks, to preserve the contents of the original disks.
     4802        </li>
     4803
     4804      </ul>
     4805
     4806      Whether to create a differencing hard disk or not depends on the
     4807      type of the hard disk attached to the virtual machine. This is
     4808      explained below.
     4809
     4810      Note that in the current implementation, only the
     4811      <link to="VirtualDiskImage"/> storage type is used to
     4812      represent differencing hard disks. In other words, all
     4813      differencing hard disks are <link to="IVirtualDiskImage"/>
     4814      objects.
     4815
     4816      <b>Normal Hard Disks</b>
     4817
     4818      Normal hard disks are the most commonly used virtual hard disk. A
     4819      normal hard disk is attached to the machine directly if it is not
     4820      already attached to some other machine. Otherwise, an attempt to
     4821      make an indirect attachment through a differencing hard disk will be
     4822      made. This attempt will fail if the hard disk is attached to a
     4823      virtual machine without snapshots (because it's impossible to create
     4824      a differencing hard disk based on a hard disk that is subject to
     4825      change).
     4826
     4827      When an indirect attachment takes place, in the simplest case, where
     4828      the machine the hard disk is being attached to doesn't have
     4829      snapshots, the differencing hard disk will be based on the normal
     4830      hard disk being attached. Otherwise, the first (i.e. the most
     4831      recent) descendant of the given normal hard disk found in the
     4832      current snapshot branch (starting from the current snapshot and
     4833      going up to the root) will be actually used as a base.
     4834
     4835      Note that when you detach an indirectly attached hard disk from the
     4836      machine, the created differencing hard disk image is simply
     4837      <b>deleted</b>, so <b>all changes are lost</b>. If you attach the
     4838      same disk again, a clean differencing disk will be created based on
     4839      the most recent child, as described above.
     4840
     4841      When taking a snapshot, the contents of all normal hard disks (and
     4842      all differencing disks whose roots are normal hard disks) currently
     4843      attached to the virtual machine is preserved by creating
     4844      differencing hard disks based on them.
     4845
     4846      <b>Immutable Hard Disks</b>
     4847
     4848      Immutable hard disks can be used to provide a sort of read-only
     4849      access. An immutable hard disk is always attached indirectly. The
     4850      created differencing hard disk is automatically wiped out (recreated
     4851      from scratch) every time you power off the virtual machine. Thus,
     4852      the contents of the immutable disk remains unchanged between runs.
     4853
     4854      Detaching an immutable hard disk deletes the differencing disk
     4855      created for it, with the same effect as in case with normal hard
     4856      disks.
     4857
     4858      When taking a snapshot, the differencing part of the immutable
     4859      hard disk is cloned (i.e. copied to a separate Virtual Disk Image
     4860      file) without any changes. This is necessary to preserve the exact
     4861      virtual machine state when you create an online snapshot.
     4862
     4863      <b>Writethrough Hard Disks</b>
     4864
     4865      Hard disks of this type are always attached directly. This means
     4866      that every given writethrough hard disk can be attached only to one
     4867      virtual machine at a time.
     4868
     4869      It is impossible to take a snapshot of a virtual machine with the
     4870      writethrough hard disk attached, because taking a snapshot implies
     4871      saving the execution state and preserving the contents of all hard
     4872      disks, but writethrough hard disks cannot be preserved. Preserving
     4873      hard disk contents is necessary to ensure the guest OS stored in the
     4874      snapshot will get the same hard disk state when restored, which is
     4875      especially important when it has open file handles or when there are
     4876      cached files and directories stored in memory.
     4877
     4878      <h3>Creating, Opening and Registering Hard Disks</h3>
     4879
     4880      Non-differencing hard disks are either created from scratch using
     4881      <link to="IVirtualBox::createHardDisk()"/> or opened from a VDI file
     4882      using <link to="IVirtualBox::openVirtualDiskImage()"/> (only for hard
     4883      disks using the VirtualDiskImage storage type). Once a hard disk is
     4884      created or opened, it needs to be registered using
     4885      <link to="IVirtualBox::registerHardDisk()"/> to make it available for
     4886      attaching to virtual machines. See the documentation of individual
     4887      interfaces for various storage types to get more information.
     4888
     4889      Differencing hard disks are never created explicitly and cannot
     4890      be registered or unregistered; they are automatically registered
     4891      upon creation and deregistered when deleted.
     4892
     4893      <h3>More about Indirect Hard Disk Attachments</h3>
     4894
     4895      Normally, when you attach a hard disk to the virtual machine, and then
     4896      query the corresponding attachment using
     4897      <link to="IMachine::getHardDisk()"/> or
     4898      <link to="IMachine::hardDiskAttachments"/> you will get the same hard
     4899      disk object, whose UUID you passed earlier to
     4900      <link to="IMachine::attachHardDisk()"/>. However, when an indirect
     4901      attachment takes place, calling <link to="IMachine::getHardDisk()"/>
     4902      will return a differencing hard disk object, that is either based on the
     4903      attached hard disk or on another differencing hard disk, the attached
     4904      hard disk is eventually a root for (as described above). In both cases
     4905      the returned hard disk object is the object the virtual machine actually
     4906      uses to perform disk writes to.
     4907
     4908      Regardless of whether the attachment is direct or indirect, the
     4909      <link to="#machineId"/> property of the attached disk will contain an
     4910      UUID of the machine object <link to="IMachine::attachHardDisk()"/>
     4911      has been called on.
     4912
     4913      Note that both <link to="IMachine::attachHardDisk()"/> and
     4914      <link to="IMachine::detachHardDisk()"/> are <i>lazy</i> operations. In
     4915      particular, this means that when an indirect attachment is made,
     4916      differencing hard disks are not created until machine settings are
     4917      committed using <link to="IMachine::saveSettings()"/>. Similarly, when a
     4918      differencing hard disk is detached, it is not deleted until
     4919      <link to="IMachine::saveSettings()"/> is called. Calling
     4920      <link to="IMachine::discardSettings()"/> cancels all lazy attachments or
     4921      detachments made since the last commit and effectively restores the
     4922      previous set of hard disks.
     4923
     4924      <h3>Hard Disk Accessibility</h3>
     4925
     4926      The <link to="#accessible"/> attribute of the hard disk object
     4927      defines the accessibility state of the respective hard disk storage
     4928      (for example, the VDI file for IVirtualDiskImage objects). If the
     4929      value of this attribute is <tt>false</tt> then some hard disk
     4930      attributes may contain invalid or outdated values (for example, the
     4931      virtual or the actual hard disk size) until a new accessibility
     4932      check is done that returns <tt>true</tt> (see the attribute
     4933      description for more details).
     4934
     4935      <note>
     4936        Because of the possible slowness of the accessibility check,
     4937        it is not implicitly performed upon the VirtualBox server startup
     4938        (to prevent the application freeze). In partcular, this means that
     4939        if you try to read hard disk properties that depend on the
     4940        accessibility state without first reading the value of the
     4941        <link to="#accessible"/> attribute and ensuring it's value is
     4942        <tt>true</tt>, you will get wrong (zero) values.
     4943      </note>
     4944
     4945    </desc>
     4946
     4947    <attribute name="id" type="uuid" readonly="yes">
     4948      <desc>
     4949
     4950        UUID of the hard disk. For newly created hard disk objects,
     4951        this value is a randomly generated UUID.
     4952
     4953      </desc>
     4954    </attribute>
     4955
     4956    <attribute name="description" type="wstring">
     4957      <desc>
     4958
     4959        Optional description of the hard disk. For a newly created hard
     4960        disk, this value is <tt>null</tt>.
     4961
     4962        <note>For some storage types, reading this property is
     4963          meaningless when <link to="#accessible"/> is <tt>false</tt>.
     4964          Also, you cannot assign it a new value in this case.</note>
     4965
     4966      </desc>
     4967    </attribute>
     4968
     4969    <attribute name="storageType" type="HardDiskStorageType" readonly="yes">
     4970      <desc>
     4971
     4972        Storage type of this hard disk.
     4973
     4974        Storage type is defined when you open or create a new hard disk
     4975        object.
     4976
     4977      </desc>
     4978    </attribute>
     4979
     4980    <attribute name="location" type="wstring" readonly="yes">
     4981      <desc>
     4982
     4983        Storage location of this hard disk. The returned string serves
     4984        for informational purposes only. To access detailed information
     4985        about the storage, query the appropriate storage-specific
     4986        interface.
     4987
     4988      </desc>
     4989    </attribute>
     4990
     4991    <attribute name="type" type="HardDiskType">
     4992      <desc>
     4993
     4994        Type (behavior) of this hard disk. For a newly created or opened hard
     4995        disk, this value is <link to="HardDiskType::NormalHardDisk"/>.
     4996
     4997        <note>
     4998          In the current implementation, this property can be
     4999          changed only on an unregistered hard disk object. This may be
     5000          changed later.
     5001        </note>
     5002
     5003      </desc>
     5004    </attribute>
     5005
     5006    <attribute name="parent" type="IHardDisk" readonly="yes">
     5007      <desc>
     5008
     5009        Parent of this hard disk (a hard disk this one is directly based
     5010        on).
     5011
     5012        Only differencing hard disks have parents, so a <tt>null</tt>
     5013        object is returned for a hard disk of any other type.
     5014      </desc>
     5015    </attribute>
     5016
     5017    <attribute name="children" type="IHardDiskCollection" readonly="yes">
     5018      <desc>
     5019
     5020        Children of this hard disk (all differencing hard disks for
     5021        those this one is a parent). An empty collection is returned, if
     5022        this hard disk doesn't have any children.
     5023
     5024      </desc>
     5025    </attribute>
     5026
     5027    <attribute name="root" type="IHardDisk" readonly="yes">
     5028      <desc>
     5029
     5030        Root hard disk of this hard disk. If this hard disk is a
     5031        differencing hard disk, its root hard disk is the first disk on
     5032        the branch. For all other types of hard disks, this property
     5033        returns the hard disk object itself (i.e. the same object you
     5034        read this property on).
     5035
     5036      </desc>
     5037    </attribute>
     5038
     5039    <attribute name="accessible" type="boolean" readonly="yes">
     5040      <desc>
     5041
     5042        Whether the hard disk storage is currently accessible or not.
     5043        The storage, for example, can be unaccessible if it doesn't exist
     5044        or if it is placed on a network resource that is not available
     5045        by the time this attribute is read.
     5046
     5047        In the current implementation, the value of this property is
     5048        also <tt>false</tt> if this hard disk is attached to a running
     5049        virtual machine.
     5050
     5051        The accessibility check is performed automatically every time
     5052        this attribute is read. You should keep it in mind that this check
     5053        may be slow and can block the calling thread for a long time (for
     5054        example, if the network resourse where the hard disk storage is
     5055        located is down).
     5056
     5057        The following attributes of the hard disk object are considered
     5058        to be invalid when this attribute is <tt>false</tt>:
     5059        <ul>
     5060          <li><link to="#size"/></li>
     5061          <li><link to="#actualSize"/></li>
     5062        </ul>
     5063        Individual hard disk storage type interfaces may define
     5064        additional attributes that depend on the accessibility state.
     5065      </desc>
     5066    </attribute>
     5067
     5068    <attribute name="allAccessible" type="boolean" readonly="yes">
     5069      <desc>
     5070
     5071        Whether the whole hard disk branch, starting from this image and
     5072        going through its ancestors up to the root, is accessible or
     5073        not.
     5074
     5075        This property makes sense only for differencing hard disks. For
     5076        all other types of hard disks it returns the same value as
     5077        <link to="#accessible"/>.
     5078
     5079      </desc>
     5080    </attribute>
     5081
     5082    <attribute name="lastAccessError" type="wstring" readonly="yes">
     5083      <desc>
     5084
     5085        String describing the reason of inaccessibility of this hard
     5086        disk after the last call to <link to="#accessible"/> that
     5087        returned <tt>false</tt>. A <tt>null</tt> value of this property
     5088        means that the last accessibility check returned <tt>true</tt>.
     5089
     5090      </desc>
     5091    </attribute>
     5092
     5093    <attribute name="size" type="unsigned long long" readonly="yes">
     5094      <desc>
     5095
     5096        Logical size of this hard disk (in megabytes), as reported to the
     5097        guest OS running inside the vurtual machine this disk is
     5098        attached to. The logical size is defined when the hard disk is
     5099        created.
     5100
     5101        <note>Reading this property on a differencing hard disk will
     5102          return the size of its root hard disk.</note>
     5103
     5104        <note>Reading this property is meaningless when
     5105          <link to="#accessible"/> is <tt>false</tt></note>
     5106
     5107      </desc>
     5108    </attribute>
     5109
     5110    <attribute name="actualSize" type="unsigned long long" readonly="yes">
     5111      <desc>
     5112
     5113        Physical size of the storage used to store hard disk data (in
     5114        bytes). This size is usually less than the logical size of the
     5115        hard disk, depending on the storage type and on the size
     5116        optimization method used for that storage.
     5117
     5118        <note>Reading this property is meaningless when
     5119          <link to="#accessible"/> is <tt>false</tt></note>
     5120
     5121      </desc>
     5122    </attribute>
     5123
     5124    <attribute name="machineId" type="uuid" readonly="yes">
     5125      <desc>
     5126
     5127        UUID of the machine this hard disk is attached to (or a
     5128        <tt>null</tt> UUID if it is not attached).
     5129
     5130        <note>Immutable hard disks are never attached directly, so this
     5131          attribute is always <tt>null</tt> in this case.</note>
     5132
     5133      </desc>
     5134    </attribute>
     5135
     5136    <attribute name="snapshotId" type="uuid" readonly="yes">
     5137      <desc>
     5138
     5139        UUID of the <link to="ISnapshot">snapshot</link> this hard disk
     5140        is associated with (or <tt>null</tt> UUID if it is not
     5141        associated with any snapshot).
     5142
     5143        <note>
     5144          This attribute is always <tt>null</tt> if <link to="#machineId"/>
     5145          is <tt>null</tt>.
     5146        </note>
     5147
     5148        <note>
     5149          Writethrough hard disks are always attached directly and cannot be
     5150          involved when taking snapshots, so this attribute is meaningless and
     5151          therefore always <tt>null</tt>.
     5152        </note>
     5153
     5154      </desc>
     5155    </attribute>
     5156
     5157    <method name="cloneToImage">
     5158
     5159      <desc>
     5160
     5161        Starts creating a clone of this hard disk. The cloned hard disk
     5162        will use the specified Virtual Disk Image file as a storage and
     5163        will contain exactly the same sector data as the hard disk being
     5164        cloned, except that a new UUID for the clone will be randomly
     5165        generated.
     5166
     5167        The specified image file path can be absolute (full path) or
     5168        relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
     5169          home directory</link>. If only a file name without any path is
     5170        given, the <link to="ISystemProperties::defaultVDIFolder">
     5171          default VDI folder</link> will be used as a path to the image
     5172        file.
     5173
     5174        It is an error to use the object returned in the @a image
     5175        parameter until the returned @a progress object reports success.
     5176
     5177        <note>In the current implementation, only non-differencing hard
     5178          disks can be cloned.</note>
     5179
     5180      </desc>
     5181
     5182      <param name="filePath" type="wstring" dir="in">
     5183        <desc>Path to a file where to store the cloned hard disk.</desc>
     5184      </param>
     5185      <param name="image" type="IVirtualDiskImage" dir="out">
     5186        <desc>Cloned hard disk object.</desc>
     5187      </param>
     5188      <param name="progress" type="IProgress" dir="return">
     5189        <desc>Progress object to track the operation completion.</desc>
     5190      </param>
     5191
     5192    </method>
     5193
     5194  </interface>
     5195
     5196  <!--
     5197  // IVirtualDiskImage
     5198  /////////////////////////////////////////////////////////////////////////
     5199  -->
     5200
     5201  <interface
     5202     name="IVirtualDiskImage" extends="$unknown"
     5203     uuid="a8265b5a-0d20-4a46-a02f-65693a4e8239"
     5204     wsmap="managed"
     5205     >
     5206
     5207    <desc>
     5208
     5209      The IVirtualDiskImage interface represents <link to="IHardDisk">virtual
     5210      hard disks</link> that use virtual disk image files to store hard disk
     5211      data.
     5212
     5213      Hard disks using virtual disk images can be either opened using
     5214      <link to="IVirtualBox::openVirtualDiskImage()"/> or created from
     5215      scratch using <link to="IVirtualBox::createHardDisk()"/>.
     5216
     5217      Objects that support this interface also support the
     5218      <link to="IHardDisk"/> interface.
     5219
     5220      When a new hard disk object is created from scatch, an image file for it
     5221      is not automatically created. To do it, you need to specify a
     5222      valid <link to="#filePath">file path</link>, and call
     5223      <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
     5224      When it is done, the hard disk object can be registered by calling
     5225      <link to="IVirtualBox::registerHardDisk()"/> and then
     5226      <link to="IMachine::attachHardDisk()">attached</link> to
     5227      virtual machines.
     5228
     5229      The <link to="IHardDisk::description">description</link> of the
     5230      Virtual Disk Image is stored in the image file. For this reason,
     5231      changing the value of this property requires the hard disk to be
     5232      <link to="IHardDisk::accessible">accessible</link>. The description
     5233      of a registered hard disk can be changed only if a virtual machine
     5234      using it is not running.
     5235
     5236    </desc>
     5237
     5238    <attribute name="filePath" type="wstring">
     5239      <desc>
     5240
     5241        Full file name of the virtual disk image of this hard disk. For
     5242        newly created hard disk objects, this value is <tt>null</tt>.
     5243
     5244        When assigning a new path, it can be absolute (full path) or
     5245        relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
     5246          home directory</link>. If only a file name without any path is
     5247        given, the <link to="ISystemProperties::defaultVDIFolder">
     5248          default VDI folder</link> will be used as a path to the image
     5249        file.
     5250
     5251        When reading this propery, a full path is always returned.
     5252
     5253        <note>
     5254          This property cannot be changed when <link to="#created"/>
     5255          returns <tt>true</tt>. In this case, the specified file name can be
     5256          absolute (full path) or relative to
     5257          the <link to="IVirtualBox::homeFolder"> VirtualBox home
     5258          directory</link>.  If only a file name without any path is given,
     5259          the <link to="ISystemProperties::defaultVDIFolder"> default VDI
     5260          folder</link> will be used as a path to the image file.
     5261        </note>
     5262
     5263      </desc>
     5264    </attribute>
     5265
     5266    <attribute name="created" type="boolean" readonly="yes">
     5267      <desc>
     5268
     5269        Whether the virual disk image is created or not. For newly
     5270        created hard disk objects or after a successful invocation of
     5271        <link to="#deleteImage()"/>, this value is <tt>false</tt> until
     5272        <link to="#createFixedImage()"/> or <link
     5273                                               to="#createDynamicImage()"/> is called.
     5274
     5275      </desc>
     5276    </attribute>
     5277
     5278    <method name="createDynamicImage">
     5279
     5280      <desc>
     5281
     5282        Starts creating a dymically expanding hard disk image in the
     5283        background. The previous image associated with this object, if
     5284        any, must be deleted using <link to="#deleteImage"/>, otherwise
     5285        the operation will fail.
     5286
     5287        <note>After the returned progress object reports that the
     5288          operation is complete, this hard disk object can be
     5289          <link to="IVirtualBox::registerHardDisk()">registered</link>
     5290          within this VirtualBox installation.</note>
     5291
     5292      </desc>
     5293
     5294      <param name="size" type="unsigned long long" dir="in">
     5295        <desc>Maximum logical size of the hard disk in megabytes.</desc>
     5296      </param>
     5297      <param name="progress" type="IProgress" dir="return">
     5298        <desc>Progress object to track the operation completion.</desc>
     5299      </param>
     5300
     5301    </method>
     5302
     5303    <method name="createFixedImage">
     5304      <desc>
     5305
     5306        Starts creating a fixed-size hard disk image in the background.  The
     5307        previous image, if any, must be deleted using
     5308        <link to="#deleteImage"/>, otherwise the operation will fail.
     5309
     5310        <note>
     5311          After the returned progress object reports that the
     5312          operation is complete, this hard disk object can be
     5313          <link to="IVirtualBox::registerHardDisk()">registered</link>
     5314          within this VirtualBox installation.
     5315        </note>
     5316
     5317      </desc>
     5318
     5319      <param name="size" type="unsigned long long" dir="in">
     5320        <desc>Logical size of the hard disk in megabytes.</desc>
     5321      </param>
     5322      <param name="progress" type="IProgress" dir="return">
     5323        <desc>Progress object to track the operation completion.</desc>
     5324      </param>
     5325
     5326    </method>
     5327
     5328    <method name="deleteImage">
     5329      <desc>
     5330
     5331        Deletes the existing hard disk image. The hard disk must not be
     5332        registered within this VirtualBox installation, otherwise the
     5333        operation will fail.
     5334
     5335        <note>
     5336          After this operation succeeds, it will be impossible to
     5337          register the hard disk until the image file is created
     5338          again.
     5339        </note>
     5340
     5341        <note>
     5342          This operation is valid only for non-differencing hard disks, after
     5343          they are unregistered using
     5344          <link to="IVirtualBox::unregisterHardDisk()"/>.
     5345        </note>
     5346
     5347      </desc>
     5348    </method>
     5349
     5350  </interface>
     5351
     5352  <!--
     5353  // IISCSIHardDisk
     5354  /////////////////////////////////////////////////////////////////////////
     5355  -->
     5356
     5357  <interface
     5358     name="IISCSIHardDisk" extends="$unknown"
     5359     uuid="003f6ca9-3257-4ef9-99c9-c66ce44576cb"
     5360     wsmap="managed"
     5361     >
     5362
     5363    <desc>
     5364
     5365      The IISCSIHardDisk interface represents <link to="IHardDisk">virtual
     5366      hard disks</link> that use the Internet SCSI (iSCSI) protocol to store
     5367      hard disk data on remote machines.
     5368
     5369      iSCSI hard disks can be created using
     5370      <link to="IVirtualBox::createHardDisk()"/>. When a new hard disk object
     5371      is created, all its properties are uninitialized. After you assign some
     5372      meaningful values to them, the hard disk object can be registered by
     5373      calling <link to="IVirtualBox::registerHardDisk()"/> and
     5374      then <link to="IMachine::attachHardDisk()">attached</link> to virtual
     5375      machines.
     5376
     5377      Objects that support this interface also support the
     5378      <link to="IHardDisk"/> interface.
     5379
     5380      The <link to="IHardDisk::description">description</link>
     5381      of the iSCSI hard disk is stored in the VirtualBox
     5382      configuration file, so it can be changed (at appropriate
     5383      times) even when
     5384      <link to="IHardDisk::accessible">accessible</link> returns
     5385      <tt>false</tt>.  However, the hard disk must not be
     5386      attached to a running virtual machine.
     5387
     5388      <note>
     5389        In the current imlementation, the type of all iSCSI hard disks
     5390        is <link to="HardDiskType::WritethroughHardDisk">Writethrough</link>
     5391        and cannot be changed.
     5392      </note>
     5393
     5394    </desc>
     5395
     5396    <attribute name="server" type="wstring">
     5397      <desc>
     5398
     5399        iSCSI Server name (either a host name or an IP address). For
     5400        newly created hard disk objects, this value is <tt>null</tt>.
     5401
     5402      </desc>
     5403    </attribute>
     5404
     5405    <attribute name="port" type="unsigned short">
     5406      <desc>
     5407
     5408        iSCSI Server port. For newly created hard disk objects, this
     5409        value is <tt>0</tt>, which means the default port.
     5410
     5411      </desc>
     5412    </attribute>
     5413
     5414    <attribute name="target" type="wstring">
     5415      <desc>
     5416
     5417        iSCSI target name. For newly created hard disk objects, this
     5418        value is <tt>null</tt>.
     5419
     5420      </desc>
     5421    </attribute>
     5422
     5423    <attribute name="lun" type="unsigned long long">
     5424      <desc>
     5425
     5426        Logical unit number for this iSCSI disk. For newly created hard
     5427        disk objects, this value is <tt>0</tt>.
     5428
     5429      </desc>
     5430    </attribute>
     5431
     5432    <attribute name="userName" type="wstring">
     5433      <desc>
     5434
     5435        User name for accessing this iSCSI disk. For newly created hard
     5436        disk objects, this value is <tt>null</tt>.
     5437
     5438      </desc>
     5439    </attribute>
     5440
     5441    <attribute name="password" type="wstring">
     5442      <desc>
     5443
     5444        User password for accessing this iSCSI disk. For newly created
     5445        hard disk objects, this value is <tt>null</tt>.
     5446
     5447      </desc>
     5448    </attribute>
     5449
     5450  </interface>
     5451
     5452  <!--
     5453  // IVMDKImage
     5454  /////////////////////////////////////////////////////////////////////////
     5455  -->
     5456
     5457  <interface
     5458     name="IVMDKImage" extends="$unknown"
     5459     uuid="178398f5-8559-4fee-979e-420af5b53eef"
     5460     wsmap="managed"
     5461     >
     5462    <desc>
     5463
     5464      The IVMDKImage interface represents <link to="IHardDisk">virtual hard
     5465      disks</link> that use VMware Virtual Machine Disk image files to store
     5466      hard disk data.
     5467
     5468      Hard disks using VMDK images can be either opened using
     5469      <link to="IVirtualBox::openHardDisk()"/> or created from
     5470      scratch using <link to="IVirtualBox::createHardDisk()"/>.
     5471
     5472      Objects that support this interface also support the
     5473      <link to="IHardDisk"/> interface.
     5474
     5475      When a new hard disk object is created from scatch, an image file for it
     5476      is not automatically created. To do it, you need to specify a
     5477      valid <link to="#filePath">file path</link>, and call
     5478      <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
     5479      When it is done, the hard disk object can be registered by calling
     5480      <link to="IVirtualBox::registerHardDisk()"/> and then
     5481      <link to="IMachine::attachHardDisk()">attached</link> to
     5482      virtual machines.
     5483
     5484      The <link to="IHardDisk::description">description</link>
     5485      of the VMDK hard disk is stored in the VirtualBox
     5486      configuration file, so it can be changed (at appropriate
     5487      times) even when
     5488      <link to="IHardDisk::accessible">accessible</link> returns
     5489      <tt>false</tt>.  However, the hard disk must not be
     5490      attached to a running virtual machine.
     5491
     5492      <note>
     5493        In the current imlementation, the type of all VMDK hard disks
     5494        is <link to="HardDiskType::WritethroughHardDisk">Writethrough</link>
     5495        and cannot be changed.
     5496      </note>
     5497
     5498    </desc>
     5499
     5500    <attribute name="filePath" type="wstring">
     5501      <desc>
     5502
     5503        Full file name of the VMDK image of this hard disk. For
     5504        newly created hard disk objects, this value is <tt>null</tt>.
     5505
     5506        When assigning a new path, it can be absolute (full path) or relative
     5507        to the <link to="IVirtualBox::homeFolder"> VirtualBox home
     5508        directory</link>. If only a file name without any path is given,
     5509        the <link to="ISystemProperties::defaultVDIFolder"> default VDI
     5510        folder</link> will be used as a path to the image file.
     5511
     5512        When reading this propery, a full path is always returned.
     5513
     5514        <note>
     5515          This property cannot be changed when <link to="#created"/>
     5516          returns <tt>true</tt>. In this case, the specified file name can be
     5517          absolute (full path) or relative to
     5518          the <link to="IVirtualBox::homeFolder"> VirtualBox home
     5519          directory</link>.  If only a file name without any path is given,
     5520          the <link to="ISystemProperties::defaultVDIFolder"> default VDI
     5521          folder</link> will be used as a path to the image file.
     5522        </note>
     5523
     5524      </desc>
     5525    </attribute>
     5526
     5527    <attribute name="created" type="boolean" readonly="yes">
     5528      <desc>
     5529
     5530        Whether the virual disk image is created or not. For newly created
     5531        hard disk objects or after a successful invocation of
     5532        <link to="#deleteImage()"/>, this value is <tt>false</tt> until
     5533        <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>
     5534        is called.
     5535
     5536      </desc>
     5537    </attribute>
     5538
     5539    <method name="createDynamicImage">
     5540
     5541      <desc>
     5542
     5543        Starts creating a dymically expanding hard disk image in the
     5544        background. The previous image associated with this object, if
     5545        any, must be deleted using <link to="#deleteImage"/>, otherwise
     5546        the operation will fail.
     5547
     5548        <note>
     5549          After the returned progress object reports that the
     5550          operation is complete, this hard disk object can be
     5551          <link to="IVirtualBox::registerHardDisk()">registered</link> within
     5552          this VirtualBox installation.
     5553        </note>
     5554
     5555      </desc>
     5556
     5557      <param name="size" type="unsigned long long" dir="in">
     5558        <desc>Maximum logical size of the hard disk in megabytes.</desc>
     5559      </param>
     5560      <param name="progress" type="IProgress" dir="return">
     5561        <desc>Progress object to track the operation completion.</desc>
     5562      </param>
     5563
     5564    </method>
     5565
     5566    <method name="createFixedImage">
     5567      <desc>
     5568
     5569        Starts creating a fixed-size hard disk image in the background.  The
     5570        previous image, if any, must be deleted using
     5571        <link to="#deleteImage"/>, otherwise the operation will fail.
     5572
     5573        <note>
     5574          After the returned progress object reports that the
     5575          operation is complete, this hard disk object can be
     5576          <link to="IVirtualBox::registerHardDisk()">registered</link> within
     5577          this VirtualBox installation.
     5578        </note>
     5579
     5580      </desc>
     5581
     5582      <param name="size" type="unsigned long long" dir="in">
     5583        <desc>Logical size of the hard disk in megabytes.</desc>
     5584      </param>
     5585      <param name="progress" type="IProgress" dir="return">
     5586        <desc>Progress object to track the operation completion.</desc>
     5587      </param>
     5588
     5589    </method>
     5590
     5591    <method name="deleteImage">
     5592      <desc>
     5593
     5594        Deletes the existing hard disk image. The hard disk must not be
     5595        registered within this VirtualBox installation, otherwise the
     5596        operation will fail.
     5597
     5598        <note>
     5599          After this operation succeeds, it will be impossible to register the
     5600          hard disk until the image file is created again.
     5601        </note>
     5602
     5603        <note>
     5604          This operation is valid only for non-differencing hard disks, after
     5605          they are unregistered using
     5606          <link to="IVirtualBox::unregisterHardDisk()"/>.
     5607        </note>
     5608
     5609      </desc>
     5610    </method>
     5611
     5612  </interface>
     5613
     5614  <!--
     5615  // IDVDImage
     5616  /////////////////////////////////////////////////////////////////////////
     5617  -->
     5618
     5619  <enumerator
     5620     name="IDVDImageEnumerator" type="IDVDImage"
     5621     uuid="9BE77C8D-E1BE-4bf2-A67B-B4DD3D2B0F28"
     5622     />
     5623
     5624  <collection
     5625     name="IDVDImageCollection" type="IDVDImage"
     5626     enumerator="IDVDImageEnumerator"
     5627     uuid="AE7053FA-ADD2-4ea4-AFCF-24D5F8DDED64"
     5628     readonly="yes"
     5629     >
     5630    <method name="findByPath">
     5631      <desc>
     5632        Searches this collection for a DVD image with the given disk path.
     5633        <note>
     5634          The method returns an error if the given name does not
     5635          correspond to any DVD image in the collection.
     5636        </note>
     5637      </desc>
     5638      <param name="path" type="wstring" dir="in">
     5639        <desc>Name of the DVD image's file system location.</desc>
     5640      </param>
     5641      <param name="image" type="IDVDImage" dir="return">
     5642        <desc>Found DVD image object</desc>
     5643      </param>
     5644    </method>
     5645  </collection>
     5646
     5647  <interface
     5648     name="IDVDImage" extends="$unknown"
     5649     uuid="140FFF03-E479-4194-8562-ABC4F8171009"
     5650     wsmap="managed"
     5651     >
     5652    <desc>
     5653
     5654      The IDVDImage interface represents a file containing the image
     5655      of the DVD or CD disk.
     5656
     5657      <h3>Image Accessibility</h3>
     5658
     5659      The <link to="#accessible"/> attribute of the image object
     5660      defines the accessibility state of the image file. If the
     5661      value of this attribute is <tt>false</tt> then some image
     5662      attributes may contain invalid or outdated values (for example, the
     5663      the image file size) until a new accessibility
     5664      check is done that returns <tt>true</tt>.
     5665
     5666      <note>
     5667        Because of the possible slowness of the accessibility check,
     5668        it is not implicitly performed upon the VirtualBox server startup
     5669        (to prevent the application freeze). In partcular, this means that
     5670        if you try to read image properties that depend on the
     5671        accessibility state without first reading the value of the
     5672        <link to="#accessible"/> attribute and ensuring it's value is
     5673        <tt>true</tt>, you will get wrong (zero) values.
     5674      </note>
     5675
     5676    </desc>
     5677    <attribute name="id" type="uuid" readonly="yes">
     5678      <desc>UUID of the CD/DVD image.</desc>
     5679    </attribute>
     5680
     5681    <attribute name="filePath" type="wstring" readonly="yes">
     5682      <desc>Full file name of the CD/DVD image.</desc>
     5683    </attribute>
     5684
     5685    <attribute name="accessible" type="boolean" readonly="yes">
     5686      <desc>
     5687
     5688        Whether the CD/DVD image is currently accessible or not.
     5689        The image, for example, can be unaccessible if it is placed
     5690        on a network share that is not available by the time
     5691        this property is read.
     5692
     5693        The accessibility check is performed automatically every time
     5694        this attribute is read. You should keep it in mind that this check
     5695        may be slow and can block the calling thread for a long time (for
     5696        example, if the network share where the image is located is down).
     5697
     5698        The following attributes of the image object are considered
     5699        to be invalid when this attribute is <tt>false</tt>:
     5700        <ul>
     5701          <li><link to="#size"/></li>
     5702        </ul>
     5703
     5704      </desc>
     5705    </attribute>
     5706
     5707    <attribute name="size" type="unsigned long long" readonly="yes">
     5708      <desc>Size of the ISO image in bytes.</desc>
     5709    </attribute>
     5710
     5711  </interface>
     5712
     5713
     5714  <!--
     5715  // IDVDDrive
     5716  /////////////////////////////////////////////////////////////////////////
     5717  -->
     5718
     5719  <enum
     5720     name="DriveState"
     5721     uuid="cb7233b7-c519-42a5-8310-1830953cacbc"
     5722     >
     5723    <const name="InvalidDriveState"  value="0"/>
     5724    <const name="NotMounted"         value="1"/>
     5725    <const name="ImageMounted"       value="2"/>
     5726    <const name="HostDriveCaptured"  value="3"/>
     5727  </enum>
     5728
     5729  <interface
     5730     name="IDVDDrive" extends="$unknown"
     5731     uuid="d9bd101a-8079-4fb9-bad1-31bf32482b75"
     5732     wsmap="managed"
     5733     >
     5734    <attribute name="state" type="DriveState" readonly="yes">
     5735      <desc>Current drive state.</desc>
     5736    </attribute>
     5737
     5738    <attribute name="passthrough" type="boolean">
     5739      <desc>
     5740        When a host drive is mounted and passthrough is enabled
     5741        the guest will be able to directly send SCSI commands to
     5742        the host drive. This enables the guest to use CD/DVD writers
     5743        but is potentially dangerous.
     5744      </desc>
     5745    </attribute>
     5746
     5747    <method name="mountImage">
     5748      <desc>Mounts the specified image.</desc>
     5749      <param name="imageId" type="uuid" dir="in"/>
     5750    </method>
     5751
     5752    <method name="captureHostDrive">
     5753      <desc>Captures the specified host drive.</desc>
     5754      <param name="drive" type="IHostDVDDrive" dir="in"/>
     5755    </method>
     5756
     5757    <method name="unmount">
     5758      <desc>Unmounts the currently mounted image/device.</desc>
     5759    </method>
     5760
     5761    <method name="getImage">
     5762      <desc>Gets the currently mounted image ID.</desc>
     5763      <param name="image" type="IDVDImage" dir="return"/>
     5764    </method>
     5765
     5766    <method name="getHostDrive">
     5767      <desc>Gets the currently mounted image ID.</desc>
     5768      <param name="drive" type="IHostDVDDrive" dir="return"/>
     5769    </method>
     5770
     5771  </interface>
     5772
     5773  <!--
     5774  // IFloppyImage
     5775  /////////////////////////////////////////////////////////////////////////
     5776  -->
     5777
     5778  <enumerator
     5779     name="IFloppyImageEnumerator" type="IFloppyImage"
     5780     uuid="902C4089-76B7-41f1-91E8-49A261A28A2C"
     5781     />
     5782
     5783  <collection
     5784     name="IFloppyImageCollection" type="IFloppyImage"
     5785     enumerator="IFloppyImageEnumerator"
     5786     uuid="327A8928-8572-446e-AD9A-18FE30E81F3F"
     5787     readonly="yes">
     5788    <method name="findByPath">
     5789      <desc>
     5790        Searches this collection for a floppy image with the given disk path.
     5791        <note>
     5792          The method returns an error if the given name does not
     5793          correspond to any floppy image in the collection.
     5794        </note>
     5795      </desc>
     5796      <param name="path" type="wstring" dir="in">
     5797        <desc>Name of the floppy image's file system location.</desc>
     5798      </param>
     5799      <param name="image" type="IFloppyImage" dir="return">
     5800        <desc>Found Floppy image object</desc>
     5801      </param>
     5802    </method>
     5803  </collection>
     5804
     5805  <interface
     5806     name="IFloppyImage" extends="$unknown"
     5807     uuid="CC696755-EA98-4ffe-9DC5-C003047034AB"
     5808     wsmap="managed"
     5809     >
     5810    <desc>
     5811
     5812      The IFloppyImage interface represents a file containing the image
     5813      of a floppy disk.
     5814
     5815      <h3>Image Accessibility</h3>
     5816
     5817      The <link to="#accessible"/> attribute of the image object
     5818      defines the accessibility state of the image file. If the
     5819      value of this attribute is <tt>false</tt> then some image
     5820      attributes may contain invalid or outdated values (for example, the
     5821      the image file size) until a new accessibility
     5822      check is done that returns <tt>true</tt>.
     5823
     5824      <note>
     5825        Because of the possible slowness of the accessibility check,
     5826        it is not implicitly performed upon the VirtualBox server startup
     5827        (to prevent the application freeze). In partcular, this means that
     5828        if you try to read image properties that depend on the
     5829        accessibility state without first reading the value of the
     5830        <link to="#accessible"/> attribute and ensuring it's value is
     5831        <tt>true</tt>, you will get wrong (zero) values.
     5832      </note>
     5833
     5834    </desc>
     5835    <attribute name="id" type="uuid" readonly="yes">
     5836      <desc>UUID of the floppy image.</desc>
     5837    </attribute>
     5838
     5839    <attribute name="filePath" type="wstring" readonly="yes">
     5840      <desc>Full file name of the floppy image.</desc>
     5841    </attribute>
     5842
     5843    <attribute name="accessible" type="boolean" readonly="yes">
     5844      <desc>
     5845
     5846        Whether the floppy image is currently accessible or not.
     5847        The image, for example, can be unaccessible if it is placed
     5848        on a network share that is not available by the time
     5849        this property is read.
     5850
     5851        The accessibility check is performed automatically every time
     5852        this attribute is read. You should keep it in mind that this check
     5853        may be slow and can block the calling thread for a long time (for
     5854        example, if the network share where the image is located is down).
     5855
     5856        The following attributes of the image object are considered
     5857        to be invalid when this attribute is <tt>false</tt>:
     5858        <ul>
     5859          <li><link to="#size"/></li>
     5860        </ul>
     5861
     5862      </desc>
     5863    </attribute>
     5864
     5865    <attribute name="size" type="unsigned long" readonly="yes">
     5866      <desc>Size of the floppy image in bytes.</desc>
     5867    </attribute>
     5868
     5869  </interface>
     5870
     5871
     5872  <!--
     5873  // IFloppyDrive
     5874  /////////////////////////////////////////////////////////////////////////
     5875  -->
     5876
     5877  <interface
     5878     name="IFloppyDrive" extends="$unknown"
     5879     uuid="E9318F71-78D2-4b00-863C-B7CB0030A2D9"
     5880     wsmap="managed"
     5881     >
     5882    <attribute name="enabled" type="boolean">
     5883      <desc>
     5884        Flag whether the floppy drive is enabled. If it is disabled,
     5885        the floppy drive will not be reported to the guest.
     5886      </desc>
     5887    </attribute>
     5888
     5889    <attribute name="state" type="DriveState" readonly="yes">
     5890      <desc>Current drive state.</desc>
     5891    </attribute>
     5892
     5893    <method name="mountImage">
     5894      <desc>Mounts the specified image.</desc>
     5895      <param name="imageId" type="uuid" dir="in"/>
     5896    </method>
     5897
     5898    <method name="captureHostDrive">
     5899      <desc>Captures the specified host drive.</desc>
     5900      <param name="drive" type="IHostFloppyDrive" dir="in"/>
     5901    </method>
     5902
     5903    <method name="unmount">
     5904      <desc>Unmounts the currently mounted image/device.</desc>
     5905    </method>
     5906
     5907    <method name="getImage">
     5908      <desc>Gets the currently mounted image ID.</desc>
     5909      <param name="image" type="IFloppyImage" dir="return"/>
     5910    </method>
     5911
     5912    <method name="getHostDrive">
     5913      <desc>Gets the currently mounted image ID.</desc>
     5914      <param name="drive" type="IHostFloppyDrive" dir="return"/>
     5915    </method>
     5916
     5917  </interface>
     5918
     5919
     5920  <!--
     5921  // IKeyboard
     5922  /////////////////////////////////////////////////////////////////////////
     5923  -->
     5924
     5925  <interface
     5926     name="IKeyboard" extends="$unknown"
     5927     uuid="FD443EC1-000A-4F5B-9282-D72760A66916"
     5928     wsmap="managed"
     5929     >
     5930    <method name="putScancode">
     5931      <desc>Sends a scancode to the keyboard.</desc>
     5932      <param name="scancode" type="long" dir="in"/>
     5933    </method>
     5934
     5935    <method name="putScancodes">
     5936      <desc>Sends an array of scancode to the keyboard.</desc>
     5937      <param name="scancodes" type="long" dir="in" array="count"/>
     5938      <param name="count" type="unsigned long" dir="in"/>
     5939      <param name="codesStored" type="unsigned long" dir="return"/>
     5940    </method>
     5941
     5942    <method name="putCAD">
     5943      <desc>Sends the Ctrl-Alt-Del sequence to the keyboard.</desc>
     5944    </method>
     5945
     5946  </interface>
     5947
     5948
     5949  <!--
     5950  // IMouse
     5951  /////////////////////////////////////////////////////////////////////////
     5952  -->
     5953
     5954  <enum
     5955     name="MouseButtonState"
     5956     uuid="03131722-2EC5-4173-9794-0DACA46673EF"
     5957     >
     5958    <const name="LeftButton"        value="0x01"/>
     5959    <const name="RightButton"       value="0x02"/>
     5960    <const name="MiddleButton"      value="0x04"/>
     5961    <const name="WheelUp"           value="0x08"/>
     5962    <const name="WheelDown"         value="0x10"/>
     5963    <const name="MouseStateMask"    value="0x1F"/>
     5964  </enum>
     5965
     5966  <interface
     5967     name="IMouse" extends="$unknown"
     5968     uuid="FD443EC1-0006-4F5B-9282-D72760A66916"
     5969     wsmap="managed"
     5970     >
     5971    <desc>
     5972      The IMouse interface represents a virtual mouse device.
     5973    </desc>
     5974
     5975    <attribute name="absoluteSupported" type="boolean" readonly="yes">
     5976      <desc>
     5977        Whether the guest OS supports absolute mouse pointer positioning
     5978        or not.
     5979        <note>
     5980          VirtualBox Guest Tools need to be installed to the guest OS
     5981          in order to enable absolute mouse positioning support.
     5982          You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
     5983          callback to be instantly informed about changes of this attribute
     5984          during virtual machine execution.
     5985        </note>
     5986        <see><link to="#putMouseEventAbsolute"/></see>
     5987      </desc>
     5988    </attribute>
     5989
     5990    <method name="putMouseEvent">
     5991      <desc>
     5992        Initiates a mouse event using relative pointer movements
     5993        along x and y axis.
     5994      </desc>
     5995
     5996      <param name="dx" type="long" dir="in">
     5997        <desc>
     5998          Amout of pixels the mouse should move to the right.
     5999          Negative values move the mouse to the left.
    44646000        </desc>
    4465 
    4466         <attribute name="id" type="uuid" readonly="yes">
    4467             <desc>UUID of the snapshot.</desc>
    4468         </attribute>
    4469 
    4470         <attribute name="name" type="wstring">
    4471             <desc>Short name of the snapshot.</desc>
    4472         </attribute>
    4473 
    4474         <attribute name="description" type="wstring">
    4475             <desc>Optional description of the snapshot.</desc>
    4476         </attribute>
    4477 
    4478         <attribute name="timeStamp" type="long long" readonly="yes">
    4479             <desc>
    4480                 Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
    4481             </desc>
    4482         </attribute>
    4483 
    4484         <attribute name="online" type="boolean" readonly="yes">
    4485             <desc>
    4486                 <tt>true</tt> if this snapshot is an online snapshot and
    4487                 <tt>false</tt> otherwise.
    4488 
    4489                 <note>
    4490                     When this attribute is <tt>true</tt>, the
    4491                     <link to="IMachine::stateFilePath"/> attribute of the
    4492                     <link to="#machine"/> object associated with this snapshot
    4493                     will point to the saved state file. Otherwise, it will be
    4494                     <tt>null</tt>.
    4495                 </note>
    4496             </desc>
    4497         </attribute>
    4498 
    4499         <attribute name="machine" type="IMachine" readonly="yes">
    4500             <desc>
    4501                 Virtual machine this snapshot is taken on. This object
    4502                 stores all settings the machine had when taking this snapshot.
    4503                 <note>
    4504                     The returned machine object is immutable, i.e. no
    4505                     any settings can be changed.
    4506                 </note>
    4507             </desc>
    4508         </attribute>
    4509 
    4510         <attribute name="parent" type="ISnapshot" readonly="yes">
    4511             <desc>
    4512                 Parent snapshot (a snapshot this one is based on).
    4513                 <note>
    4514                     It's not an error to read this attribute on a snapshot
    4515                     that doesn't have a parent -- a null object will be
    4516                     returned to indicate this.
    4517                 </note>
    4518             </desc>
    4519         </attribute>
    4520 
    4521         <attribute name="children" type="ISnapshotCollection" readonly="yes">
    4522             <desc>
    4523                 Child snapshots (all snapshots having this one as a parent).
    4524                 <note>
    4525                     In the current implementation, there can be only one
    4526                     child snapshot, or no children at all, meaning this is the
    4527                     last (head) snapshot.
    4528                 </note>
    4529             </desc>
    4530         </attribute>
    4531 
    4532     </interface>
    4533 
    4534     <!--
    4535     // IHardDisk
    4536     /////////////////////////////////////////////////////////////////////////
    4537     -->
    4538 
    4539     <enum
    4540         name="HardDiskStorageType"
    4541         uuid="48138584-ad99-479d-a36f-eb82a7663685"
    4542     >
     6001      </param>
     6002      <param name="dy" type="long" dir="in">
    45436003        <desc>
    4544             Virtual hard disk storage type.
    4545             <see>IHardDisk</see>
     6004          Amout of pixels the mouse should move downwards.
     6005          Negative values move the mouse upwards.
    45466006        </desc>
    4547         <const name="VirtualDiskImage" value="0">
    4548             <desc>
    4549                 Virtual Disk Image, VDI (a regular file in the file
    4550                 system of the host OS, see <link to="IVirtualDiskImage"/>)
    4551             </desc>
    4552         </const>
    4553         <const name="ISCSIHardDisk" value="1">
    4554             <desc>
    4555                 iSCSI Remote Disk (a disk accessed via the Internet
    4556                 SCSI protocol over a TCP/IP network, see
    4557                 <link to="IISCSIHardDisk"/>)
    4558             </desc>
    4559         </const>
    4560         <const name="VMDKImage" value="2">
    4561             <desc>
    4562                 VMware Virtual Machine Disk image (a regular file in the file
    4563                 system of the host OS, see <link to="IVMDKImage"/>)
    4564             </desc>
    4565         </const>
    4566     </enum>
    4567 
    4568     <enum
    4569         name="HardDiskType"
    4570         uuid="a348fafd-a64e-4643-ba65-eb3896bd7e0a"
    4571     >
     6007      </param>
     6008      <param name="dz" type="long" dir="in">
    45726009        <desc>
    4573             Virtual hard disk type.
    4574             <see>IHardDisk</see>
     6010          Amount of mouse wheel moves.
     6011          Positive values describe clockwize wheel rotations,
     6012          negative values describe counterclockwise rotations.
    45756013        </desc>
    4576         <const name="NormalHardDisk" value="0">
    4577             <desc>
    4578                 Normal hard disk (attached directly or indirectly, preserved
    4579                 when taking snapshots).
    4580             </desc>
    4581         </const>
    4582         <const name="ImmutableHardDisk" value="1">
    4583             <desc>
    4584                 Immutable hard disk (attached indirectly, changes are wiped out
    4585                 after powering off the virtual machine).
    4586             </desc>
    4587         </const>
    4588         <const name="WritethroughHardDisk" value="2">
    4589             <desc>
    4590                 Write through hard disk (attached directly, ignored when
    4591                 taking snapshots).
    4592             </desc>
    4593         </const>
    4594     </enum>
    4595 
    4596     <interface
    4597         name="IHardDiskAttachment" extends="$unknown"
    4598         uuid="c0ffe596-21c6-4797-8d8a-b47b66881e7a"
    4599         wsmap="struct"
    4600     >
    4601         <attribute name="hardDisk" type="IHardDisk" readonly="yes">
    4602             <desc>Harddisk object this attachment is about.</desc>
    4603         </attribute>
    4604 
    4605         <attribute name="controller" type="DiskControllerType" readonly="yes">
    4606             <desc>Disk controller ID of this attachment.</desc>
    4607         </attribute>
    4608 
    4609         <attribute name="deviceNumber" type="long" readonly="yes">
    4610             <desc>Device number of the attachment.</desc>
    4611         </attribute>
    4612 
    4613     </interface>
    4614 
    4615     <enumerator
    4616         name="IHardDiskAttachmentEnumerator" type="IHardDiskAttachment"
    4617         uuid="9955e486-2f0b-432a-99e4-0ebbd338875e"
    4618     />
    4619 
    4620     <collection
    4621         name="IHardDiskAttachmentCollection" type="IHardDiskAttachment"
    4622         enumerator="IHardDiskAttachmentEnumerator"
    4623         uuid="8f727842-bb77-45d4-92de-4ec14bf613c9"
    4624         readonly="yes"
    4625     />
    4626 
    4627     <enumerator
    4628         name="IHardDiskEnumerator" type="IHardDisk"
    4629         uuid="b976f97b-cdb8-47e3-9860-084031cbd533"
    4630     />
    4631 
    4632     <collection
    4633         name="IHardDiskCollection" type="IHardDisk"
    4634         enumerator="IHardDiskEnumerator"
    4635         uuid="43EAC2BC-5C61-40fa-BC38-46DE2C7DB6BB"
    4636         readonly="yes"
    4637     />
    4638 
    4639     <interface
    4640         name="IHardDisk" extends="$unknown"
    4641         uuid="FD443EC1-000F-4F5B-9282-D72760A66916"
    4642         wsmap="managed"
    4643     >
     6014      </param>
     6015      <param name="buttonState" type="long" dir="in">
    46446016        <desc>
    4645             The IHardDisk interface represents a virtual hard disk drive
    4646             used by virtual machines.
    4647 
    4648             The virtual hard disk drive virtualizes the hard disk hardware and
    4649             looks like a regular hard disk inside the virtual machine and
    4650             the guest OS.
    4651 
    4652             <h3>Storage Types</h3>
    4653 
    4654             The <link to="HardDiskStorageType">storage type</link> of the
    4655             virtual hard disk determines where and how it stores its data
    4656             (sectors). Currently, the following storage types are supported:
    4657 
    4658             <ul>
    4659 
    4660                 <li><i>Virtual Disk Image (VDI)</i>, a regular file in the file
    4661                 system of the host OS (represented by the <link
    4662                 to="IVirtualDiskImage"/> interface). This file has a special
    4663                 format optimized so that unused sectors of data occupy much less
    4664                 space than on a physical hard disk.</li>
    4665 
    4666                 <li><i>iSCSI Remote Disk</i>, a disk accessed via the Internet
    4667                 SCSI protocol over a TCP/IP network link (represented by the
    4668                 <link to="IISCSIHardDisk"/> interface).</li>
    4669 
    4670                 <li><i>VMware VMDK Image</i>, a regular file in the file
    4671                 system of the host OS (represented by the <link
    4672                 to="IVMDKImage"/> interface).</li>
    4673 
    4674             </ul>
    4675 
    4676             The storage type of the particular hard disk object is indicated by
    4677             the <link to="#storageType"/> property.
    4678 
    4679             Each storage type is represented by its own interface (as shown
    4680             above), that allows to query and set properties and perform
    4681             operations specific to that storage type. When an IHardDisk object
    4682             reports it uses some particular storage type, it also guaranteed to
    4683             support the corresponding interface which you can query. And vice
    4684             versa, every object that supports a storage-specific interface, also
    4685             supports IHardDisk.
    4686 
    4687             <h3>Virtual Hard Disk Types</h3>
    4688 
    4689             The <link to="HardDiskType">type</link> of the virtual hard disk
    4690             determines how it is attached to the virtual machine when you call
    4691             <link to="IMachine::attachHardDisk()"/> and what happens to it when
    4692             a <link to="ISnapshot">snapshot</link> of the virtual machine is
    4693             taken.
    4694 
    4695             There are three types of virtual hard disks:
    4696 
    4697             <ul>
    4698                 <li><i>Normal</i></li>
    4699                 <li><i>Immutable</i></li>
    4700                 <li><i>Writethrough</i></li>
    4701             </ul>
    4702 
    4703             The virtual disk type is indicated by the <link to="#type"/>
    4704             property. Each of the above types is described in detail further
    4705             down.
    4706 
    4707             There is also a forth, "hidden" virtual disk type:
    4708             <i>Differencing</i>. It is "hidden" because you cannot directly
    4709             create hard disks of this type -- they are automatically created by
    4710             VirtualBox when necessary.
    4711 
    4712             <b>Differencing Hard Disks</b>
    4713 
    4714             Unlike disks of other types (that are similar to real hard disks),
    4715             the differencing hard disk does not store the full range of data
    4716             sectors. Instead, it stores only a subset of sectors of some other
    4717             disk that were changed since the differencing hard disk has been
    4718             created. Thus, every differencing hard disk has a parent hard disk
    4719             it is linked to, and represents the difference between the initial
    4720             and the current hard disk state. A differencing hard disk can be
    4721             linked to another differencing hard disk -- this way, differencing
    4722             hard disks can form a branch of changes. More over, a given virtual
    4723             hard disk can have more than one differencing hard disk linked to
    4724             it.
    4725 
    4726             A disk the differencing hard disk is linked to (or, in other
    4727             words, based on) is called a <i>parent</i> hard disk and is
    4728             accessible through the <link to="#parent"/> property. Similarly, all
    4729             existing differencing hard disks for a given parent hard disk are
    4730             called its <i>child</i> hard disks (and accessible through the <link
    4731             to="#children"/> property).
    4732 
    4733             All differencing hard disks use Virtual Disk Image files to store
    4734             changed sectors. They have the <link to="#type"/> property set to
    4735             Normal, but can be easily distinguished from normal hard disks using
    4736             the <link to="#parent"/> property: all differencing hard disks have
    4737             a parent, while all normal hard disks don't.
    4738 
    4739             When the virtual machine makes an attempt to read a sector that is
    4740             missing in a differencing hard disk, its parent is accessed to
    4741             resolve the sector in question. This process continues until the
    4742             sector is found, or until the root hard disk is encountered, which
    4743             always contains all sectors. As a consequence,
    4744 
    4745             <ul>
    4746 
    4747                 <li>The virtual hard disk geometry seen by the guest OS is
    4748                 always defined by the root hard disk.</li>
    4749 
    4750                 <li>All hard disks on a branch, up to the root, must be <link
    4751                 to="#accessible"/> for a given differencing hard disk in order
    4752                 to let it function properly when the virtual machine is
    4753                 running.</li>
    4754 
    4755             </ul>
    4756 
    4757             Differencing hard disks can be implicitly created by VirtualBox in
    4758             the following cases:
    4759 
    4760             <ul>
    4761 
    4762                 <li>When a hard disk is <i>indirectly</i> attached to the
    4763                 virtual machine using <link to="IMachine::attachHardDisk()"/>.
    4764                 In this case, all disk writes performed by the guest OS will go
    4765                 to the created diffferencing hard disk, as opposed to the
    4766                 <i>direct</i> attachment, where all changes are written to the
    4767                 attached hard disk itself.</li>
    4768 
    4769                 <li>When a <link to="ISnapshot">snapshot</link> of the virtual
    4770                 machine is taken. After that, disk writes to hard disks the
    4771                 differencing ones have been created for, will be directed to
    4772                 those differencing hard disks, to preserve the contents of the
    4773                 original disks.</li>
    4774 
    4775             </ul>
    4776 
    4777             Whether to create a differencing hard disk or not depends on the
    4778             type of the hard disk attached to the virtual machine. This is
    4779             explained below.
    4780 
    4781             Note that in the current implementation, only the
    4782             <link to="VirtualDiskImage"/> storage type is used to
    4783             represent differencing hard disks. In other words, all
    4784             differencing hard disks are <link to="IVirtualDiskImage"/>
    4785             objects.
    4786 
    4787             <b>Normal Hard Disks</b>
    4788 
    4789             Normal hard disks are the most commonly used virtual hard disk. A
    4790             normal hard disk is attached to the machine directly if it is not
    4791             already attached to some other machine. Otherwise, an attempt to
    4792             make an indirect attachment through a differencing hard disk will be
    4793             made. This attempt will fail if the hard disk is attached to a
    4794             virtual machine without snapshots (because it's impossible to create
    4795             a differencing hard disk based on a hard disk that is subject to
    4796             change).
    4797 
    4798             When an indirect attachment takes place, in the simplest case, where
    4799             the machine the hard disk is being attached to doesn't have
    4800             snapshots, the differencing hard disk will be based on the normal
    4801             hard disk being attached. Otherwise, the first (i.e. the most
    4802             recent) descendant of the given normal hard disk found in the
    4803             current snapshot branch (starting from the current snapshot and
    4804             going up to the root) will be actually used as a base.
    4805 
    4806             Note that when you detach an indirectly attached hard disk from the
    4807             machine, the created differencing hard disk image is simply
    4808             <b>deleted</b>, so <b>all changes are lost</b>. If you attach the
    4809             same disk again, a clean differencing disk will be created based on
    4810             the most recent child, as described above.
    4811 
    4812             When taking a snapshot, the contents of all normal hard disks (and
    4813             all differencing disks whose roots are normal hard disks) currently
    4814             attached to the virtual machine is preserved by creating
    4815             differencing hard disks based on them.
    4816 
    4817             <b>Immutable Hard Disks</b>
    4818 
    4819             Immutable hard disks can be used to provide a sort of read-only
    4820             access. An immutable hard disk is always attached indirectly. The
    4821             created differencing hard disk is automatically wiped out (recreated
    4822             from scratch) every time you power off the virtual machine. Thus,
    4823             the contents of the immutable disk remains unchanged between runs.
    4824 
    4825             Detaching an immutable hard disk deletes the differencing disk
    4826             created for it, with the same effect as in case with normal hard
    4827             disks.
    4828 
    4829             When taking a snapshot, the differencing part of the immutable
    4830             hard disk is cloned (i.e. copied to a separate Virtual Disk Image
    4831             file) without any changes. This is necessary to preserve the exact
    4832             virtual machine state when you create an online snapshot.
    4833 
    4834             <b>Writethrough Hard Disks</b>
    4835 
    4836             Hard disks of this type are always attached directly. This means
    4837             that every given writethrough hard disk can be attached only to one
    4838             virtual machine at a time.
    4839 
    4840             It is impossible to take a snapshot of a virtual machine with the
    4841             writethrough hard disk attached, because taking a snapshot implies
    4842             saving the execution state and preserving the contents of all hard
    4843             disks, but writethrough hard disks cannot be preserved. Preserving
    4844             hard disk contents is necessary to ensure the guest OS stored in the
    4845             snapshot will get the same hard disk state when restored, which is
    4846             especially important when it has open file handles or when there are
    4847             cached files and directories stored in memory.
    4848 
    4849             <h3>Creating, Opening and Registering Hard Disks</h3>
    4850 
    4851             Non-differencing hard disks are either created from scratch using
    4852             <link to="IVirtualBox::createHardDisk()"/> or opened from a VDI file
    4853             using <link to="IVirtualBox::openVirtualDiskImage()"/> (only for
    4854             hard disks using the VirtualDiskImage storage type). Once a hard
    4855             disk is created or opened, it needs to be registered using <link
    4856             to="IVirtualBox::registerHardDisk()"/> to make it available for
    4857             attaching to virtual machines. See the documentation of individual
    4858             interfaces for various storage types to get more information.
    4859 
    4860             Differencing hard disks are never created explicitly and cannot
    4861             be registered or unregistered; they are automatically registered
    4862             upon creation and deregistered when deleted.
    4863 
    4864             <h3>More about Indirect Hard Disk Attachments</h3>
    4865 
    4866             Normally, when you attach a hard disk to the virtual machine, and
    4867             then query the corresponding attachment using <link
    4868             to="IMachine::getHardDisk()"/> or <link
    4869             to="IMachine::hardDiskAttachments"/> you will get the same hard disk
    4870             object, whose UUID you passed earlier to <link
    4871             to="IMachine::attachHardDisk()"/>. However, when an indirect
    4872             attachment takes place, calling <link to="IMachine::getHardDisk()"/>
    4873             will return a differencing hard disk object, that is either based on
    4874             the attached hard disk or on another differencing hard disk, the
    4875             attached hard disk is eventually a root for (as described above). In
    4876             both cases the returned hard disk object is the object the virtual
    4877             machine actually uses to perform disk writes to.
    4878 
    4879             Regardless of whether the attachment is direct or indirect, the
    4880             <link to="#machineId"/> property of the attached disk will contain an
    4881             UUID of the machine object <link to="IMachine::attachHardDisk()"/>
    4882             has been called on.
    4883 
    4884             Note that both <link to="IMachine::attachHardDisk()"/> and <link
    4885             to="IMachine::detachHardDisk()"/> are <i>lazy</i> operations. In
    4886             particular, this means that when an indirect attachment is made,
    4887             differencing hard disks are not created until machine settings are
    4888             committed using <link to="IMachine::saveSettings()"/>. Similarly,
    4889             when a differencing hard disk is detached, it is not deleted until
    4890             <link to="IMachine::saveSettings()"/> is called. Calling <link
    4891             to="IMachine::discardSettings()"/> cancels all lazy attachments or
    4892             detachments made since the last commit and effectively restores the
    4893             previous set of hard disks.
    4894 
    4895             <h3>Hard Disk Accessibility</h3>
    4896 
    4897             The <link to="#accessible"/> attribute of the hard disk object
    4898             defines the accessibility state of the respective hard disk storage
    4899             (for example, the VDI file for IVirtualDiskImage objects). If the
    4900             value of this attribute is <tt>false</tt> then some hard disk
    4901             attributes may contain invalid or outdated values (for example, the
    4902             virtual or the actual hard disk size) until a new accessibility
    4903             check is done that returns <tt>true</tt> (see the attribute
    4904             description for more details).
    4905 
    4906             <note>
    4907             Because of the possible slowness of the accessibility check,
    4908             it is not implicitly performed upon the VirtualBox server startup
    4909             (to prevent the application freeze). In partcular, this means that
    4910             if you try to read hard disk properties that depend on the
    4911             accessibility state without first reading the value of the
    4912             <link to="#accessible"/> attribute and ensuring it's value is
    4913             <tt>true</tt>, you will get wrong (zero) values.
    4914             </note>
    4915 
     6017          The current state of mouse buttons. Every bit represents
     6018          a mouse button as follows:
     6019          <table>
     6020            <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
     6021            <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
     6022            <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
     6023          </table>
     6024          A value of <tt>1</tt> means the corresponding button is pressed.
     6025          otherwise it is released.
    49166026        </desc>
    4917 
    4918         <attribute name="id" type="uuid" readonly="yes">
    4919             <desc>
    4920 
    4921                 UUID of the hard disk. For newly created hard disk objects,
    4922                 this value is a randomly generated UUID.
    4923 
    4924             </desc>
    4925         </attribute>
    4926 
    4927         <attribute name="description" type="wstring">
    4928             <desc>
    4929 
    4930                 Optional description of the hard disk. For a newly created hard
    4931                 disk, this value is <tt>null</tt>.
    4932 
    4933                 <note>For some storage types, reading this property is
    4934                 meaningless when <link to="#accessible"/> is <tt>false</tt>.
    4935                 Also, you cannot assign it a new value in this case.</note>
    4936 
    4937             </desc>
    4938         </attribute>
    4939 
    4940         <attribute name="storageType" type="HardDiskStorageType" readonly="yes">
    4941             <desc>
    4942 
    4943                 Storage type of this hard disk.
    4944 
    4945                 Storage type is defined when you open or create a new hard disk
    4946                 object.
    4947 
    4948             </desc>
    4949         </attribute>
    4950 
    4951         <attribute name="location" type="wstring" readonly="yes">
    4952             <desc>
    4953 
    4954                 Storage location of this hard disk. The returned string serves
    4955                 for informational purposes only. To access detailed information
    4956                 about the storage, query the appropriate storage-specific
    4957                 interface.
    4958 
    4959             </desc>
    4960         </attribute>
    4961 
    4962         <attribute name="type" type="HardDiskType">
    4963             <desc>
    4964 
    4965                 Type (behavior) of this hard disk. For a newly created or opened
    4966                 hard disk, this value is <link
    4967                 to="HardDiskType::NormalHardDisk"/>.
    4968 
    4969                 <note>In the current implementation, this property can be
    4970                 changed only on an unregistered hard disk object. This may be
    4971                 changed later.</note>
    4972 
    4973             </desc>
    4974         </attribute>
    4975 
    4976         <attribute name="parent" type="IHardDisk" readonly="yes">
    4977             <desc>
    4978 
    4979                 Parent of this hard disk (a hard disk this one is directly based
    4980                 on).
    4981 
    4982                 Only differencing hard disks have parents, so a <tt>null</tt>
    4983                 object is returned for a hard disk of any other type.
    4984             </desc>
    4985         </attribute>
    4986 
    4987         <attribute name="children" type="IHardDiskCollection" readonly="yes">
    4988             <desc>
    4989 
    4990                 Children of this hard disk (all differencing hard disks for
    4991                 those this one is a parent). An empty collection is returned, if
    4992                 this hard disk doesn't have any children.
    4993 
    4994             </desc>
    4995         </attribute>
    4996 
    4997         <attribute name="root" type="IHardDisk" readonly="yes">
    4998             <desc>
    4999 
    5000                 Root hard disk of this hard disk. If this hard disk is a
    5001                 differencing hard disk, its root hard disk is the first disk on
    5002                 the branch. For all other types of hard disks, this property
    5003                 returns the hard disk object itself (i.e. the same object you
    5004                 read this property on).
    5005 
    5006             </desc>
    5007         </attribute>
    5008 
    5009         <attribute name="accessible" type="boolean" readonly="yes">
    5010             <desc>
    5011 
    5012                 Whether the hard disk storage is currently accessible or not.
    5013                 The storage, for example, can be unaccessible if it doesn't exist
    5014                 or if it is placed on a network resource that is not available
    5015                 by the time this attribute is read.
    5016 
    5017                 In the current implementation, the value of this property is
    5018                 also <tt>false</tt> if this hard disk is attached to a running
    5019                 virtual machine.
    5020 
    5021                 The accessibility check is performed automatically every time
    5022                 this attribute is read. You should keep it in mind that this check
    5023                 may be slow and can block the calling thread for a long time (for
    5024                 example, if the network resourse where the hard disk storage is
    5025                 located is down).
    5026 
    5027                 The following attributes of the hard disk object are considered
    5028                 to be invalid when this attribute is <tt>false</tt>:
    5029                 <ul>
    5030                 <li><link to="#size"/></li>
    5031                 <li><link to="#actualSize"/></li>
    5032                 </ul>
    5033                 Individual hard disk storage type interfaces may define
    5034                 additional attributes that depend on the accessibility state.
    5035             </desc>
    5036         </attribute>
    5037 
    5038         <attribute name="allAccessible" type="boolean" readonly="yes">
    5039             <desc>
    5040 
    5041                 Whether the whole hard disk branch, starting from this image and
    5042                 going through its ancestors up to the root, is accessible or
    5043                 not.
    5044 
    5045                 This property makes sense only for differencing hard disks. For
    5046                 all other types of hard disks it returns the same value as
    5047                 <link to="#accessible"/>.
    5048 
    5049             </desc>
    5050         </attribute>
    5051 
    5052         <attribute name="lastAccessError" type="wstring" readonly="yes">
    5053             <desc>
    5054 
    5055                 String describing the reason of inaccessibility of this hard
    5056                 disk after the last call to <link to="#accessible"/> that
    5057                 returned <tt>false</tt>. A <tt>null</tt> value of this property
    5058                 means that the last accessibility check returned <tt>true</tt>.
    5059 
    5060             </desc>
    5061         </attribute>
    5062 
    5063         <attribute name="size" type="unsigned long long" readonly="yes">
    5064             <desc>
    5065 
    5066                 Logical size of this hard disk (in megabytes), as reported to the
    5067                 guest OS running inside the vurtual machine this disk is
    5068                 attached to. The logical size is defined when the hard disk is
    5069                 created.
    5070 
    5071                 <note>Reading this property on a differencing hard disk will
    5072                 return the size of its root hard disk.</note>
    5073 
    5074                 <note>Reading this property is meaningless when
    5075                 <link to="#accessible"/> is <tt>false</tt></note>
    5076 
    5077             </desc>
    5078         </attribute>
    5079 
    5080         <attribute name="actualSize" type="unsigned long long" readonly="yes">
    5081             <desc>
    5082 
    5083                 Physical size of the storage used to store hard disk data (in
    5084                 bytes). This size is usually less than the logical size of the
    5085                 hard disk, depending on the storage type and on the size
    5086                 optimization method used for that storage.
    5087 
    5088                 <note>Reading this property is meaningless when
    5089                 <link to="#accessible"/> is <tt>false</tt></note>
    5090 
    5091             </desc>
    5092         </attribute>
    5093 
    5094         <attribute name="machineId" type="uuid" readonly="yes">
    5095             <desc>
    5096 
    5097                 UUID of the machine this hard disk is attached to (or a
    5098                 <tt>null</tt> UUID if it is not attached).
    5099 
    5100                 <note>Immutable hard disks are never attached directly, so this
    5101                 attribute is always <tt>null</tt> in this case.</note>
    5102 
    5103             </desc>
    5104         </attribute>
    5105 
    5106         <attribute name="snapshotId" type="uuid" readonly="yes">
    5107             <desc>
    5108 
    5109                 UUID of the <link to="ISnapshot">snapshot</link> this hard disk
    5110                 is associated with (or <tt>null</tt> UUID if it is not
    5111                 associated with any snapshot).
    5112 
    5113                 <note>This attribute is always <tt>null</tt> if <link
    5114                 to="#machineId"/> is <tt>null</tt>.</note>
    5115 
    5116                 <note>Writethrough hard disks are always attached directly and
    5117                 cannot be involved when taking snapshots, so this attribute is
    5118                 meaningless and therefore always <tt>null</tt>.</note>
    5119 
    5120             </desc>
    5121         </attribute>
    5122 
    5123         <method name="cloneToImage">
    5124 
    5125             <desc>
    5126 
    5127                 Starts creating a clone of this hard disk. The cloned hard disk
    5128                 will use the specified Virtual Disk Image file as a storage and
    5129                 will contain exactly the same sector data as the hard disk being
    5130                 cloned, except that a new UUID for the clone will be randomly
    5131                 generated.
    5132 
    5133                 The specified image file path can be absolute (full path) or
    5134                 relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
    5135                 home directory</link>. If only a file name without any path is
    5136                 given, the <link to="ISystemProperties::defaultVDIFolder">
    5137                 default VDI folder</link> will be used as a path to the image
    5138                 file.
    5139 
    5140                 It is an error to use the object returned in the @a image
    5141                 parameter until the returned @a progress object reports success.
    5142 
    5143                 <note>In the current implementation, only non-differencing hard
    5144                 disks can be cloned.</note>
    5145 
    5146             </desc>
    5147 
    5148             <param name="filePath" type="wstring" dir="in">
    5149                 <desc>Path to a file where to store the cloned hard disk.</desc>
    5150             </param>
    5151             <param name="image" type="IVirtualDiskImage" dir="out">
    5152                 <desc>Cloned hard disk object.</desc>
    5153             </param>
    5154             <param name="progress" type="IProgress" dir="return">
    5155                 <desc>Progress object to track the operation completion.</desc>
    5156             </param>
    5157 
    5158         </method>
    5159 
    5160     </interface>
    5161 
    5162     <!--
    5163     // IVirtualDiskImage
    5164     /////////////////////////////////////////////////////////////////////////
    5165     -->
    5166 
    5167     <interface
    5168         name="IVirtualDiskImage" extends="$unknown"
    5169         uuid="a8265b5a-0d20-4a46-a02f-65693a4e8239"
    5170         wsmap="managed"
    5171     >
    5172 
     6027      </param>
     6028    </method>
     6029
     6030    <method name="putMouseEventAbsolute">
     6031      <desc>
     6032        Positions the mouse pointer using absolute x and y coordinates.
     6033        These coordinates are expressed in pixels and
     6034        start from <tt>[1,1]</tt> which corresponds to the top left
     6035        corner of the virtual display.
     6036
     6037        <note>
     6038          This method will have effect only if absolute mouse
     6039          positioning is supported by the guest OS.
     6040        </note>
     6041
     6042        <see><link to="#absoluteSupported"/></see>
     6043      </desc>
     6044
     6045      <param name="x" type="long" dir="in">
    51736046        <desc>
    5174 
    5175             The IVirtualDiskImage interface represents <link
    5176             to="IHardDisk">virtual hard disks</link> that use virtual disk image
    5177             files to store hard disk data.
    5178 
    5179             Hard disks using virtual disk images can be either opened using
    5180             <link to="IVirtualBox::openVirtualDiskImage()"/> or created from
    5181             scratch using <link to="IVirtualBox::createHardDisk()"/>.
    5182 
    5183             Objects that support this interface also support the <link
    5184             to="IHardDisk"/> interface.
    5185 
    5186             When a new hard disk object is created from scatch, an image file
    5187             for it is not automatically created. To do it, you need to specify a
    5188             valid <link to="#filePath">file path</link>, and call <link
    5189             to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
    5190             When it is done, the hard disk object can be registered by calling
    5191             <link to="IVirtualBox::registerHardDisk()"/> and then
    5192             <link to="IMachine::attachHardDisk()">attached</link> to
    5193             virtual machines.
    5194 
    5195             The <link to="IHardDisk::description">description</link> of the
    5196             Virtual Disk Image is stored in the image file. For this reason,
    5197             changing the value of this property requires the hard disk to be
    5198             <link to="IHardDisk::accessible">accessible</link>. The description
    5199             of a registered hard disk can be changed only if a virtual machine
    5200             using it is not running.
    5201 
     6047          X coordinate of the pointer in pixels, starting from <tt>1</tt>.
    52026048        </desc>
    5203 
    5204         <attribute name="filePath" type="wstring">
    5205             <desc>
    5206 
    5207                 Full file name of the virtual disk image of this hard disk. For
    5208                 newly created hard disk objects, this value is <tt>null</tt>.
    5209 
    5210                 When assigning a new path, it can be absolute (full path) or
    5211                 relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
    5212                 home directory</link>. If only a file name without any path is
    5213                 given, the <link to="ISystemProperties::defaultVDIFolder">
    5214                 default VDI folder</link> will be used as a path to the image
    5215                 file.
    5216 
    5217                 When reading this propery, a full path is always returned.
    5218 
    5219                 <note>This property cannot be changed when <link to="#created"/>
    5220                 returns <tt>true</tt>. In this case, the specified file name can
    5221                 be absolute (full path) or relative to the <link
    5222                 to="IVirtualBox::homeFolder"> VirtualBox home directory</link>.
    5223                 If only a file name without any path is given, the <link
    5224                 to="ISystemProperties::defaultVDIFolder"> default VDI
    5225                 folder</link> will be used as a path to the image file.</note>
    5226 
    5227             </desc>
    5228         </attribute>
    5229 
    5230         <attribute name="created" type="boolean" readonly="yes">
    5231             <desc>
    5232 
    5233                 Whether the virual disk image is created or not. For newly
    5234                 created hard disk objects or after a successful invocation of
    5235                 <link to="#deleteImage()"/>, this value is <tt>false</tt> until
    5236                 <link to="#createFixedImage()"/> or <link
    5237                 to="#createDynamicImage()"/> is called.
    5238 
    5239             </desc>
    5240         </attribute>
    5241 
    5242         <method name="createDynamicImage">
    5243 
    5244             <desc>
    5245 
    5246                 Starts creating a dymically expanding hard disk image in the
    5247                 background. The previous image associated with this object, if
    5248                 any, must be deleted using <link to="#deleteImage"/>, otherwise
    5249                 the operation will fail.
    5250 
    5251                 <note>After the returned progress object reports that the
    5252                 operation is complete, this hard disk object can be
    5253                 <link to="IVirtualBox::registerHardDisk()">registered</link>
    5254                 within this VirtualBox installation.</note>
    5255 
    5256             </desc>
    5257 
    5258             <param name="size" type="unsigned long long" dir="in">
    5259                 <desc>Maximum logical size of the hard disk in megabytes.</desc>
    5260             </param>
    5261             <param name="progress" type="IProgress" dir="return">
    5262                 <desc>Progress object to track the operation completion.</desc>
    5263             </param>
    5264 
    5265         </method>
    5266 
    5267         <method name="createFixedImage">
    5268             <desc>
    5269 
    5270                 Starts creating a fixed-size hard disk image in the background.
    5271                 The previous image, if any, must be deleted using <link
    5272                 to="#deleteImage"/>, otherwise the operation will fail.
    5273 
    5274                 <note>After the returned progress object reports that the
    5275                 operation is complete, this hard disk object can be
    5276                 <link to="IVirtualBox::registerHardDisk()">registered</link>
    5277                 within this VirtualBox installation.</note>
    5278 
    5279             </desc>
    5280 
    5281             <param name="size" type="unsigned long long" dir="in">
    5282                 <desc>Logical size of the hard disk in megabytes.</desc>
    5283             </param>
    5284             <param name="progress" type="IProgress" dir="return">
    5285                 <desc>Progress object to track the operation completion.</desc>
    5286             </param>
    5287 
    5288         </method>
    5289 
    5290         <method name="deleteImage">
    5291             <desc>
    5292 
    5293                 Deletes the existing hard disk image. The hard disk must not be
    5294                 registered within this VirtualBox installation, otherwise the
    5295                 operation will fail.
    5296 
    5297                 <note>After this operation succeeds, it will be impossible to
    5298                 register the hard disk until the image file is created
    5299                 again.</note>
    5300 
    5301                 <note>This operation is valid only for non-differencing hard
    5302                 disks, after they are unregistered using <link
    5303                 to="IVirtualBox::unregisterHardDisk()"/>.</note>
    5304 
    5305             </desc>
    5306         </method>
    5307 
    5308     </interface>
    5309 
    5310     <!--
    5311     // IISCSIHardDisk
    5312     /////////////////////////////////////////////////////////////////////////
    5313     -->
    5314 
    5315     <interface
    5316         name="IISCSIHardDisk" extends="$unknown"
    5317         uuid="003f6ca9-3257-4ef9-99c9-c66ce44576cb"
    5318         wsmap="managed"
    5319     >
    5320 
     6049      </param>
     6050      <param name="y" type="long" dir="in">
    53216051        <desc>
    5322 
    5323             The IISCSIHardDisk interface represents <link to="IHardDisk">virtual
    5324             hard disks</link> that use the Internet SCSI (iSCSI) protocol to
    5325             store hard disk data on remote machines.
    5326 
    5327             iSCSI hard disks can be created using <link
    5328             to="IVirtualBox::createHardDisk()"/>. When a new hard disk object is
    5329             created, all its properties are uninitialized. After you assign some
    5330             meaningful values to them, the hard disk object can be registered by
    5331             calling <link to="IVirtualBox::registerHardDisk()"/> and then <link
    5332             to="IMachine::attachHardDisk()">attached</link> to virtual machines.
    5333 
    5334             Objects that support this interface also support the <link
    5335             to="IHardDisk"/> interface.
    5336 
    5337             The <link to="IHardDisk::description">description</link>
    5338             of the iSCSI hard disk is stored in the VirtualBox
    5339             configuration file, so it can be changed (at appropriate
    5340             times) even when
    5341             <link to="IHardDisk::accessible">accessible</link> returns
    5342             <tt>false</tt>.  However, the hard disk must not be
    5343             attached to a running virtual machine.
    5344 
    5345             <note>In the current imlementation, the type of all iSCSI hard disks
    5346             is <link to="HardDiskType::WritethroughHardDisk">Writethrough</link>
    5347             and cannot be changed.</note>
    5348 
     6052          Y coordinate of the pointer in pixels, starting from <tt>1</tt>.
    53496053        </desc>
    5350 
    5351         <attribute name="server" type="wstring">
    5352             <desc>
    5353 
    5354                 iSCSI Server name (either a host name or an IP address). For
    5355                 newly created hard disk objects, this value is <tt>null</tt>.
    5356 
    5357             </desc>
    5358         </attribute>
    5359 
    5360         <attribute name="port" type="unsigned short">
    5361             <desc>
    5362 
    5363                 iSCSI Server port. For newly created hard disk objects, this
    5364                 value is <tt>0</tt>, which means the default port.
    5365 
    5366             </desc>
    5367         </attribute>
    5368 
    5369         <attribute name="target" type="wstring">
    5370             <desc>
    5371 
    5372                 iSCSI target name. For newly created hard disk objects, this
    5373                 value is <tt>null</tt>.
    5374 
    5375             </desc>
    5376         </attribute>
    5377 
    5378         <attribute name="lun" type="unsigned long long">
    5379             <desc>
    5380 
    5381                 Logical unit number for this iSCSI disk. For newly created hard
    5382                 disk objects, this value is <tt>0</tt>.
    5383 
    5384             </desc>
    5385         </attribute>
    5386 
    5387         <attribute name="userName" type="wstring">
    5388             <desc>
    5389 
    5390                 User name for accessing this iSCSI disk. For newly created hard
    5391                 disk objects, this value is <tt>null</tt>.
    5392 
    5393             </desc>
    5394         </attribute>
    5395 
    5396         <attribute name="password" type="wstring">
    5397             <desc>
    5398 
    5399                 User password for accessing this iSCSI disk. For newly created
    5400                 hard disk objects, this value is <tt>null</tt>.
    5401 
    5402             </desc>
    5403         </attribute>
    5404 
    5405     </interface>
    5406 
    5407     <!--
    5408     // IVMDKImage
    5409     /////////////////////////////////////////////////////////////////////////
    5410     -->
    5411 
    5412     <interface
    5413         name="IVMDKImage" extends="$unknown"
    5414         uuid="178398f5-8559-4fee-979e-420af5b53eef"
    5415         wsmap="managed"
    5416     >
     6054      </param>
     6055      <param name="dz" type="long" dir="in">
    54176056        <desc>
    5418 
    5419             The IVMDKImage interface represents <link
    5420             to="IHardDisk">virtual hard disks</link> that use
    5421             VMware Virtual Machine Disk image files to store hard disk data.
    5422 
    5423             Hard disks using VMDK images can be either opened using
    5424             <link to="IVirtualBox::openHardDisk()"/> or created from
    5425             scratch using <link to="IVirtualBox::createHardDisk()"/>.
    5426 
    5427             Objects that support this interface also support the <link
    5428             to="IHardDisk"/> interface.
    5429 
    5430             When a new hard disk object is created from scatch, an image file
    5431             for it is not automatically created. To do it, you need to specify a
    5432             valid <link to="#filePath">file path</link>, and call <link
    5433             to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
    5434             When it is done, the hard disk object can be registered by calling
    5435             <link to="IVirtualBox::registerHardDisk()"/> and then
    5436             <link to="IMachine::attachHardDisk()">attached</link> to
    5437             virtual machines.
    5438 
    5439             The <link to="IHardDisk::description">description</link>
    5440             of the VMDK hard disk is stored in the VirtualBox
    5441             configuration file, so it can be changed (at appropriate
    5442             times) even when
    5443             <link to="IHardDisk::accessible">accessible</link> returns
    5444             <tt>false</tt>.  However, the hard disk must not be
    5445             attached to a running virtual machine.
    5446 
    5447             <note>In the current imlementation, the type of all VMDK hard disks
    5448             is <link to="HardDiskType::WritethroughHardDisk">Writethrough</link>
    5449             and cannot be changed.</note>
    5450 
     6057          Amout of mouse wheel moves.
     6058          Positive values describe clockwize wheel rotations,
     6059          negative values describe counterclockwise rotations.
    54516060        </desc>
    5452 
    5453         <attribute name="filePath" type="wstring">
    5454             <desc>
    5455 
    5456                 Full file name of the VMDK image of this hard disk. For
    5457                 newly created hard disk objects, this value is <tt>null</tt>.
    5458 
    5459                 When assigning a new path, it can be absolute (full path) or
    5460                 relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
    5461                 home directory</link>. If only a file name without any path is
    5462                 given, the <link to="ISystemProperties::defaultVDIFolder">
    5463                 default VDI folder</link> will be used as a path to the image
    5464                 file.
    5465 
    5466                 When reading this propery, a full path is always returned.
    5467 
    5468                 <note>This property cannot be changed when <link to="#created"/>
    5469                 returns <tt>true</tt>. In this case, the specified file name can
    5470                 be absolute (full path) or relative to the <link
    5471                 to="IVirtualBox::homeFolder"> VirtualBox home directory</link>.
    5472                 If only a file name without any path is given, the <link
    5473                 to="ISystemProperties::defaultVDIFolder"> default VDI
    5474                 folder</link> will be used as a path to the image file.</note>
    5475 
    5476             </desc>
    5477         </attribute>
    5478 
    5479         <attribute name="created" type="boolean" readonly="yes">
    5480             <desc>
    5481 
    5482                 Whether the virual disk image is created or not. For newly
    5483                 created hard disk objects or after a successful invocation of
    5484                 <link to="#deleteImage()"/>, this value is <tt>false</tt> until
    5485                 <link to="#createFixedImage()"/> or <link
    5486                 to="#createDynamicImage()"/> is called.
    5487 
    5488             </desc>
    5489         </attribute>
    5490 
    5491         <method name="createDynamicImage">
    5492 
    5493             <desc>
    5494 
    5495                 Starts creating a dymically expanding hard disk image in the
    5496                 background. The previous image associated with this object, if
    5497                 any, must be deleted using <link to="#deleteImage"/>, otherwise
    5498                 the operation will fail.
    5499 
    5500                 <note>After the returned progress object reports that the
    5501                 operation is complete, this hard disk object can be
    5502                 <link to="IVirtualBox::registerHardDisk()">registered</link>
    5503                 within this VirtualBox installation.</note>
    5504 
    5505             </desc>
    5506 
    5507             <param name="size" type="unsigned long long" dir="in">
    5508                 <desc>Maximum logical size of the hard disk in megabytes.</desc>
    5509             </param>
    5510             <param name="progress" type="IProgress" dir="return">
    5511                 <desc>Progress object to track the operation completion.</desc>
    5512             </param>
    5513 
    5514         </method>
    5515 
    5516         <method name="createFixedImage">
    5517             <desc>
    5518 
    5519                 Starts creating a fixed-size hard disk image in the background.
    5520                 The previous image, if any, must be deleted using <link
    5521                 to="#deleteImage"/>, otherwise the operation will fail.
    5522 
    5523                 <note>After the returned progress object reports that the
    5524                 operation is complete, this hard disk object can be
    5525                 <link to="IVirtualBox::registerHardDisk()">registered</link>
    5526                 within this VirtualBox installation.</note>
    5527 
    5528             </desc>
    5529 
    5530             <param name="size" type="unsigned long long" dir="in">
    5531                 <desc>Logical size of the hard disk in megabytes.</desc>
    5532             </param>
    5533             <param name="progress" type="IProgress" dir="return">
    5534                 <desc>Progress object to track the operation completion.</desc>
    5535             </param>
    5536 
    5537         </method>
    5538 
    5539         <method name="deleteImage">
    5540             <desc>
    5541 
    5542                 Deletes the existing hard disk image. The hard disk must not be
    5543                 registered within this VirtualBox installation, otherwise the
    5544                 operation will fail.
    5545 
    5546                 <note>After this operation succeeds, it will be impossible to
    5547                 register the hard disk until the image file is created
    5548                 again.</note>
    5549 
    5550                 <note>This operation is valid only for non-differencing hard
    5551                 disks, after they are unregistered using <link
    5552                 to="IVirtualBox::unregisterHardDisk()"/>.</note>
    5553 
    5554             </desc>
    5555         </method>
    5556 
    5557     </interface>
    5558 
    5559     <!--
    5560     // IDVDImage
    5561     /////////////////////////////////////////////////////////////////////////
    5562     -->
    5563 
    5564     <enumerator
    5565         name="IDVDImageEnumerator" type="IDVDImage"
    5566         uuid="9BE77C8D-E1BE-4bf2-A67B-B4DD3D2B0F28"
    5567     />
    5568 
    5569     <collection
    5570         name="IDVDImageCollection" type="IDVDImage"
    5571         enumerator="IDVDImageEnumerator"
    5572         uuid="AE7053FA-ADD2-4ea4-AFCF-24D5F8DDED64"
    5573         readonly="yes"
    5574     >
    5575         <method name="findByPath">
    5576             <desc>
    5577                 Searches this collection for a DVD image with the given disk path.
    5578                 <note>
    5579                     The method returns an error if the given name does not
    5580                     correspond to any DVD image in the collection.
    5581                 </note>
    5582             </desc>
    5583             <param name="path" type="wstring" dir="in">
    5584                 <desc>Name of the DVD image's file system location.</desc>
    5585             </param>
    5586             <param name="image" type="IDVDImage" dir="return">
    5587                 <desc>Found DVD image object</desc>
    5588             </param>
    5589         </method>
    5590     </collection>
    5591 
    5592     <interface
    5593         name="IDVDImage" extends="$unknown"
    5594         uuid="140FFF03-E479-4194-8562-ABC4F8171009"
    5595         wsmap="managed"
    5596     >
     6061      </param>
     6062      <param name="buttonState" type="long" dir="in">
    55976063        <desc>
    5598 
    5599             The IDVDImage interface represents a file containing the image
    5600             of the DVD or CD disk.
    5601 
    5602             <h3>Image Accessibility</h3>
    5603 
    5604             The <link to="#accessible"/> attribute of the image object
    5605             defines the accessibility state of the image file. If the
    5606             value of this attribute is <tt>false</tt> then some image
    5607             attributes may contain invalid or outdated values (for example, the
    5608             the image file size) until a new accessibility
    5609             check is done that returns <tt>true</tt>.
    5610 
    5611             <note>
    5612             Because of the possible slowness of the accessibility check,
    5613             it is not implicitly performed upon the VirtualBox server startup
    5614             (to prevent the application freeze). In partcular, this means that
    5615             if you try to read image properties that depend on the
    5616             accessibility state without first reading the value of the
    5617             <link to="#accessible"/> attribute and ensuring it's value is
    5618             <tt>true</tt>, you will get wrong (zero) values.
    5619             </note>
    5620 
     6064          The current state of mouse buttons. Every bit represents
     6065          a mouse button as follows:
     6066          <table>
     6067            <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
     6068            <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
     6069            <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
     6070          </table>
     6071          A value of <tt>1</tt> means the corresponding button is pressed.
     6072          otherwise it is released.
    56216073        </desc>
    5622         <attribute name="id" type="uuid" readonly="yes">
    5623             <desc>UUID of the CD/DVD image.</desc>
    5624         </attribute>
    5625 
    5626         <attribute name="filePath" type="wstring" readonly="yes">
    5627             <desc>Full file name of the CD/DVD image.</desc>
    5628         </attribute>
    5629 
    5630         <attribute name="accessible" type="boolean" readonly="yes">
    5631             <desc>
    5632 
    5633                 Whether the CD/DVD image is currently accessible or not.
    5634                 The image, for example, can be unaccessible if it is placed
    5635                 on a network share that is not available by the time
    5636                 this property is read.
    5637 
    5638                 The accessibility check is performed automatically every time
    5639                 this attribute is read. You should keep it in mind that this check
    5640                 may be slow and can block the calling thread for a long time (for
    5641                 example, if the network share where the image is located is down).
    5642 
    5643                 The following attributes of the image object are considered
    5644                 to be invalid when this attribute is <tt>false</tt>:
    5645                 <ul>
    5646                 <li><link to="#size"/></li>
    5647                 </ul>
    5648 
    5649             </desc>
    5650         </attribute>
    5651 
    5652         <attribute name="size" type="unsigned long long" readonly="yes">
    5653             <desc>Size of the ISO image in bytes.</desc>
    5654         </attribute>
    5655 
    5656     </interface>
    5657 
    5658 
    5659     <!--
    5660     // IDVDDrive
    5661     /////////////////////////////////////////////////////////////////////////
    5662     -->
    5663 
    5664     <enum
    5665         name="DriveState"
    5666         uuid="cb7233b7-c519-42a5-8310-1830953cacbc"
    5667     >
    5668         <const name="InvalidDriveState"  value="0"/>
    5669         <const name="NotMounted"         value="1"/>
    5670         <const name="ImageMounted"       value="2"/>
    5671         <const name="HostDriveCaptured"  value="3"/>
    5672     </enum>
    5673 
    5674     <interface
    5675         name="IDVDDrive" extends="$unknown"
    5676         uuid="d9bd101a-8079-4fb9-bad1-31bf32482b75"
    5677         wsmap="managed"
    5678     >
    5679         <attribute name="state" type="DriveState" readonly="yes">
    5680             <desc>Current drive state.</desc>
    5681         </attribute>
    5682 
    5683         <attribute name="passthrough" type="boolean">
    5684             <desc>
    5685                 When a host drive is mounted and passthrough is enabled
    5686                 the guest will be able to directly send SCSI commands to
    5687                 the host drive. This enables the guest to use CD/DVD writers
    5688                 but is potentially dangerous.
    5689             </desc>
    5690         </attribute>
    5691 
    5692         <method name="mountImage">
    5693             <desc>Mounts the specified image.</desc>
    5694             <param name="imageId" type="uuid" dir="in"/>
    5695         </method>
    5696 
    5697         <method name="captureHostDrive">
    5698             <desc>Captures the specified host drive.</desc>
    5699             <param name="drive" type="IHostDVDDrive" dir="in"/>
    5700         </method>
    5701 
    5702         <method name="unmount">
    5703             <desc>Unmounts the currently mounted image/device.</desc>
    5704         </method>
    5705 
    5706         <method name="getImage">
    5707             <desc>Gets the currently mounted image ID.</desc>
    5708             <param name="image" type="IDVDImage" dir="return"/>
    5709         </method>
    5710 
    5711         <method name="getHostDrive">
    5712             <desc>Gets the currently mounted image ID.</desc>
    5713             <param name="drive" type="IHostDVDDrive" dir="return"/>
    5714         </method>
    5715 
    5716     </interface>
    5717 
    5718     <!--
    5719     // IFloppyImage
    5720     /////////////////////////////////////////////////////////////////////////
    5721     -->
    5722 
    5723     <enumerator
    5724         name="IFloppyImageEnumerator" type="IFloppyImage"
    5725         uuid="902C4089-76B7-41f1-91E8-49A261A28A2C"
    5726     />
    5727 
    5728     <collection
    5729         name="IFloppyImageCollection" type="IFloppyImage"
    5730         enumerator="IFloppyImageEnumerator"
    5731         uuid="327A8928-8572-446e-AD9A-18FE30E81F3F"
    5732         readonly="yes">
    5733         <method name="findByPath">
    5734             <desc>
    5735                 Searches this collection for a floppy image with the given disk path.
    5736                 <note>
    5737                     The method returns an error if the given name does not
    5738                     correspond to any floppy image in the collection.
    5739                 </note>
    5740             </desc>
    5741             <param name="path" type="wstring" dir="in">
    5742                 <desc>Name of the floppy image's file system location.</desc>
    5743             </param>
    5744             <param name="image" type="IFloppyImage" dir="return">
    5745                 <desc>Found Floppy image object</desc>
    5746             </param>
    5747         </method>
    5748     </collection>
    5749 
    5750     <interface
    5751         name="IFloppyImage" extends="$unknown"
    5752         uuid="CC696755-EA98-4ffe-9DC5-C003047034AB"
    5753         wsmap="managed"
    5754     >
     6074      </param>
     6075    </method>
     6076
     6077  </interface>
     6078
     6079
     6080  <!--
     6081  // IDisplay
     6082  /////////////////////////////////////////////////////////////////////////
     6083  -->
     6084
     6085  <enum
     6086     name="FramebufferAccelerationOperation"
     6087     uuid="f0e5ebbe-dc8e-4e2d-916e-53baa3844df8"
     6088     >
     6089    <const name="SolidFillAcceleration"   value="1"/>
     6090    <const name="ScreenCopyAcceleration"  value="2"/>
     6091  </enum>
     6092
     6093  <enum
     6094     name="FramebufferPixelFormat"
     6095     uuid="d15f9c8b-bd7e-4003-981c-4ca14f49f2c3"
     6096     >
     6097    <const name="PixelFormatDefault"      value="0"/>
     6098    <const name="PixelFormatRGB16"        value="1"/>
     6099    <const name="PixelFormatRGB24"        value="2"/>
     6100    <const name="PixelFormatRGB32"        value="3"/>
     6101  </enum>
     6102
     6103  <interface
     6104     name="IFramebuffer" extends="$unknown"
     6105     uuid="9f3eba23-6a75-49f3-93e7-cad00fb605f6"
     6106     wsmap="suppress"
     6107     >
     6108    <attribute name="address" type="octet" mod="ptr" readonly="yes">
     6109      <desc>Address of the start byte of the framebuffer.</desc>
     6110    </attribute>
     6111
     6112    <attribute name="width" type="unsigned long" readonly="yes">
     6113      <desc>Framebuffer width.</desc>
     6114    </attribute>
     6115
     6116    <attribute name="height" type="unsigned long" readonly="yes">
     6117      <desc>Framebuffer height.</desc>
     6118    </attribute>
     6119
     6120    <attribute name="colorDepth" type="unsigned long" readonly="yes">
     6121      <desc>Framebuffer color depth.</desc>
     6122    </attribute>
     6123
     6124    <attribute name="lineSize" type="unsigned long" readonly="yes">
     6125      <desc>framebuffer scan line size in bytes.</desc>
     6126    </attribute>
     6127
     6128    <attribute name="pixelFormat" type="FramebufferPixelFormat" readonly="yes">
     6129      <desc>Framebuffer pixel format.</desc>
     6130    </attribute>
     6131
     6132    <attribute name="heightReduction" type="unsigned long" readonly="yes">
     6133      <desc>
     6134        Hint from the framebuffer about how much of the standard
     6135        screen height it wants to use for itself. This information is
     6136        exposed to the guest through the VESA BIOS and VMMDev interface
     6137        so that it can use it for determining its video mode table. It
     6138        is not guaranteed that the guest respects the value.
     6139      </desc>
     6140    </attribute>
     6141
     6142    <attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
     6143      <desc>
     6144        An alpha-blended overlay which is superposed over the framebuffer.
     6145        The initial purpose is to allow the display of icons providing
     6146        information about the VM state, including disk activity, in front
     6147        ends which do not have other means of doing that.  The overlay is
     6148        designed to controlled exclusively by IDisplay.  It has no locking
     6149        of its own, and any changes made to it are not guaranteed to be
     6150        visible until the affected portion of IFramebuffer is updated.  The
     6151        overlay can be created lazily the first time it is requested.  This
     6152        attribute can also return NULL to signal that the overlay is not
     6153        implemented.
     6154      </desc>
     6155    </attribute>
     6156
     6157    <method name="lock">
     6158      <desc>
     6159        Locks the framebuffer.
     6160        Gets called by the display object where this buffer is
     6161        registered.
     6162      </desc>
     6163    </method>
     6164
     6165    <method name="unlock">
     6166      <desc>
     6167        Unlocks the framebuffer.
     6168        Gets called by the display object where this buffer is
     6169        registered.
     6170      </desc>
     6171    </method>
     6172
     6173    <method name="notifyUpdate">
     6174      <desc>
     6175        Informs about an update.
     6176        Gets called by the display object where this buffer is
     6177        registered.
     6178      </desc>
     6179      <param name="x" type="unsigned long" dir="in"/>
     6180      <param name="y" type="unsigned long" dir="in"/>
     6181      <param name="width" type="unsigned long" dir="in"/>
     6182      <param name="height" type="unsigned long" dir="in"/>
     6183      <param name="finished" type="boolean" dir="return"/>
     6184    </method>
     6185
     6186    <method name="requestResize">
     6187      <desc>
     6188        Requests a size and pixel format change.
     6189
     6190        The IFramebuffer implementation should try to setup
     6191        a memory buffer suitable for the given pixel format
     6192        and line size.
     6193        The buffer must be page aligned, must contain
     6194        whole number of pages, and one should be able
     6195        to lock it to obtain physical addresses of pages.
     6196        (Note: this method is currently not supported,
     6197        use the below mentioned vram pointer!)
     6198
     6199        If the requested pixel format is not supported,
     6200        or a PixelFormatDefault is requested,
     6201        a default format is set. In that case the memory
     6202        buffer does not have to be aligned and lockable.
     6203
     6204        The callee is also allowed to use the guest video memory
     6205        buffer (pointed to by the @a vram parameter) directly instead
     6206        of allocating its own buffer. To indicate that the framebuffer
     6207        wants to use the guest video memory, its <link to="#address"/>
     6208        implementation must return the same address as it gets in
     6209        the @a vram parameter of this method.
     6210
     6211        For non linear modes (such as text and standard VGA), the @a
     6212        vram parameter is @c NULL and must not be used. When it's not
     6213        NULL, it is recommended to use it to access the guest video
     6214        memory instead of creating a separate buffer as it will at
     6215        least remove one copy operation.
     6216
     6217        The caller checks if the call was successful
     6218        via the <link to="#pixelFormat"/> property.
     6219
     6220        <note>
     6221          This method is called by IDisplay under the IFramebuffer
     6222          lock.
     6223        </note>
     6224      </desc>
     6225      <param name="screenId" type="unsigned long" dir="in">
     6226        <desc>The value to be used in the <link to="IDisplay::resizeCompleted()"/> call.</desc>
     6227      </param>
     6228      <param name="pixelFormat" type="FramebufferPixelFormat" dir="in">
     6229        <desc>Pixel format of the surface (BPP and layout)</desc>
     6230      </param>
     6231      <param name="vram" type="octet" mod="ptr" dir="in">
     6232        <desc>Pointer to the guest VRAM (NULL for non linear modes)</desc>
     6233      </param>
     6234      <param name="lineSize" type="unsigned long" dir="in">
     6235        <desc>Size of one scan line, in bytes.</desc>
     6236      </param>
     6237      <param name="width" type="unsigned long" dir="in">
     6238        <desc>Width of the guest display, in pixels.</desc>
     6239      </param>
     6240      <param name="height" type="unsigned long" dir="in">
     6241        <desc>Height of the guest display, in pixels.</desc>
     6242      </param>
     6243      <param name="finished" type="boolean" dir="return">
    57556244        <desc>
    5756 
    5757             The IFloppyImage interface represents a file containing the image
    5758             of a floppy disk.
    5759 
    5760             <h3>Image Accessibility</h3>
    5761 
    5762             The <link to="#accessible"/> attribute of the image object
    5763             defines the accessibility state of the image file. If the
    5764             value of this attribute is <tt>false</tt> then some image
    5765             attributes may contain invalid or outdated values (for example, the
    5766             the image file size) until a new accessibility
    5767             check is done that returns <tt>true</tt>.
    5768 
    5769             <note>
    5770             Because of the possible slowness of the accessibility check,
    5771             it is not implicitly performed upon the VirtualBox server startup
    5772             (to prevent the application freeze). In partcular, this means that
    5773             if you try to read image properties that depend on the
    5774             accessibility state without first reading the value of the
    5775             <link to="#accessible"/> attribute and ensuring it's value is
    5776             <tt>true</tt>, you will get wrong (zero) values.
    5777             </note>
    5778 
     6245          Can the VM start using the new framebuffer immediately
     6246          after this method returns or it should wait for
     6247          <link to="IDisplay::resizeCompleted()"/>.
    57796248        </desc>
    5780         <attribute name="id" type="uuid" readonly="yes">
    5781             <desc>UUID of the floppy image.</desc>
    5782         </attribute>
    5783 
    5784         <attribute name="filePath" type="wstring" readonly="yes">
    5785             <desc>Full file name of the floppy image.</desc>
    5786         </attribute>
    5787 
    5788         <attribute name="accessible" type="boolean" readonly="yes">
    5789             <desc>
    5790 
    5791                 Whether the floppy image is currently accessible or not.
    5792                 The image, for example, can be unaccessible if it is placed
    5793                 on a network share that is not available by the time
    5794                 this property is read.
    5795 
    5796                 The accessibility check is performed automatically every time
    5797                 this attribute is read. You should keep it in mind that this check
    5798                 may be slow and can block the calling thread for a long time (for
    5799                 example, if the network share where the image is located is down).
    5800 
    5801                 The following attributes of the image object are considered
    5802                 to be invalid when this attribute is <tt>false</tt>:
    5803                 <ul>
    5804                 <li><link to="#size"/></li>
    5805                 </ul>
    5806 
    5807             </desc>
    5808         </attribute>
    5809 
    5810         <attribute name="size" type="unsigned long" readonly="yes">
    5811             <desc>Size of the floppy image in bytes.</desc>
    5812         </attribute>
    5813 
    5814     </interface>
    5815 
    5816 
    5817     <!--
    5818     // IFloppyDrive
    5819     /////////////////////////////////////////////////////////////////////////
    5820     -->
    5821 
    5822     <interface
    5823         name="IFloppyDrive" extends="$unknown"
    5824         uuid="E9318F71-78D2-4b00-863C-B7CB0030A2D9"
    5825         wsmap="managed"
    5826     >
    5827         <attribute name="enabled" type="boolean">
    5828             <desc>
    5829                 Flag whether the floppy drive is enabled. If it is disabled,
    5830                 the floppy drive will not be reported to the guest.
    5831             </desc>
    5832         </attribute>
    5833 
    5834         <attribute name="state" type="DriveState" readonly="yes">
    5835             <desc>Current drive state.</desc>
    5836         </attribute>
    5837 
    5838         <method name="mountImage">
    5839             <desc>Mounts the specified image.</desc>
    5840             <param name="imageId" type="uuid" dir="in"/>
    5841         </method>
    5842 
    5843         <method name="captureHostDrive">
    5844             <desc>Captures the specified host drive.</desc>
    5845             <param name="drive" type="IHostFloppyDrive" dir="in"/>
    5846         </method>
    5847 
    5848         <method name="unmount">
    5849             <desc>Unmounts the currently mounted image/device.</desc>
    5850         </method>
    5851 
    5852         <method name="getImage">
    5853             <desc>Gets the currently mounted image ID.</desc>
    5854             <param name="image" type="IFloppyImage" dir="return"/>
    5855         </method>
    5856 
    5857         <method name="getHostDrive">
    5858             <desc>Gets the currently mounted image ID.</desc>
    5859             <param name="drive" type="IHostFloppyDrive" dir="return"/>
    5860         </method>
    5861 
    5862     </interface>
    5863 
    5864 
    5865     <!--
    5866     // IKeyboard
    5867     /////////////////////////////////////////////////////////////////////////
    5868     -->
    5869 
    5870     <interface
    5871         name="IKeyboard" extends="$unknown"
    5872         uuid="FD443EC1-000A-4F5B-9282-D72760A66916"
    5873         wsmap="managed"
    5874     >
    5875         <method name="putScancode">
    5876             <desc>Sends a scancode to the keyboard.</desc>
    5877             <param name="scancode" type="long" dir="in"/>
    5878         </method>
    5879 
    5880         <method name="putScancodes">
    5881             <desc>Sends an array of scancode to the keyboard.</desc>
    5882             <param name="scancodes" type="long" dir="in" array="count"/>
    5883             <param name="count" type="unsigned long" dir="in"/>
    5884             <param name="codesStored" type="unsigned long" dir="return"/>
    5885         </method>
    5886 
    5887         <method name="putCAD">
    5888             <desc>Sends the Ctrl-Alt-Del sequence to the keyboard.</desc>
    5889         </method>
    5890 
    5891     </interface>
    5892 
    5893 
    5894     <!--
    5895     // IMouse
    5896     /////////////////////////////////////////////////////////////////////////
    5897     -->
    5898 
    5899     <enum
    5900         name="MouseButtonState"
    5901         uuid="03131722-2EC5-4173-9794-0DACA46673EF"
    5902     >
    5903         <const name="LeftButton"        value="0x01"/>
    5904         <const name="RightButton"       value="0x02"/>
    5905         <const name="MiddleButton"      value="0x04"/>
    5906         <const name="WheelUp"           value="0x08"/>
    5907         <const name="WheelDown"         value="0x10"/>
    5908         <const name="MouseStateMask"    value="0x1F"/>
    5909     </enum>
    5910 
    5911     <interface
    5912         name="IMouse" extends="$unknown"
    5913         uuid="FD443EC1-0006-4F5B-9282-D72760A66916"
    5914         wsmap="managed"
    5915     >
     6249      </param>
     6250    </method>
     6251
     6252    <method name="operationSupported">
     6253      <desc>
     6254        Returns whether the given acceleration operation is supported
     6255        by the IFramebuffer implementation. If not, the display object
     6256        will not attempt to call the corresponding IFramebuffer entry
     6257        point. Even if an operation is indicated to supported, the
     6258        IFramebuffer implementation always has the option to return non
     6259        supported from the corresponding acceleration method in which
     6260        case the operation will be performed by the display engine. This
     6261        allows for reduced IFramebuffer implementation complexity where
     6262        only common cases are handled.
     6263      </desc>
     6264      <param name="operation" type="FramebufferAccelerationOperation" dir="in"/>
     6265      <param name="supported" type="boolean" dir="return"/>
     6266    </method>
     6267
     6268    <method name="videoModeSupported">
     6269      <desc>
     6270        Returns whether the framebuffer implementation is willing to
     6271        support a given video mode. In case it is not able to render
     6272        the video mode (or for some reason not willing), it should
     6273        return false. Usually this method is called when the guest
     6274        asks the VMM device whether a given video mode is supported
     6275        so the information returned is directly exposed to the guest.
     6276        It is important that this method returns very quickly.
     6277      </desc>
     6278      <param name="width" type="unsigned long" dir="in"/>
     6279      <param name="height" type="unsigned long" dir="in"/>
     6280      <param name="bpp" type="unsigned long" dir="in"/>
     6281      <param name="supported" type="boolean" dir="return"/>
     6282    </method>
     6283
     6284    <method name="solidFill">
     6285      <desc>
     6286        Fill the specified rectangle on screen with a solid color.
     6287      </desc>
     6288      <param name="x" type="unsigned long" dir="in"/>
     6289      <param name="y" type="unsigned long" dir="in"/>
     6290      <param name="width" type="unsigned long" dir="in"/>
     6291      <param name="height" type="unsigned long" dir="in"/>
     6292      <param name="color" type="unsigned long" dir="in"/>
     6293      <param name="handled" type="boolean" dir="return"/>
     6294    </method>
     6295
     6296    <method name="copyScreenBits">
     6297      <desc>
     6298        Copy specified rectangle on the screen.
     6299      </desc>
     6300      <param name="xDst" type="unsigned long" dir="in"/>
     6301      <param name="yDst" type="unsigned long" dir="in"/>
     6302      <param name="xSrc" type="unsigned long" dir="in"/>
     6303      <param name="ySrc" type="unsigned long" dir="in"/>
     6304      <param name="width" type="unsigned long" dir="in"/>
     6305      <param name="height" type="unsigned long" dir="in"/>
     6306      <param name="handled" type="boolean" dir="return"/>
     6307    </method>
     6308
     6309  </interface>
     6310
     6311  <interface
     6312     name="IFramebufferOverlay" extends="IFrameBuffer"
     6313     uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
     6314     wsmap="suppress"
     6315     >
     6316    <desc>
     6317      An alpha blended overlay for displaying status icons above an IFramebuffer.
     6318      It is always created not visible, so that it must be explicitly shown.  It
     6319      only covers a portion of the IFramebuffer, determined by its width, height
     6320      and co-ordinates.  It is always in packed pixel little-endian 32bit ARGB (in
     6321      that order) format, and may be written to directly.  Do re-read the width
     6322      though, after setting it, as it may be adjusted (increased) to make it more
     6323      suitable for the front end.
     6324    </desc>
     6325    <attribute name="x" type="unsigned long" readonly="yes">
     6326      <desc>X position of the overlay, relative to the framebuffer.</desc>
     6327    </attribute>
     6328
     6329    <attribute name="y" type="unsigned long" readonly="yes">
     6330      <desc>Y position of the overlay, relative to the framebuffer.</desc>
     6331    </attribute>
     6332
     6333    <attribute name="visible" type="boolean" readonly="no">
     6334      <desc>
     6335        Whether the overlay is currently visible.
     6336      </desc>
     6337    </attribute>
     6338
     6339    <attribute name="alpha" type="unsigned long" readonly="no">
     6340      <desc>
     6341        The global alpha value for the overlay.  This may or may not be
     6342        supported by a given front end.
     6343      </desc>
     6344    </attribute>
     6345
     6346    <method name="move">
     6347      <desc>
     6348        Changes the overlay's position relative to the IFramebuffer.
     6349      </desc>
     6350      <param name="x" type="unsigned long" dir="in"/>
     6351      <param name="y" type="unsigned long" dir="in"/>
     6352    </method>
     6353
     6354  </interface>
     6355
     6356  <interface
     6357     name="IDisplay" extends="$unknown"
     6358     uuid="e740a435-88d1-4f14-b9ca-a1b30e2c5038"
     6359     wsmap="suppress"
     6360     >
     6361    <attribute name="width" type="unsigned long" readonly="yes">
     6362      <desc>Current display width.</desc>
     6363    </attribute>
     6364
     6365    <attribute name="height" type="unsigned long" readonly="yes">
     6366      <desc>Current display height.</desc>
     6367    </attribute>
     6368
     6369    <attribute name="colorDepth" type="unsigned long" readonly="yes">
     6370      <desc>
     6371        Current guest display color depth. Note that this may differ
     6372        from <link to="IFramebuffer::colorDepth">IFramebuffer::colorDepth</link>.
     6373      </desc>
     6374    </attribute>
     6375
     6376    <method name="setupInternalFramebuffer">
     6377      <desc>
     6378        Prepares an internally managed framebuffer.
     6379      </desc>
     6380      <param name="depth" type="unsigned long" dir="in"/>
     6381    </method>
     6382
     6383    <method name="lockFramebuffer">
     6384      <desc>
     6385        Requests access to the internal framebuffer.
     6386      </desc>
     6387      <param name="address" type="octet" mod="ptr" dir="return"/>
     6388    </method>
     6389
     6390    <method name="unlockFramebuffer">
     6391      <desc>
     6392        Releases access to the internal framebuffer.
     6393      </desc>
     6394    </method>
     6395
     6396    <method name="registerExternalFramebuffer">
     6397      <desc>
     6398        Registers an external framebuffer.
     6399      </desc>
     6400      <param name="framebuffer" type="IFramebuffer" dir="in"/>
     6401    </method>
     6402
     6403    <method name="setFramebuffer">
     6404      <desc>
     6405        Sets the framebuffer for given screen.
     6406      </desc>
     6407      <param name="screenId" type="unsigned long" dir="in"/>
     6408      <param name="framebuffer" type="IFramebuffer" dir="in"/>
     6409    </method>
     6410
     6411    <method name="queryFramebuffer">
     6412      <desc>
     6413        Queries the framebuffer for given screen.
     6414      </desc>
     6415      <param name="screenId" type="unsigned long" dir="in"/>
     6416      <param name="framebuffer" type="IFramebuffer" dir="out"/>
     6417      <param name="xOrigin" type="long" dir="out"/>
     6418      <param name="yOrigin" type="long" dir="out"/>
     6419    </method>
     6420
     6421    <method name="setVideoModeHint">
     6422      <desc>
     6423        Asks VirtualBox to request the given video mode from
     6424        the guest. This is just a hint and it cannot be guaranteed
     6425        that the requested resolution will be used. Guest Additions
     6426        are required for the request to be seen by guests. The caller
     6427        should issue the request and wait for a resolution change and
     6428        after a timeout retry.
     6429        Specifying "0" for either width and height or the color depth
     6430        means that the dimensions or color depth should not be changed.
     6431        It is possible to specify the number of the guest display
     6432        that has to be resized, if guest supports multimonitor configuration.
     6433        The display value 0 means primary display, 1 - first secondary.
     6434      </desc>
     6435      <param name="width" type="unsigned long" dir="in"/>
     6436      <param name="height" type="unsigned long" dir="in"/>
     6437      <param name="colorDepth" type="unsigned long" dir="in"/>
     6438      <param name="display" type="unsigned long" dir="in"/>
     6439    </method>
     6440
     6441    <method name="takeScreenShot">
     6442      <desc>
     6443        Takes a screen shot of the requested size and copies it to the
     6444        32-bpp buffer allocated by the caller.
     6445      </desc>
     6446      <param name="address" type="octet" mod="ptr" dir="in"/>
     6447      <param name="width" type="unsigned long" dir="in"/>
     6448      <param name="height" type="unsigned long" dir="in"/>
     6449    </method>
     6450
     6451    <method name="drawToScreen">
     6452      <desc>
     6453        Draws a 32-bpp image of the specified size from the given buffer
     6454        to the given point on the VM display.
     6455      </desc>
     6456      <param name="address" type="octet" mod="ptr" dir="in"/>
     6457      <param name="x" type="unsigned long" dir="in"/>
     6458      <param name="y" type="unsigned long" dir="in"/>
     6459      <param name="width" type="unsigned long" dir="in"/>
     6460      <param name="height" type="unsigned long" dir="in"/>
     6461    </method>
     6462
     6463    <method name="invalidateAndUpdate">
     6464      <desc>
     6465        Does a full invalidation of the VM display and instructs the VM
     6466        to update it.
     6467      </desc>
     6468    </method>
     6469
     6470    <method name="resizeCompleted">
     6471      <desc>
     6472        Signals that a framebuffer has completed the resize operation.
     6473      </desc>
     6474      <param name="screenId" type="unsigned long" dir="in"/>
     6475    </method>
     6476
     6477    <method name="updateCompleted">
     6478      <desc>
     6479        Signals that a framebuffer has completed the update operation.
     6480      </desc>
     6481    </method>
     6482
     6483  </interface>
     6484
     6485  <!--
     6486  // INetworkAdapter
     6487  /////////////////////////////////////////////////////////////////////////
     6488  -->
     6489
     6490  <enum
     6491     name="NetworkAttachmentType"
     6492     uuid="8730d899-d036-4925-bc63-e58f3486f4bf"
     6493     >
     6494    <const name="NoNetworkAttachment"            value="0"/>
     6495    <const name="NATNetworkAttachment"           value="1"/>
     6496    <const name="HostInterfaceNetworkAttachment" value="2"/>
     6497    <const name="InternalNetworkAttachment"      value="3"/>
     6498  </enum>
     6499
     6500  <enum
     6501     name="NetworkAdapterType"
     6502     uuid="156b17b9-5d61-4d54-be90-62e37dda848d"
     6503     >
     6504    <const name="InvalidNetworkAdapterType"      value="0"/>
     6505    <const name="NetworkAdapterAm79C970A"        value="1"/>
     6506    <const name="NetworkAdapterAm79C973"         value="2"/>
     6507  </enum>
     6508
     6509  <interface
     6510     name="INetworkAdapter" extends="$unknown"
     6511     uuid="78dfc978-ecb0-44ee-8b20-54549dd4539e"
     6512     wsmap="managed"
     6513     >
     6514    <attribute name="adapterType" type="NetworkAdapterType">
     6515      <desc>
     6516        Type of the virtual network adapter. Depending on this value,
     6517        VirtualBox will provide a different virtual network hardware
     6518        to the guest.
     6519      </desc>
     6520    </attribute>
     6521
     6522    <attribute name="slot" type="unsigned long" readonly="yes">
     6523      <desc>
     6524        Slot number this adapter is plugged into. Corresponds to
     6525        the value you pass to <link to="IMachine::getNetworkAdapter"/>
     6526        to obtain this instance.
     6527      </desc>
     6528    </attribute>
     6529
     6530    <attribute name="enabled" type="boolean">
     6531      <desc>
     6532        Flag whether the network adapter is present in the
     6533        guest system. If disabled, the virtual guest hardware will
     6534        not contain this network adapter. Can only be changed when
     6535        the VM is not running.
     6536      </desc>
     6537    </attribute>
     6538
     6539    <attribute name="MACAddress" type="wstring">
     6540      <desc>
     6541        Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
     6542        it to NULL, VirtualBox will generate a unique MAC address.
     6543      </desc>
     6544    </attribute>
     6545
     6546    <attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
     6547
     6548    <attribute name="hostInterface" type="wstring">
     6549      <desc>
     6550        Name of the Host Network Interface that is currently in use. NULL will be returned
     6551        if no device has been allocated. On Linux, setting this refers to a permanent TAP
     6552        device. However, a file descriptor has precedence over the interface name on Linux.
     6553        Note that when VBox allocates a TAP device, this property will not be set, i.e. the
     6554        interface name would have to be determined using the file descriptor and /proc/self/fd.
     6555      </desc>
     6556    </attribute>
     6557
     6558<if target="xpidl">
     6559    <attribute name="TAPFileDescriptor" type="long">
     6560      <desc>
     6561        File descriptor of the TAP device. It can either be setup by the caller
     6562        which has to supply an existing valid file handle allocated in the parent
     6563        process of the VM process or allocated by VirtualBox. The value is -1 if it
     6564        has not been defined. This property is non persistent, i.e. it will not be
     6565        stored in the VM's configuration data and thus has to be set at each startup.
     6566      </desc>
     6567    </attribute>
     6568    <attribute name="TAPSetupApplication" type="wstring">
     6569      <desc>
     6570        Application to start to configure the TAP device.
     6571        It is being passed two parameters, 1) the file handle (as ascii),
     6572        2) the TAP device name if it is available.
     6573      </desc>
     6574    </attribute>
     6575    <attribute name="TAPTerminateApplication" type="wstring">
     6576      <desc>
     6577        Application to start before closing a TAP device.
     6578        It is being passed two parameters, 1) the file handle (as ascii),
     6579        2) the TAP device name if it is available.
     6580      </desc>
     6581    </attribute>
     6582</if>
     6583
     6584    <attribute name="internalNetwork" type="wstring">
     6585      <desc>
     6586        Name of the internal network the VM is attached to.
     6587      </desc>
     6588    </attribute>
     6589
     6590    <attribute name="cableConnected" type="boolean">
     6591      <desc>
     6592        Flag whether the adapter reports the cable as connected or not.
     6593        It can be used to report offline situations to a VM.
     6594      </desc>
     6595    </attribute>
     6596
     6597    <attribute name="traceEnabled" type="boolean">
     6598      <desc>
     6599        Flag whether network traffic from/to the network card should be traced.
     6600        Can only be toggled when the VM is turned off.
     6601      </desc>
     6602    </attribute>
     6603
     6604    <attribute name="traceFile" type="wstring">
     6605      <desc>
     6606        Filename where a network trace will be stored. If not set, VBox-pid.pcap
     6607        will be used.
     6608      </desc>
     6609    </attribute>
     6610
     6611    <method name="attachToNAT">
     6612      <desc>
     6613        Attach the network adapter to the Network Address Translation (NAT) interface.
     6614      </desc>
     6615    </method>
     6616
     6617    <method name="attachToHostInterface">
     6618      <desc>
     6619        Attach the network adapter to a host interface. On Linux, the TAP
     6620        setup application will be executed if configured and unless a device
     6621        name and/or file descriptor has been set, a new TAP interface will be
     6622        created.
     6623      </desc>
     6624    </method>
     6625
     6626    <method name="attachToInternalNetwork">
     6627      <desc>
     6628        Attach the network adapter to an internal network.
     6629      </desc>
     6630    </method>
     6631
     6632    <method name="detach">
     6633      <desc>
     6634        Detach the network adapter
     6635      </desc>
     6636    </method>
     6637  </interface>
     6638
     6639
     6640  <!--
     6641  // IMachineDebugger
     6642  /////////////////////////////////////////////////////////////////////////
     6643  -->
     6644
     6645  <interface
     6646     name="IMachineDebugger" extends="$unknown"
     6647     uuid="288da658-74fa-4877-ab5c-dafdad19a1cd"
     6648     wsmap="suppress"
     6649     >
     6650    <method name="resetStats">
     6651      <desc>
     6652        Reset VM statistics.
     6653      </desc>
     6654    </method>
     6655
     6656    <method name="dumpStats">
     6657      <desc>
     6658        Dumps VM statistics.
     6659      </desc>
     6660    </method>
     6661
     6662    <attribute name="singlestep" type="boolean">
     6663      <desc>Switch for enabling singlestepping.</desc>
     6664    </attribute>
     6665
     6666    <attribute name="recompileUser" type="boolean">
     6667      <desc>Switch for forcing code recompilation for user mode code.</desc>
     6668    </attribute>
     6669
     6670    <attribute name="recompileSupervisor" type="boolean">
     6671      <desc>Switch for forcing code recompilation for supervisor mode code.</desc>
     6672    </attribute>
     6673
     6674    <attribute name="PATMEnabled" type="boolean">
     6675      <desc>Switch for enabling and disabling the PATM component.</desc>
     6676    </attribute>
     6677
     6678    <attribute name="CSAMEnabled" type="boolean">
     6679      <desc>Switch for enabling and disabling the CSAM component.</desc>
     6680    </attribute>
     6681
     6682    <attribute name="LogEnabled" type="boolean">
     6683      <desc>Switch for enabling and disabling logging.</desc>
     6684    </attribute>
     6685
     6686    <attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
     6687      <desc>
     6688        Flag indicating whether the VM is currently making use of CPU hardware
     6689        virtualization extensions
     6690      </desc>
     6691    </attribute>
     6692
     6693    <attribute name="VirtualTimeRate" type="unsigned long">
     6694      <desc>
     6695        The rate at which the virtual time runs expressed as a percentage.
     6696        The accepted range is 2% to 20000%.
     6697      </desc>
     6698    </attribute>
     6699
     6700    <!-- @todo method for setting log flags, groups and destination! -->
     6701
     6702    <attribute name="VM" type="unsigned long long" readonly="yes">
     6703      <desc>
     6704        Gets the VM handle. This is only for internal use while
     6705        we carve the details of this interface.
     6706      </desc>
     6707    </attribute>
     6708
     6709  </interface>
     6710
     6711  <!--
     6712  // IUSBController
     6713  /////////////////////////////////////////////////////////////////////////
     6714  -->
     6715
     6716  <interface
     6717     name="IUSBController" extends="$unknown"
     6718     uuid="9a110c34-93c2-46b0-8ac2-b09d1067be56"
     6719     wsmap="managed"
     6720     >
     6721    <attribute name="enabled" type="boolean">
     6722      <desc>
     6723        Flag whether the USB controller is present in the
     6724        guest system. If disabled, the virtual guest hardware will
     6725        not contain any USB controller. Can only be changed when
     6726        the VM is powered off.
     6727      </desc>
     6728    </attribute>
     6729
     6730    <attribute name="USBStandard" type="unsigned short" readonly="yes">
     6731      <desc>
     6732        USB standard version which the controller implements.
     6733        This is a BCD which means that the major version is in the
     6734        high byte and minor version is in the low byte.
     6735      </desc>
     6736    </attribute>
     6737
     6738    <attribute name="DeviceFilters" type="IUSBDeviceFilterCollection" readonly="yes">
     6739      <desc>
     6740        List of USB device filters associated with the machine.
     6741
     6742        If the machine is currently running, these filters are activated
     6743        every time a new (supported) USB device is attached to the host
     6744        computer that was not ignored by global filters
     6745        (<link to="IHost::USBDeviceFilters"/>).
     6746
     6747        These filters are also activated when the machine is powered up.
     6748        They are run against a list of all currently available USB
     6749        devices (in states
     6750        <link to="USBDeviceState::USBDeviceAvailable">USBDeviceAvailable</link>,
     6751        <link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,
     6752        <link to="USBDeviceState::USBDeviceHeld">USBDeviceHeld</link>)
     6753        that were not previously ignored by global filters.
     6754
     6755        If at least one filter matches the USB device in question, this
     6756        device is automatically captured (attached to) the virtual USB
     6757        controller of this machine.
     6758
     6759        <see>IUSBDeviceFilter, ::IUSBController</see>
     6760      </desc>
     6761    </attribute>
     6762
     6763    <method name="createDeviceFilter">
     6764      <desc>
     6765        Creates a new USB device filter. All attributes except
     6766        the filter name are set to <tt>null</tt> (any match),
     6767        <i>active</i> is <tt>false</tt> (the filter is not active).
     6768
     6769        The created filter can then be added to the list of filters using
     6770        <link to="#insertDeviceFilter()"/>.
     6771
     6772        <see>#DeviceFilters</see>
     6773      </desc>
     6774      <param name="name" type="wstring" dir="in">
    59166775        <desc>
    5917             The IMouse interface represents a virtual mouse device.
     6776          Filter name. See <link to="IUSBDeviceFilter::name"/>
     6777          for more info.
    59186778        </desc>
    5919 
    5920         <attribute name="absoluteSupported" type="boolean" readonly="yes">
    5921             <desc>
    5922                 Whether the guest OS supports absolute mouse pointer positioning
    5923                 or not.
    5924                 <note>
    5925                     VirtualBox Guest Tools need to be installed to the guest OS
    5926                     in order to enable absolute mouse positioning support.
    5927                     You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
    5928                     callback to be instantly informed about changes of this attribute
    5929                     during virtual machine execution.
    5930                 </note>
    5931                 <see><link to="#putMouseEventAbsolute"/></see>
    5932             </desc>
    5933         </attribute>
    5934 
    5935         <method name="putMouseEvent">
    5936             <desc>
    5937                 Initiates a mouse event using relative pointer movements
    5938                 along x and y axis.
    5939             </desc>
    5940 
    5941             <param name="dx" type="long" dir="in">
    5942                 <desc>
    5943                     Amout of pixels the mouse should move to the right.
    5944                     Negative values move the mouse to the left.
    5945                 </desc>
    5946             </param>
    5947             <param name="dy" type="long" dir="in">
    5948                 <desc>
    5949                     Amout of pixels the mouse should move downwards.
    5950                     Negative values move the mouse upwards.
    5951                 </desc>
    5952             </param>
    5953             <param name="dz" type="long" dir="in">
    5954                 <desc>
    5955                     Amount of mouse wheel moves.
    5956                     Positive values describe clockwize wheel rotations,
    5957                     negative values describe counterclockwise rotations.
    5958                 </desc>
    5959             </param>
    5960             <param name="buttonState" type="long" dir="in">
    5961                 <desc>
    5962                     The current state of mouse buttons. Every bit represents
    5963                     a mouse button as follows:
    5964                     <table>
    5965                     <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
    5966                     <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
    5967                     <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
    5968                     </table>
    5969                     A value of <tt>1</tt> means the corresponding button is pressed.
    5970                     otherwise it is released.
    5971                 </desc>
    5972             </param>
    5973         </method>
    5974 
    5975         <method name="putMouseEventAbsolute">
    5976             <desc>
    5977                 Positions the mouse pointer using absolute x and y coordinates.
    5978                 These coordinates are expressed in pixels and
    5979                 start from <tt>[1,1]</tt> which corresponds to the top left
    5980                 corner of the virtual display.
    5981 
    5982                 <note>
    5983                     This method will have effect only if absolute mouse
    5984                     positioning is supported by the guest OS.
    5985                 </note>
    5986 
    5987                 <see><link to="#absoluteSupported"/></see>
    5988             </desc>
    5989 
    5990             <param name="x" type="long" dir="in">
    5991                 <desc>
    5992                     X coordinate of the pointer in pixels, starting from <tt>1</tt>.
    5993                 </desc>
    5994             </param>
    5995             <param name="y" type="long" dir="in">
    5996                 <desc>
    5997                     Y coordinate of the pointer in pixels, starting from <tt>1</tt>.
    5998                 </desc>
    5999             </param>
    6000             <param name="dz" type="long" dir="in">
    6001                 <desc>
    6002                     Amout of mouse wheel moves.
    6003                     Positive values describe clockwize wheel rotations,
    6004                     negative values describe counterclockwise rotations.
    6005                 </desc>
    6006             </param>
    6007             <param name="buttonState" type="long" dir="in">
    6008                 <desc>
    6009                     The current state of mouse buttons. Every bit represents
    6010                     a mouse button as follows:
    6011                     <table>
    6012                     <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
    6013                     <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
    6014                     <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
    6015                     </table>
    6016                     A value of <tt>1</tt> means the corresponding button is pressed.
    6017                     otherwise it is released.
    6018                 </desc>
    6019             </param>
    6020         </method>
    6021 
    6022     </interface>
    6023 
    6024 
    6025     <!--
    6026     // IDisplay
    6027     /////////////////////////////////////////////////////////////////////////
    6028     -->
    6029 
    6030     <enum
    6031         name="FramebufferAccelerationOperation"
    6032         uuid="f0e5ebbe-dc8e-4e2d-916e-53baa3844df8"
    6033     >
    6034         <const name="SolidFillAcceleration"   value="1"/>
    6035         <const name="ScreenCopyAcceleration"  value="2"/>
    6036     </enum>
    6037 
    6038     <enum
    6039         name="FramebufferPixelFormat"
    6040         uuid="d15f9c8b-bd7e-4003-981c-4ca14f49f2c3"
    6041     >
    6042         <const name="PixelFormatDefault"      value="0"/>
    6043         <const name="PixelFormatRGB16"        value="1"/>
    6044         <const name="PixelFormatRGB24"        value="2"/>
    6045         <const name="PixelFormatRGB32"        value="3"/>
    6046     </enum>
    6047 
    6048     <interface
    6049         name="IFramebuffer" extends="$unknown"
    6050         uuid="9f3eba23-6a75-49f3-93e7-cad00fb605f6"
    6051         wsmap="suppress"
    6052     >
    6053         <attribute name="address" type="octet" mod="ptr" readonly="yes">
    6054             <desc>Address of the start byte of the framebuffer.</desc>
    6055         </attribute>
    6056 
    6057         <attribute name="width" type="unsigned long" readonly="yes">
    6058             <desc>Framebuffer width.</desc>
    6059         </attribute>
    6060 
    6061         <attribute name="height" type="unsigned long" readonly="yes">
    6062             <desc>Framebuffer height.</desc>
    6063         </attribute>
    6064 
    6065         <attribute name="colorDepth" type="unsigned long" readonly="yes">
    6066             <desc>Framebuffer color depth.</desc>
    6067         </attribute>
    6068 
    6069         <attribute name="lineSize" type="unsigned long" readonly="yes">
    6070             <desc>framebuffer scan line size in bytes.</desc>
    6071         </attribute>
    6072 
    6073         <attribute name="pixelFormat" type="FramebufferPixelFormat" readonly="yes">
    6074             <desc>Framebuffer pixel format.</desc>
    6075         </attribute>
    6076 
    6077         <attribute name="heightReduction" type="unsigned long" readonly="yes">
    6078             <desc>
    6079                 Hint from the framebuffer about how much of the standard
    6080                 screen height it wants to use for itself. This information is
    6081                 exposed to the guest through the VESA BIOS and VMMDev interface
    6082                 so that it can use it for determining its video mode table. It
    6083                 is not guaranteed that the guest respects the value.
    6084             </desc>
    6085         </attribute>
    6086 
    6087         <attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
    6088             <desc>
    6089                 An alpha-blended overlay which is superposed over the framebuffer.
    6090                 The initial purpose is to allow the display of icons providing
    6091                 information about the VM state, including disk activity, in front
    6092                 ends which do not have other means of doing that.  The overlay is
    6093                 designed to controlled exclusively by IDisplay.  It has no locking
    6094                 of its own, and any changes made to it are not guaranteed to be
    6095                 visible until the affected portion of IFramebuffer is updated.  The
    6096                 overlay can be created lazily the first time it is requested.  This
    6097                 attribute can also return NULL to signal that the overlay is not
    6098                 implemented.
    6099             </desc>
    6100         </attribute>
    6101 
    6102         <method name="lock">
    6103             <desc>
    6104                 Locks the framebuffer.
    6105                 Gets called by the display object where this buffer is
    6106                 registered.
    6107             </desc>
    6108         </method>
    6109 
    6110         <method name="unlock">
    6111             <desc>
    6112                 Unlocks the framebuffer.
    6113                 Gets called by the display object where this buffer is
    6114                 registered.
    6115             </desc>
    6116         </method>
    6117 
    6118         <method name="notifyUpdate">
    6119             <desc>
    6120                 Informs about an update.
    6121                 Gets called by the display object where this buffer is
    6122                 registered.
    6123             </desc>
    6124             <param name="x" type="unsigned long" dir="in"/>
    6125             <param name="y" type="unsigned long" dir="in"/>
    6126             <param name="width" type="unsigned long" dir="in"/>
    6127             <param name="height" type="unsigned long" dir="in"/>
    6128             <param name="finished" type="boolean" dir="return"/>
    6129         </method>
    6130 
    6131         <method name="requestResize">
    6132             <desc>
    6133                 Requests a size and pixel format change.
    6134 
    6135                 The IFramebuffer implementation should try to setup
    6136                 a memory buffer suitable for the given pixel format
    6137                 and line size.
    6138                 The buffer must be page aligned, must contain
    6139                 whole number of pages, and one should be able
    6140                 to lock it to obtain physical addresses of pages.
    6141                 (Note: this method is currently not supported,
    6142                 use the below mentioned vram pointer!)
    6143 
    6144                 If the requested pixel format is not supported,
    6145                 or a PixelFormatDefault is requested,
    6146                 a default format is set. In that case the memory
    6147                 buffer does not have to be aligned and lockable.
    6148 
    6149                 The callee is also allowed to use the guest video memory
    6150                 buffer (pointed to by the @a vram parameter) directly instead
    6151                 of allocating its own buffer. To indicate that the framebuffer
    6152                 wants to use the guest video memory, its <link to="#address"/>
    6153                 implementation must return the same address as it gets in
    6154                 the @a vram parameter of this method.
    6155 
    6156                 For non linear modes (such as text and standard VGA), the @a
    6157                 vram parameter is @c NULL and must not be used. When it's not
    6158                 NULL, it is recommended to use it to access the guest video
    6159                 memory instead of creating a separate buffer as it will at
    6160                 least remove one copy operation.
    6161 
    6162                 The caller checks if the call was successful
    6163                 via the <link to="#pixelFormat"/> property.
    6164 
    6165                 <note>
    6166                     This method is called by IDisplay under the IFramebuffer
    6167                     lock.
    6168                 </note>
    6169             </desc>
    6170             <param name="screenId" type="unsigned long" dir="in">
    6171                 <desc>The value to be used in the <link to="IDisplay::resizeCompleted()"/> call.</desc>
    6172             </param>
    6173             <param name="pixelFormat" type="FramebufferPixelFormat" dir="in">
    6174                 <desc>Pixel format of the surface (BPP and layout)</desc>
    6175             </param>
    6176             <param name="vram" type="octet" mod="ptr" dir="in">
    6177                 <desc>Pointer to the guest VRAM (NULL for non linear modes)</desc>
    6178             </param>
    6179             <param name="lineSize" type="unsigned long" dir="in">
    6180                 <desc>Size of one scan line, in bytes.</desc>
    6181             </param>
    6182             <param name="width" type="unsigned long" dir="in">
    6183                 <desc>Width of the guest display, in pixels.</desc>
    6184             </param>
    6185             <param name="height" type="unsigned long" dir="in">
    6186                 <desc>Height of the guest display, in pixels.</desc>
    6187             </param>
    6188             <param name="finished" type="boolean" dir="return">
    6189                 <desc>
    6190                     Can the VM start using the new framebuffer immediately
    6191                     after this method returns or it should wait for
    6192                     <link to="IDisplay::resizeCompleted()"/>.
    6193                 </desc>
    6194             </param>
    6195         </method>
    6196 
    6197         <method name="operationSupported">
    6198             <desc>
    6199                 Returns whether the given acceleration operation is supported
    6200                 by the IFramebuffer implementation. If not, the display object
    6201                 will not attempt to call the corresponding IFramebuffer entry
    6202                 point. Even if an operation is indicated to supported, the
    6203                 IFramebuffer implementation always has the option to return non
    6204                 supported from the corresponding acceleration method in which
    6205                 case the operation will be performed by the display engine. This
    6206                 allows for reduced IFramebuffer implementation complexity where
    6207                 only common cases are handled.
    6208             </desc>
    6209             <param name="operation" type="FramebufferAccelerationOperation" dir="in"/>
    6210             <param name="supported" type="boolean" dir="return"/>
    6211         </method>
    6212 
    6213         <method name="videoModeSupported">
    6214             <desc>
    6215                 Returns whether the framebuffer implementation is willing to
    6216                 support a given video mode. In case it is not able to render
    6217                 the video mode (or for some reason not willing), it should
    6218                 return false. Usually this method is called when the guest
    6219                 asks the VMM device whether a given video mode is supported
    6220                 so the information returned is directly exposed to the guest.
    6221                 It is important that this method returns very quickly.
    6222             </desc>
    6223             <param name="width" type="unsigned long" dir="in"/>
    6224             <param name="height" type="unsigned long" dir="in"/>
    6225             <param name="bpp" type="unsigned long" dir="in"/>
    6226             <param name="supported" type="boolean" dir="return"/>
    6227         </method>
    6228 
    6229         <method name="solidFill">
    6230             <desc>
    6231                 Fill the specified rectangle on screen with a solid color.
    6232             </desc>
    6233             <param name="x" type="unsigned long" dir="in"/>
    6234             <param name="y" type="unsigned long" dir="in"/>
    6235             <param name="width" type="unsigned long" dir="in"/>
    6236             <param name="height" type="unsigned long" dir="in"/>
    6237             <param name="color" type="unsigned long" dir="in"/>
    6238             <param name="handled" type="boolean" dir="return"/>
    6239         </method>
    6240 
    6241         <method name="copyScreenBits">
    6242             <desc>
    6243                 Copy specified rectangle on the screen.
    6244             </desc>
    6245             <param name="xDst" type="unsigned long" dir="in"/>
    6246             <param name="yDst" type="unsigned long" dir="in"/>
    6247             <param name="xSrc" type="unsigned long" dir="in"/>
    6248             <param name="ySrc" type="unsigned long" dir="in"/>
    6249             <param name="width" type="unsigned long" dir="in"/>
    6250             <param name="height" type="unsigned long" dir="in"/>
    6251             <param name="handled" type="boolean" dir="return"/>
    6252         </method>
    6253 
    6254     </interface>
    6255 
    6256     <interface
    6257         name="IFramebufferOverlay" extends="IFrameBuffer"
    6258         uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
    6259         wsmap="suppress"
    6260     >
    6261       <desc>
    6262           An alpha blended overlay for displaying status icons above an IFramebuffer.
    6263           It is always created not visible, so that it must be explicitly shown.  It
    6264           only covers a portion of the IFramebuffer, determined by its width, height
    6265           and co-ordinates.  It is always in packed pixel little-endian 32bit ARGB (in
    6266           that order) format, and may be written to directly.  Do re-read the width
    6267           though, after setting it, as it may be adjusted (increased) to make it more
    6268           suitable for the front end.
    6269       </desc>
    6270         <attribute name="x" type="unsigned long" readonly="yes">
    6271             <desc>X position of the overlay, relative to the framebuffer.</desc>
    6272         </attribute>
    6273 
    6274         <attribute name="y" type="unsigned long" readonly="yes">
    6275             <desc>Y position of the overlay, relative to the framebuffer.</desc>
    6276         </attribute>
    6277 
    6278         <attribute name="visible" type="boolean" readonly="no">
    6279             <desc>
    6280                 Whether the overlay is currently visible.
    6281             </desc>
    6282         </attribute>
    6283 
    6284         <attribute name="alpha" type="unsigned long" readonly="no">
    6285             <desc>
    6286                 The global alpha value for the overlay.  This may or may not be
    6287                 supported by a given front end.
    6288             </desc>
    6289         </attribute>
    6290 
    6291         <method name="move">
    6292             <desc>
    6293                 Changes the overlay's position relative to the IFramebuffer.
    6294             </desc>
    6295             <param name="x" type="unsigned long" dir="in"/>
    6296             <param name="y" type="unsigned long" dir="in"/>
    6297         </method>
    6298 
    6299     </interface>
    6300 
    6301     <interface
    6302         name="IDisplay" extends="$unknown"
    6303         uuid="e740a435-88d1-4f14-b9ca-a1b30e2c5038"
    6304         wsmap="suppress"
    6305     >
    6306         <attribute name="width" type="unsigned long" readonly="yes">
    6307             <desc>Current display width.</desc>
    6308         </attribute>
    6309 
    6310         <attribute name="height" type="unsigned long" readonly="yes">
    6311             <desc>Current display height.</desc>
    6312         </attribute>
    6313 
    6314         <attribute name="colorDepth" type="unsigned long" readonly="yes">
    6315             <desc>
    6316                 Current guest display color depth. Note that this may differ
    6317                 from <link to="IFramebuffer::colorDepth">IFramebuffer::colorDepth</link>.
    6318             </desc>
    6319         </attribute>
    6320 
    6321         <method name="setupInternalFramebuffer">
    6322             <desc>
    6323                 Prepares an internally managed framebuffer.
    6324             </desc>
    6325             <param name="depth" type="unsigned long" dir="in"/>
    6326         </method>
    6327 
    6328         <method name="lockFramebuffer">
    6329             <desc>
    6330                Requests access to the internal framebuffer.
    6331             </desc>
    6332             <param name="address" type="octet" mod="ptr" dir="return"/>
    6333         </method>
    6334 
    6335         <method name="unlockFramebuffer">
    6336             <desc>
    6337                 Releases access to the internal framebuffer.
    6338             </desc>
    6339         </method>
    6340 
    6341         <method name="registerExternalFramebuffer">
    6342             <desc>
    6343                 Registers an external framebuffer.
    6344             </desc>
    6345             <param name="framebuffer" type="IFramebuffer" dir="in"/>
    6346         </method>
    6347 
    6348         <method name="setFramebuffer">
    6349             <desc>
    6350                 Sets the framebuffer for given screen.
    6351             </desc>
    6352             <param name="screenId" type="unsigned long" dir="in"/>
    6353             <param name="framebuffer" type="IFramebuffer" dir="in"/>
    6354         </method>
    6355 
    6356         <method name="queryFramebuffer">
    6357             <desc>
    6358                 Queries the framebuffer for given screen.
    6359             </desc>
    6360             <param name="screenId" type="unsigned long" dir="in"/>
    6361             <param name="framebuffer" type="IFramebuffer" dir="out"/>
    6362             <param name="xOrigin" type="long" dir="out"/>
    6363             <param name="yOrigin" type="long" dir="out"/>
    6364         </method>
    6365 
    6366         <method name="setVideoModeHint">
    6367             <desc>
    6368                 Asks VirtualBox to request the given video mode from
    6369                 the guest. This is just a hint and it cannot be guaranteed
    6370                 that the requested resolution will be used. Guest Additions
    6371                 are required for the request to be seen by guests. The caller
    6372                 should issue the request and wait for a resolution change and
    6373                 after a timeout retry.
    6374                 Specifying "0" for either width and height or the color depth
    6375                 means that the dimensions or color depth should not be changed.
    6376                 It is possible to specify the number of the guest display
    6377                 that has to be resized, if guest supports multimonitor configuration.
    6378                 The display value 0 means primary display, 1 - first secondary.
    6379             </desc>
    6380             <param name="width" type="unsigned long" dir="in"/>
    6381             <param name="height" type="unsigned long" dir="in"/>
    6382             <param name="colorDepth" type="unsigned long" dir="in"/>
    6383             <param name="display" type="unsigned long" dir="in"/>
    6384         </method>
    6385 
    6386         <method name="takeScreenShot">
    6387             <desc>
    6388                 Takes a screen shot of the requested size and copies it to the
    6389                 32-bpp buffer allocated by the caller.
    6390             </desc>
    6391             <param name="address" type="octet" mod="ptr" dir="in"/>
    6392             <param name="width" type="unsigned long" dir="in"/>
    6393             <param name="height" type="unsigned long" dir="in"/>
    6394         </method>
    6395 
    6396         <method name="drawToScreen">
    6397             <desc>
    6398                 Draws a 32-bpp image of the specified size from the given buffer
    6399                 to the given point on the VM display.
    6400             </desc>
    6401             <param name="address" type="octet" mod="ptr" dir="in"/>
    6402             <param name="x" type="unsigned long" dir="in"/>
    6403             <param name="y" type="unsigned long" dir="in"/>
    6404             <param name="width" type="unsigned long" dir="in"/>
    6405             <param name="height" type="unsigned long" dir="in"/>
    6406         </method>
    6407 
    6408         <method name="invalidateAndUpdate">
    6409             <desc>
    6410                 Does a full invalidation of the VM display and instructs the VM
    6411                 to update it.
    6412             </desc>
    6413         </method>
    6414 
    6415         <method name="resizeCompleted">
    6416             <desc>
    6417                 Signals that a framebuffer has completed the resize operation.
    6418             </desc>
    6419             <param name="screenId" type="unsigned long" dir="in"/>
    6420         </method>
    6421 
    6422         <method name="updateCompleted">
    6423             <desc>
    6424                 Signals that a framebuffer has completed the update operation.
    6425             </desc>
    6426         </method>
    6427 
    6428     </interface>
    6429 
    6430     <!--
    6431     // INetworkAdapter
    6432     /////////////////////////////////////////////////////////////////////////
    6433     -->
    6434 
    6435     <enum
    6436         name="NetworkAttachmentType"
    6437         uuid="8730d899-d036-4925-bc63-e58f3486f4bf"
    6438     >
    6439         <const name="NoNetworkAttachment"            value="0"/>
    6440         <const name="NATNetworkAttachment"           value="1"/>
    6441         <const name="HostInterfaceNetworkAttachment" value="2"/>
    6442         <const name="InternalNetworkAttachment"      value="3"/>
    6443     </enum>
    6444 
    6445     <enum
    6446         name="NetworkAdapterType"
    6447         uuid="156b17b9-5d61-4d54-be90-62e37dda848d"
    6448     >
    6449         <const name="InvalidNetworkAdapterType"      value="0"/>
    6450         <const name="NetworkAdapterAm79C970A"        value="1"/>
    6451         <const name="NetworkAdapterAm79C973"         value="2"/>
    6452     </enum>
    6453 
    6454     <interface
    6455         name="INetworkAdapter" extends="$unknown"
    6456         uuid="78dfc978-ecb0-44ee-8b20-54549dd4539e"
    6457         wsmap="managed"
    6458     >
    6459         <attribute name="adapterType" type="NetworkAdapterType">
    6460             <desc>
    6461                 Type of the virtual network adapter. Depending on this value,
    6462                 VirtualBox will provide a different virtual network hardware
    6463                 to the guest.
    6464             </desc>
    6465         </attribute>
    6466 
    6467         <attribute name="slot" type="unsigned long" readonly="yes">
    6468             <desc>
    6469                 Slot number this adapter is plugged into. Corresponds to
    6470                 the value you pass to <link to="IMachine::getNetworkAdapter"/>
    6471                 to obtain this instance.
    6472             </desc>
    6473         </attribute>
    6474 
    6475         <attribute name="enabled" type="boolean">
    6476             <desc>
    6477                 Flag whether the network adapter is present in the
    6478                 guest system. If disabled, the virtual guest hardware will
    6479                 not contain this network adapter. Can only be changed when
    6480                 the VM is not running.
    6481             </desc>
    6482         </attribute>
    6483 
    6484         <attribute name="MACAddress" type="wstring">
    6485             <desc>
    6486                 Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
    6487                 it to NULL, VirtualBox will generate a unique MAC address.
    6488             </desc>
    6489         </attribute>
    6490 
    6491         <attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
    6492 
    6493         <attribute name="hostInterface" type="wstring">
    6494             <desc>
    6495                 Name of the Host Network Interface that is currently in use. NULL will be returned
    6496                 if no device has been allocated. On Linux, setting this refers to a permanent TAP
    6497                 device. However, a file descriptor has precedence over the interface name on Linux.
    6498                 Note that when VBox allocates a TAP device, this property will not be set, i.e. the
    6499                 interface name would have to be determined using the file descriptor and /proc/self/fd.
    6500             </desc>
    6501         </attribute>
    6502 
    6503 <if target="xpidl">
    6504         <attribute name="TAPFileDescriptor" type="long">
    6505             <desc>
    6506                 File descriptor of the TAP device. It can either be setup by the caller
    6507                 which has to supply an existing valid file handle allocated in the parent
    6508                 process of the VM process or allocated by VirtualBox. The value is -1 if it
    6509                 has not been defined. This property is non persistent, i.e. it will not be
    6510                 stored in the VM's configuration data and thus has to be set at each startup.
    6511             </desc>
    6512         </attribute>
    6513         <attribute name="TAPSetupApplication" type="wstring">
    6514             <desc>
    6515                 Application to start to configure the TAP device.
    6516                 It is being passed two parameters, 1) the file handle (as ascii),
    6517                 2) the TAP device name if it is available.
    6518             </desc>
    6519         </attribute>
    6520         <attribute name="TAPTerminateApplication" type="wstring">
    6521             <desc>
    6522                 Application to start before closing a TAP device.
    6523                 It is being passed two parameters, 1) the file handle (as ascii),
    6524                 2) the TAP device name if it is available.
    6525             </desc>
    6526         </attribute>
     6779      </param>
     6780      <param name="filter" type="IUSBDeviceFilter" dir="return">
     6781        <desc>Created filter object.</desc>
     6782      </param>
     6783    </method>
     6784
     6785    <method name="insertDeviceFilter">
     6786      <desc>
     6787        Inserts the given USB device to the specified position
     6788        in the list of filters.
     6789
     6790        Positions are numbered starting from <tt>0</tt>. If the specified
     6791        position is equal to or greater than the number of elements in
     6792        the list, the filter is added to the end of the collection.
     6793
     6794        <note>
     6795          Duplicates are not allowed, so an attempt to inster a
     6796          filter that is already in the collection, will return an
     6797          error.
     6798        </note>
     6799
     6800        <see>#DeviceFilters</see>
     6801      </desc>
     6802      <param name="position" type="unsigned long" dir="in">
     6803        <desc>Position to insert the filter to.</desc>
     6804      </param>
     6805      <param name="filter" type="IUSBDeviceFilter" dir="in">
     6806        <desc>USB device filter to insert.</desc>
     6807      </param>
     6808    </method>
     6809
     6810    <method name="removeDeviceFilter">
     6811      <desc>
     6812        Removes a USB device filter from the specified position in the
     6813        list of filters.
     6814
     6815        Positions are numbered starting from <tt>0</tt>. Specifying a
     6816        position equal to or greater than the number of elements in
     6817        the list will produce an error.
     6818
     6819        <see>#DeviceFilters</see>
     6820      </desc>
     6821      <param name="position" type="unsigned long" dir="in">
     6822        <desc>Position to remove the filter from.</desc>
     6823      </param>
     6824      <param name="filter" type="IUSBDeviceFilter" dir="return">
     6825        <desc>Removed USB device filter.</desc>
     6826      </param>
     6827    </method>
     6828
     6829  </interface>
     6830
     6831
     6832  <!--
     6833  // IUSBDevice
     6834  /////////////////////////////////////////////////////////////////////////
     6835  -->
     6836
     6837  <enumerator
     6838     name="IUSBDeviceEnumerator" type="IUSBDevice"
     6839     uuid="aefe00f7-eb8a-454b-9ea4-fd5ad93c0e99"
     6840     />
     6841
     6842  <collection
     6843     name="IUSBDeviceCollection" type="IUSBDevice"
     6844     enumerator="IUSBDeviceEnumerator"
     6845     uuid="e31f3248-90dd-4ca2-95f0-6b36042d96a2"
     6846     readonly="yes"
     6847     >
     6848    <method name="findById">
     6849      <desc>
     6850        Searches this collection for a USB device with the given UUID.
     6851        <note>
     6852          The method returns an error if the given UUID does not
     6853          correspond to any USB device in the collection.
     6854        </note>
     6855        <see>IUSBDevice::id</see>
     6856      </desc>
     6857      <param name="id" type="uuid" dir="in">
     6858        <desc>UUID of the USB device to search for.</desc>
     6859      </param>
     6860      <param name="device" type="IUSBDevice" dir="return">
     6861        <desc>Found USB device object.</desc>
     6862      </param>
     6863    </method>
     6864
     6865    <method name="findByAddress">
     6866      <desc>
     6867        Searches this collection for a USB device with the given
     6868        host address.
     6869        <note>
     6870          The method returns an error if the given address does not
     6871          correspond to any USB device in the collection.
     6872        </note>
     6873        <see>IUSBDevice::address</see>
     6874      </desc>
     6875      <param name="name" type="wstring" dir="in">
     6876        <desc>
     6877          Address of the USB device (as assigned by the host) to
     6878          search for.
     6879        </desc>
     6880      </param>
     6881      <param name="device" type="IUSBDevice" dir="return">
     6882        <desc>Found USB device object.</desc>
     6883      </param>
     6884    </method>
     6885
     6886  </collection>
     6887
     6888  <interface
     6889     name="IUSBDevice" extends="$unknown"
     6890     uuid="c5ab8d05-1999-4e48-ae34-cdeb235aacf0"
     6891     wsmap="managed"
     6892     >
     6893    <desc>
     6894      The IUSBDevice interface represents a USB device captured by
     6895      (attached to) a running virtual machine's USB controller.
     6896      <see>IConsole::USBDevices</see>
     6897    </desc>
     6898
     6899    <attribute name="id" type="uuid" readonly="yes">
     6900      <desc>
     6901        Unique USB device ID. This ID is built from #vendorId,
     6902        #productId, #revision and #serialNumber.
     6903      </desc>
     6904    </attribute>
     6905
     6906    <attribute name="vendorId" type="unsigned short" readonly="yes">
     6907      <desc>Vendor ID.</desc>
     6908    </attribute>
     6909
     6910    <attribute name="productId" type="unsigned short" readonly="yes">
     6911      <desc>Product ID.</desc>
     6912    </attribute>
     6913
     6914    <attribute name="revision" type="unsigned short" readonly="yes">
     6915      <desc>
     6916        Product revision number. This is a packed BCD represented as
     6917        unsigned short. The high byte is the integer part and the low
     6918        byte is the decimal.
     6919      </desc>
     6920    </attribute>
     6921
     6922    <attribute name="manufacturer" type="wstring" readonly="yes">
     6923      <desc>Manufacturer string.</desc>
     6924    </attribute>
     6925
     6926    <attribute name="product" type="wstring" readonly="yes">
     6927      <desc>Product string.</desc>
     6928    </attribute>
     6929
     6930    <attribute name="serialNumber" type="wstring" readonly="yes">
     6931      <desc>Serial number string.</desc>
     6932    </attribute>
     6933
     6934    <attribute name="address" type="wstring" readonly="yes">
     6935      <desc>Host specific address of the device.</desc>
     6936    </attribute>
     6937
     6938    <attribute name="port" type="unsigned short" readonly="yes">
     6939      <desc>
     6940        Host USB port number the device is physically
     6941        coonected to.
     6942      </desc>
     6943    </attribute>
     6944
     6945    <attribute name="remote" type="boolean" readonly="yes">
     6946      <desc>
     6947        Whether the device is physically connected to a remote VRDP
     6948        client or to a local host machine.
     6949      </desc>
     6950    </attribute>
     6951
     6952  </interface>
     6953
     6954
     6955  <!--
     6956  // IUSBDeviceFilter
     6957  /////////////////////////////////////////////////////////////////////////
     6958  -->
     6959
     6960  <enumerator
     6961     name="IUSBDeviceFilterEnumerator" type="IUSBDeviceFilter"
     6962     uuid="8d066d8b-3576-4a22-a387-847840937453"
     6963     />
     6964
     6965  <collection
     6966     name="IUSBDeviceFilterCollection" type="IUSBDeviceFilter"
     6967     enumerator="IUSBDeviceFilterEnumerator"
     6968     uuid="4fa3fc99-ceb1-4bf5-a9cb-e962d825c1ef"
     6969     readonly="yes"
     6970     />
     6971
     6972  <interface
     6973     name="IUSBDeviceFilter" extends="$unknown"
     6974     uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
     6975     wsmap="managed"
     6976     >
     6977    <desc>
     6978      The IUSBDeviceFilter interface represents an USB device filter used
     6979      to perform actions on a group of USB devices.
     6980
     6981      This type of filters is used by running virtual machines to
     6982      automatically capture selected USB devices once they are physically
     6983      attached to the host computer.
     6984
     6985      A USB device is matched to the given device filter if and only if all
     6986      attributes of the device match the corresponding attributes of the
     6987      filter (that is, attributes are joined together using the logical AND
     6988      operation). On the other hand, all together, filters in the list of
     6989      filters carry the semantics of the logical OR operation. So if it is
     6990      desirable to create a match like "this vendor id OR this product id",
     6991      one needs to create two filters and specify "any match" (see below)
     6992      for unused attributes.
     6993
     6994      All filter attributes used for matching are strings. Each string
     6995      is an expression representing a set of values of the corresponding
     6996      device attribute, that will match the given filter. Currently, the
     6997      following filtering expressions are supported:
     6998
     6999      <ul>
     7000        <li><i>Interval filters</i>. Used to specify valid intervals for
     7001          integer device attributes (Vendor ID, Product ID and Revision).
     7002          The format of the string is:
     7003
     7004          <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt>
     7005
     7006          where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
     7007          (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
     7008          or decimal (otherwise) form, so that <tt>m &lt; n</tt>. If <tt>m</tt>
     7009          is ommitted before a dash (<tt>-</tt>), the minimum possible integer
     7010          is assumed; if <tt>n</tt> is ommitted after a dash, the maximum
     7011          possible integer is assummed.
     7012        </li>
     7013        <li><i>Boolean filters</i>. Used to specify acceptable values for
     7014          boolean device attributes. The format of the string is:
     7015
     7016          <tt>true|false|yes|no|0|1</tt>
     7017
     7018        </li>
     7019        <li><i>Exact match</i>. Used to specify a single value for the given
     7020          device attribute. Any string that does't start with <tt>int:</tt>
     7021          represents the exact match. String device attributes are compared to
     7022          this string including case of symbols. Integer attributes are first
     7023          converted to a string (see individual filter attributes) and then
     7024          compared ignoring case.
     7025
     7026        </li>
     7027        <li><i>Any match</i>. Any value of the corresponding device attribute
     7028          will match the given filter. An empty or <tt>null</tt> string is
     7029          used to construct this type of filtering expressions.
     7030
     7031        </li>
     7032      </ul>
     7033
     7034      <note>
     7035        On the Windows host platform, interval filters are not currently
     7036        available. Also all string filter attributes
     7037        (<link to="#manufacturer"/>, <link to="#product"/>,
     7038        <link to="#serialNumber"/>) are ignored, so they behave as
     7039        <i>any match</i> no matter what string expression is specified.
     7040      </note>
     7041
     7042      <see>IUSBController::DeviceFilters, IHostUSBDeviceFilter</see>
     7043    </desc>
     7044
     7045    <attribute name="name" type="wstring">
     7046      <desc>
     7047        Visible name for this filter.
     7048        This name is used to visually distungish one filter from another,
     7049        so it can neither be <tt>null</tt> nor an empty string.
     7050      </desc>
     7051    </attribute>
     7052
     7053    <attribute name="active" type="boolean">
     7054      <desc>Whether this filter active or has been temporarily disabled.</desc>
     7055    </attribute>
     7056
     7057    <attribute name="vendorId" type="wstring">
     7058      <desc>
     7059        <link to="IUSBDevice::vendorId">Vendor ID</link> filter.
     7060        The string representation for the <i>exact matching</i>
     7061        has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
     7062        (including leading zeroes).
     7063      </desc>
     7064    </attribute>
     7065
     7066    <attribute name="productId" type="wstring">
     7067      <desc>
     7068        <link to="IUSBDevice::productId">Product ID</link> filter.
     7069        The string representation for the <i>exact matching</i>
     7070        has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
     7071        (including leading zeroes).
     7072      </desc>
     7073    </attribute>
     7074
     7075    <attribute name="revision" type="wstring">
     7076      <desc>
     7077        <link to="IUSBDevice::productId">Product revision number</link>
     7078        filter. The string representation for the <i>exact matching</i>
     7079        has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
     7080        of the integer part of the revision, and <tt>F</tt> is the
     7081        decimal digit of its fractional part (including leading and
     7082        trailing zeroes).
     7083        Note that for interval filters, it's best to use the hexadecimal
     7084        form, because the revision is stored as a 16 bit packed BCD value;
     7085        so the expression <tt>int:0x0100-0x0199</tt> will match any
     7086        revision from <tt>1.0</tt> to <tt>1.99</tt>.
     7087      </desc>
     7088    </attribute>
     7089
     7090    <attribute name="manufacturer" type="wstring">
     7091      <desc>
     7092        <link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
     7093      </desc>
     7094    </attribute>
     7095
     7096    <attribute name="product" type="wstring">
     7097      <desc>
     7098        <link to="IUSBDevice::product">Product</link> filter.
     7099      </desc>
     7100    </attribute>
     7101
     7102    <attribute name="serialNumber" type="wstring">
     7103      <desc>
     7104        <link to="IUSBDevice::serialNumber">Serial number</link> filter.
     7105      </desc>
     7106    </attribute>
     7107
     7108    <attribute name="port" type="wstring">
     7109      <desc>
     7110        <link to="IUSBDevice::port">Host USB port</link> filter.
     7111      </desc>
     7112    </attribute>
     7113
     7114    <attribute name="remote" type="wstring">
     7115      <desc>
     7116        <link to="IUSBDevice::remote">Remote state</link> filter.
     7117        <note>
     7118          This filter makes sense only for machine USB filters,
     7119          i.e. it is ignored by IHostUSBDeviceFilter objects.
     7120        </note>
     7121      </desc>
     7122    </attribute>
     7123
     7124  </interface>
     7125
     7126
     7127  <!--
     7128  // IHostUSBDevice
     7129  /////////////////////////////////////////////////////////////////////////
     7130  -->
     7131
     7132  <enum
     7133     name="USBDeviceState"
     7134     uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
     7135     >
     7136    <desc>
     7137      USB device state. This enumeration represents all possible states
     7138      of the USB device physically attached to the host computer regarding
     7139      its state on the host computer and availability to guest computers
     7140      (all currently running virtual machines).
     7141
     7142      Once a supported USB device is attached to the host, global USB
     7143      filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
     7144      either ignore the device, or put ot to #USBDeviceHeld state, or do
     7145      nothing. Unless the device is ignored by global filters, filters of
     7146      all currently running guests (<link to="IUSBController::DeviceFilters"/>)
     7147      are activated that can put it to #USBDeviceCaptured state.
     7148
     7149      If the device was ignored by global filters, or didn't match
     7150      any filters at all (including guest ones), it is handled by the host
     7151      in a normal way. In this case, the device state is determined by
     7152      the host and can be one of #USBDeviceUnavailable, #USBDeviceBusy or
     7153      #USBDeviceAvailable, depending on the current device usage.
     7154
     7155      Besides auto-capturing based on filters, the device can be manually
     7156      captured by guests (<link to="IConsole::attachUSBDevice()"/>) if its
     7157      state is #USBDeviceBusy, #USBDeviceAvailable or #USBDeviceHeld.
     7158
     7159      <note>
     7160        Due to differences in USB stack implementations in Linux and Win32,
     7161        states #USBDeviceBusy and #USBDeviceAvailable are applicable
     7162        only to the Linux version of the product. This also means that
     7163        (<link to="IConsole::attachUSBDevice()"/>) can only succeed
     7164        on Win32 if the device state is #USBDeviceHeld.
     7165      </note>
     7166
     7167      <see>IHostUSBDevice, IHostUSBDeviceFilter</see>
     7168    </desc>
     7169
     7170    <const name="USBDeviceNotSupported" value="0">
     7171      <desc>
     7172        Not supported by the VirtualBox server, not available to guests.
     7173      </desc>
     7174    </const>
     7175    <const name="USBDeviceUnavailable"  value="1">
     7176      <desc>
     7177        Being used by the host computer exclusively,
     7178        not available to guests.
     7179      </desc>
     7180    </const>
     7181    <const name="USBDeviceBusy"         value="2">
     7182      <desc>
     7183        Being used by the host computer, potentially available to guests.
     7184      </desc>
     7185    </const>
     7186    <const name="USBDeviceAvailable"    value="3">
     7187      <desc>
     7188        Not used by the host computer, available to guests.
     7189        The host computer can also start using the device at any time.
     7190      </desc>
     7191    </const>
     7192    <const name="USBDeviceHeld"         value="4">
     7193      <desc>
     7194        Held by the VirtualBox server (ignored by the host computer),
     7195        available to guests.
     7196      </desc>
     7197    </const>
     7198    <const name="USBDeviceCaptured"     value="5">
     7199      <desc>
     7200        Captured by one of the guest computers, not available
     7201        to anybody else.
     7202      </desc>
     7203    </const>
     7204  </enum>
     7205
     7206  <enumerator
     7207     name="IHostUSBDeviceEnumerator" type="IHostUSBDevice"
     7208     uuid="a0c55136-939f-4d20-b9d3-4d406f08bfa5"
     7209     />
     7210
     7211  <collection
     7212     name="IHostUSBDeviceCollection" type="IHostUSBDevice"
     7213     enumerator="IHostUSBDeviceEnumerator"
     7214     uuid="f9d3f96d-b027-4994-b589-70bb9ee0d364"
     7215     readonly="yes"
     7216     >
     7217    <method name="findById">
     7218      <desc>
     7219        Searches this collection for a USB device with the given UUID.
     7220        <note>
     7221          The method returns an error if the given UUID does not
     7222          correspond to any USB device in the collection.
     7223        </note>
     7224        <see>IHostUSBDevice::id</see>
     7225      </desc>
     7226      <param name="id" type="uuid" dir="in">
     7227        <desc>UUID of the USB device to search for.</desc>
     7228      </param>
     7229      <param name="device" type="IHostUSBDevice" dir="return">
     7230        <desc>Found USB device object.</desc>
     7231      </param>
     7232    </method>
     7233
     7234    <method name="findByAddress">
     7235      <desc>
     7236        Searches this collection for a USB device with the given
     7237        host address.
     7238        <note>
     7239          The method returns an error if the given address does not
     7240          correspond to any USB device in the collection.
     7241        </note>
     7242        <see>IHostUSBDevice::address</see>
     7243      </desc>
     7244      <param name="name" type="wstring" dir="in">
     7245        <desc>
     7246          Address of the USB device (as assigned by the host) to
     7247          search for.
     7248        </desc>
     7249      </param>
     7250      <param name="device" type="IHostUSBDevice" dir="return">
     7251        <desc>Found USB device object.</desc>
     7252      </param>
     7253    </method>
     7254
     7255  </collection>
     7256
     7257  <interface
     7258     name="IHostUSBDevice" extends="IUSBDevice"
     7259     uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
     7260     wsmap="managed"
     7261     >
     7262    <desc>
     7263      The IHostUSBDevice interface represents a USB device attached to
     7264      the host computer.
     7265
     7266      Among with properties inherited from IUSBDevice,
     7267      this interface adds the <link to="#state"/> property
     7268      that holds the courrent state of the USB device.
     7269
     7270      <see>IHost::USBDevices, IHost::USBDeviceFilters</see>
     7271    </desc>
     7272
     7273    <attribute name="state" type="USBDeviceState" readonly="yes">
     7274      <desc>
     7275        Current state of the device.
     7276      </desc>
     7277    </attribute>
     7278
     7279    <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
     7280
     7281  </interface>
     7282
     7283
     7284  <!--
     7285  // IHostUSBDeviceFilter
     7286  /////////////////////////////////////////////////////////////////////////
     7287  -->
     7288
     7289  <enum
     7290     name="USBDeviceFilterAction"
     7291     uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
     7292     >
     7293    <desc>
     7294      Actions for host USB device filters.
     7295      <see>IHostUSBDeviceFilter, USBDeviceState</see>
     7296    </desc>
     7297
     7298    <const name="InvalidUSBDeviceFilterAction"  value="0"/>
     7299    <const name="USBDeviceFilterIgnore"         value="1">
     7300      <desc>Ignore the matched USB device.</desc>
     7301    </const>
     7302    <const name="USBDeviceFilterHold"           value="2">
     7303      <desc>Hold the matched USB device.</desc>
     7304    </const>
     7305  </enum>
     7306
     7307  <enumerator
     7308     name="IHostUSBDeviceFilterEnumerator" type="IHostUSBDeviceFilter"
     7309     uuid="ff735211-903e-4642-9c37-189eb44579fe"
     7310     />
     7311
     7312  <collection
     7313     name="IHostUSBDeviceFilterCollection" type="IHostUSBDeviceFilter"
     7314     enumerator="IHostUSBDeviceFilterEnumerator"
     7315     uuid="1a80458b-87f1-4a74-995d-04e2330119e0"
     7316     readonly="yes"
     7317     />
     7318
     7319  <interface
     7320     name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
     7321     uuid="4cc70246-d74a-400f-8222-3900489c0374"
     7322     wsmap="managed"
     7323     >
     7324    <desc>
     7325      The IHostUSBDeviceFilter interface represents a USB device filter used
     7326      by the host computer.
     7327
     7328      Using filters of this type, the host computer determines the initial
     7329      state of the USB device after it is physically attached to the
     7330      host's USB controller.
     7331
     7332      <note>
     7333        The <link to="#remote"/> attribute is ignored by this type of
     7334        filters, because it makes sense only for
     7335        <link to="IUSBController::DeviceFilters">machine USB filters</link>.
     7336      </note>
     7337
     7338      <see>IHost::USBDeviceFilters</see>
     7339    </desc>
     7340
     7341    <attribute name="action" type="USBDeviceFilterAction">
     7342      <desc>
     7343        Action performed by the host when an attached USB device
     7344        matches this filter.
     7345      </desc>
     7346    </attribute>
     7347
     7348  </interface>
     7349
     7350  <!--
     7351  // IAudioAdapter
     7352  /////////////////////////////////////////////////////////////////////////
     7353  -->
     7354
     7355  <enum
     7356     name="AudioDriverType"
     7357     uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
     7358     >
     7359    <const name="NullAudioDriver"   value="0"/>
     7360    <const name="WINMMAudioDriver"  value="1"/>
     7361    <const name="OSSAudioDriver"    value="2"/>
     7362    <const name="ALSAAudioDriver"   value="3"/>
     7363    <const name="DSOUNDAudioDriver" value="4"/>
     7364    <const name="CoreAudioDriver"   value="5"/>
     7365    <const name="MMPMAudioDriver"   value="5"/>
     7366  </enum>
     7367
     7368  <interface
     7369     name="IAudioAdapter" extends="$unknown"
     7370     uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
     7371     wsmap="struct"
     7372     >
     7373    <attribute name="enabled" type="boolean">
     7374      <desc>
     7375        Flag whether the audio adapter is present in the
     7376        guest system. If disabled, the virtual guest hardware will
     7377        not contain any audio adapter. Can only be changed when
     7378        the VM is not running.
     7379      </desc>
     7380    </attribute>
     7381    <attribute name="audioDriver" type="AudioDriverType">
     7382      <desc>
     7383        Audio driver the adapter is connected to. This setting
     7384        can only be changed when the VM is not running.
     7385      </desc>
     7386    </attribute>
     7387  </interface>
     7388
     7389  <!--
     7390  // IVRDPServer
     7391  /////////////////////////////////////////////////////////////////////////
     7392  -->
     7393
     7394  <enum
     7395     name="VRDPAuthType"
     7396     uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
     7397     >
     7398    <const name="VRDPAuthNull"            value="0"/>
     7399    <const name="VRDPAuthExternal"        value="1"/>
     7400    <const name="VRDPAuthGuest"           value="2"/>
     7401  </enum>
     7402
     7403  <interface
     7404     name="IVRDPServer" extends="$unknown"
     7405     uuid="ed9d31ae-867f-45fc-b727-6740084d1883"
     7406     wsmap="struct"
     7407     >
     7408    <attribute name="enabled" type="boolean">
     7409      <desc>VRDP server status.</desc>
     7410    </attribute>
     7411
     7412    <attribute name="port" type="unsigned long">
     7413      <desc>VRDP server port.</desc>
     7414    </attribute>
     7415
     7416    <attribute name="netAddress" type="wstring">
     7417      <desc>VRDP server address.</desc>
     7418    </attribute>
     7419
     7420    <attribute name="authType" type="VRDPAuthType">
     7421      <desc>VRDP authentication method.</desc>
     7422    </attribute>
     7423
     7424    <attribute name="authTimeout" type="unsigned long">
     7425      <desc>Timeout for guest authentication. Milliseconds.</desc>
     7426    </attribute>
     7427
     7428    <attribute name="allowMultiConnection" type="boolean">
     7429      <desc>
     7430        Flag whether multiple simultaneous connections to the VM are permitted.
     7431        Note that this will be replaced by a more powerful mechanism in the future.
     7432      </desc>
     7433    </attribute>
     7434
     7435  </interface>
     7436
     7437
     7438  <!--
     7439  // ISharedFolder
     7440  /////////////////////////////////////////////////////////////////////////
     7441  -->
     7442
     7443  <enumerator
     7444     name="ISharedFolderEnumerator" type="ISharedFolder"
     7445     uuid="1d420fd8-e7c1-4511-abf4-a504dc6d0cbf"
     7446     />
     7447
     7448  <collection
     7449     name="ISharedFolderCollection" type="ISharedFolder"
     7450     enumerator="ISharedFolderEnumerator"
     7451     uuid="9c7e2282-bb16-4fa7-9138-f383c5e02353"
     7452     readonly="yes">
     7453
     7454    <method name="findByName">
     7455      <desc>
     7456        Searches this collection for a shared folder drive with the
     7457        given logical name.
     7458        <note>
     7459          The method returns an error if the given name does not
     7460          correspond to any shared folder in the collection.
     7461        </note>
     7462      </desc>
     7463      <param name="name" type="wstring" dir="in">
     7464        <desc>Logical name of the shared folder to search for</desc>
     7465      </param>
     7466      <param name="sharedFolder" type="ISharedFolder" dir="return">
     7467        <desc>Found shared folder object</desc>
     7468      </param>
     7469    </method>
     7470
     7471  </collection>
     7472
     7473  <interface
     7474     name="ISharedFolder" extends="$unknown"
     7475     uuid="8b0c5f70-9139-4f97-a421-64d5e9c335d5"
     7476     wsmap="struct"
     7477     >
     7478    <desc>
     7479      The ISharedFolder interface represents a folder in the host
     7480      computer's file system accessible from a guest OS running inside a
     7481      virtual machine using an associated logical name.
     7482
     7483      There are three types of shared folders:
     7484      <ul>
     7485        <li>permanent (<link to="IMachine::sharedFolders"/>)</li>
     7486        <li>transient (<link to="IConsole::sharedFolders"/>)</li>
     7487        <li>global (<link to="IVirtualBox::sharedFolders"/>)</li>
     7488      </ul>
     7489
     7490      For a given virtual machine, both permanently and transiently
     7491      shared folders have the same logical name space which also includes
     7492      all globally shared folders. Thus, every folder in this name space
     7493      must have an unique logical name. Note that permanent and transient
     7494      shares of other machines are in different name spaces, so they don't
     7495      have to have unique names.
     7496    </desc>
     7497
     7498    <attribute name="name" type="wstring" readonly="yes">
     7499      <desc>Logical name of the shared folder.</desc>
     7500    </attribute>
     7501
     7502    <attribute name="hostPath" type="wstring" readonly="yes">
     7503      <desc>Full path to the shared folder in the host file system.</desc>
     7504    </attribute>
     7505
     7506    <attribute name="accessible" type="boolean" readonly="yes">
     7507      <desc>
     7508        Whether the folder defined by the host path is currently
     7509        accessible or not.
     7510        For example, the folder can be unaccessible if it is placed
     7511        on the network share that is not available by the time
     7512        this property is read.
     7513      </desc>
     7514    </attribute>
     7515
     7516  </interface>
     7517
     7518  <!--
     7519  // ISession
     7520  /////////////////////////////////////////////////////////////////////////
     7521  -->
     7522
     7523  <interface
     7524     name="IInternalSessionControl" extends="$unknown"
     7525     uuid="80a9b698-cc60-48cf-ab88-a7c2ea4013a6"
     7526     internal="yes"
     7527     wsmap="suppress"
     7528     >
     7529    <method name="getPID">
     7530      <desc>PID of the process that has created this Session object.
     7531      </desc>
     7532      <param name="pid" type="unsigned long" dir="return"/>
     7533    </method>
     7534
     7535    <method name="getRemoteConsole">
     7536      <desc>Returns the console object suitable for remote control.</desc>
     7537      <param name="console" type="IConsole" dir="return"/>
     7538    </method>
     7539
     7540    <method name="assignMachine">
     7541      <desc>
     7542        Assigns the machine object associated with this direct-type
     7543        session or informs the session that it will be a remote one
     7544        (if machine = NULL).
     7545      </desc>
     7546      <param name="machine" type="IMachine" dir="in"/>
     7547    </method>
     7548
     7549    <method name="assignRemoteMachine">
     7550      <desc>
     7551        Assigns the machine and the (remote) console object associated with
     7552        this remote-type session.
     7553      </desc>
     7554      <param name="machine" type="IMachine" dir="in"/>
     7555      <param name="console" type="IConsole" dir="in"/>
     7556    </method>
     7557
     7558    <method name="updateMachineState">
     7559      <desc>
     7560        Updates the machine state in the VM process.
     7561        Must be called only in certain cases
     7562        (see the method implementation).
     7563      </desc>
     7564      <param name="aMachineState" type="MachineState" dir="in"/>
     7565    </method>
     7566
     7567    <method name="uninitialize">
     7568      <desc>
     7569        Uninitializes (closes) this session. Used by VirtualBox to close
     7570        the corresponding remote session when the direct session dies
     7571        or gets closed.
     7572      </desc>
     7573    </method>
     7574
     7575    <method name="onDVDDriveChange">
     7576      <desc>
     7577        Triggered when settings of the DVD drive object of the
     7578        associated virtual machine have changed.
     7579      </desc>
     7580    </method>
     7581
     7582    <method name="onFloppyDriveChange">
     7583      <desc>
     7584        Triggered when settings of the floppy drive object of the
     7585        associated virtual machine have changed.
     7586      </desc>
     7587    </method>
     7588
     7589    <method name="onNetworkAdapterChange">
     7590      <desc>
     7591        Triggered when settions of a network adapter of the
     7592        associated virtual machine have changed.
     7593      </desc>
     7594      <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
     7595    </method>
     7596
     7597    <method name="onVRDPServerChange">
     7598      <desc>
     7599        Triggered when settings of the VRDP server object of the
     7600        associated virtual machine have changed.
     7601      </desc>
     7602    </method>
     7603
     7604    <method name="onUSBControllerChange">
     7605      <desc>
     7606        Triggered when settings of the USB controller object of the
     7607        associated virtual machine have changed.
     7608      </desc>
     7609    </method>
     7610
     7611    <method name="onUSBDeviceAttach">
     7612      <desc>
     7613        Triggered when a request to capture a USB device (as a result
     7614        of matched USB filters or direct call to
     7615        <link to="IConsole::attachUSBDevice"/>) has completed.
     7616        A @c null @a error object means success, otherwise it
     7617        describes a failure.
     7618      </desc>
     7619      <param name="device" type="IUSBDevice" dir="in"/>
     7620      <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
     7621    </method>
     7622
     7623    <method name="onUSBDeviceDetach">
     7624      <desc>
     7625        Triggered when a request to release the USB device (as a result
     7626        of machine termination or direct call to
     7627        <link to="IConsole::detachUSBDevice"/>) has completed.
     7628        A @c null @a error object means success, otherwise it
     7629      </desc>
     7630      <param name="id" type="uuid" dir="in"/>
     7631      <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
     7632    </method>
     7633
     7634    <method name="onShowWindow">
     7635      <desc>
     7636        Called by <link to="IMachine::canShowConsoleWindow()"/> and by
     7637        <link to="IMachine::showConsoleWindow()"/> in order to notify
     7638        console callbacks
     7639        <link to="IConsoleCallback::onCanShowWindow()"/>
     7640        and <link to="IConsoleCallback::onShowWindow()"/>.
     7641      </desc>
     7642      <param name="check" type="boolean" dir="in"/>
     7643      <param name="canShow" type="boolean" dir="out"/>
     7644      <param name="winId" type="unsigned long long" dir="out"/>
     7645    </method>
     7646
     7647  </interface>
     7648
     7649  <interface
     7650     name="ISession" extends="$dispatched"
     7651     uuid="12F4DCDB-12B2-4ec1-B7CD-DDD9F6C5BF4D"
     7652     wsmap="managed"
     7653     >
     7654    <attribute name="state" type="SessionState" readonly="yes">
     7655      <desc>Current state of this session.</desc>
     7656    </attribute>
     7657
     7658    <attribute name="type" type="SessionType" readonly="yes">
     7659      <desc>
     7660        Type of this session. The value of this attribute is valid only
     7661        if the session is currently open (i.e. its #state is SessionType::SessionOpen),
     7662        otherwise an error will be returned.
     7663      </desc>
     7664    </attribute>
     7665
     7666    <attribute name="machine" type="IMachine" readonly="yes">
     7667      <desc>Machine object associated with this session.</desc>
     7668    </attribute>
     7669
     7670    <attribute name="console" type="IConsole" readonly="yes">
     7671      <desc>Console object associated with this session.</desc>
     7672    </attribute>
     7673
     7674    <method name="close">
     7675      <desc>
     7676        Closes this session.
     7677        <note>
     7678          If a direct session for a machine opened with
     7679          <link to="IVirtualBox::openSession()"/> is not explicitly
     7680          closed when the application terminates, the state of the
     7681          machine will be set to <link to="MachineState::Aborted"/>
     7682          on the server. Generally, it is recommended to close all
     7683          open sessions explicitly before terminating the application
     7684          (no matter what is the reason of the termination).
     7685        </note>
     7686      </desc>
     7687    </method>
     7688
     7689  </interface>
     7690
     7691  <class name="Session" uuid="3C02F46D-C9D2-4f11-A384-53F0CF917214"
     7692         namespace="virtualbox.org">
     7693    <interface name="ISession" default="yes"/>
     7694  </class>
     7695
     7696<if target="wsdl">
     7697
     7698  <!--
     7699  // IManagedObjectRef
     7700  /////////////////////////////////////////////////////////////////////////
     7701  -->
     7702
     7703  <interface
     7704     name="IManagedObjectRef" extends="$unknown"
     7705     uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
     7706     internal="yes"
     7707     wsmap="explicit"
     7708     >
     7709    <method name="getInterfaceName">
     7710      <desc>
     7711        Returns the name of the interface that this managed object represents,
     7712        for example, "IMachine", as a string.
     7713      </desc>
     7714    </method>
     7715
     7716    <method name="release">
     7717      <desc>
     7718        Releases this managed object reference and frees the resources that
     7719        were allocated for it in the web service server process. After calling
     7720        this method, the identifier of the reference can no longer be used.
     7721      </desc>
     7722    </method>
     7723
     7724  </interface>
     7725
    65277726</if>
    65287727
    6529         <attribute name="internalNetwork" type="wstring">
    6530             <desc>
    6531                 Name of the internal network the VM is attached to.
    6532             </desc>
    6533         </attribute>
    6534 
    6535         <attribute name="cableConnected" type="boolean">
    6536             <desc>
    6537                 Flag whether the adapter reports the cable as connected or not.
    6538                 It can be used to report offline situations to a VM.
    6539             </desc>
    6540         </attribute>
    6541 
    6542         <attribute name="traceEnabled" type="boolean">
    6543             <desc>
    6544                 Flag whether network traffic from/to the network card should be traced.
    6545                 Can only be toggled when the VM is turned off.
    6546             </desc>
    6547         </attribute>
    6548 
    6549         <attribute name="traceFile" type="wstring">
    6550             <desc>
    6551                 Filename where a network trace will be stored. If not set, VBox-pid.pcap
    6552                 will be used.
    6553             </desc>
    6554         </attribute>
    6555 
    6556         <method name="attachToNAT">
    6557             <desc>
    6558                 Attach the network adapter to the Network Address Translation (NAT) interface.
    6559             </desc>
    6560         </method>
    6561 
    6562         <method name="attachToHostInterface">
    6563             <desc>
    6564                 Attach the network adapter to a host interface. On Linux, the TAP
    6565                 setup application will be executed if configured and unless a device
    6566                 name and/or file descriptor has been set, a new TAP interface will be
    6567                 created.
    6568             </desc>
    6569         </method>
    6570 
    6571         <method name="attachToInternalNetwork">
    6572             <desc>
    6573                 Attach the network adapter to an internal network.
    6574             </desc>
    6575         </method>
    6576 
    6577         <method name="detach">
    6578             <desc>
    6579                 Detach the network adapter
    6580             </desc>
    6581         </method>
    6582     </interface>
    6583 
    6584 
    6585     <!--
    6586     // IMachineDebugger
    6587     /////////////////////////////////////////////////////////////////////////
    6588     -->
    6589 
    6590     <interface
    6591         name="IMachineDebugger" extends="$unknown"
    6592         uuid="288da658-74fa-4877-ab5c-dafdad19a1cd"
    6593         wsmap="suppress"
    6594     >
    6595         <method name="resetStats">
    6596             <desc>
    6597                 Reset VM statistics.
    6598             </desc>
    6599         </method>
    6600 
    6601         <method name="dumpStats">
    6602             <desc>
    6603                 Dumps VM statistics.
    6604             </desc>
    6605         </method>
    6606 
    6607         <attribute name="singlestep" type="boolean">
    6608             <desc>Switch for enabling singlestepping.</desc>
    6609         </attribute>
    6610 
    6611         <attribute name="recompileUser" type="boolean">
    6612             <desc>Switch for forcing code recompilation for user mode code.</desc>
    6613         </attribute>
    6614 
    6615         <attribute name="recompileSupervisor" type="boolean">
    6616             <desc>Switch for forcing code recompilation for supervisor mode code.</desc>
    6617         </attribute>
    6618 
    6619         <attribute name="PATMEnabled" type="boolean">
    6620             <desc>Switch for enabling and disabling the PATM component.</desc>
    6621         </attribute>
    6622 
    6623         <attribute name="CSAMEnabled" type="boolean">
    6624             <desc>Switch for enabling and disabling the CSAM component.</desc>
    6625         </attribute>
    6626 
    6627         <attribute name="LogEnabled" type="boolean">
    6628             <desc>Switch for enabling and disabling logging.</desc>
    6629         </attribute>
    6630 
    6631         <attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
    6632             <desc>
    6633                 Flag indicating whether the VM is currently making use of CPU hardware
    6634                 virtualization extensions
    6635             </desc>
    6636         </attribute>
    6637 
    6638         <attribute name="VirtualTimeRate" type="unsigned long">
    6639             <desc>
    6640                 The rate at which the virtual time runs expressed as a percentage.
    6641                 The accepted range is 2% to 20000%.
    6642             </desc>
    6643         </attribute>
    6644 
    6645         <!-- @todo method for setting log flags, groups and destination! -->
    6646 
    6647         <attribute name="VM" type="unsigned long long" readonly="yes">
    6648             <desc>
    6649                 Gets the VM handle. This is only for internal use while
    6650                 we carve the details of this interface.
    6651             </desc>
    6652         </attribute>
    6653 
    6654     </interface>
    6655 
    6656     <!--
    6657     // IUSBController
    6658     /////////////////////////////////////////////////////////////////////////
    6659     -->
    6660 
    6661     <interface
    6662         name="IUSBController" extends="$unknown"
    6663         uuid="9a110c34-93c2-46b0-8ac2-b09d1067be56"
    6664         wsmap="managed"
    6665     >
    6666         <attribute name="enabled" type="boolean">
    6667             <desc>
    6668                 Flag whether the USB controller is present in the
    6669                 guest system. If disabled, the virtual guest hardware will
    6670                 not contain any USB controller. Can only be changed when
    6671                 the VM is powered off.
    6672             </desc>
    6673         </attribute>
    6674 
    6675         <attribute name="USBStandard" type="unsigned short" readonly="yes">
    6676             <desc>
    6677                 USB standard version which the controller implements.
    6678                 This is a BCD which means that the major version is in the
    6679                 high byte and minor version is in the low byte.
    6680             </desc>
    6681         </attribute>
    6682 
    6683         <attribute name="DeviceFilters" type="IUSBDeviceFilterCollection" readonly="yes">
    6684             <desc>
    6685                 List of USB device filters associated with the machine.
    6686 
    6687                 If the machine is currently running, these filters are activated
    6688                 every time a new (supported) USB device is attached to the host
    6689                 computer that was not ignored by global filters
    6690                 (<link to="IHost::USBDeviceFilters"/>).
    6691 
    6692                 These filters are also activated when the machine is powered up.
    6693                 They are run against a list of all currently available USB
    6694                 devices (in states
    6695                 <link to="USBDeviceState::USBDeviceAvailable">USBDeviceAvailable</link>,
    6696                 <link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,
    6697                 <link to="USBDeviceState::USBDeviceHeld">USBDeviceHeld</link>)
    6698                 that were not previously ignored by global filters.
    6699 
    6700                 If at least one filter matches the USB device in question, this
    6701                 device is automatically captured (attached to) the virtual USB
    6702                 controller of this machine.
    6703 
    6704                 <see>IUSBDeviceFilter, ::IUSBController</see>
    6705             </desc>
    6706         </attribute>
    6707 
    6708         <method name="createDeviceFilter">
    6709             <desc>
    6710                 Creates a new USB device filter. All attributes except
    6711                 the filter name are set to <tt>null</tt> (any match),
    6712                 <i>active</i> is <tt>false</tt> (the filter is not active).
    6713 
    6714                 The created filter can then be added to the list of filters using
    6715                 <link to="#insertDeviceFilter()"/>.
    6716 
    6717                 <see>#DeviceFilters</see>
    6718             </desc>
    6719             <param name="name" type="wstring" dir="in">
    6720                 <desc>
    6721                     Filter name. See <link to="IUSBDeviceFilter::name"/>
    6722                     for more info.
    6723                 </desc>
    6724             </param>
    6725             <param name="filter" type="IUSBDeviceFilter" dir="return">
    6726                 <desc>Created filter object.</desc>
    6727             </param>
    6728         </method>
    6729 
    6730         <method name="insertDeviceFilter">
    6731             <desc>
    6732                 Inserts the given USB device to the specified position
    6733                 in the list of filters.
    6734 
    6735                 Positions are numbered starting from <tt>0</tt>. If the specified
    6736                 position is equal to or greater than the number of elements in
    6737                 the list, the filter is added to the end of the collection.
    6738 
    6739                 <note>
    6740                     Duplicates are not allowed, so an attempt to inster a
    6741                     filter that is already in the collection, will return an
    6742                     error.
    6743                 </note>
    6744 
    6745                 <see>#DeviceFilters</see>
    6746             </desc>
    6747             <param name="position" type="unsigned long" dir="in">
    6748                 <desc>Position to insert the filter to.</desc>
    6749             </param>
    6750             <param name="filter" type="IUSBDeviceFilter" dir="in">
    6751                 <desc>USB device filter to insert.</desc>
    6752             </param>
    6753         </method>
    6754 
    6755         <method name="removeDeviceFilter">
    6756             <desc>
    6757                 Removes a USB device filter from the specified position in the
    6758                 list of filters.
    6759 
    6760                 Positions are numbered starting from <tt>0</tt>. Specifying a
    6761                 position equal to or greater than the number of elements in
    6762                 the list will produce an error.
    6763 
    6764                 <see>#DeviceFilters</see>
    6765             </desc>
    6766             <param name="position" type="unsigned long" dir="in">
    6767                 <desc>Position to remove the filter from.</desc>
    6768             </param>
    6769             <param name="filter" type="IUSBDeviceFilter" dir="return">
    6770                 <desc>Removed USB device filter.</desc>
    6771             </param>
    6772         </method>
    6773 
    6774     </interface>
    6775 
    6776 
    6777     <!--
    6778     // IUSBDevice
    6779     /////////////////////////////////////////////////////////////////////////
    6780     -->
    6781 
    6782     <enumerator
    6783         name="IUSBDeviceEnumerator" type="IUSBDevice"
    6784         uuid="aefe00f7-eb8a-454b-9ea4-fd5ad93c0e99"
    6785     />
    6786 
    6787     <collection
    6788         name="IUSBDeviceCollection" type="IUSBDevice"
    6789         enumerator="IUSBDeviceEnumerator"
    6790         uuid="e31f3248-90dd-4ca2-95f0-6b36042d96a2"
    6791         readonly="yes"
    6792     >
    6793         <method name="findById">
    6794             <desc>
    6795                 Searches this collection for a USB device with the given UUID.
    6796                 <note>
    6797                     The method returns an error if the given UUID does not
    6798                     correspond to any USB device in the collection.
    6799                 </note>
    6800                 <see>IUSBDevice::id</see>
    6801             </desc>
    6802             <param name="id" type="uuid" dir="in">
    6803                 <desc>UUID of the USB device to search for.</desc>
    6804             </param>
    6805             <param name="device" type="IUSBDevice" dir="return">
    6806                 <desc>Found USB device object.</desc>
    6807             </param>
    6808         </method>
    6809 
    6810         <method name="findByAddress">
    6811             <desc>
    6812                 Searches this collection for a USB device with the given
    6813                 host address.
    6814                 <note>
    6815                     The method returns an error if the given address does not
    6816                     correspond to any USB device in the collection.
    6817                 </note>
    6818                 <see>IUSBDevice::address</see>
    6819             </desc>
    6820             <param name="name" type="wstring" dir="in">
    6821                 <desc>
    6822                     Address of the USB device (as assigned by the host) to
    6823                     search for.
    6824                 </desc>
    6825             </param>
    6826             <param name="device" type="IUSBDevice" dir="return">
    6827                 <desc>Found USB device object.</desc>
    6828             </param>
    6829         </method>
    6830 
    6831     </collection>
    6832 
    6833     <interface
    6834         name="IUSBDevice" extends="$unknown"
    6835         uuid="c5ab8d05-1999-4e48-ae34-cdeb235aacf0"
    6836         wsmap="managed"
    6837     >
    6838         <desc>
    6839             The IUSBDevice interface represents a USB device captured by
    6840             (attached to) a running virtual machine's USB controller.
    6841             <see>IConsole::USBDevices</see>
    6842         </desc>
    6843 
    6844         <attribute name="id" type="uuid" readonly="yes">
    6845             <desc>
    6846                 Unique USB device ID. This ID is built from #vendorId,
    6847                 #productId, #revision and #serialNumber.
    6848             </desc>
    6849         </attribute>
    6850 
    6851         <attribute name="vendorId" type="unsigned short" readonly="yes">
    6852             <desc>Vendor ID.</desc>
    6853         </attribute>
    6854 
    6855         <attribute name="productId" type="unsigned short" readonly="yes">
    6856             <desc>Product ID.</desc>
    6857         </attribute>
    6858 
    6859         <attribute name="revision" type="unsigned short" readonly="yes">
    6860             <desc>
    6861                 Product revision number. This is a packed BCD represented as
    6862                 unsigned short. The high byte is the integer part and the low
    6863                 byte is the decimal.
    6864             </desc>
    6865         </attribute>
    6866 
    6867         <attribute name="manufacturer" type="wstring" readonly="yes">
    6868             <desc>Manufacturer string.</desc>
    6869         </attribute>
    6870 
    6871         <attribute name="product" type="wstring" readonly="yes">
    6872             <desc>Product string.</desc>
    6873         </attribute>
    6874 
    6875         <attribute name="serialNumber" type="wstring" readonly="yes">
    6876             <desc>Serial number string.</desc>
    6877         </attribute>
    6878 
    6879         <attribute name="address" type="wstring" readonly="yes">
    6880             <desc>Host specific address of the device.</desc>
    6881         </attribute>
    6882 
    6883         <attribute name="port" type="unsigned short" readonly="yes">
    6884             <desc>
    6885                 Host USB port number the device is physically
    6886                 coonected to.
    6887             </desc>
    6888         </attribute>
    6889 
    6890         <attribute name="remote" type="boolean" readonly="yes">
    6891             <desc>
    6892                 Whether the device is physically connected to a remote VRDP
    6893                 client or to a local host machine.
    6894             </desc>
    6895         </attribute>
    6896 
    6897     </interface>
    6898 
    6899 
    6900     <!--
    6901     // IUSBDeviceFilter
    6902     /////////////////////////////////////////////////////////////////////////
    6903     -->
    6904 
    6905     <enumerator
    6906         name="IUSBDeviceFilterEnumerator" type="IUSBDeviceFilter"
    6907         uuid="8d066d8b-3576-4a22-a387-847840937453"
    6908     />
    6909 
    6910     <collection
    6911         name="IUSBDeviceFilterCollection" type="IUSBDeviceFilter"
    6912         enumerator="IUSBDeviceFilterEnumerator"
    6913         uuid="4fa3fc99-ceb1-4bf5-a9cb-e962d825c1ef"
    6914         readonly="yes"
    6915     />
    6916 
    6917     <interface
    6918         name="IUSBDeviceFilter" extends="$unknown"
    6919         uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
    6920         wsmap="managed"
    6921     >
    6922         <desc>
    6923             The IUSBDeviceFilter interface represents an USB device filter used
    6924             to perform actions on a group of USB devices.
    6925 
    6926             This type of filters is used by running virtual machines to
    6927             automatically capture selected USB devices once they are physically
    6928             attached to the host computer.
    6929 
    6930             A USB device is matched to the given device filter if and only if all
    6931             attributes of the device match the corresponding attributes of the
    6932             filter (that is, attributes are joined together using the logical AND
    6933             operation). On the other hand, all together, filters in the list of
    6934             filters carry the semantics of the logical OR operation. So if it is
    6935             desirable to create a match like "this vendor id OR this product id",
    6936             one needs to create two filters and specify "any match" (see below)
    6937             for unused attributes.
    6938 
    6939             All filter attributes used for matching are strings. Each string
    6940             is an expression representing a set of values of the corresponding
    6941             device attribute, that will match the given filter. Currently, the
    6942             following filtering expressions are supported:
    6943 
    6944             <ul>
    6945             <li><i>Interval filters</i>. Used to specify valid intervals for
    6946             integer device attributes (Vendor ID, Product ID and Revision).
    6947             The format of the string is:
    6948 
    6949             <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt>
    6950 
    6951             where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
    6952             (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
    6953             or decimal (otherwise) form, so that <tt>m &lt; n</tt>. If <tt>m</tt>
    6954             is ommitted before a dash (<tt>-</tt>), the minimum possible integer
    6955             is assumed; if <tt>n</tt> is ommitted after a dash, the maximum
    6956             possible integer is assummed.
    6957             </li>
    6958             <li><i>Boolean filters</i>. Used to specify acceptable values for
    6959             boolean device attributes. The format of the string is:
    6960 
    6961             <tt>true|false|yes|no|0|1</tt>
    6962 
    6963             </li>
    6964             <li><i>Exact match</i>. Used to specify a single value for the given
    6965             device attribute. Any string that does't start with <tt>int:</tt>
    6966             represents the exact match. String device attributes are compared to
    6967             this string including case of symbols. Integer attributes are first
    6968             converted to a string (see individual filter attributes) and then
    6969             compared ignoring case.
    6970 
    6971             </li>
    6972             <li><i>Any match</i>. Any value of the corresponding device attribute
    6973             will match the given filter. An empty or <tt>null</tt> string is
    6974             used to construct this type of filtering expressions.
    6975 
    6976             </li>
    6977             </ul>
    6978 
    6979             <note>
    6980                 On the Windows host platform, interval filters are not currently
    6981                 available. Also all string filter attributes
    6982                 (<link to="#manufacturer"/>, <link to="#product"/>,
    6983                 <link to="#serialNumber"/>) are ignored, so they behave as
    6984                 <i>any match</i> no matter what string expression is specified.
    6985             </note>
    6986 
    6987             <see>IUSBController::DeviceFilters, IHostUSBDeviceFilter</see>
    6988         </desc>
    6989 
    6990         <attribute name="name" type="wstring">
    6991             <desc>
    6992                 Visible name for this filter.
    6993                 This name is used to visually distungish one filter from another,
    6994                 so it can neither be <tt>null</tt> nor an empty string.
    6995             </desc>
    6996         </attribute>
    6997 
    6998         <attribute name="active" type="boolean">
    6999             <desc>Whether this filter active or has been temporarily disabled.</desc>
    7000         </attribute>
    7001 
    7002         <attribute name="vendorId" type="wstring">
    7003             <desc>
    7004                 <link to="IUSBDevice::vendorId">Vendor ID</link> filter.
    7005                 The string representation for the <i>exact matching</i>
    7006                 has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
    7007                 (including leading zeroes).
    7008             </desc>
    7009         </attribute>
    7010 
    7011         <attribute name="productId" type="wstring">
    7012             <desc>
    7013                 <link to="IUSBDevice::productId">Product ID</link> filter.
    7014                 The string representation for the <i>exact matching</i>
    7015                 has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
    7016                 (including leading zeroes).
    7017             </desc>
    7018         </attribute>
    7019 
    7020         <attribute name="revision" type="wstring">
    7021             <desc>
    7022                 <link to="IUSBDevice::productId">Product revision number</link>
    7023                 filter. The string representation for the <i>exact matching</i>
    7024                 has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
    7025                 of the integer part of the revision, and <tt>F</tt> is the
    7026                 decimal digit of its fractional part (including leading and
    7027                 trailing zeroes).
    7028                 Note that for interval filters, it's best to use the hexadecimal
    7029                 form, because the revision is stored as a 16 bit packed BCD value;
    7030                 so the expression <tt>int:0x0100-0x0199</tt> will match any
    7031                 revision from <tt>1.0</tt> to <tt>1.99</tt>.
    7032             </desc>
    7033         </attribute>
    7034 
    7035         <attribute name="manufacturer" type="wstring">
    7036             <desc>
    7037                 <link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
    7038             </desc>
    7039         </attribute>
    7040 
    7041         <attribute name="product" type="wstring">
    7042             <desc>
    7043                 <link to="IUSBDevice::product">Product</link> filter.
    7044             </desc>
    7045         </attribute>
    7046 
    7047         <attribute name="serialNumber" type="wstring">
    7048             <desc>
    7049                 <link to="IUSBDevice::serialNumber">Serial number</link> filter.
    7050             </desc>
    7051         </attribute>
    7052 
    7053         <attribute name="port" type="wstring">
    7054             <desc>
    7055                 <link to="IUSBDevice::port">Host USB port</link> filter.
    7056             </desc>
    7057         </attribute>
    7058 
    7059         <attribute name="remote" type="wstring">
    7060             <desc>
    7061                 <link to="IUSBDevice::remote">Remote state</link> filter.
    7062                 <note>
    7063                     This filter makes sense only for machine USB filters,
    7064                     i.e. it is ignored by IHostUSBDeviceFilter objects.
    7065                 </note>
    7066             </desc>
    7067         </attribute>
    7068 
    7069     </interface>
    7070 
    7071 
    7072     <!--
    7073     // IHostUSBDevice
    7074     /////////////////////////////////////////////////////////////////////////
    7075     -->
    7076 
    7077     <enum
    7078         name="USBDeviceState"
    7079         uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
    7080     >
    7081         <desc>
    7082             USB device state. This enumeration represents all possible states
    7083             of the USB device physically attached to the host computer regarding
    7084             its state on the host computer and availability to guest computers
    7085             (all currently running virtual machines).
    7086 
    7087             Once a supported USB device is attached to the host, global USB
    7088             filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
    7089             either ignore the device, or put ot to #USBDeviceHeld state, or do
    7090             nothing. Unless the device is ignored by global filters, filters of
    7091             all currently running guests (<link to="IUSBController::DeviceFilters"/>)
    7092             are activated that can put it to #USBDeviceCaptured state.
    7093 
    7094             If the device was ignored by global filters, or didn't match
    7095             any filters at all (including guest ones), it is handled by the host
    7096             in a normal way. In this case, the device state is determined by
    7097             the host and can be one of #USBDeviceUnavailable, #USBDeviceBusy or
    7098             #USBDeviceAvailable, depending on the current device usage.
    7099 
    7100             Besides auto-capturing based on filters, the device can be manually
    7101             captured by guests (<link to="IConsole::attachUSBDevice()"/>) if its
    7102             state is #USBDeviceBusy, #USBDeviceAvailable or #USBDeviceHeld.
    7103 
    7104             <note>
    7105                 Due to differences in USB stack implementations in Linux and Win32,
    7106                 states #USBDeviceBusy and #USBDeviceAvailable are applicable
    7107                 only to the Linux version of the product. This also means that
    7108                 (<link to="IConsole::attachUSBDevice()"/>) can only succeed
    7109                 on Win32 if the device state is #USBDeviceHeld.
    7110             </note>
    7111 
    7112             <see>IHostUSBDevice, IHostUSBDeviceFilter</see>
    7113         </desc>
    7114 
    7115         <const name="USBDeviceNotSupported" value="0">
    7116             <desc>
    7117                 Not supported by the VirtualBox server, not available to guests.
    7118             </desc>
    7119         </const>
    7120         <const name="USBDeviceUnavailable"  value="1">
    7121             <desc>
    7122                 Being used by the host computer exclusively,
    7123                 not available to guests.
    7124             </desc>
    7125         </const>
    7126         <const name="USBDeviceBusy"         value="2">
    7127             <desc>
    7128                 Being used by the host computer, potentially available to guests.
    7129             </desc>
    7130         </const>
    7131         <const name="USBDeviceAvailable"    value="3">
    7132             <desc>
    7133                 Not used by the host computer, available to guests.
    7134                 The host computer can also start using the device at any time.
    7135             </desc>
    7136         </const>
    7137         <const name="USBDeviceHeld"         value="4">
    7138             <desc>
    7139                 Held by the VirtualBox server (ignored by the host computer),
    7140                 available to guests.
    7141             </desc>
    7142         </const>
    7143         <const name="USBDeviceCaptured"     value="5">
    7144             <desc>
    7145                 Captured by one of the guest computers, not available
    7146                 to anybody else.
    7147             </desc>
    7148         </const>
    7149     </enum>
    7150 
    7151     <enumerator
    7152         name="IHostUSBDeviceEnumerator" type="IHostUSBDevice"
    7153         uuid="a0c55136-939f-4d20-b9d3-4d406f08bfa5"
    7154     />
    7155 
    7156     <collection
    7157         name="IHostUSBDeviceCollection" type="IHostUSBDevice"
    7158         enumerator="IHostUSBDeviceEnumerator"
    7159         uuid="f9d3f96d-b027-4994-b589-70bb9ee0d364"
    7160         readonly="yes"
    7161     >
    7162         <method name="findById">
    7163             <desc>
    7164                 Searches this collection for a USB device with the given UUID.
    7165                 <note>
    7166                     The method returns an error if the given UUID does not
    7167                     correspond to any USB device in the collection.
    7168                 </note>
    7169                 <see>IHostUSBDevice::id</see>
    7170             </desc>
    7171             <param name="id" type="uuid" dir="in">
    7172                 <desc>UUID of the USB device to search for.</desc>
    7173             </param>
    7174             <param name="device" type="IHostUSBDevice" dir="return">
    7175                 <desc>Found USB device object.</desc>
    7176             </param>
    7177         </method>
    7178 
    7179         <method name="findByAddress">
    7180             <desc>
    7181                 Searches this collection for a USB device with the given
    7182                 host address.
    7183                 <note>
    7184                     The method returns an error if the given address does not
    7185                     correspond to any USB device in the collection.
    7186                 </note>
    7187                 <see>IHostUSBDevice::address</see>
    7188             </desc>
    7189             <param name="name" type="wstring" dir="in">
    7190                 <desc>
    7191                     Address of the USB device (as assigned by the host) to
    7192                     search for.
    7193                 </desc>
    7194             </param>
    7195             <param name="device" type="IHostUSBDevice" dir="return">
    7196                 <desc>Found USB device object.</desc>
    7197             </param>
    7198         </method>
    7199 
    7200     </collection>
    7201 
    7202     <interface
    7203         name="IHostUSBDevice" extends="IUSBDevice"
    7204         uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
    7205         wsmap="managed"
    7206     >
    7207         <desc>
    7208             The IHostUSBDevice interface represents a USB device attached to
    7209             the host computer.
    7210 
    7211             Among with properties inherited from IUSBDevice,
    7212             this interface adds the <link to="#state"/> property
    7213             that holds the courrent state of the USB device.
    7214 
    7215             <see>IHost::USBDevices, IHost::USBDeviceFilters</see>
    7216         </desc>
    7217 
    7218         <attribute name="state" type="USBDeviceState" readonly="yes">
    7219             <desc>
    7220                 Current state of the device.
    7221             </desc>
    7222         </attribute>
    7223 
    7224         <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
    7225 
    7226     </interface>
    7227 
    7228 
    7229     <!--
    7230     // IHostUSBDeviceFilter
    7231     /////////////////////////////////////////////////////////////////////////
    7232     -->
    7233 
    7234     <enum
    7235         name="USBDeviceFilterAction"
    7236         uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
    7237     >
    7238         <desc>
    7239             Actions for host USB device filters.
    7240             <see>IHostUSBDeviceFilter, USBDeviceState</see>
    7241         </desc>
    7242 
    7243         <const name="InvalidUSBDeviceFilterAction"  value="0"/>
    7244         <const name="USBDeviceFilterIgnore"         value="1">
    7245             <desc>Ignore the matched USB device.</desc>
    7246         </const>
    7247         <const name="USBDeviceFilterHold"           value="2">
    7248             <desc>Hold the matched USB device.</desc>
    7249         </const>
    7250     </enum>
    7251 
    7252     <enumerator
    7253         name="IHostUSBDeviceFilterEnumerator" type="IHostUSBDeviceFilter"
    7254         uuid="ff735211-903e-4642-9c37-189eb44579fe"
    7255     />
    7256 
    7257     <collection
    7258         name="IHostUSBDeviceFilterCollection" type="IHostUSBDeviceFilter"
    7259         enumerator="IHostUSBDeviceFilterEnumerator"
    7260         uuid="1a80458b-87f1-4a74-995d-04e2330119e0"
    7261         readonly="yes"
    7262     />
    7263 
    7264     <interface
    7265         name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
    7266         uuid="4cc70246-d74a-400f-8222-3900489c0374"
    7267         wsmap="managed"
    7268     >
    7269         <desc>
    7270             The IHostUSBDeviceFilter interface represents a USB device filter used
    7271             by the host computer.
    7272 
    7273             Using filters of this type, the host computer determines the initial
    7274             state of the USB device after it is physically attached to the
    7275             host's USB controller.
    7276 
    7277             <note>
    7278                 The <link to="#remote"/> attribute is ignored by this type of
    7279                 filters, because it makes sense only for
    7280                 <link to="IUSBController::DeviceFilters">machine USB filters</link>.
    7281             </note>
    7282 
    7283             <see>IHost::USBDeviceFilters</see>
    7284         </desc>
    7285 
    7286         <attribute name="action" type="USBDeviceFilterAction">
    7287             <desc>
    7288                 Action performed by the host when an attached USB device
    7289                 matches this filter.
    7290             </desc>
    7291         </attribute>
    7292 
    7293     </interface>
    7294 
    7295     <!--
    7296     // IAudioAdapter
    7297     /////////////////////////////////////////////////////////////////////////
    7298     -->
    7299 
    7300     <enum
    7301         name="AudioDriverType"
    7302         uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
    7303     >
    7304         <const name="NullAudioDriver"   value="0"/>
    7305         <const name="WINMMAudioDriver"  value="1"/>
    7306         <const name="OSSAudioDriver"    value="2"/>
    7307         <const name="ALSAAudioDriver"   value="3"/>
    7308         <const name="DSOUNDAudioDriver" value="4"/>
    7309         <const name="CoreAudioDriver"   value="5"/>
    7310         <const name="MMPMAudioDriver"   value="5"/>
    7311     </enum>
    7312 
    7313     <interface
    7314         name="IAudioAdapter" extends="$unknown"
    7315         uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
    7316         wsmap="struct"
    7317     >
    7318         <attribute name="enabled" type="boolean">
    7319             <desc>
    7320                 Flag whether the audio adapter is present in the
    7321                 guest system. If disabled, the virtual guest hardware will
    7322                 not contain any audio adapter. Can only be changed when
    7323                 the VM is not running.
    7324             </desc>
    7325         </attribute>
    7326         <attribute name="audioDriver" type="AudioDriverType">
    7327             <desc>
    7328                 Audio driver the adapter is connected to. This setting
    7329                 can only be changed when the VM is not running.
    7330             </desc>
    7331         </attribute>
    7332     </interface>
    7333 
    7334     <!--
    7335     // IVRDPServer
    7336     /////////////////////////////////////////////////////////////////////////
    7337     -->
    7338 
    7339     <enum
    7340         name="VRDPAuthType"
    7341         uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
    7342     >
    7343         <const name="VRDPAuthNull"            value="0"/>
    7344         <const name="VRDPAuthExternal"        value="1"/>
    7345         <const name="VRDPAuthGuest"           value="2"/>
    7346     </enum>
    7347 
    7348     <interface
    7349         name="IVRDPServer" extends="$unknown"
    7350         uuid="ed9d31ae-867f-45fc-b727-6740084d1883"
    7351         wsmap="struct"
    7352     >
    7353         <attribute name="enabled" type="boolean">
    7354             <desc>VRDP server status.</desc>
    7355         </attribute>
    7356 
    7357         <attribute name="port" type="unsigned long">
    7358             <desc>VRDP server port.</desc>
    7359         </attribute>
    7360 
    7361         <attribute name="netAddress" type="wstring">
    7362             <desc>VRDP server address.</desc>
    7363         </attribute>
    7364 
    7365         <attribute name="authType" type="VRDPAuthType">
    7366             <desc>VRDP authentication method.</desc>
    7367         </attribute>
    7368 
    7369         <attribute name="authTimeout" type="unsigned long">
    7370             <desc>Timeout for guest authentication. Milliseconds.</desc>
    7371         </attribute>
    7372 
    7373         <attribute name="allowMultiConnection" type="boolean">
    7374             <desc>
    7375                 Flag whether multiple simultaneous connections to the VM are permitted.
    7376                 Note that this will be replaced by a more powerful mechanism in the future.
    7377             </desc>
    7378         </attribute>
    7379 
    7380     </interface>
    7381 
    7382 
    7383     <!--
    7384     // ISharedFolder
    7385     /////////////////////////////////////////////////////////////////////////
    7386     -->
    7387 
    7388     <enumerator
    7389         name="ISharedFolderEnumerator" type="ISharedFolder"
    7390         uuid="1d420fd8-e7c1-4511-abf4-a504dc6d0cbf"
    7391     />
    7392 
    7393     <collection
    7394         name="ISharedFolderCollection" type="ISharedFolder"
    7395         enumerator="ISharedFolderEnumerator"
    7396         uuid="9c7e2282-bb16-4fa7-9138-f383c5e02353"
    7397         readonly="yes">
    7398 
    7399         <method name="findByName">
    7400             <desc>
    7401                 Searches this collection for a shared folder drive with the
    7402                 given logical name.
    7403                 <note>
    7404                     The method returns an error if the given name does not
    7405                     correspond to any shared folder in the collection.
    7406                 </note>
    7407             </desc>
    7408             <param name="name" type="wstring" dir="in">
    7409                 <desc>Logical name of the shared folder to search for</desc>
    7410             </param>
    7411             <param name="sharedFolder" type="ISharedFolder" dir="return">
    7412                 <desc>Found shared folder object</desc>
    7413             </param>
    7414         </method>
    7415 
    7416     </collection>
    7417 
    7418     <interface
    7419         name="ISharedFolder" extends="$unknown"
    7420         uuid="8b0c5f70-9139-4f97-a421-64d5e9c335d5"
    7421         wsmap="struct"
    7422     >
    7423         <desc>
    7424             The ISharedFolder interface represents a folder in the host
    7425             computer's file system accessible from a guest OS running inside a
    7426             virtual machine using an associated logical name.
    7427 
    7428             There are three types of shared folders:
    7429             <ul>
    7430                 <li>permanent (<link to="IMachine::sharedFolders"/>)</li>
    7431                 <li>transient (<link to="IConsole::sharedFolders"/>)</li>
    7432                 <li>global (<link to="IVirtualBox::sharedFolders"/>)</li>
    7433             </ul>
    7434 
    7435             For a given virtual machine, both permanently and transiently
    7436             shared folders have the same logical name space which also includes
    7437             all globally shared folders. Thus, every folder in this name space
    7438             must have an unique logical name. Note that permanent and transient
    7439             shares of other machines are in different name spaces, so they don't
    7440             have to have unique names.
    7441         </desc>
    7442 
    7443         <attribute name="name" type="wstring" readonly="yes">
    7444             <desc>Logical name of the shared folder.</desc>
    7445         </attribute>
    7446 
    7447         <attribute name="hostPath" type="wstring" readonly="yes">
    7448             <desc>Full path to the shared folder in the host file system.</desc>
    7449         </attribute>
    7450 
    7451         <attribute name="accessible" type="boolean" readonly="yes">
    7452             <desc>
    7453                 Whether the folder defined by the host path is currently
    7454                 accessible or not.
    7455                 For example, the folder can be unaccessible if it is placed
    7456                 on the network share that is not available by the time
    7457                 this property is read.
    7458             </desc>
    7459         </attribute>
    7460 
    7461     </interface>
    7462 
    7463     <!--
    7464     // ISession
    7465     /////////////////////////////////////////////////////////////////////////
    7466     -->
    7467 
    7468     <interface
    7469         name="IInternalSessionControl" extends="$unknown"
    7470         uuid="80a9b698-cc60-48cf-ab88-a7c2ea4013a6"
    7471         internal="yes"
    7472         wsmap="suppress"
    7473     >
    7474         <method name="getPID">
    7475             <desc>PID of the process that has created this Session object.
    7476             </desc>
    7477             <param name="pid" type="unsigned long" dir="return"/>
    7478         </method>
    7479 
    7480         <method name="getRemoteConsole">
    7481             <desc>Returns the console object suitable for remote control.</desc>
    7482             <param name="console" type="IConsole" dir="return"/>
    7483         </method>
    7484 
    7485         <method name="assignMachine">
    7486             <desc>
    7487                 Assigns the machine object associated with this direct-type
    7488                 session or informs the session that it will be a remote one
    7489                 (if machine = NULL).
    7490             </desc>
    7491             <param name="machine" type="IMachine" dir="in"/>
    7492         </method>
    7493 
    7494         <method name="assignRemoteMachine">
    7495             <desc>
    7496                 Assigns the machine and the (remote) console object associated with
    7497                 this remote-type session.
    7498             </desc>
    7499             <param name="machine" type="IMachine" dir="in"/>
    7500             <param name="console" type="IConsole" dir="in"/>
    7501         </method>
    7502 
    7503         <method name="updateMachineState">
    7504             <desc>
    7505                 Updates the machine state in the VM process.
    7506                 Must be called only in certain cases
    7507                 (see the method implementation).
    7508             </desc>
    7509             <param name="aMachineState" type="MachineState" dir="in"/>
    7510         </method>
    7511 
    7512         <method name="uninitialize">
    7513             <desc>
    7514                 Uninitializes (closes) this session. Used by VirtualBox to close
    7515                 the corresponding remote session when the direct session dies
    7516                 or gets closed.
    7517             </desc>
    7518         </method>
    7519 
    7520         <method name="onDVDDriveChange">
    7521             <desc>
    7522                 Triggered when settings of the DVD drive object of the
    7523                 associated virtual machine have changed.
    7524             </desc>
    7525         </method>
    7526 
    7527         <method name="onFloppyDriveChange">
    7528             <desc>
    7529                 Triggered when settings of the floppy drive object of the
    7530                 associated virtual machine have changed.
    7531             </desc>
    7532         </method>
    7533 
    7534         <method name="onNetworkAdapterChange">
    7535              <desc>
    7536                  Triggered when settions of a network adapter of the
    7537                  associated virtual machine have changed.
    7538              </desc>
    7539             <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
    7540          </method>
    7541 
    7542         <method name="onVRDPServerChange">
    7543             <desc>
    7544                 Triggered when settings of the VRDP server object of the
    7545                 associated virtual machine have changed.
    7546             </desc>
    7547         </method>
    7548 
    7549         <method name="onUSBControllerChange">
    7550             <desc>
    7551                 Triggered when settings of the USB controller object of the
    7552                 associated virtual machine have changed.
    7553             </desc>
    7554         </method>
    7555 
    7556         <method name="onUSBDeviceAttach">
    7557             <desc>
    7558                 Triggered when a request to capture a USB device (as a result
    7559                 of matched USB filters or direct call to
    7560                 <link to="IConsole::attachUSBDevice"/>) has completed.
    7561                 A @c null @a error object means success, otherwise it
    7562                 describes a failure.
    7563             </desc>
    7564             <param name="device" type="IUSBDevice" dir="in"/>
    7565             <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
    7566         </method>
    7567 
    7568         <method name="onUSBDeviceDetach">
    7569             <desc>
    7570                 Triggered when a request to release the USB device (as a result
    7571                 of machine termination or direct call to
    7572                 <link to="IConsole::detachUSBDevice"/>) has completed.
    7573                 A @c null @a error object means success, otherwise it
    7574             </desc>
    7575             <param name="id" type="uuid" dir="in"/>
    7576             <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
    7577         </method>
    7578 
    7579         <method name="onShowWindow">
    7580             <desc>
    7581                 Called by <link to="IMachine::canShowConsoleWindow()"/> and by
    7582                 <link to="IMachine::showConsoleWindow()"/> in order to notify
    7583                 console callbacks
    7584                 <link to="IConsoleCallback::onCanShowWindow()"/>
    7585                 and <link to="IConsoleCallback::onShowWindow()"/>.
    7586             </desc>
    7587             <param name="check" type="boolean" dir="in"/>
    7588             <param name="canShow" type="boolean" dir="out"/>
    7589             <param name="winId" type="unsigned long long" dir="out"/>
    7590         </method>
    7591 
    7592     </interface>
    7593 
    7594     <interface
    7595         name="ISession" extends="$dispatched"
    7596         uuid="12F4DCDB-12B2-4ec1-B7CD-DDD9F6C5BF4D"
    7597         wsmap="managed"
    7598     >
    7599         <attribute name="state" type="SessionState" readonly="yes">
    7600             <desc>Current state of this session.</desc>
    7601         </attribute>
    7602 
    7603         <attribute name="type" type="SessionType" readonly="yes">
    7604             <desc>
    7605                 Type of this session. The value of this attribute is valid only
    7606                 if the session is currently open (i.e. its #state is SessionType::SessionOpen),
    7607                 otherwise an error will be returned.
    7608             </desc>
    7609         </attribute>
    7610 
    7611         <attribute name="machine" type="IMachine" readonly="yes">
    7612             <desc>Machine object associated with this session.</desc>
    7613         </attribute>
    7614 
    7615         <attribute name="console" type="IConsole" readonly="yes">
    7616             <desc>Console object associated with this session.</desc>
    7617         </attribute>
    7618 
    7619         <method name="close">
    7620             <desc>
    7621                 Closes this session.
    7622                 <note>
    7623                     If a direct session for a machine opened with
    7624                     <link to="IVirtualBox::openSession()"/> is not explicitly
    7625                     closed when the application terminates, the state of the
    7626                     machine will be set to <link to="MachineState::Aborted"/>
    7627                     on the server. Generally, it is recommended to close all
    7628                     open sessions explicitly before terminating the application
    7629                     (no matter what is the reason of the termination).
    7630                 </note>
    7631             </desc>
    7632         </method>
    7633 
    7634     </interface>
    7635 
    7636     <class name="Session" uuid="3C02F46D-C9D2-4f11-A384-53F0CF917214"
    7637            namespace="virtualbox.org">
    7638         <interface name="ISession" default="yes"/>
    7639     </class>
    7640 
    7641 <if target="wsdl">
    7642 
    7643     <!--
    7644     // IManagedObjectRef
    7645     /////////////////////////////////////////////////////////////////////////
    7646     -->
    7647 
    7648     <interface
    7649         name="IManagedObjectRef" extends="$unknown"
    7650         uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
    7651         internal="yes"
    7652         wsmap="explicit"
    7653     >
    7654         <method name="getInterfaceName">
    7655             <desc>
    7656                 Returns the name of the interface that this managed object represents,
    7657                 for example, "IMachine", as a string.
    7658             </desc>
    7659         </method>
    7660 
    7661         <method name="release">
    7662             <desc>
    7663                 Releases this managed object reference and frees the resources that
    7664                 were allocated for it in the web service server process. After calling
    7665                 this method, the identifier of the reference can no longer be used.
    7666             </desc>
    7667         </method>
    7668 
    7669     </interface>
    7670 </if>
    7671 
    76727728</module>
    76737729
Note: See TracChangeset for help on using the changeset viewer.

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