5 The VirtualBox COM/XPCOM API

304 Pages·2010·1.69 MB·English

by  Oracle Corporation

Oracle VM
VirtualBox(cid:13)
R
Programming Guide and
Reference
Version 3.2.8
(cid:13)c 2004-2010 Oracle Corporation
http://www.virtualbox.org
Contents
1 Introduction 14
1.1 Modularity: thebuildingblocksofVirtualBox . . . . . . . . . . . . . . . 14
1.2 Twoguisesofthesame“MainAPI”:thewebserviceorCOM/XPCOM . . 15
1.3 Aboutwebservicesingeneral . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4 Runningthewebservice . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.4.1 Commandlineoptionsofvboxwebsrv . . . . . . . . . . . . . . . 18
1.4.2 Authenticatingatwebservicelogon . . . . . . . . . . . . . . . . 19
1.4.3 Solarishost: startingthewebserviceviaSMF . . . . . . . . . . 20
2 Theobject-orientedwebservice(OOWS) 21
2.1 Theobject-orientedwebserviceforJAX-WS . . . . . . . . . . . . . . . . 21
2.1.1 Preparations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.1.2 Gettingstarted: runningthesamplecode . . . . . . . . . . . . . 21
2.1.3 Loggingontothewebservice . . . . . . . . . . . . . . . . . . . 22
2.1.4 Obtainingbasicmachineinformation. Readingattributes . . . . 23
2.1.5 Changingmachinesettings. Sessions . . . . . . . . . . . . . . . 23
2.1.6 Startingmachines . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.1.7 Objectmanagement . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.2 Theobject-orientedwebserviceforPython . . . . . . . . . . . . . . . . 25
2.3 Theobject-orientedwebserviceforPHP . . . . . . . . . . . . . . . . . . 26
3 Usingtherawwebservicewithanylanguage 27
3.1 RawwebserviceexampleforJavawithAxis . . . . . . . . . . . . . . . . 27
3.2 RawwebserviceexampleforPerl. . . . . . . . . . . . . . . . . . . . . . 28
3.3 Programmingconsiderationsfortherawwebservice . . . . . . . . . . . 29
3.3.1 Fundamentalconventions . . . . . . . . . . . . . . . . . . . . . 29
3.3.2 Example: Atypicalwebserviceclientsession . . . . . . . . . . . 30
3.3.3 Managedobjectreferences . . . . . . . . . . . . . . . . . . . . . 31
3.3.4 Somemoredetailaboutwebserviceoperation . . . . . . . . . . 32
4 UsingtheMainAPIdocumentationtowritewebserviceclients 35
5 TheVirtualBoxCOM/XPCOMAPI 36
5.1 PythonCOMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.2 CommonPythonbindingslayer . . . . . . . . . . . . . . . . . . . . . . . 37
5.3 C++COMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.4 Eventqueueprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2
Contents
5.5 VisualBasicandVisualBasicScript(VBS)onWindowshosts . . . . . . 40
5.6 CbindingtoXPCOMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5.6.1 Gettingstarted . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.6.2 XPCOMinitialization . . . . . . . . . . . . . . . . . . . . . . . . 41
5.6.3 XPCOMmethodinvocation . . . . . . . . . . . . . . . . . . . . . 41
5.6.4 XPCOMattributeaccess . . . . . . . . . . . . . . . . . . . . . . . 42
5.6.5 Stringhandling . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.6.6 XPCOMuninitialization . . . . . . . . . . . . . . . . . . . . . . . 43
5.6.7 Compilingandlinking. . . . . . . . . . . . . . . . . . . . . . . . 44
6 TheVirtualBoxshell 45
7 MainAPIchangelog 47
7.1 IncompatibleAPIchangeswithversion3.2 . . . . . . . . . . . . . . . . 47
7.2 IncompatibleAPIchangeswithversion3.1 . . . . . . . . . . . . . . . . 48
7.3 IncompatibleAPIchangeswithversion3.0 . . . . . . . . . . . . . . . . 49
7.4 IncompatibleAPIchangeswithversion2.2 . . . . . . . . . . . . . . . . 51
7.5 IncompatibleAPIchangeswithversion2.1 . . . . . . . . . . . . . . . . 52
8 Licenseinformation 54
9 Classes(interfaces) 55
9.1 IAppliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
9.1.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
9.1.2 createVFSExplorer . . . . . . . . . . . . . . . . . . . . . . . . . . 57
9.1.3 getWarnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
9.1.4 importMachines . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
9.1.5 interpret . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
9.1.6 read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
9.1.7 write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
9.2 IAudioAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
9.2.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
9.3 IBIOSSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
9.3.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
9.4 IConsole. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.4.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9.4.2 adoptSavedState. . . . . . . . . . . . . . . . . . . . . . . . . . . 63
9.4.3 attachUSBDevice . . . . . . . . . . . . . . . . . . . . . . . . . . 64
9.4.4 createSharedFolder . . . . . . . . . . . . . . . . . . . . . . . . . 64
9.4.5 deleteSnapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
9.4.6 detachUSBDevice . . . . . . . . . . . . . . . . . . . . . . . . . . 66
9.4.7 findUSBDeviceByAddress . . . . . . . . . . . . . . . . . . . . . . 66
9.4.8 findUSBDeviceById . . . . . . . . . . . . . . . . . . . . . . . . . 66
9.4.9 forgetSavedState . . . . . . . . . . . . . . . . . . . . . . . . . . 67
9.4.10 getDeviceActivity . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3
Contents
9.4.11 getGuestEnteredACPIMode . . . . . . . . . . . . . . . . . . . . . 67
9.4.12 getPowerButtonHandled . . . . . . . . . . . . . . . . . . . . . . 67
9.4.13 pause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
9.4.14 powerButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
9.4.15 powerDown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
9.4.16 powerUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
9.4.17 powerUpPaused . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
9.4.18 registerCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
9.4.19 removeSharedFolder . . . . . . . . . . . . . . . . . . . . . . . . 70
9.4.20 reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
9.4.21 restoreSnapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
9.4.22 resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
9.4.23 saveState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
9.4.24 sleepButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
9.4.25 takeSnapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
9.4.26 teleport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
9.4.27 unregisterCallback. . . . . . . . . . . . . . . . . . . . . . . . . . 73
9.5 IConsoleCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
9.5.1 onAdditionsStateChange . . . . . . . . . . . . . . . . . . . . . . 74
9.5.2 onCPUChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
9.5.3 onCanShowWindow . . . . . . . . . . . . . . . . . . . . . . . . . 74
9.5.4 onKeyboardLedsChange. . . . . . . . . . . . . . . . . . . . . . . 75
9.5.5 onMediumChange . . . . . . . . . . . . . . . . . . . . . . . . . . 75
9.5.6 onMouseCapabilityChange . . . . . . . . . . . . . . . . . . . . . 75
9.5.7 onMousePointerShapeChange . . . . . . . . . . . . . . . . . . . 76
9.5.8 onNetworkAdapterChange . . . . . . . . . . . . . . . . . . . . . 77
9.5.9 onParallelPortChange . . . . . . . . . . . . . . . . . . . . . . . . 77
9.5.10 onRemoteDisplayInfoChange . . . . . . . . . . . . . . . . . . . . 77
9.5.11 onRuntimeError . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
9.5.12 onSerialPortChange . . . . . . . . . . . . . . . . . . . . . . . . . 79
9.5.13 onSharedFolderChange . . . . . . . . . . . . . . . . . . . . . . . 79
9.5.14 onShowWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.5.15 onStateChange . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
9.5.16 onStorageControllerChange . . . . . . . . . . . . . . . . . . . . 81
9.5.17 onUSBControllerChange . . . . . . . . . . . . . . . . . . . . . . 81
9.5.18 onUSBDeviceStateChange . . . . . . . . . . . . . . . . . . . . . 81
9.5.19 onVRDPServerChange. . . . . . . . . . . . . . . . . . . . . . . . 82
9.6 IDHCPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
9.6.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
9.6.2 setConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
9.6.3 start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
9.6.4 stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
9.7 IDisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
9.7.1 completeVHWACommand . . . . . . . . . . . . . . . . . . . . . 84
9.7.2 drawToScreen . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
4
Contents
9.7.3 getFramebuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
9.7.4 getScreenResolution. . . . . . . . . . . . . . . . . . . . . . . . . 85
9.7.5 invalidateAndUpdate . . . . . . . . . . . . . . . . . . . . . . . . 86
9.7.6 resizeCompleted . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
9.7.7 setFramebuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
9.7.8 setSeamlessMode . . . . . . . . . . . . . . . . . . . . . . . . . . 86
9.7.9 setVideoModeHint . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.7.10 takeScreenShot . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.7.11 takeScreenShotToArray . . . . . . . . . . . . . . . . . . . . . . . 88
9.8 IFramebuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9.8.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
9.8.2 getVisibleRegion . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
9.8.3 lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
9.8.4 notifyUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
9.8.5 processVHWACommand . . . . . . . . . . . . . . . . . . . . . . 92
9.8.6 requestResize . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
9.8.7 setVisibleRegion . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
9.8.8 unlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
9.8.9 videoModeSupported . . . . . . . . . . . . . . . . . . . . . . . . 95
9.9 IFramebufferOverlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
9.9.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
9.9.2 move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
9.10 IGuest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
9.10.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
9.10.2 executeProcess . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
9.10.3 getProcessOutput . . . . . . . . . . . . . . . . . . . . . . . . . . 99
9.10.4 getProcessStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
9.10.5 internalGetStatistics . . . . . . . . . . . . . . . . . . . . . . . . . 99
9.10.6 setCredentials . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
9.11 IGuestOSType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
9.11.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
9.12 IHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
9.12.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
9.12.2 createHostOnlyNetworkInterface. . . . . . . . . . . . . . . . . .106
9.12.3 createUSBDeviceFilter. . . . . . . . . . . . . . . . . . . . . . . .107
9.12.4 findHostDVDDrive . . . . . . . . . . . . . . . . . . . . . . . . . .107
9.12.5 findHostFloppyDrive . . . . . . . . . . . . . . . . . . . . . . . .107
9.12.6 findHostNetworkInterfaceById . . . . . . . . . . . . . . . . . . .107
9.12.7 findHostNetworkInterfaceByName . . . . . . . . . . . . . . . . .108
9.12.8 findHostNetworkInterfacesOfType . . . . . . . . . . . . . . . . .108
9.12.9 findUSBDeviceByAddress . . . . . . . . . . . . . . . . . . . . . .108
9.12.10findUSBDeviceById . . . . . . . . . . . . . . . . . . . . . . . . .108
9.12.11getProcessorCPUIDLeaf . . . . . . . . . . . . . . . . . . . . . . .109
9.12.12getProcessorDescription. . . . . . . . . . . . . . . . . . . . . . .109
9.12.13getProcessorFeature . . . . . . . . . . . . . . . . . . . . . . . . .110
5
Contents
9.12.14getProcessorSpeed. . . . . . . . . . . . . . . . . . . . . . . . . .110
9.12.15insertUSBDeviceFilter . . . . . . . . . . . . . . . . . . . . . . . .110
9.12.16removeHostOnlyNetworkInterface . . . . . . . . . . . . . . . . .111
9.12.17removeUSBDeviceFilter . . . . . . . . . . . . . . . . . . . . . . .111
9.13 IHostNetworkInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
9.13.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
9.13.2 dhcpRediscover . . . . . . . . . . . . . . . . . . . . . . . . . . .113
9.13.3 enableDynamicIpConfig . . . . . . . . . . . . . . . . . . . . . . .113
9.13.4 enableStaticIpConfig . . . . . . . . . . . . . . . . . . . . . . . .113
9.13.5 enableStaticIpConfigV6 . . . . . . . . . . . . . . . . . . . . . . .114
9.14 IHostUSBDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
9.14.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
9.15 IHostUSBDeviceFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
9.15.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
9.16 IInternalMachineControl. . . . . . . . . . . . . . . . . . . . . . . . . . .115
9.16.1 adoptSavedState. . . . . . . . . . . . . . . . . . . . . . . . . . .115
9.16.2 autoCaptureUSBDevices . . . . . . . . . . . . . . . . . . . . . .115
9.16.3 beginPowerUp . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
9.16.4 beginSavingState . . . . . . . . . . . . . . . . . . . . . . . . . .115
9.16.5 beginTakingSnapshot . . . . . . . . . . . . . . . . . . . . . . . .116
9.16.6 captureUSBDevice . . . . . . . . . . . . . . . . . . . . . . . . . .116
9.16.7 deleteSnapshot . . . . . . . . . . . . . . . . . . . . . . . . . . .117
9.16.8 detachAllUSBDevices . . . . . . . . . . . . . . . . . . . . . . . .117
9.16.9 detachUSBDevice . . . . . . . . . . . . . . . . . . . . . . . . . .117
9.16.10endPowerUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
9.16.11endSavingState . . . . . . . . . . . . . . . . . . . . . . . . . . .118
9.16.12endTakingSnapshot . . . . . . . . . . . . . . . . . . . . . . . . .118
9.16.13finishOnlineMergeMedium . . . . . . . . . . . . . . . . . . . . .119
9.16.14getIPCId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
9.16.15lockMedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
9.16.16onSessionEnd . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
9.16.17pullGuestProperties . . . . . . . . . . . . . . . . . . . . . . . . .120
9.16.18pushGuestProperty . . . . . . . . . . . . . . . . . . . . . . . . .120
9.16.19restoreSnapshot . . . . . . . . . . . . . . . . . . . . . . . . . . .120
9.16.20runUSBDeviceFilters . . . . . . . . . . . . . . . . . . . . . . . .121
9.16.21setRemoveSavedState . . . . . . . . . . . . . . . . . . . . . . . .121
9.16.22unlockMedia . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
9.16.23updateState . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
9.17 IInternalSessionControl . . . . . . . . . . . . . . . . . . . . . . . . . . .122
9.17.1 accessGuestProperty. . . . . . . . . . . . . . . . . . . . . . . . .122
9.17.2 assignMachine . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
9.17.3 assignRemoteMachine. . . . . . . . . . . . . . . . . . . . . . . .123
9.17.4 enumerateGuestProperties . . . . . . . . . . . . . . . . . . . . .123
9.17.5 getPID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
9.17.6 getRemoteConsole . . . . . . . . . . . . . . . . . . . . . . . . . .124
6
Contents
9.17.7 onCPUChange . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
9.17.8 onMediumChange . . . . . . . . . . . . . . . . . . . . . . . . . .124
9.17.9 onNetworkAdapterChange . . . . . . . . . . . . . . . . . . . . .125
9.17.10onParallelPortChange . . . . . . . . . . . . . . . . . . . . . . . .125
9.17.11onSerialPortChange . . . . . . . . . . . . . . . . . . . . . . . . .126
9.17.12onSharedFolderChange . . . . . . . . . . . . . . . . . . . . . . .126
9.17.13onShowWindow . . . . . . . . . . . . . . . . . . . . . . . . . . .126
9.17.14onStorageControllerChange . . . . . . . . . . . . . . . . . . . .127
9.17.15onUSBControllerChange . . . . . . . . . . . . . . . . . . . . . .127
9.17.16onUSBDeviceAttach . . . . . . . . . . . . . . . . . . . . . . . . .127
9.17.17onUSBDeviceDetach. . . . . . . . . . . . . . . . . . . . . . . . .128
9.17.18onVRDPServerChange. . . . . . . . . . . . . . . . . . . . . . . .128
9.17.19onlineMergeMedium . . . . . . . . . . . . . . . . . . . . . . . .128
9.17.20uninitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
9.17.21updateMachineState . . . . . . . . . . . . . . . . . . . . . . . .129
9.18 IKeyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
9.18.1 putCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
9.18.2 putScancode . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
9.18.3 putScancodes . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
9.19 ILocalOwner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
9.19.1 setLocalObject . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
9.20 IMachine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
9.20.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
9.20.2 addStorageController . . . . . . . . . . . . . . . . . . . . . . . .142
9.20.3 attachDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
9.20.4 canShowConsoleWindow . . . . . . . . . . . . . . . . . . . . . .144
9.20.5 createSharedFolder . . . . . . . . . . . . . . . . . . . . . . . . .144
9.20.6 deleteSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
9.20.7 detachDevice. . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
9.20.8 discardSettings . . . . . . . . . . . . . . . . . . . . . . . . . . .146
9.20.9 enumerateGuestProperties . . . . . . . . . . . . . . . . . . . . .147
9.20.10export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
9.20.11findSnapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
9.20.12getBootOrder . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
9.20.13getCPUIDLeaf . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
9.20.14getCPUProperty . . . . . . . . . . . . . . . . . . . . . . . . . . .149
9.20.15getCPUStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
9.20.16getExtraData . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
9.20.17getExtraDataKeys . . . . . . . . . . . . . . . . . . . . . . . . . .149
9.20.18getGuestProperty . . . . . . . . . . . . . . . . . . . . . . . . . .150
9.20.19getGuestPropertyTimestamp . . . . . . . . . . . . . . . . . . . .150
9.20.20getGuestPropertyValue . . . . . . . . . . . . . . . . . . . . . . .150
9.20.21getHWVirtExProperty . . . . . . . . . . . . . . . . . . . . . . . .151
9.20.22getMedium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
9.20.23getMediumAttachment . . . . . . . . . . . . . . . . . . . . . . .151
7
Contents
9.20.24getMediumAttachmentsOfController . . . . . . . . . . . . . . . .152
9.20.25getNetworkAdapter . . . . . . . . . . . . . . . . . . . . . . . . .152
9.20.26getParallelPort . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
9.20.27getSerialPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
9.20.28getSnapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
9.20.29getStorageControllerByInstance . . . . . . . . . . . . . . . . . .153
9.20.30getStorageControllerByName . . . . . . . . . . . . . . . . . . . .154
9.20.31hotPlugCPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
9.20.32hotUnplugCPU . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
9.20.33mountMedium . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
9.20.34passthroughDevice . . . . . . . . . . . . . . . . . . . . . . . . .155
9.20.35queryLogFilename . . . . . . . . . . . . . . . . . . . . . . . . . .156
9.20.36querySavedScreenshotPNGSize . . . . . . . . . . . . . . . . . .156
9.20.37querySavedThumbnailSize . . . . . . . . . . . . . . . . . . . . .156
9.20.38readLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
9.20.39readSavedScreenshotPNGToArray . . . . . . . . . . . . . . . . .157
9.20.40readSavedThumbnailToArray . . . . . . . . . . . . . . . . . . . .157
9.20.41removeAllCPUIDLeaves . . . . . . . . . . . . . . . . . . . . . . .158
9.20.42removeCPUIDLeaf . . . . . . . . . . . . . . . . . . . . . . . . . .158
9.20.43removeSharedFolder . . . . . . . . . . . . . . . . . . . . . . . .158
9.20.44removeStorageController . . . . . . . . . . . . . . . . . . . . . .158
9.20.45saveSettings . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
9.20.46setBootOrder. . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
9.20.47setCPUIDLeaf . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
9.20.48setCPUProperty . . . . . . . . . . . . . . . . . . . . . . . . . . .160
9.20.49setCurrentSnapshot . . . . . . . . . . . . . . . . . . . . . . . . .161
9.20.50setExtraData . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
9.20.51setGuestProperty . . . . . . . . . . . . . . . . . . . . . . . . . .162
9.20.52setGuestPropertyValue . . . . . . . . . . . . . . . . . . . . . . .162
9.20.53setHWVirtExProperty . . . . . . . . . . . . . . . . . . . . . . . .163
9.20.54showConsoleWindow . . . . . . . . . . . . . . . . . . . . . . . .163
9.21 IMachineDebugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
9.21.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
9.21.2 dumpStats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
9.21.3 getStats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
9.21.4 injectNMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
9.21.5 resetStats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
9.22 IManagedObjectRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
9.22.1 getInterfaceName . . . . . . . . . . . . . . . . . . . . . . . . . .166
9.22.2 release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .166
9.23 IMedium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167
9.23.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
9.23.2 cloneTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
9.23.3 close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
9.23.4 compact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
8
Contents
9.23.5 createBaseStorage . . . . . . . . . . . . . . . . . . . . . . . . . .179
9.23.6 createDiffStorage . . . . . . . . . . . . . . . . . . . . . . . . . .180
9.23.7 deleteStorage . . . . . . . . . . . . . . . . . . . . . . . . . . . .180
9.23.8 getProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181
9.23.9 getProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181
9.23.10getSnapshotIds . . . . . . . . . . . . . . . . . . . . . . . . . . .182
9.23.11lockRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182
9.23.12lockWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
9.23.13mergeTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
9.23.14refreshState . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
9.23.15reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
9.23.16resize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
9.23.17setProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
9.23.18setProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
9.23.19unlockRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
9.23.20unlockWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
9.24 IMediumAttachment . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
9.24.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
9.25 IMediumFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
9.25.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
9.25.2 describeProperties . . . . . . . . . . . . . . . . . . . . . . . . . .190
9.26 IMouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
9.26.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
9.26.2 putMouseEvent . . . . . . . . . . . . . . . . . . . . . . . . . . .192
9.26.3 putMouseEventAbsolute . . . . . . . . . . . . . . . . . . . . . .192
9.27 INATEngine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
9.27.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
9.27.2 addRedirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195
9.27.3 getNetworkSettings . . . . . . . . . . . . . . . . . . . . . . . . .195
9.27.4 removeRedirect . . . . . . . . . . . . . . . . . . . . . . . . . . .196
9.27.5 setNetworkSettings . . . . . . . . . . . . . . . . . . . . . . . . .196
9.28 INetworkAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196
9.28.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
9.28.2 attachToBridgedInterface . . . . . . . . . . . . . . . . . . . . . .199
9.28.3 attachToHostOnlyInterface . . . . . . . . . . . . . . . . . . . . .199
9.28.4 attachToInternalNetwork . . . . . . . . . . . . . . . . . . . . . .199
9.28.5 attachToNAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199
9.28.6 attachToVDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199
9.28.7 detach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199
9.29 IParallelPort. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
9.29.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
9.30 IPerformanceCollector . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
9.30.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202
9.30.2 disableMetrics . . . . . . . . . . . . . . . . . . . . . . . . . . . .202
9.30.3 enableMetrics . . . . . . . . . . . . . . . . . . . . . . . . . . . .203
9
Contents
9.30.4 getMetrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203
9.30.5 queryMetricsData . . . . . . . . . . . . . . . . . . . . . . . . . .204
9.30.6 setupMetrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
9.31 IPerformanceMetric . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
9.31.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
9.32 IProgress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
9.32.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
9.32.2 cancel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
9.32.3 setCurrentOperationProgress . . . . . . . . . . . . . . . . . . . .210
9.32.4 setNextOperation . . . . . . . . . . . . . . . . . . . . . . . . . .210
9.32.5 waitForCompletion . . . . . . . . . . . . . . . . . . . . . . . . .210
9.32.6 waitForOperationCompletion . . . . . . . . . . . . . . . . . . . .210
9.33 IRemoteDisplayInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211
9.33.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211
9.34 ISerialPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
9.34.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
9.35 ISession . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
9.35.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
9.35.2 close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
9.36 ISharedFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
9.36.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .218
9.37 ISnapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
9.37.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
9.38 IStorageController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
9.38.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
9.38.2 getIDEEmulationPort . . . . . . . . . . . . . . . . . . . . . . . .223
9.38.3 setIDEEmulationPort . . . . . . . . . . . . . . . . . . . . . . . .224
9.39 ISystemProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
9.39.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
9.39.2 getDeviceTypesForStorageBus . . . . . . . . . . . . . . . . . . .229
9.39.3 getMaxDevicesPerPortForStorageBus . . . . . . . . . . . . . . .230
9.39.4 getMaxInstancesOfStorageBus . . . . . . . . . . . . . . . . . . .230
9.39.5 getMaxPortCountForStorageBus . . . . . . . . . . . . . . . . . .230
9.39.6 getMinPortCountForStorageBus . . . . . . . . . . . . . . . . . .230
9.40 IUSBController . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
9.40.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
9.40.2 createDeviceFilter . . . . . . . . . . . . . . . . . . . . . . . . . .231
9.40.3 insertDeviceFilter . . . . . . . . . . . . . . . . . . . . . . . . . .232
9.40.4 removeDeviceFilter . . . . . . . . . . . . . . . . . . . . . . . . .232
9.41 IUSBDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
9.41.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
9.42 IUSBDeviceFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
9.42.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
9.43 IVFSExplorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
9.43.1 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
10