Changeset 16690 in vbox
- Timestamp:
- Feb 11, 2009 7:14:27 PM (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/VBox/Main/idl/VirtualBox.xidl
r16687 r16690 437 437 438 438 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"/>). 440 440 441 441 <pre> … … 621 621 <desc> 622 622 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"/> 624 624 call (<link to="IMachine::sessionState"/>); 625 625 the session is currently being opened 626 as a result of <link to="IVirtualBox::openRemoteSession ()"/>626 as a result of <link to="IVirtualBox::openRemoteSession"/> 627 627 call (<link to="ISession::state"/>) 628 628 </desc> … … 651 651 <desc> 652 652 Direct session 653 (opened by <link to="IVirtualBox::openSession ()"/>)653 (opened by <link to="IVirtualBox::openSession"/>) 654 654 </desc> 655 655 </const> … … 657 657 <desc> 658 658 Remote session 659 (opened by <link to="IVirtualBox::openRemoteSession ()"/>)659 (opened by <link to="IVirtualBox::openRemoteSession"/>) 660 660 </desc> 661 661 </const> … … 663 663 <desc> 664 664 Existing session 665 (opened by <link to="IVirtualBox::openExistingSession ()"/>)665 (opened by <link to="IVirtualBox::openExistingSession"/>) 666 666 </desc> 667 667 </const> … … 1111 1111 <li><link to="DeviceType_HardDisk"/>: the media is a hard disk 1112 1112 that, if registered, can be obtained using the 1113 <link to="IVirtualBox::getHardDisk2 ()"/> call.</li>1113 <link to="IVirtualBox::getHardDisk2"/> call.</li> 1114 1114 <li><link to="DeviceType_DVD"/>: the media is a CD/DVD image 1115 1115 that, if registered, can be obtained using the 1116 <link to="IVirtualBox::getDVDImage ()"/> call.</li>1116 <link to="IVirtualBox::getDVDImage"/> call.</li> 1117 1117 <li><link to="DeviceType_Floppy"/>: the media is a Floppy image 1118 1118 that, if registered, can be obtained using the 1119 <link to="IVirtualBox::getFloppyImage ()"/> call.</li>1119 <link to="IVirtualBox::getFloppyImage"/> call.</li> 1120 1120 </ul> 1121 1121 … … 1336 1336 VirtualBox startup) but it doesn't save the changes back until 1337 1337 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"/> 1339 1339 explicitly. Therefore, if the value of this attribute differs from the 1340 1340 value of <link to="#settingsFormatVersion"/>, then it … … 1365 1365 VirtualBox uses this version of the format when saving settings files 1366 1366 (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"/>). 1368 1368 1369 1369 <see>settingsFileVersion</see> … … 1452 1452 1453 1453 <li> 1454 Call <link to="IMachine::saveSettings ()" /> to write the settings1454 Call <link to="IMachine::saveSettings" /> to write the settings 1455 1455 to the machine's XML settings file. The configuration of the newly 1456 1456 created machine will not be saved to disk until this method is … … 1459 1459 1460 1460 <li> 1461 Call <link to="#registerMachine ()" /> to add the machine to the list1461 Call <link to="#registerMachine" /> to add the machine to the list 1462 1462 of machines known to VirtualBox. 1463 1463 </li> … … 1538 1538 settings file to store machine settings. 1539 1539 1540 As opposed to machines created by <link to="#createMachine ()"/>,1540 As opposed to machines created by <link to="#createMachine"/>, 1541 1541 the settings file of the machine created in "legacy" mode is not 1542 1542 automatically renamed when the machine name is changed -- it will always … … 1550 1550 Note that the configuration of the newly created machine is not 1551 1551 saved to disk (and therefore no settings file is created) 1552 until <link to="IMachine::saveSettings ()"/> is called. If the1552 until <link to="IMachine::saveSettings"/> is called. If the 1553 1553 specified settings file already exists, this method 1554 1554 will fail with <link to="VBOX_E_FILE_ERROR"/>.. 1555 1555 1556 See <link to="#createMachine ()"/> for more information.1556 See <link to="#createMachine"/> for more information. 1557 1557 1558 1558 @deprecated This method may be removed later. Use <link 1559 to="IVirtualBox::createMachine ()"/> instead.1559 to="IVirtualBox::createMachine"/> instead. 1560 1560 1561 1561 <note> … … 1597 1597 Opens a virtual machine from the existing settings file. 1598 1598 The opened machine remains unregistered until you call 1599 <link to="#registerMachine ()"/>.1599 <link to="#registerMachine"/>. 1600 1600 1601 1601 The specified settings file name can be absolute … … 1629 1629 1630 1630 Registers the machine previously created using 1631 <link to="#createMachine ()"/> or opened using1632 <link to="#openMachine ()"/> within this VirtualBox installation. After1631 <link to="#createMachine"/> or opened using 1632 <link to="#openMachine"/> within this VirtualBox installation. After 1633 1633 successful method invocation, the 1634 1634 <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent … … 1748 1748 allocate a format-specific storage unit at the specified location: 1749 1749 <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> 1753 1753 </ul> 1754 1754 … … 1759 1759 After the storage unit is successfully created, the hard disk gets 1760 1760 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"/> 1762 1762 methods. Remembered root (base) hard disks are also returned as part of 1763 1763 the <link to="#hardDisks2"/> array. See IHardDisk2 for more details. … … 1806 1806 After the hard disk is successfully opened by this method, it gets 1807 1807 remembered by (known to) this VirtualBox installation and will be 1808 accessible through <link to="#getHardDisk2 ()"/> and1809 <link to="#findHardDisk2 ()"/> methods. Remembered root (base) hard disks1808 accessible through <link to="#getHardDisk2"/> and 1809 <link to="#findHardDisk2"/> methods. Remembered root (base) hard disks 1810 1810 are also returned as part of the <link to="#hardDisks2"/> array and can 1811 1811 be attached to virtual machines. See IHardDisk2 for more details. … … 1852 1852 The hard disk with the given UUID must be known to this VirtualBox 1853 1853 installation, i.e. it must be previously created by 1854 <link to="#createHardDisk2 ()"/> or opened by <link1855 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. 1856 1856 1857 1857 <result name="VBOX_E_OBJECT_NOT_FOUND"> … … 1875 1875 The given hard disk must be known to this VirtualBox installation, i.e. 1876 1876 it must be previously created by 1877 <link to="#createHardDisk2 ()"/> or opened by <link1878 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. 1879 1879 1880 1880 The search is done by comparing the value of the @a location argument to … … 1911 1911 After the image is successfully opened by this method, it gets 1912 1912 remembered by (known to) this VirtualBox installation and will be 1913 accessible through <link to="#getDVDImage ()"/> and1914 <link to="#findDVDImage ()"/> methods. Remembered images are also1913 accessible through <link to="#getDVDImage"/> and 1914 <link to="#findDVDImage"/> methods. Remembered images are also 1915 1915 returned as part of the <link to="#DVDImages"/> array and can be mounted 1916 1916 to virtual machines. See IMedium for more details. … … 1951 1951 The image with the given UUID must be known to this VirtualBox 1952 1952 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. 1954 1954 1955 1955 <result name="VBOX_E_OBJECT_NOT_FOUND"> … … 1972 1972 The image with the given UUID must be known to this VirtualBox 1973 1973 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. 1975 1975 1976 1976 The search is done by comparing the value of the @a location argument to … … 2008 2008 After the image is successfully opened by this method, it gets 2009 2009 remembered by (known to) this VirtualBox installation and will be 2010 accessible through <link to="#getFloppyImage ()"/> and2011 <link to="#findFloppyImage ()"/> methods. Remembered images are also2010 accessible through <link to="#getFloppyImage"/> and 2011 <link to="#findFloppyImage"/> methods. Remembered images are also 2012 2012 returned as part of the <link to="#floppyImages"/> array and can be 2013 2013 mounted to virtual machines. See IMedium for more details. … … 2050 2050 The image with the given UUID must be known to this VirtualBox 2051 2051 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. 2053 2053 2054 2054 <result name="VBOX_E_OBJECT_NOT_FOUND"> … … 2071 2071 The image with the given UUID must be known to this VirtualBox 2072 2072 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. 2074 2074 2075 2075 The search is done by comparing the value of the @a location argument to … … 2224 2224 Before performing the actual data change, this method will ask all 2225 2225 registered callbacks using the 2226 <link to="IVirtualBoxCallback::onExtraDataCanChange ()"/>2226 <link to="IVirtualBoxCallback::onExtraDataCanChange"/> 2227 2227 notification for a permission. If one of the callbacks refuses the 2228 2228 new value, the change will not be performed. … … 2230 2230 <note> 2231 2231 On success, the 2232 <link to="IVirtualBoxCallback::onExtraDataChange ()"/> notification2232 <link to="IVirtualBoxCallback::onExtraDataChange"/> notification 2233 2233 is called to inform all registered callbacks about a successful data 2234 2234 change. … … 2303 2303 <li>Call <link to="IMachine::saveSettings" />.</li> 2304 2304 2305 <li>Close the session by calling <link to="ISession::close ()"/>.</li>2305 <li>Close the session by calling <link to="ISession::close"/>.</li> 2306 2306 </ol> 2307 2307 … … 2454 2454 for modification. 2455 2455 2456 As opposed to <link to="#openRemoteSession ()"/>, the number of2456 As opposed to <link to="#openRemoteSession"/>, the number of 2457 2457 remote sessions opened this way is not limited by the API 2458 2458 … … 2645 2645 Creates a backup copy of the global settings file 2646 2646 (<link to="#settingsFilePath"/>) in case of auto-conversion, and then 2647 calls <link to="#saveSettings ()"/>.2647 calls <link to="#saveSettings"/>. 2648 2648 2649 2649 Note that the backup copy is created <b>only</b> if the settings file 2650 2650 auto-conversion took place (see <link to="#settingsFileVersion"/> for 2651 2651 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. 2653 2653 2654 2654 The backup copy is created in the same directory where the original … … 2670 2670 receive a full path to the created backup file (for informational 2671 2671 purposes). Note that this will happen even if the subsequent 2672 <link to="#saveSettings ()"/> call performed by this method after the2672 <link to="#saveSettings"/> call performed by this method after the 2673 2673 copy operation, fails. 2674 2674 … … 3754 3754 subdirectory this settings file resides in. Thus, every time you 3755 3755 change the value of this property, the settings file will be 3756 renamed once you call <link to="#saveSettings ()"/> to confirm the3756 renamed once you call <link to="#saveSettings"/> to confirm the 3757 3757 change. The containing subdirectory will be also renamed, but 3758 3758 only if it has exactly the same name as the settings file … … 3772 3772 is being used by another running machine or by any other 3773 3773 process in the host operating system at a time when 3774 <link to="#saveSettings ()"/> is called.3774 <link to="#saveSettings"/> is called. 3775 3775 </li> 3776 3776 </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"/> 3778 3778 will return an appropriate error message explaining the exact 3779 3779 reason and the changes you made to this machine will not be … … 3781 3781 <note> 3782 3782 For "legacy" machines created using the 3783 <link to="IVirtualBox::createLegacyMachine ()"/> call,3783 <link to="IVirtualBox::createLegacyMachine"/> call, 3784 3784 the above naming limitations do not apply because the 3785 3785 machine name does not affect the settings file name. … … 3998 3998 VirtualBox startup) but it doesn't save the changes back until 3999 3999 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"/> 4001 4001 explicitly. Therefore, if the value of this attribute differs from the 4002 4002 value of <link to="IVirtualBox::settingsFormatVersion"/>, then it … … 4029 4029 <note> 4030 4030 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"/> 4032 4032 is called (no matter if any machine settings have been 4033 4033 changed after the creation or not). For opened machines … … 4046 4046 SessionSpawning or SessionOpen, this attribute contains the 4047 4047 same value as passed to the 4048 <link to="IVirtualBox::openRemoteSession ()"/> method in the @a4048 <link to="IVirtualBox::openRemoteSession"/> method in the @a 4049 4049 type parameter. If the session was opened directly using 4050 <link to="IVirtualBox::openSession ()"/>, or if4050 <link to="IVirtualBox::openSession"/>, or if 4051 4051 <link to="#sessionState"/> is SessionClosed, the value of this 4052 4052 attribute is @c null. … … 4059 4059 platform-dependent identifier of the process that has opened a 4060 4060 direct session for this machine using the 4061 <link to="IVirtualBox::openSession ()"/> call. The returned value4061 <link to="IVirtualBox::openSession"/> call. The returned value 4062 4062 is only valid if <link to="#sessionState"/> is SessionOpen or 4063 4063 SessionClosing (i.e. a session is currently open or being … … 4271 4271 You cannot attach a hard disk to a running machine. Also, you cannot 4272 4272 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"/>. 4274 4274 </note> 4275 4275 <note> … … 4277 4277 disk will implicitly be created for it and attached instead. If the 4278 4278 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"/>, 4280 4280 this implicitly created differencing hard disk will implicitly 4281 4281 be deleted. … … 4318 4318 4319 4319 Note that if the hard disk was indirectly attached by 4320 <link to="#attachHardDisk2 ()"/> to the given device slot then this4320 <link to="#attachHardDisk2"/> to the given device slot then this 4321 4321 method will return not the same object as passed to the 4322 <link to="#attachHardDisk2 ()"/> call. See <link to="IHardDisk2"/> for4322 <link to="#attachHardDisk2"/> call. See <link to="IHardDisk2"/> for 4323 4323 more detailed information about attaching hard disks. 4324 4324 … … 4350 4350 that the hard disk remains associated with the machine when this method 4351 4351 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"/> 4353 4353 for more detailed information about attaching hard disks. 4354 4354 … … 4358 4358 <note> 4359 4359 Detaching differencing hard disks implicitly created by <link 4360 to="#attachHardDisk2 ()"/> for the indirect attachment using this4360 to="#attachHardDisk2"/> for the indirect attachment using this 4361 4361 method will <b>not</b> implicitly delete them. The 4362 <link to="IHardDisk2::deleteStorage ()"/> operation should be4362 <link to="IHardDisk2::deleteStorage"/> operation should be 4363 4363 explicitly performed by the caller after the hard disk is successfully 4364 4364 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. 4366 4366 </note> 4367 4367 … … 4499 4499 Before performing the actual data change, this method will ask all 4500 4500 registered callbacks using the 4501 <link to="IVirtualBoxCallback::onExtraDataCanChange ()"/>4501 <link to="IVirtualBoxCallback::onExtraDataCanChange"/> 4502 4502 notification for a permission. If one of the callbacks refuses the 4503 4503 new value, the change will not be performed. … … 4505 4505 <note> 4506 4506 On success, the 4507 <link to="IVirtualBoxCallback::onExtraDataChange ()"/> notification4507 <link to="IVirtualBoxCallback::onExtraDataChange"/> notification 4508 4508 is called to inform all registered callbacks about a successful data 4509 4509 change. … … 4535 4535 Saves any changes to machine settings made since the session 4536 4536 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"/>. 4538 4538 For registered machines, new settings become visible to all 4539 4539 other VirtualBox clients after successful invocation of this 4540 4540 method. 4541 4541 <note> 4542 The method sends <link to="IVirtualBoxCallback::onMachineDataChange ()"/>4542 The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/> 4543 4543 notification event after the configuration has been successfully 4544 4544 saved (only for registered machines). … … 4569 4569 Creates a backup copy of the machine settings file (<link 4570 4570 to="#settingsFilePath"/>) in case of auto-conversion, and then calls 4571 <link to="#saveSettings ()"/>.4571 <link to="#saveSettings"/>. 4572 4572 4573 4573 Note that the backup copy is created <b>only</b> if the settings file 4574 4574 auto-conversion took place (see <link to="#settingsFileVersion"/> for 4575 4575 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. 4577 4577 4578 4578 The backup copy is created in the same directory where the original … … 4594 4594 receive a full path to the created backup file (for informational 4595 4595 purposes). Note that this will happen even if the subsequent 4596 <link to="#saveSettings ()"/> call performed by this method after the4596 <link to="#saveSettings"/> call performed by this method after the 4597 4597 copy operation, fails. 4598 4598 … … 4628 4628 <desc> 4629 4629 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"/> 4631 4631 or <link to="#discardSettings"/>. 4632 4632 <note> … … 4665 4665 <note> 4666 4666 The deleted machine settings file can be restored (saved again) 4667 by calling <link to="#saveSettings ()"/>.4667 by calling <link to="#saveSettings"/>. 4668 4668 </note> 4669 4669 … … 5275 5275 execution is always paused before calling this notification, and 5276 5276 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"/>. 5279 5279 Resuming the execution can lead to unpredictable results. 5280 5280 … … 5289 5289 as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user 5290 5290 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"/> 5292 5292 call. If the machine execution is not Paused during this 5293 5293 notification, then it means this notification is a <i>warning</i> … … 5333 5333 <desc> 5334 5334 Notification when a call to 5335 <link to="IMachine::canShowConsoleWindow ()"/> is made by a5335 <link to="IMachine::canShowConsoleWindow"/> is made by a 5336 5336 front-end to check if a subsequent call to 5337 <link to="IMachine::showConsoleWindow ()"/> can succeed.5337 <link to="IMachine::showConsoleWindow"/> can succeed. 5338 5338 5339 5339 The callee should give an answer appropriate to the current … … 5362 5362 <desc> 5363 5363 Notification when a call to 5364 <link to="IMachine::showConsoleWindow ()"/>5364 <link to="IMachine::showConsoleWindow"/> 5365 5365 requests the console window to be activated and brought to 5366 5366 foreground on the desktop of the host PC. … … 5828 5828 <note> 5829 5829 On success, this method implicitly calls 5830 <link to="IMachine::saveSettings ()"/> to save all current machine5830 <link to="IMachine::saveSettings"/> to save all current machine 5831 5831 settings (including runtime changes to the DVD drive, etc.). 5832 5832 Together with the impossibility to change any VM settings when it is … … 6023 6023 6024 6024 <note> 6025 This method implicitly calls <link to="IMachine::saveSettings ()"/> to6025 This method implicitly calls <link to="IMachine::saveSettings"/> to 6026 6026 save all current machine settings before taking an offline snapshot. 6027 6027 </note> … … 6122 6122 <note> 6123 6123 Note that discarding the current snapshot 6124 will implicitly call <link to="IMachine::saveSettings ()"/> to6124 will implicitly call <link to="IMachine::saveSettings"/> to 6125 6125 make all current machine settings permanent. 6126 6126 </note> … … 6139 6139 <method name="discardCurrentState"> 6140 6140 <desc> 6141 This operation is similar to <link to="#discardSnapshot ()"/> but6141 This operation is similar to <link to="#discardSnapshot"/> but 6142 6142 affects the current machine state. This means that the state stored in 6143 6143 the current snapshot will become a new current state, and all current … … 6160 6160 If the machine state is <link to="MachineState_Saved">Saved</link> 6161 6161 prior to this operation, the saved state file will be implicitly 6162 discarded (as if <link to="IConsole::discardSavedState ()"/> were6162 discarded (as if <link to="IConsole::discardSavedState"/> were 6163 6163 called). 6164 6164 </note> … … 6179 6179 doing <link to="IConsole::discardSnapshot">discardSnapshot</link> 6180 6180 (currentSnapshot.id(), progress) followed by 6181 <link to="#discardCurrentState ()"/>.6181 <link to="#discardCurrentState"/>. 6182 6182 6183 6183 As a result, the machine will be fully restored from the … … 6190 6190 machine will be restored from its last snapshot, before discarding 6191 6191 it. This differs from performing a single 6192 <link to="#discardSnapshot ()"/> call (note that no6193 <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) 6194 6194 to the effect that the latter will preserve the current state instead of 6195 6195 discarding it. … … 6206 6206 If the machine state is <link to="MachineState_Saved">Saved</link> 6207 6207 prior to this operation, the saved state file will be implicitly 6208 discarded (as if <link to="#discardSavedState ()"/> were6208 discarded (as if <link to="#discardSavedState"/> were 6209 6209 called). 6210 6210 </note> … … 6686 6686 6687 6687 The created filter can be added to the list of filters using 6688 <link to="#insertUSBDeviceFilter ()"/>.6688 <link to="#insertUSBDeviceFilter"/>. 6689 6689 6690 6690 <see>#USBDeviceFilters</see> … … 6881 6881 to the total number of devices a machine can boot from, to make it 6882 6882 possible to include all possible devices to the boot list. 6883 <see><link to="IMachine::setBootOrder ()"/></see>6883 <see><link to="IMachine::setBootOrder"/></see> 6884 6884 </desc> 6885 6885 </attribute> … … 6913 6913 6914 6914 <see> 6915 <link to="IVirtualBox::createMachine ()"/>,6916 <link to="IVirtualBox::openMachine ()"/>6915 <link to="IVirtualBox::createMachine"/>, 6916 <link to="IVirtualBox::openMachine"/> 6917 6917 </see> 6918 6918 </desc> … … 6951 6951 <see> 6952 6952 IHardDisk2, 6953 <link to="IVirtualBox::createHardDisk2 ()"/>,6954 <link to="IVirtualBox::openHardDisk2 ()"/>,6953 <link to="IVirtualBox::createHardDisk2"/>, 6954 <link to="IVirtualBox::openHardDisk2"/>, 6955 6955 <link to="IMedium::location"/> 6956 6956 </see> … … 6965 6965 Keep in mind that the hard disk format identifier 6966 6966 (<link to="IHardDiskFormat::id"/>) used in other API calls like 6967 <link to="IVirtualBox::createHardDisk2 ()"/> to refer to a particular6967 <link to="IVirtualBox::createHardDisk2"/> to refer to a particular 6968 6968 hard disk format is a case-insensitive string. This means that, for 6969 6969 example, all of the following strings: … … 6990 6990 The hard disk format set by this attribute is used by VirtualBox 6991 6991 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> 6993 6993 format argument. A more complex example is implicit creation of 6994 6994 differencing hard disks when taking a snapshot of a virtual machine: … … 7014 7014 <link to="#hardDiskFormats"/>, 7015 7015 <link to="IHardDiskFormat::id"/>, 7016 <link to="IVirtualBox::createHardDisk2 ()"/>7016 <link to="IVirtualBox::createHardDisk2"/> 7017 7017 </see> 7018 7018 </desc> … … 7495 7495 In the current implementation, multiple snapshot branches within one 7496 7496 virtual machine are not allowed. Every machine has a single branch, 7497 and <link to="IConsole::takeSnapshot ()"/> operation adds a new7497 and <link to="IConsole::takeSnapshot"/> operation adds a new 7498 7498 snapshot to the top of that branch. 7499 7499 7500 7500 Existing snapshots can be discarded using 7501 <link to="IConsole::discardSnapshot ()"/>.7501 <link to="IConsole::discardSnapshot"/>. 7502 7502 7503 7503 <h3>Current snapshot</h3> … … 7522 7522 directly from IVirtualBox 7523 7523 using <link 7524 to="IVirtualBox::getMachine ()">getMachine()</link>, <link7525 to="IVirtualBox::findMachine ()">findMachine()</link>, etc. (as opposed7524 to="IVirtualBox::getMachine">getMachine()</link>, <link 7525 to="IVirtualBox::findMachine">findMachine()</link>, etc. (as opposed 7526 7526 to instances returned by <link to="ISnapshot::machine"/>). This state 7527 7527 is always used when the machine is <link to="IConsole::powerUp"> powered … … 7544 7544 7545 7545 Similarly to snapshots, the current machine state can be discarded 7546 using <link to="IConsole::discardCurrentState ()"/>.7546 using <link to="IConsole::discardCurrentState"/>. 7547 7547 7548 7548 <h3>Taking and discarding snapshots</h3> … … 7554 7554 <tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr> 7555 7555 7556 <tr><td><link to="IConsole::takeSnapshot ()"/></td>7556 <tr><td><link to="IConsole::takeSnapshot"/></td> 7557 7557 7558 7558 <td>Save the current state of the virtual machine, including all … … 7564 7564 taken)</td></tr> 7565 7565 7566 <tr><td><link to="IConsole::discardSnapshot ()"/></td>7566 <tr><td><link to="IConsole::discardSnapshot"/></td> 7567 7567 7568 7568 <td>Forget the state of the virtual machine stored in the snapshot: … … 7573 7573 current state are not directly affected</td></tr> 7574 7574 7575 <tr><td><link to="IConsole::discardCurrentState ()"/></td>7575 <tr><td><link to="IConsole::discardCurrentState"/></td> 7576 7576 7577 7577 <td>Restore the current state of the virtual machine from the state … … 7582 7582 is lost</td></tr> 7583 7583 7584 <tr><td><link to="IConsole::discardCurrentSnapshotAndState ()"/></td>7584 <tr><td><link to="IConsole::discardCurrentSnapshotAndState"/></td> 7585 7585 7586 7586 <td>Completely revert the virtual machine to the state it was in … … 7741 7741 media type: 7742 7742 <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> 7746 7746 </ul> 7747 7747 7748 7748 New hard disk media are created using the 7749 <link to="IVirtualBox::createHardDisk2 ()"/> method. CD/DVD and floppy7749 <link to="IVirtualBox::createHardDisk2"/> method. CD/DVD and floppy 7750 7750 images are created outside VirtualBox, usually by storing a copy 7751 7751 of the real medium of the corresponding type in a regular file. … … 7766 7766 <link to="IVirtualBox::DVDImages"/> and 7767 7767 <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"/> 7769 7769 and similar methods or by location using 7770 <link to="IVirtualBox::findHardDisk2 ()"/> and similar methods.7770 <link to="IVirtualBox::findHardDisk2"/> and similar methods. 7771 7771 7772 7772 Only known media can be attached to virtual machines. 7773 7773 7774 7774 Removing known media from the media registry is performed when the given 7775 medium is closed using the <link to="#close ()"/> method or when its7775 medium is closed using the <link to="#close"/> method or when its 7776 7776 associated storage unit is deleted (only for hard disks). 7777 7777 … … 7946 7946 The returned array will include a machine even if this medium is not 7947 7947 attached to that machine in the current state but attached to it in 7948 one of the machine's snapshots. See <link to="#getSnapshotIds ()"/> for7948 one of the machine's snapshots. See <link to="#getSnapshotIds"/> for 7949 7949 details. 7950 7950 </note> … … 7987 7987 The read lock is shared: many clients can simultaneously lock the 7988 7988 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. 7990 7990 7991 7991 When the medium is locked for reading, it cannot be modified … … 8001 8001 8002 8002 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"/> 8004 8004 can be nested and must be followed by the same number of paired 8005 <link to="#unlockRead ()"/> calls.8005 <link to="#unlockRead"/> calls. 8006 8006 8007 8007 This method sets the media state to <link … … 8033 8033 <method name="unlockRead"> 8034 8034 <desc> 8035 Cancels the read lock previously set by <link to="#lockRead ()"/>.8035 Cancels the read lock previously set by <link to="#lockRead"/>. 8036 8036 8037 8037 Either on success or on failure, this method returns the current state 8038 8038 of the medium <b>after</b> the operation. 8039 8039 8040 See <link to="#lockRead ()"/> for more details.8040 See <link to="#lockRead"/> for more details. 8041 8041 8042 8042 <result name="VBOX_E_INVALID_OBJECT_STATE"> … … 8056 8056 Locks this medium for writing. 8057 8057 8058 The write lock, as opposed to <link to="#lockRead ()"/>, is8058 The write lock, as opposed to <link to="#lockRead"/>, is 8059 8059 exclusive: there may be only one client that holds a write lock 8060 8060 and there may be no read locks while the write lock is held. … … 8073 8073 8074 8074 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"/> 8076 8076 can <b>not</b> be nested and must be followed by a paired <link 8077 to="#unlockWrite ()"/> call.8077 to="#unlockWrite"/> call. 8078 8078 8079 8079 This method sets the media state to <link … … 8104 8104 <method name="unlockWrite"> 8105 8105 <desc> 8106 Cancels the write lock previously set by <link to="#lockWrite ()"/>.8106 Cancels the write lock previously set by <link to="#lockWrite"/>. 8107 8107 8108 8108 Either on success or on failure, this method returns the current 8109 8109 state of the medium <b>after</b> the operation. 8110 8110 8111 See <link to="#lockWrite ()"/> for more details.8111 See <link to="#lockWrite"/> for more details. 8112 8112 8113 8113 <result name="VBOX_E_INVALID_OBJECT_STATE"> … … 8288 8288 8289 8289 New base hard disks are created using 8290 <link to="IVirtualBox::createHardDisk2 ()"/>. Existing hard disks are8291 opened using <link to="IVirtualBox::openHardDisk2 ()"/>. Differencing hard8290 <link to="IVirtualBox::createHardDisk2"/>. Existing hard disks are 8291 opened using <link to="IVirtualBox::openHardDisk2"/>. Differencing hard 8292 8292 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"/>. 8294 8294 8295 8295 After the hard disk is successfully created (including the storage unit) 8296 8296 or opened, it becomes a known hard disk (remembered in the internal media 8297 8297 registry). Known hard disks can be attached to a virtual machine, accessed 8298 through <link to="IVirtualBox::getHardDisk2 ()"/> and8299 <link to="IVirtualBox::findHardDisk2 ()"/> methods or enumerated using the8298 through <link to="IVirtualBox::getHardDisk2"/> and 8299 <link to="IVirtualBox::findHardDisk2"/> methods or enumerated using the 8300 8300 <link to="IVirtualBox::hardDisks2"/> array (only for base hard disks). 8301 8301 8302 The following methods, besides <link to="IMedium::close ()"/>,8302 The following methods, besides <link to="IMedium::close"/>, 8303 8303 automatically remove the hard disk from the media registry: 8304 8304 <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> 8307 8307 </ul> 8308 8308 … … 8338 8338 8339 8339 Hard disks are attached to virtual machines using the 8340 <link to="IMachine::attachHardDisk2 ()"/> method and detached using the8341 <link to="IMachine::detachHardDisk2 ()"/> method. Depending on their8340 <link to="IMachine::attachHardDisk2"/> method and detached using the 8341 <link to="IMachine::detachHardDisk2"/> method. Depending on their 8342 8342 <link to="#type"/>, hard disks are attached either 8343 8343 <i>directly</i> or <i>indirectly</i>. … … 8348 8348 hard disk linked to it is implicitly created and this differencing hard 8349 8349 disk is associated with the machine and used for hard disk operations. 8350 This also means that if <link to="IMachine::attachHardDisk2 ()"/> performs8350 This also means that if <link to="IMachine::attachHardDisk2"/> performs 8351 8351 a direct attachment then the same hard disk will be returned in response 8352 to the subsequent <link to="IMachine::getHardDisk2 ()"/> call; however if8352 to the subsequent <link to="IMachine::getHardDisk2"/> call; however if 8353 8353 an indirect attachment is performed then 8354 <link to="IMachine::getHardDisk2 ()"/> will return the implicitly created8354 <link to="IMachine::getHardDisk2"/> will return the implicitly created 8355 8355 differencing hard disk, not the original one passed to <link 8356 to="IMachine::attachHardDisk2 ()"/>. The following table shows the8356 to="IMachine::attachHardDisk2"/>. The following table shows the 8357 8357 dependency of the attachment type on the hard disk type: 8358 8358 … … 8415 8415 Detaching hard disks is performed in a <i>deferred</i> fashion. This means 8416 8416 that the given hard disk remains associated with the given machine after a 8417 successful <link to="IMachine::detachHardDisk2 ()"/> call until8418 <link to="IMachine::saveSettings ()"/> is called to save all changes to8417 successful <link to="IMachine::detachHardDisk2"/> call until 8418 <link to="IMachine::saveSettings"/> is called to save all changes to 8419 8419 machine settings to disk. This deferring is necessary to guarantee that 8420 8420 the hard disk configuration may be restored at any time by a call to 8421 <link to="IMachine::discardSettings ()"/> before the settings8421 <link to="IMachine::discardSettings"/> before the settings 8422 8422 are saved (committed). 8423 8423 8424 Note that if <link to="IMachine::discardSettings ()"/> is called after8424 Note that if <link to="IMachine::discardSettings"/> is called after 8425 8425 indirectly attaching some hard disks to the machine but before a call to 8426 <link to="IMachine::saveSettings ()"/> is made, it will implicitly delete8426 <link to="IMachine::saveSettings"/> is made, it will implicitly delete 8427 8427 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. 8429 8429 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 ()"/>. This8430 detached explicitly using the <link to="IMachine::detachHardDisk2"/> 8431 call if it is made before <link to="IMachine::saveSettings"/>. This 8432 8432 implicit deletion is safe because newly created differencing hard 8433 8433 disks do not contain any user data. 8434 8434 8435 8435 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 will8436 implicitly created by <link to="IMachine::attachHardDisk2"/> 8437 before the last <link to="IMachine::saveSettings"/> call will 8438 8438 <b>not</b> implicitly delete them as they may already contain some data 8439 8439 (for example, as a result of virtual machine execution). If these hard 8440 8440 disks are no more necessary, the caller can always delete them explicitly 8441 using <link to="#deleteStorage ()"/> after they are actually de-associated8442 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. 8443 8443 8444 8444 <h3>Smart Attachment</h3> … … 8503 8503 attachment is searched for descendants. This backup copy is created when 8504 8504 the hard disk configuration is changed for the first time after the last 8505 <link to="IMachine::saveSettings ()"/> call and used by8506 <link to="IMachine::discardSettings ()"/> to undo the recent hard disk8505 <link to="IMachine::saveSettings"/> call and used by 8506 <link to="IMachine::discardSettings"/> to undo the recent hard disk 8507 8507 changes. When such a descendant is found in this backup copy, it will be 8508 8508 simply re-attached back, without creating a new differencing hard disk for … … 8641 8641 8642 8642 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"/>. 8644 8644 8645 8645 Note that if this method returns a <tt>null</tt> @a value, the requested … … 8664 8664 8665 8665 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"/>. 8667 8667 8668 8668 Note that setting the property value to <tt>null</tt> is equivalent to … … 8694 8694 8695 8695 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"/>. 8697 8697 8698 8698 The method returns two arrays, the array of property names corresponding … … 8734 8734 from the @a names array. 8735 8735 8736 Using this method over <link to="#setProperty ()"/> is preferred if you8736 Using this method over <link to="#setProperty"/> is preferred if you 8737 8737 need to set several properties at once since it will result into less 8738 8738 IPC calls. 8739 8739 8740 8740 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"/>. 8742 8742 8743 8743 Note that setting the property value to <tt>null</tt> is equivalent to … … 9013 9013 format and at the location defined by the @a target argument. 9014 9014 9015 This operation is similar to <link to="#cloneTo ()"/> except that when9015 This operation is similar to <link to="#cloneTo"/> except that when 9016 9016 applied to a differencing hard disk, it will also copy missing hard disk 9017 9017 data from all parent hard disks it is linked to. This will make the … … 9025 9025 <note> 9026 9026 For base hard disks, this operation is identical to 9027 <link to="#cloneTo ()"/>.9027 <link to="#cloneTo"/>. 9028 9028 </note> 9029 9029 <note> … … 9172 9172 Each hard disk format is identified by a string represented by the 9173 9173 <link to="#id"/> attribute. This string is used in calls like 9174 <link to="IVirtualBox::createHardDisk2 ()"/> to specify the desired9174 <link to="IVirtualBox::createHardDisk2"/> to specify the desired 9175 9175 format. 9176 9176 … … 9196 9196 This string is used in methods of other interfaces where it is necessary 9197 9197 to specify a hard disk format, such as 9198 <link to="IVirtualBox::createHardDisk2 ()"/>.9198 <link to="IVirtualBox::createHardDisk2"/>. 9199 9199 </desc> 9200 9200 </attribute> … … 9673 9673 be used to test for particular values of <link 9674 9674 to="IFramebuffer::pixelFormat"/>. See also <link 9675 to="IFramebuffer::requestResize ()"/>.9675 to="IFramebuffer::requestResize"/>. 9676 9676 9677 9677 See also www.fourcc.org for more information about FOURCC pixel formats. … … 9741 9741 Defines whether this frame buffer uses the virtual video card's memory 9742 9742 buffer (guest VRAM) directly or not. See <link 9743 to="IFramebuffer::requestResize ()"/> for more information.9743 to="IFramebuffer::requestResize"/> for more information. 9744 9744 </desc> 9745 9745 </attribute> … … 9865 9865 resize cannot be finished immediately during this call, @a finished 9866 9866 must be set to @c false, and the implementation must call 9867 <link to="IDisplay::resizeCompleted ()"/> after it has returned from9867 <link to="IDisplay::resizeCompleted"/> after it has returned from 9868 9868 this method as soon as possible. If @a finished is @c false, the 9869 9869 machine will not call any frame buffer methods until 9870 <link to="IDisplay::resizeCompleted ()"/> is called.9870 <link to="IDisplay::resizeCompleted"/> is called. 9871 9871 9872 9872 Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>, … … 9883 9883 <note> 9884 9884 This method is called by the IDisplay object under the 9885 <link to="#lock ()"/> provided by this IFramebuffer9885 <link to="#lock"/> provided by this IFramebuffer 9886 9886 implementation. If this method returns @c false in @a finished, then 9887 9887 this lock is not released until 9888 <link to="IDisplay::resizeCompleted ()"/> is called.9888 <link to="IDisplay::resizeCompleted"/> is called. 9889 9889 </note> 9890 9890 </desc> … … 9892 9892 <desc> 9893 9893 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. 9895 9895 </desc> 9896 9896 </param> … … 9920 9920 Can the VM start using the new frame buffer immediately 9921 9921 after this method returns or it should wait for 9922 <link to="IDisplay::resizeCompleted ()"/>.9922 <link to="IDisplay::resizeCompleted"/>. 9923 9923 </desc> 9924 9924 </param> … … 10806 10806 10807 10807 The created filter can then be added to the list of filters using 10808 <link to="#insertDeviceFilter ()"/>.10808 <link to="#insertDeviceFilter"/>. 10809 10809 10810 10810 <result name="VBOX_E_INVALID_VM_STATE"> … … 11241 11241 11242 11242 Besides auto-capturing based on filters, the device can be manually 11243 captured by guests (<link to="IConsole::attachUSBDevice ()"/>) if its11243 captured by guests (<link to="IConsole::attachUSBDevice"/>) if its 11244 11244 state is USBDeviceState_Busy, USBDeviceState_Available or 11245 11245 USBDeviceState_Held. … … 11249 11249 states USBDeviceState_Busy and USBDeviceState_vailable are applicable 11250 11250 only to the Linux version of the product. This also means that (<link 11251 to="IConsole::attachUSBDevice ()"/>) can only succeed on Win32 if the11251 to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the 11252 11252 device state is USBDeviceState_Held. 11253 11253 </note> … … 11974 11974 <method name="onShowWindow"> 11975 11975 <desc> 11976 Called by <link to="IMachine::canShowConsoleWindow ()"/> and by11977 <link to="IMachine::showConsoleWindow ()"/> in order to notify11976 Called by <link to="IMachine::canShowConsoleWindow"/> and by 11977 <link to="IMachine::showConsoleWindow"/> in order to notify 11978 11978 console callbacks 11979 <link to="IConsoleCallback::onCanShowWindow ()"/>11980 and <link to="IConsoleCallback::onShowWindow ()"/>.11979 <link to="IConsoleCallback::onCanShowWindow"/> 11980 and <link to="IConsoleCallback::onShowWindow"/>. 11981 11981 11982 11982 <result name="VBOX_E_INVALID_OBJECT_STATE"> … … 11992 11992 <method name="accessGuestProperty"> 11993 11993 <desc> 11994 Called by <link to="IMachine::getGuestProperty ()"/> and by11995 <link to="IMachine::setGuestProperty ()"/> in order to read and11994 Called by <link to="IMachine::getGuestProperty"/> and by 11995 <link to="IMachine::setGuestProperty"/> in order to read and 11996 11996 modify guest properties. 11997 11997 … … 12173 12173 12174 12174 Otherwise, if a direct session for a machine opened with 12175 <link to="IVirtualBox::openSession ()"/> is not explicitly closed12175 <link to="IVirtualBox::openSession"/> is not explicitly closed 12176 12176 when the application terminates, the state of the machine will 12177 12177 be set to <link to="MachineState_Aborted" /> on the server.
Note:
See TracChangeset
for help on using the changeset viewer.