VirtualBox

Changeset 16690 in vbox


Ignore:
Timestamp:
Feb 11, 2009 7:14:27 PM (16 years ago)
Author:
vboxsync
Message:

Main: API documentation.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/VBox/Main/idl/VirtualBox.xidl

    r16687 r16690  
    437437
    438438      The first diagram shows what happens when a lengthy setup operation is
    439       being executed (such as <link to="IMachine::attachHardDisk2()"/>).
     439      being executed (such as <link to="IMachine::attachHardDisk2"/>).
    440440
    441441      <pre>
     
    621621      <desc>
    622622        A new (direct) session is being opened for the machine
    623         as a result of <link to="IVirtualBox::openRemoteSession()"/>
     623        as a result of <link to="IVirtualBox::openRemoteSession"/>
    624624        call (<link to="IMachine::sessionState"/>);
    625625        the session is currently being opened
    626         as a result of <link to="IVirtualBox::openRemoteSession()"/>
     626        as a result of <link to="IVirtualBox::openRemoteSession"/>
    627627        call (<link to="ISession::state"/>)
    628628      </desc>
     
    651651      <desc>
    652652        Direct session
    653         (opened by <link to="IVirtualBox::openSession()"/>)
     653        (opened by <link to="IVirtualBox::openSession"/>)
    654654      </desc>
    655655    </const>
     
    657657      <desc>
    658658        Remote session
    659         (opened by <link to="IVirtualBox::openRemoteSession()"/>)
     659        (opened by <link to="IVirtualBox::openRemoteSession"/>)
    660660      </desc>
    661661    </const>
     
    663663      <desc>
    664664        Existing session
    665         (opened by <link to="IVirtualBox::openExistingSession()"/>)
     665        (opened by <link to="IVirtualBox::openExistingSession"/>)
    666666      </desc>
    667667    </const>
     
    11111111        <li><link to="DeviceType_HardDisk"/>: the media is a hard disk
    11121112        that, if registered, can be obtained using the
    1113         <link to="IVirtualBox::getHardDisk2()"/> call.</li>
     1113        <link to="IVirtualBox::getHardDisk2"/> call.</li>
    11141114        <li><link to="DeviceType_DVD"/>: the media is a CD/DVD image
    11151115        that, if registered, can be obtained using the
    1116         <link to="IVirtualBox::getDVDImage()"/> call.</li>
     1116        <link to="IVirtualBox::getDVDImage"/> call.</li>
    11171117        <li><link to="DeviceType_Floppy"/>: the media is a Floppy image
    11181118        that, if registered, can be obtained using the
    1119         <link to="IVirtualBox::getFloppyImage()"/> call.</li>
     1119        <link to="IVirtualBox::getFloppyImage"/> call.</li>
    11201120        </ul>
    11211121
     
    13361336        VirtualBox startup) but it doesn't save the changes back until
    13371337        you call a method that implicitly saves settings (such as
    1338         <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>
     1338        <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
    13391339        explicitly. Therefore, if the value of this attribute differs from the
    13401340        value of <link to="#settingsFormatVersion"/>, then it
     
    13651365        VirtualBox uses this version of the format when saving settings files
    13661366        (either as a result of method calls that require to save settings or as
    1367         a result of an explicit call to <link to="#saveSettings()"/>).
     1367        a result of an explicit call to <link to="#saveSettings"/>).
    13681368
    13691369        <see>settingsFileVersion</see>
     
    14521452
    14531453          <li>
    1454             Call <link to="IMachine::saveSettings()" /> to write the settings
     1454            Call <link to="IMachine::saveSettings" /> to write the settings
    14551455            to the machine's XML settings file. The configuration of the newly
    14561456            created machine will not be saved to disk until this method is
     
    14591459
    14601460          <li>
    1461             Call <link to="#registerMachine()" /> to add the machine to the list
     1461            Call <link to="#registerMachine" /> to add the machine to the list
    14621462            of machines known to VirtualBox.
    14631463          </li>
     
    15381538        settings file to store machine settings.
    15391539
    1540         As opposed to machines created by <link to="#createMachine()"/>,
     1540        As opposed to machines created by <link to="#createMachine"/>,
    15411541        the settings file of the machine created in "legacy" mode is not
    15421542        automatically renamed when the machine name is changed -- it will always
     
    15501550        Note that the configuration of the newly created machine is not
    15511551        saved to disk (and therefore no settings file is created)
    1552         until <link to="IMachine::saveSettings()"/> is called. If the
     1552        until <link to="IMachine::saveSettings"/> is called. If the
    15531553        specified settings file already exists, this method
    15541554        will fail with <link to="VBOX_E_FILE_ERROR"/>..
    15551555
    1556         See <link to="#createMachine()"/> for more information.
     1556        See <link to="#createMachine"/> for more information.
    15571557
    15581558        @deprecated This method may be removed later. Use <link
    1559         to="IVirtualBox::createMachine()"/> instead.
     1559        to="IVirtualBox::createMachine"/> instead.
    15601560
    15611561        <note>
     
    15971597        Opens a virtual machine from the existing settings file.
    15981598        The opened machine remains unregistered until you call
    1599         <link to="#registerMachine()"/>.
     1599        <link to="#registerMachine"/>.
    16001600
    16011601        The specified settings file name can be absolute
     
    16291629
    16301630        Registers the machine previously created using
    1631         <link to="#createMachine()"/> or opened using
    1632         <link to="#openMachine()"/> within this VirtualBox installation. After
     1631        <link to="#createMachine"/> or opened using
     1632        <link to="#openMachine"/> within this VirtualBox installation. After
    16331633        successful method invocation, the
    16341634        <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
     
    17481748        allocate a format-specific storage unit at the specified location:
    17491749        <ul>
    1750           <li><link to="IHardDisk2::createDynamicStorage()"/></li>
    1751           <li><link to="IHardDisk2::createFixedStorage()"/></li>
    1752           <li><link to="IHardDisk2::createDiffStorage()"/></li>
     1750          <li><link to="IHardDisk2::createDynamicStorage"/></li>
     1751          <li><link to="IHardDisk2::createFixedStorage"/></li>
     1752          <li><link to="IHardDisk2::createDiffStorage"/></li>
    17531753        </ul>
    17541754
     
    17591759        After the storage unit is successfully created, the hard disk gets
    17601760        remembered by this VirtualBox installation and will be accessible
    1761         through <link to="#getHardDisk2()"/> and <link to="#findHardDisk2()"/>
     1761        through <link to="#getHardDisk2"/> and <link to="#findHardDisk2"/>
    17621762        methods. Remembered root (base) hard disks are also returned as part of
    17631763        the <link to="#hardDisks2"/> array. See IHardDisk2 for more details.
     
    18061806        After the hard disk is successfully opened by this method, it gets
    18071807        remembered by (known to) this VirtualBox installation and will be
    1808         accessible through <link to="#getHardDisk2()"/> and
    1809         <link to="#findHardDisk2()"/> methods. Remembered root (base) hard disks
     1808        accessible through <link to="#getHardDisk2"/> and
     1809        <link to="#findHardDisk2"/> methods. Remembered root (base) hard disks
    18101810        are also returned as part of the <link to="#hardDisks2"/> array and can
    18111811        be attached to virtual machines. See IHardDisk2 for more details.
     
    18521852        The hard disk with the given UUID must be known to this VirtualBox
    18531853        installation, i.e. it must be previously created by
    1854         <link to="#createHardDisk2()"/> or opened by <link
    1855         to="#openHardDisk2()"/>, or attached to some known virtual machine.
     1854        <link to="#createHardDisk2"/> or opened by <link
     1855        to="#openHardDisk2"/>, or attached to some known virtual machine.
    18561856
    18571857        <result name="VBOX_E_OBJECT_NOT_FOUND">
     
    18751875        The given hard disk must be known to this VirtualBox installation, i.e.
    18761876        it must be previously created by
    1877         <link to="#createHardDisk2()"/> or opened by <link
    1878         to="#openHardDisk2()"/>, or attached to some known virtual machine.
     1877        <link to="#createHardDisk2"/> or opened by <link
     1878        to="#openHardDisk2"/>, or attached to some known virtual machine.
    18791879
    18801880        The search is done by comparing the value of the @a location argument to
     
    19111911        After the image is successfully opened by this method, it gets
    19121912        remembered by (known to) this VirtualBox installation and will be
    1913         accessible through <link to="#getDVDImage()"/> and
    1914         <link to="#findDVDImage()"/> methods. Remembered images are also
     1913        accessible through <link to="#getDVDImage"/> and
     1914        <link to="#findDVDImage"/> methods. Remembered images are also
    19151915        returned as part of the <link to="#DVDImages"/> array and can be mounted
    19161916        to virtual machines. See IMedium for more details.
     
    19511951        The image with the given UUID must be known to this VirtualBox
    19521952        installation, i.e. it must be previously opened by <link
    1953         to="#openDVDImage()"/>, or mounted to some known virtual machine.
     1953        to="#openDVDImage"/>, or mounted to some known virtual machine.
    19541954
    19551955        <result name="VBOX_E_OBJECT_NOT_FOUND">
     
    19721972        The image with the given UUID must be known to this VirtualBox
    19731973        installation, i.e. it must be previously opened by <link
    1974         to="#openDVDImage()"/>, or mounted to some known virtual machine.
     1974        to="#openDVDImage"/>, or mounted to some known virtual machine.
    19751975
    19761976        The search is done by comparing the value of the @a location argument to
     
    20082008        After the image is successfully opened by this method, it gets
    20092009        remembered by (known to) this VirtualBox installation and will be
    2010         accessible through <link to="#getFloppyImage()"/> and
    2011         <link to="#findFloppyImage()"/> methods. Remembered images are also
     2010        accessible through <link to="#getFloppyImage"/> and
     2011        <link to="#findFloppyImage"/> methods. Remembered images are also
    20122012        returned as part of the <link to="#floppyImages"/> array and can be
    20132013        mounted to virtual machines. See IMedium for more details.
     
    20502050        The image with the given UUID must be known to this VirtualBox
    20512051        installation, i.e. it must be previously opened by <link
    2052         to="#openFloppyImage()"/>, or mounted to some known virtual machine.
     2052        to="#openFloppyImage"/>, or mounted to some known virtual machine.
    20532053
    20542054        <result name="VBOX_E_OBJECT_NOT_FOUND">
     
    20712071        The image with the given UUID must be known to this VirtualBox
    20722072        installation, i.e. it must be previously opened by <link
    2073         to="#openFloppyImage()"/>, or mounted to some known virtual machine.
     2073        to="#openFloppyImage"/>, or mounted to some known virtual machine.
    20742074
    20752075        The search is done by comparing the value of the @a location argument to
     
    22242224          Before performing the actual data change, this method will ask all
    22252225          registered callbacks using the
    2226           <link to="IVirtualBoxCallback::onExtraDataCanChange()"/>
     2226          <link to="IVirtualBoxCallback::onExtraDataCanChange"/>
    22272227          notification for a permission. If one of the callbacks refuses the
    22282228          new value, the change will not be performed.
     
    22302230        <note>
    22312231          On success, the
    2232           <link to="IVirtualBoxCallback::onExtraDataChange()"/> notification
     2232          <link to="IVirtualBoxCallback::onExtraDataChange"/> notification
    22332233          is called to inform all registered callbacks about a successful data
    22342234          change.
     
    23032303        <li>Call <link to="IMachine::saveSettings" />.</li>
    23042304
    2305         <li>Close the session by calling <link to="ISession::close()"/>.</li>
     2305        <li>Close the session by calling <link to="ISession::close"/>.</li>
    23062306        </ol>
    23072307
     
    24542454        for modification.
    24552455
    2456         As opposed to <link to="#openRemoteSession()"/>, the number of
     2456        As opposed to <link to="#openRemoteSession"/>, the number of
    24572457        remote sessions opened this way is not limited by the API
    24582458
     
    26452645        Creates a backup copy of the global settings file
    26462646        (<link to="#settingsFilePath"/>) in case of auto-conversion, and then
    2647         calls <link to="#saveSettings()"/>.
     2647        calls <link to="#saveSettings"/>.
    26482648
    26492649        Note that the backup copy is created <b>only</b> if the settings file
    26502650        auto-conversion took place (see <link to="#settingsFileVersion"/> for
    26512651        details). Otherwise, this call is fully equivalent to
    2652         <link to="#saveSettings()"/> and no backup copying is done.
     2652        <link to="#saveSettings"/> and no backup copying is done.
    26532653
    26542654        The backup copy is created in the same directory where the original
     
    26702670        receive a full path to the created backup file (for informational
    26712671        purposes). Note that this will happen even if the subsequent
    2672         <link to="#saveSettings()"/> call performed by this method after the
     2672        <link to="#saveSettings"/> call performed by this method after the
    26732673        copy operation, fails.
    26742674
     
    37543754        subdirectory this settings file resides in. Thus, every time you
    37553755        change the value of this property, the settings file will be
    3756         renamed once you call <link to="#saveSettings()"/> to confirm the
     3756        renamed once you call <link to="#saveSettings"/> to confirm the
    37573757        change. The containing subdirectory will be also renamed, but
    37583758        only if it has exactly the same name as the settings file
     
    37723772            is being used by another running machine or by any other
    37733773            process in the host operating system at a time when
    3774             <link to="#saveSettings()"/> is called.
     3774            <link to="#saveSettings"/> is called.
    37753775          </li>
    37763776        </ul>
    3777         If any of the above limitations are hit, <link to="#saveSettings()"/>
     3777        If any of the above limitations are hit, <link to="#saveSettings"/>
    37783778        will return an appropriate error message explaining the exact
    37793779        reason and the changes you made to this machine will not be
     
    37813781        <note>
    37823782          For "legacy" machines created using the
    3783           <link to="IVirtualBox::createLegacyMachine()"/> call,
     3783          <link to="IVirtualBox::createLegacyMachine"/> call,
    37843784          the above naming limitations do not apply because the
    37853785          machine name does not affect the settings file name.
     
    39983998        VirtualBox startup) but it doesn't save the changes back until
    39993999        you call a method that implicitly saves settings (such as
    4000         <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>
     4000        <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
    40014001        explicitly. Therefore, if the value of this attribute differs from the
    40024002        value of <link to="IVirtualBox::settingsFormatVersion"/>, then it
     
    40294029        <note>
    40304030          For newly created unregistered machines, the value of this
    4031           property is always TRUE until <link to="#saveSettings()"/>
     4031          property is always TRUE until <link to="#saveSettings"/>
    40324032          is called (no matter if any machine settings have been
    40334033          changed after the creation or not). For opened machines
     
    40464046        SessionSpawning or SessionOpen, this attribute contains the
    40474047        same value as passed to the
    4048         <link to="IVirtualBox::openRemoteSession()"/> method in the @a
     4048        <link to="IVirtualBox::openRemoteSession"/> method in the @a
    40494049        type parameter. If the session was opened directly using
    4050         <link to="IVirtualBox::openSession()"/>, or if
     4050        <link to="IVirtualBox::openSession"/>, or if
    40514051        <link to="#sessionState"/> is SessionClosed, the value of this
    40524052        attribute is @c null.
     
    40594059        platform-dependent identifier of the process that has opened a
    40604060        direct session for this machine using the
    4061         <link to="IVirtualBox::openSession()"/> call. The returned value
     4061        <link to="IVirtualBox::openSession"/> call. The returned value
    40624062        is only valid if <link to="#sessionState"/> is SessionOpen or
    40634063        SessionClosing (i.e. a session is currently open or being
     
    42714271          You cannot attach a hard disk to a running machine. Also, you cannot
    42724272          attach a hard disk to a newly created machine until this machine's
    4273           settings are saved to disk using <link to="#saveSettings()"/>.
     4273          settings are saved to disk using <link to="#saveSettings"/>.
    42744274        </note>
    42754275        <note>
     
    42774277          disk will implicitly be created for it and attached instead. If the
    42784278          changes made to the machine settings (including this indirect
    4279           attachment) are later cancelled using <link to="#discardSettings()"/>,
     4279          attachment) are later cancelled using <link to="#discardSettings"/>,
    42804280          this implicitly created differencing hard disk will implicitly
    42814281          be deleted.
     
    43184318
    43194319        Note that if the hard disk was indirectly attached by
    4320         <link to="#attachHardDisk2()"/> to the given device slot then this
     4320        <link to="#attachHardDisk2"/> to the given device slot then this
    43214321        method will return not the same object as passed to the
    4322         <link to="#attachHardDisk2()"/> call. See <link to="IHardDisk2"/> for
     4322        <link to="#attachHardDisk2"/> call. See <link to="IHardDisk2"/> for
    43234323        more detailed information about attaching hard disks.
    43244324
     
    43504350        that the hard disk remains associated with the machine when this method
    43514351        returns and gets actually de-associated only after a successful
    4352         <link to="#saveSettings()"/> call. See <link to="IHardDisk2"/>
     4352        <link to="#saveSettings"/> call. See <link to="IHardDisk2"/>
    43534353        for more detailed information about attaching hard disks.
    43544354
     
    43584358        <note>
    43594359          Detaching differencing hard disks implicitly created by <link
    4360           to="#attachHardDisk2()"/> for the indirect attachment using this
     4360          to="#attachHardDisk2"/> for the indirect attachment using this
    43614361          method will <b>not</b> implicitly delete them. The
    4362           <link to="IHardDisk2::deleteStorage()"/> operation should be
     4362          <link to="IHardDisk2::deleteStorage"/> operation should be
    43634363          explicitly performed by the caller after the hard disk is successfully
    43644364          detached and the settings are saved with
    4365           <link to="#saveSettings()"/>, if it is the desired action.
     4365          <link to="#saveSettings"/>, if it is the desired action.
    43664366        </note>
    43674367
     
    44994499          Before performing the actual data change, this method will ask all
    45004500          registered callbacks using the
    4501           <link to="IVirtualBoxCallback::onExtraDataCanChange()"/>
     4501          <link to="IVirtualBoxCallback::onExtraDataCanChange"/>
    45024502          notification for a permission. If one of the callbacks refuses the
    45034503          new value, the change will not be performed.
     
    45054505        <note>
    45064506          On success, the
    4507           <link to="IVirtualBoxCallback::onExtraDataChange()"/> notification
     4507          <link to="IVirtualBoxCallback::onExtraDataChange"/> notification
    45084508          is called to inform all registered callbacks about a successful data
    45094509          change.
     
    45354535        Saves any changes to machine settings made since the session
    45364536        has been opened or a new machine has been created, or since the
    4537         last call to <link to="#saveSettings()"/> or <link to="#discardSettings()"/>.
     4537        last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
    45384538        For registered machines, new settings become visible to all
    45394539        other VirtualBox clients after successful invocation of this
    45404540        method.
    45414541        <note>
    4542           The method sends <link to="IVirtualBoxCallback::onMachineDataChange()"/>
     4542          The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
    45434543          notification event after the configuration has been successfully
    45444544          saved (only for registered machines).
     
    45694569        Creates a backup copy of the machine settings file (<link
    45704570        to="#settingsFilePath"/>) in case of auto-conversion, and then calls
    4571         <link to="#saveSettings()"/>.
     4571        <link to="#saveSettings"/>.
    45724572
    45734573        Note that the backup copy is created <b>only</b> if the settings file
    45744574        auto-conversion took place (see <link to="#settingsFileVersion"/> for
    45754575        details). Otherwise, this call is fully equivalent to
    4576         <link to="#saveSettings()"/> and no backup copying is done.
     4576        <link to="#saveSettings"/> and no backup copying is done.
    45774577
    45784578        The backup copy is created in the same directory where the original
     
    45944594        receive a full path to the created backup file (for informational
    45954595        purposes). Note that this will happen even if the subsequent
    4596         <link to="#saveSettings()"/> call performed by this method after the
     4596        <link to="#saveSettings"/> call performed by this method after the
    45974597        copy operation, fails.
    45984598
     
    46284628      <desc>
    46294629        Discards any changes to the machine settings made since the session
    4630         has been opened or since the last call to <link to="#saveSettings()"/>
     4630        has been opened or since the last call to <link to="#saveSettings"/>
    46314631        or <link to="#discardSettings"/>.
    46324632        <note>
     
    46654665        <note>
    46664666          The deleted machine settings file can be restored (saved again)
    4667           by calling <link to="#saveSettings()"/>.
     4667          by calling <link to="#saveSettings"/>.
    46684668        </note>
    46694669
     
    52755275        execution is always paused before calling this notification, and
    52765276        the notification handler is supposed either to immediately save
    5277         the virtual machine state using <link to="IConsole::saveState()"/>
    5278         or power it off using <link to="IConsole::powerDown()"/>.
     5277        the virtual machine state using <link to="IConsole::saveState"/>
     5278        or power it off using <link to="IConsole::powerDown"/>.
    52795279        Resuming the execution can lead to unpredictable results.
    52805280
     
    52895289        as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
    52905290        wants to retry, the notification handler should continue
    5291         the machine execution using the <link to="IConsole::resume()"/>
     5291        the machine execution using the <link to="IConsole::resume"/>
    52925292        call. If the machine execution is not Paused during this
    52935293        notification, then it means this notification is a <i>warning</i>
     
    53335333      <desc>
    53345334        Notification when a call to
    5335         <link to="IMachine::canShowConsoleWindow()"/> is made by a
     5335        <link to="IMachine::canShowConsoleWindow"/> is made by a
    53365336        front-end to check if a subsequent call to
    5337         <link to="IMachine::showConsoleWindow()"/> can succeed.
     5337        <link to="IMachine::showConsoleWindow"/> can succeed.
    53385338
    53395339        The callee should give an answer appropriate to the current
     
    53625362      <desc>
    53635363        Notification when a call to
    5364         <link to="IMachine::showConsoleWindow()"/>
     5364        <link to="IMachine::showConsoleWindow"/>
    53655365        requests the console window to be activated and brought to
    53665366        foreground on the desktop of the host PC.
     
    58285828        <note>
    58295829          On success, this method implicitly calls
    5830           <link to="IMachine::saveSettings()"/> to save all current machine
     5830          <link to="IMachine::saveSettings"/> to save all current machine
    58315831          settings (including runtime changes to the DVD drive, etc.).
    58325832          Together with the impossibility to change any VM settings when it is
     
    60236023
    60246024        <note>
    6025           This method implicitly calls <link to="IMachine::saveSettings()"/> to
     6025          This method implicitly calls <link to="IMachine::saveSettings"/> to
    60266026          save all current machine settings before taking an offline snapshot.
    60276027        </note>
     
    61226122        <note>
    61236123          Note that discarding the current snapshot
    6124           will implicitly call <link to="IMachine::saveSettings()"/> to
     6124          will implicitly call <link to="IMachine::saveSettings"/> to
    61256125          make all current machine settings permanent.
    61266126        </note>
     
    61396139    <method name="discardCurrentState">
    61406140      <desc>
    6141         This operation is similar to <link to="#discardSnapshot()"/> but
     6141        This operation is similar to <link to="#discardSnapshot"/> but
    61426142        affects the current machine state. This means that the state stored in
    61436143        the current snapshot will become a new current state, and all current
     
    61606160          If the machine state is <link to="MachineState_Saved">Saved</link>
    61616161          prior to this operation, the saved state file will be implicitly
    6162           discarded (as if <link to="IConsole::discardSavedState()"/> were
     6162          discarded (as if <link to="IConsole::discardSavedState"/> were
    61636163          called).
    61646164        </note>
     
    61796179        doing <link to="IConsole::discardSnapshot">discardSnapshot</link>
    61806180        (currentSnapshot.id(), progress) followed by
    6181         <link to="#discardCurrentState()"/>.
     6181        <link to="#discardCurrentState"/>.
    61826182
    61836183        As a result, the machine will be fully restored from the
     
    61906190        machine will be restored from its last snapshot, before discarding
    61916191        it. This differs from performing a single
    6192         <link to="#discardSnapshot()"/> call (note that no
    6193         <link to="#discardCurrentState()"/> will be possible after it)
     6192        <link to="#discardSnapshot"/> call (note that no
     6193        <link to="#discardCurrentState"/> will be possible after it)
    61946194        to the effect that the latter will preserve the current state instead of
    61956195        discarding it.
     
    62066206          If the machine state is <link to="MachineState_Saved">Saved</link>
    62076207          prior to this operation, the saved state file will be implicitly
    6208           discarded (as if <link to="#discardSavedState()"/> were
     6208          discarded (as if <link to="#discardSavedState"/> were
    62096209          called).
    62106210        </note>
     
    66866686
    66876687        The created filter can be added to the list of filters using
    6688         <link to="#insertUSBDeviceFilter()"/>.
     6688        <link to="#insertUSBDeviceFilter"/>.
    66896689
    66906690        <see>#USBDeviceFilters</see>
     
    68816881        to the total number of devices a machine can boot from, to make it
    68826882        possible to include all possible devices to the boot list.
    6883         <see><link to="IMachine::setBootOrder()"/></see>
     6883        <see><link to="IMachine::setBootOrder"/></see>
    68846884      </desc>
    68856885    </attribute>
     
    69136913
    69146914        <see>
    6915           <link to="IVirtualBox::createMachine()"/>,
    6916           <link to="IVirtualBox::openMachine()"/>
     6915          <link to="IVirtualBox::createMachine"/>,
     6916          <link to="IVirtualBox::openMachine"/>
    69176917        </see>
    69186918      </desc>
     
    69516951        <see>
    69526952          IHardDisk2,
    6953           <link to="IVirtualBox::createHardDisk2()"/>,
    6954           <link to="IVirtualBox::openHardDisk2()"/>,
     6953          <link to="IVirtualBox::createHardDisk2"/>,
     6954          <link to="IVirtualBox::openHardDisk2"/>,
    69556955          <link to="IMedium::location"/>
    69566956        </see>
     
    69656965        Keep in mind that the hard disk format identifier
    69666966        (<link to="IHardDiskFormat::id"/>) used in other API calls like
    6967         <link to="IVirtualBox::createHardDisk2()"/> to refer to a particular
     6967        <link to="IVirtualBox::createHardDisk2"/> to refer to a particular
    69686968        hard disk format is a case-insensitive string. This means that, for
    69696969        example, all of the following strings:
     
    69906990        The hard disk format set by this attribute is used by VirtualBox
    69916991        when the hard disk format was not specified explicitly. One example is
    6992         <link to="IVirtualBox::createHardDisk2()"/> with the <tt>null</tt>
     6992        <link to="IVirtualBox::createHardDisk2"/> with the <tt>null</tt>
    69936993        format argument. A more complex example is implicit creation of
    69946994        differencing hard disks when taking a snapshot of a virtual machine:
     
    70147014          <link to="#hardDiskFormats"/>,
    70157015          <link to="IHardDiskFormat::id"/>,
    7016           <link to="IVirtualBox::createHardDisk2()"/>
     7016          <link to="IVirtualBox::createHardDisk2"/>
    70177017        </see>
    70187018      </desc>
     
    74957495      In the current implementation, multiple snapshot branches within one
    74967496      virtual machine are not allowed. Every machine has a single branch,
    7497       and <link to="IConsole::takeSnapshot()"/> operation adds a new
     7497      and <link to="IConsole::takeSnapshot"/> operation adds a new
    74987498      snapshot to the top of that branch.
    74997499
    75007500      Existing snapshots can be discarded using
    7501       <link to="IConsole::discardSnapshot()"/>.
     7501      <link to="IConsole::discardSnapshot"/>.
    75027502
    75037503      <h3>Current snapshot</h3>
     
    75227522      directly from IVirtualBox
    75237523      using <link
    7524       to="IVirtualBox::getMachine()">getMachine()</link>, <link
    7525       to="IVirtualBox::findMachine()">findMachine()</link>, etc. (as opposed
     7524      to="IVirtualBox::getMachine">getMachine()</link>, <link
     7525      to="IVirtualBox::findMachine">findMachine()</link>, etc. (as opposed
    75267526      to instances returned by <link to="ISnapshot::machine"/>).  This state
    75277527      is always used when the machine is <link to="IConsole::powerUp"> powered
     
    75447544
    75457545      Similarly to snapshots, the current machine state can be discarded
    7546       using <link to="IConsole::discardCurrentState()"/>.
     7546      using <link to="IConsole::discardCurrentState"/>.
    75477547
    75487548      <h3>Taking and discarding snapshots</h3>
     
    75547554        <tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr>
    75557555
    7556         <tr><td><link to="IConsole::takeSnapshot()"/></td>
     7556        <tr><td><link to="IConsole::takeSnapshot"/></td>
    75577557
    75587558          <td>Save the current state of the virtual machine, including all
     
    75647564            taken)</td></tr>
    75657565
    7566         <tr><td><link to="IConsole::discardSnapshot()"/></td>
     7566        <tr><td><link to="IConsole::discardSnapshot"/></td>
    75677567
    75687568          <td>Forget the state of the virtual machine stored in the snapshot:
     
    75737573            current state are not directly affected</td></tr>
    75747574
    7575         <tr><td><link to="IConsole::discardCurrentState()"/></td>
     7575        <tr><td><link to="IConsole::discardCurrentState"/></td>
    75767576
    75777577          <td>Restore the current state of the virtual machine from the state
     
    75827582            is lost</td></tr>
    75837583
    7584         <tr><td><link to="IConsole::discardCurrentSnapshotAndState()"/></td>
     7584        <tr><td><link to="IConsole::discardCurrentSnapshotAndState"/></td>
    75857585
    75867586          <td>Completely revert the virtual machine to the state it was in
     
    77417741      media type:
    77427742      <ul>
    7743         <li><link to="IVirtualBox::openHardDisk2()"/></li>
    7744         <li><link to="IVirtualBox::openDVDImage()"/></li>
    7745         <li><link to="IVirtualBox::openFloppyImage()"/></li>
     7743        <li><link to="IVirtualBox::openHardDisk2"/></li>
     7744        <li><link to="IVirtualBox::openDVDImage"/></li>
     7745        <li><link to="IVirtualBox::openFloppyImage"/></li>
    77467746      </ul>
    77477747
    77487748      New hard disk media are created using the
    7749       <link to="IVirtualBox::createHardDisk2()"/> method. CD/DVD and floppy
     7749      <link to="IVirtualBox::createHardDisk2"/> method. CD/DVD and floppy
    77507750      images are created outside VirtualBox, usually by storing a copy
    77517751      of the real medium of the corresponding type in a regular file.
     
    77667766      <link to="IVirtualBox::DVDImages"/> and
    77677767      <link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
    7768       quickly found by UUID using <link to="IVirtualBox::getHardDisk2()"/>
     7768      quickly found by UUID using <link to="IVirtualBox::getHardDisk2"/>
    77697769      and similar methods or by location using
    7770       <link to="IVirtualBox::findHardDisk2()"/> and similar methods.
     7770      <link to="IVirtualBox::findHardDisk2"/> and similar methods.
    77717771
    77727772      Only known media can be attached to virtual machines.
    77737773
    77747774      Removing known media from the media registry is performed when the given
    7775       medium is closed using the <link to="#close()"/> method or when its
     7775      medium is closed using the <link to="#close"/> method or when its
    77767776      associated storage unit is deleted (only for hard disks).
    77777777
     
    79467946          The returned array will include a machine even if this medium is not
    79477947          attached to that machine in the current state but attached to it in
    7948           one of the machine's snapshots. See <link to="#getSnapshotIds()"/> for
     7948          one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
    79497949          details.
    79507950        </note>
     
    79877987        The read lock is shared: many clients can simultaneously lock the
    79887988        same media for reading unless it is already locked for writing (see
    7989         <link to="#lockWrite()"/>) in which case an error is returned.
     7989        <link to="#lockWrite"/>) in which case an error is returned.
    79907990
    79917991        When the medium is locked for reading, it cannot be modified
     
    80018001
    80028002        The medium locked for reading must be unlocked using the <link
    8003         to="#unlockRead()"/> method. Calls to <link to="#lockRead()"/>
     8003        to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
    80048004        can be nested and must be followed by the same number of paired
    8005         <link to="#unlockRead()"/> calls.
     8005        <link to="#unlockRead"/> calls.
    80068006
    80078007        This method sets the media state to <link
     
    80338033    <method name="unlockRead">
    80348034      <desc>
    8035         Cancels the read lock previously set by <link to="#lockRead()"/>.
     8035        Cancels the read lock previously set by <link to="#lockRead"/>.
    80368036
    80378037        Either on success or on failure, this method returns the current state
    80388038        of the medium <b>after</b> the operation.
    80398039
    8040         See <link to="#lockRead()"/> for more details.
     8040        See <link to="#lockRead"/> for more details.
    80418041
    80428042        <result name="VBOX_E_INVALID_OBJECT_STATE">
     
    80568056        Locks this medium for writing.
    80578057
    8058         The write lock, as opposed to <link to="#lockRead()"/>, is
     8058        The write lock, as opposed to <link to="#lockRead"/>, is
    80598059        exclusive: there may be only one client that holds a write lock
    80608060        and there may be no read locks while the write lock is held.
     
    80738073
    80748074        The medium locked for writing must be unlocked using the <link
    8075         to="#unlockWrite()"/> method. Calls to <link to="#lockWrite()"/>
     8075        to="#unlockWrite"/> method. Calls to <link to="#lockWrite"/>
    80768076        can <b>not</b> be nested and must be followed by a paired <link
    8077         to="#unlockWrite()"/> call.
     8077        to="#unlockWrite"/> call.
    80788078
    80798079        This method sets the media state to <link
     
    81048104    <method name="unlockWrite">
    81058105      <desc>
    8106         Cancels the write lock previously set by <link to="#lockWrite()"/>.
     8106        Cancels the write lock previously set by <link to="#lockWrite"/>.
    81078107
    81088108        Either on success or on failure, this method returns the current
    81098109        state of the medium <b>after</b> the operation.
    81108110
    8111         See <link to="#lockWrite()"/> for more details.
     8111        See <link to="#lockWrite"/> for more details.
    81128112
    81138113        <result name="VBOX_E_INVALID_OBJECT_STATE">
     
    82888288
    82898289      New base hard disks are created using
    8290       <link to="IVirtualBox::createHardDisk2()"/>. Existing hard disks are
    8291       opened using <link to="IVirtualBox::openHardDisk2()"/>. Differencing hard
     8290      <link to="IVirtualBox::createHardDisk2"/>. Existing hard disks are
     8291      opened using <link to="IVirtualBox::openHardDisk2"/>. Differencing hard
    82928292      disks are usually implicitly created by VirtualBox when needed but may
    8293       also be created explicitly using <link to="#createDiffStorage()"/>.
     8293      also be created explicitly using <link to="#createDiffStorage"/>.
    82948294
    82958295      After the hard disk is successfully created (including the storage unit)
    82968296      or opened, it becomes a known hard disk (remembered in the internal media
    82978297      registry). Known hard disks can be attached to a virtual machine, accessed
    8298       through <link to="IVirtualBox::getHardDisk2()"/> and
    8299       <link to="IVirtualBox::findHardDisk2()"/> methods or enumerated using the
     8298      through <link to="IVirtualBox::getHardDisk2"/> and
     8299      <link to="IVirtualBox::findHardDisk2"/> methods or enumerated using the
    83008300      <link to="IVirtualBox::hardDisks2"/> array (only for base hard disks).
    83018301
    8302       The following methods, besides <link to="IMedium::close()"/>,
     8302      The following methods, besides <link to="IMedium::close"/>,
    83038303      automatically remove the hard disk from the media registry:
    83048304      <ul>
    8305         <li><link to="#deleteStorage()"/></li>
    8306         <li><link to="#mergeTo()"/></li>
     8305        <li><link to="#deleteStorage"/></li>
     8306        <li><link to="#mergeTo"/></li>
    83078307      </ul>
    83088308
     
    83388338
    83398339      Hard disks are attached to virtual machines using the
    8340       <link to="IMachine::attachHardDisk2()"/> method and detached using the
    8341       <link to="IMachine::detachHardDisk2()"/> method. Depending on their
     8340      <link to="IMachine::attachHardDisk2"/> method and detached using the
     8341      <link to="IMachine::detachHardDisk2"/> method. Depending on their
    83428342      <link to="#type"/>, hard disks are attached either
    83438343      <i>directly</i> or <i>indirectly</i>.
     
    83488348      hard disk linked to it is implicitly created and this differencing hard
    83498349      disk is associated with the machine and used for hard disk operations.
    8350       This also means that if <link to="IMachine::attachHardDisk2()"/> performs
     8350      This also means that if <link to="IMachine::attachHardDisk2"/> performs
    83518351      a direct attachment then the same hard disk will be returned in response
    8352       to the subsequent  <link to="IMachine::getHardDisk2()"/> call; however if
     8352      to the subsequent  <link to="IMachine::getHardDisk2"/> call; however if
    83538353      an indirect attachment is performed then
    8354       <link to="IMachine::getHardDisk2()"/> will return the implicitly created
     8354      <link to="IMachine::getHardDisk2"/> will return the implicitly created
    83558355      differencing hard disk, not the original one passed to <link
    8356       to="IMachine::attachHardDisk2()"/>. The following table shows the
     8356      to="IMachine::attachHardDisk2"/>. The following table shows the
    83578357      dependency of the attachment type on the hard disk type:
    83588358
     
    84158415      Detaching hard disks is performed in a <i>deferred</i> fashion. This means
    84168416      that the given hard disk remains associated with the given machine after a
    8417       successful <link to="IMachine::detachHardDisk2()"/> call until
    8418       <link to="IMachine::saveSettings()"/> is called to save all changes to
     8417      successful <link to="IMachine::detachHardDisk2"/> call until
     8418      <link to="IMachine::saveSettings"/> is called to save all changes to
    84198419      machine settings to disk. This deferring is necessary to guarantee that
    84208420      the hard disk configuration may be restored at any time by a call to
    8421       <link to="IMachine::discardSettings()"/>  before the settings
     8421      <link to="IMachine::discardSettings"/>  before the settings
    84228422      are saved (committed).
    84238423
    8424       Note that if <link to="IMachine::discardSettings()"/> is called after
     8424      Note that if <link to="IMachine::discardSettings"/> is called after
    84258425      indirectly attaching some hard disks to the machine but before a call to
    8426       <link to="IMachine::saveSettings()"/> is made, it will implicitly delete
     8426      <link to="IMachine::saveSettings"/> is made, it will implicitly delete
    84278427      all differencing hard disks implicitly created by
    8428       <link to="IMachine::attachHardDisk2()"/> for these indirect attachments.
     8428      <link to="IMachine::attachHardDisk2"/> for these indirect attachments.
    84298429      Such implicitly created hard disks will also be immediately deleted when
    8430       detached explicitly using the <link to="IMachine::detachHardDisk2()"/>
    8431       call if it is made before <link to="IMachine::saveSettings()"/>. This
     8430      detached explicitly using the <link to="IMachine::detachHardDisk2"/>
     8431      call if it is made before <link to="IMachine::saveSettings"/>. This
    84328432      implicit deletion is safe because newly created differencing hard
    84338433      disks do not contain any user data.
    84348434
    84358435      However, keep in mind that detaching differencing hard disks that were
    8436       implicitly created by <link to="IMachine::attachHardDisk2()"/>
    8437       before the last <link to="IMachine::saveSettings()"/> call will
     8436      implicitly created by <link to="IMachine::attachHardDisk2"/>
     8437      before the last <link to="IMachine::saveSettings"/> call will
    84388438      <b>not</b> implicitly delete them as they may already contain some data
    84398439      (for example, as a result of virtual machine execution). If these hard
    84408440      disks are no more necessary, the caller can always delete them explicitly
    8441       using <link to="#deleteStorage()"/> after they are actually de-associated
    8442       from this machine by the <link to="IMachine::saveSettings()"/> call.
     8441      using <link to="#deleteStorage"/> after they are actually de-associated
     8442      from this machine by the <link to="IMachine::saveSettings"/> call.
    84438443
    84448444      <h3>Smart Attachment</h3>
     
    85038503      attachment is searched for descendants. This backup copy is created when
    85048504      the hard disk configuration is changed for the first time after the last
    8505       <link to="IMachine::saveSettings()"/> call and used by
    8506       <link to="IMachine::discardSettings()"/> to undo the recent hard disk
     8505      <link to="IMachine::saveSettings"/> call and used by
     8506      <link to="IMachine::discardSettings"/> to undo the recent hard disk
    85078507      changes. When such a descendant is found in this backup copy, it will be
    85088508      simply re-attached back, without creating a new differencing hard disk for
     
    86418641
    86428642        The list of all properties supported by the given hard disk format can
    8643         be obtained with <link to="IHardDiskFormat::describeProperties()"/>.
     8643        be obtained with <link to="IHardDiskFormat::describeProperties"/>.
    86448644
    86458645        Note that if this method returns a <tt>null</tt> @a value, the requested
     
    86648664
    86658665        The list of all properties supported by the given hard disk format can
    8666         be obtained with <link to="IHardDiskFormat::describeProperties()"/>.
     8666        be obtained with <link to="IHardDiskFormat::describeProperties"/>.
    86678667
    86688668        Note that setting the property value to <tt>null</tt> is equivalent to
     
    86948694
    86958695        The list of all properties supported by the given hard disk format can
    8696         be obtained with <link to="IHardDiskFormat::describeProperties()"/>.
     8696        be obtained with <link to="IHardDiskFormat::describeProperties"/>.
    86978697
    86988698        The method returns two arrays, the array of property names corresponding
     
    87348734        from the @a names array.
    87358735
    8736         Using this method over <link to="#setProperty()"/> is preferred if you
     8736        Using this method over <link to="#setProperty"/> is preferred if you
    87378737        need to set several properties at once since it will result into less
    87388738        IPC calls.
    87398739
    87408740        The list of all properties supported by the given hard disk format can
    8741         be obtained with <link to="IHardDiskFormat::describeProperties()"/>.
     8741        be obtained with <link to="IHardDiskFormat::describeProperties"/>.
    87428742
    87438743        Note that setting the property value to <tt>null</tt> is equivalent to
     
    90139013        format and at the location defined by the @a target argument.
    90149014
    9015         This operation is similar to <link to="#cloneTo()"/> except that when
     9015        This operation is similar to <link to="#cloneTo"/> except that when
    90169016        applied to a differencing hard disk, it will also copy missing hard disk
    90179017        data from all parent hard disks it is linked to. This will make the
     
    90259025        <note>
    90269026          For base hard disks, this operation is identical to
    9027           <link to="#cloneTo()"/>.
     9027          <link to="#cloneTo"/>.
    90289028        </note>
    90299029        <note>
     
    91729172        Each hard disk format is identified by a string represented by the
    91739173        <link to="#id"/> attribute. This string is used in calls like
    9174         <link to="IVirtualBox::createHardDisk2()"/> to specify the desired
     9174        <link to="IVirtualBox::createHardDisk2"/> to specify the desired
    91759175        format.
    91769176
     
    91969196        This string is used in methods of other interfaces where it is necessary
    91979197        to specify a hard disk format, such as
    9198         <link to="IVirtualBox::createHardDisk2()"/>.
     9198        <link to="IVirtualBox::createHardDisk2"/>.
    91999199      </desc>
    92009200    </attribute>
     
    96739673      be used to test for particular values of <link
    96749674      to="IFramebuffer::pixelFormat"/>. See also <link
    9675       to="IFramebuffer::requestResize()"/>.
     9675      to="IFramebuffer::requestResize"/>.
    96769676
    96779677      See also www.fourcc.org for more information about FOURCC pixel formats.
     
    97419741        Defines whether this frame buffer uses the virtual video card's memory
    97429742        buffer (guest VRAM) directly or not. See <link
    9743         to="IFramebuffer::requestResize()"/> for more information.
     9743        to="IFramebuffer::requestResize"/> for more information.
    97449744      </desc>
    97459745    </attribute>
     
    98659865        resize cannot be finished immediately during this call, @a finished
    98669866        must be set to @c false, and the implementation must call
    9867         <link to="IDisplay::resizeCompleted()"/> after it has returned from
     9867        <link to="IDisplay::resizeCompleted"/> after it has returned from
    98689868        this method as soon as possible. If @a finished is @c false, the
    98699869        machine will not call any frame buffer methods until
    9870         <link to="IDisplay::resizeCompleted()"/> is called.
     9870        <link to="IDisplay::resizeCompleted"/> is called.
    98719871
    98729872        Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
     
    98839883        <note>
    98849884          This method is called by the IDisplay object under the
    9885           <link to="#lock()"/> provided by this IFramebuffer
     9885          <link to="#lock"/> provided by this IFramebuffer
    98869886          implementation. If this method returns @c false in @a finished, then
    98879887          this lock is not released until
    9888           <link to="IDisplay::resizeCompleted()"/> is called.
     9888          <link to="IDisplay::resizeCompleted"/> is called.
    98899889        </note>
    98909890      </desc>
     
    98929892        <desc>
    98939893          Logical screen number. Must be used in the corresponding call to
    9894           <link to="IDisplay::resizeCompleted()"/> if this call is made.
     9894          <link to="IDisplay::resizeCompleted"/> if this call is made.
    98959895        </desc>
    98969896      </param>
     
    99209920          Can the VM start using the new frame buffer immediately
    99219921          after this method returns or it should wait for
    9922           <link to="IDisplay::resizeCompleted()"/>.
     9922          <link to="IDisplay::resizeCompleted"/>.
    99239923        </desc>
    99249924      </param>
     
    1080610806
    1080710807        The created filter can then be added to the list of filters using
    10808         <link to="#insertDeviceFilter()"/>.
     10808        <link to="#insertDeviceFilter"/>.
    1080910809
    1081010810        <result name="VBOX_E_INVALID_VM_STATE">
     
    1124111241
    1124211242      Besides auto-capturing based on filters, the device can be manually
    11243       captured by guests (<link to="IConsole::attachUSBDevice()"/>) if its
     11243      captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
    1124411244      state is USBDeviceState_Busy, USBDeviceState_Available or
    1124511245      USBDeviceState_Held.
     
    1124911249        states USBDeviceState_Busy and USBDeviceState_vailable are applicable
    1125011250        only to the Linux version of the product. This also means that (<link
    11251         to="IConsole::attachUSBDevice()"/>) can only succeed on Win32 if the
     11251        to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
    1125211252        device state is USBDeviceState_Held.
    1125311253      </note>
     
    1197411974    <method name="onShowWindow">
    1197511975      <desc>
    11976         Called by <link to="IMachine::canShowConsoleWindow()"/> and by
    11977         <link to="IMachine::showConsoleWindow()"/> in order to notify
     11976        Called by <link to="IMachine::canShowConsoleWindow"/> and by
     11977        <link to="IMachine::showConsoleWindow"/> in order to notify
    1197811978        console callbacks
    11979         <link to="IConsoleCallback::onCanShowWindow()"/>
    11980         and <link to="IConsoleCallback::onShowWindow()"/>.
     11979        <link to="IConsoleCallback::onCanShowWindow"/>
     11980        and <link to="IConsoleCallback::onShowWindow"/>.
    1198111981
    1198211982        <result name="VBOX_E_INVALID_OBJECT_STATE">
     
    1199211992    <method name="accessGuestProperty">
    1199311993      <desc>
    11994         Called by <link to="IMachine::getGuestProperty()"/> and by
    11995         <link to="IMachine::setGuestProperty()"/> in order to read and
     11994        Called by <link to="IMachine::getGuestProperty"/> and by
     11995        <link to="IMachine::setGuestProperty"/> in order to read and
    1199611996        modify guest properties.
    1199711997
     
    1217312173
    1217412174        Otherwise, if a direct session for a machine opened with
    12175         <link to="IVirtualBox::openSession()"/> is not explicitly closed
     12175        <link to="IVirtualBox::openSession"/> is not explicitly closed
    1217612176        when the application terminates, the state of the machine will
    1217712177        be set to <link to="MachineState_Aborted" /> on the server.
Note: See TracChangeset for help on using the changeset viewer.

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