Oracle VM VirtualBox R Programming Guide and Reference Version 4.1.24 c 2004-2012 Oracle Corporation http://www.virtualbox.org Contents 1 Introduction 16 1.1 Modularity: the building blocks of VirtualBox................... 16 1.2 Two guises of the same “Main API”: the web service or COM/XPCOM...... 17 1.3 About web services in general............................ 18 1.4 Running the web service............................... 19 1.4.1 Command line options of vboxwebsrv................... 19 1.4.2 Authenticating at web service logon.................... 20 2 Environment-specific notes 22 2.1 Using the object-oriented web service (OOWS)................... 22 2.1.1 The object-oriented web service for JAX-WS................ 22 2.1.2 The object-oriented web service for Python................ 24 2.1.3 The object-oriented web service for PHP................. 25 2.2 Using the raw web service with any language................... 25 2.2.1 Raw web service example for Java with Axis............... 25 2.2.2 Raw web service example for Perl..................... 26 2.2.3 Programming considerations for the raw web service.......... 27 2.3 Using COM/XPCOM directly............................. 31 2.3.1 Python COM API.............................. 31 2.3.2 Common Python bindings layer...................... 31 2.3.3 C++ COM API............................... 32 2.3.4 Event queue processing........................... 33 2.3.5 Visual Basic and Visual Basic Script (VBS) on Windows hosts...... 34 2.3.6 C binding to XPCOM API.......................... 34 3 Basic VirtualBox concepts; some examples 39 3.1 Obtaining basic machine information. Reading attributes............. 39 3.2 Changing machine settings. Sessions........................ 39 3.3 Launching virtual machines............................. 40 3.4 VirtualBox events................................... 40 4 The VirtualBox shell 42 5 Classes (interfaces) 44 5.1 IAdditionsFacility................................... 44 5.1.1 Attributes.................................. 44 5.2 IAdditionsStateChangedEvent (IEvent)....................... 44 5.3 IAppliance....................................... 45 5.3.1 Attributes.................................. 46 5.3.2 createVFSExplorer.............................. 47 5.3.3 getWarnings................................. 47 5.3.4 importMachines............................... 47 5.3.5 interpret................................... 47 5.3.6 read..................................... 47 5.3.7 write..................................... 48 5.4 IAudioAdapter..................................... 48 2 Contents 5.4.1 Attributes.................................. 48 5.5 IBIOSSettings..................................... 48 5.5.1 Attributes.................................. 49 5.6 IBandwidthControl.................................. 50 5.6.1 Attributes.................................. 50 5.6.2 createBandwidthGroup........................... 50 5.6.3 deleteBandwidthGroup........................... 50 5.6.4 getAllBandwidthGroups........................... 50 5.6.5 getBandwidthGroup............................. 50 5.7 IBandwidthGroup................................... 50 5.7.1 Attributes.................................. 51 5.8 IBandwidthGroupChangedEvent (IEvent)...................... 51 5.8.1 Attributes.................................. 51 5.9 ICPUChangedEvent (IEvent)............................. 51 5.9.1 Attributes.................................. 51 5.10 ICPUExecutionCapChangedEvent (IEvent)..................... 52 5.10.1 Attributes.................................. 52 5.11 ICanShowWindowEvent (IVetoEvent)........................ 52 5.12 IConsole........................................ 52 5.12.1 Attributes.................................. 52 5.12.2 adoptSavedState............................... 55 5.12.3 attachUSBDevice.............................. 55 5.12.4 createSharedFolder............................. 55 5.12.5 deleteSnapshot............................... 56 5.12.6 deleteSnapshotAndAllChildren....................... 57 5.12.7 deleteSnapshotRange............................ 57 5.12.8 detachUSBDevice.............................. 58 5.12.9 discardSavedState.............................. 58 5.12.10 findUSBDeviceByAddress.......................... 58 5.12.11 findUSBDeviceById............................. 59 5.12.12 getDeviceActivity.............................. 59 5.12.13 getGuestEnteredACPIMode......................... 59 5.12.14 getPowerButtonHandled.......................... 59 5.12.15 pause..................................... 59 5.12.16 powerButton................................. 60 5.12.17 powerDown................................. 60 5.12.18 powerUp................................... 60 5.12.19 powerUpPaused............................... 61 5.12.20 removeSharedFolder............................ 61 5.12.21 reset..................................... 61 5.12.22 restoreSnapshot............................... 61 5.12.23 resume.................................... 62 5.12.24 saveState................................... 62 5.12.25 sleepButton................................. 62 5.12.26 takeSnapshot................................ 63 5.12.27 teleport.................................... 63 5.13 IDHCPServer..................................... 64 5.13.1 Attributes.................................. 64 5.13.2 setConfiguration............................... 64 5.13.3 start..................................... 65 5.13.4 stop...................................... 65 5.14 IDisplay........................................ 65 5.14.1 completeVHWACommand......................... 65 3 Contents 5.14.2 drawToScreen................................ 66 5.14.3 getFramebuffer............................... 66 5.14.4 getScreenResolution............................. 67 5.14.5 invalidateAndUpdate............................ 67 5.14.6 resizeCompleted............................... 67 5.14.7 setFramebuffer............................... 67 5.14.8 setSeamlessMode.............................. 68 5.14.9 setVideoModeHint.............................. 68 5.14.10 takeScreenShot............................... 68 5.14.11 takeScreenShotPNGToArray........................ 69 5.14.12 takeScreenShotToArray........................... 69 5.15 IEvent......................................... 70 5.15.1 Attributes.................................. 71 5.15.2 setProcessed................................. 71 5.15.3 waitProcessed................................ 71 5.16 IEventListener..................................... 71 5.16.1 handleEvent................................. 71 5.17 IEventSource..................................... 72 5.17.1 createAggregator.............................. 72 5.17.2 createListener................................ 72 5.17.3 eventProcessed............................... 72 5.17.4 fireEvent................................... 72 5.17.5 getEvent................................... 73 5.17.6 registerListener............................... 73 5.17.7 unregisterListener.............................. 73 5.18 IEventSourceChangedEvent (IEvent)........................ 74 5.18.1 Attributes.................................. 74 5.19 IExtPack (IExtPackBase)............................... 74 5.19.1 queryObject................................. 74 5.20 IExtPackBase...................................... 74 5.20.1 Attributes.................................. 75 5.20.2 queryLicense................................. 76 5.21 IExtPackFile (IExtPackBase)............................. 76 5.21.1 Attributes.................................. 76 5.21.2 install..................................... 77 5.22 IExtPackManager................................... 77 5.22.1 Attributes.................................. 77 5.22.2 cleanup.................................... 77 5.22.3 find...................................... 77 5.22.4 isExtPackUsable............................... 78 5.22.5 openExtPackFile............................... 78 5.22.6 queryAllPlugInsForFrontend........................ 78 5.22.7 uninstall................................... 78 5.23 IExtPackPlugIn.................................... 78 5.23.1 Attributes.................................. 79 5.24 IExtraDataCanChangeEvent (IVetoEvent)...................... 79 5.24.1 Attributes.................................. 79 5.25 IExtraDataChangedEvent (IEvent).......................... 80 5.25.1 Attributes.................................. 80 5.26 IFramebuffer...................................... 80 5.26.1 Attributes.................................. 80 5.26.2 getVisibleRegion............................... 82 5.26.3 lock...................................... 82 4 Contents 5.26.4 notifyUpdate................................. 82 5.26.5 processVHWACommand.......................... 83 5.26.6 requestResize................................ 83 5.26.7 setVisibleRegion............................... 84 5.26.8 unlock.................................... 85 5.26.9 videoModeSupported............................ 85 5.27 IFramebufferOverlay (IFramebuffer)........................ 85 5.27.1 Attributes.................................. 86 5.27.2 move..................................... 86 5.28 IGuest......................................... 86 5.28.1 Attributes.................................. 87 5.28.2 copyFromGuest............................... 87 5.28.3 copyToGuest................................. 88 5.28.4 directoryClose................................ 88 5.28.5 directoryCreate............................... 89 5.28.6 directoryOpen................................ 89 5.28.7 directoryRead...............................