Home

SDK documentation - Oracle Software Downloads

1. l l Stopping powerDown lt Note that states to the right from PoweredOff Aborted and Saved in the above diagram are called online VM states These states represent the virtual machine which is being executed in a dedicated process usually with a GUI window attached to it where you can see the activity of the virtual machine and interact with it There are two special pseudo states FirstOnline and LastOnline that can be used in relational expressions to detect if the given machine state is online or not if machine GetState gt MachineState_FirstOnline amp machine GetState lt MachineState_LastOnline the machine is being executed When the virtual machine is in one of the online VM states that is being executed only a few machine settings can be modified Methods working with such settings contain an explicit note 352 6 Enumerations enums about that An attempt to change any other setting or perform a modifying operation during this time will result in the VBOX_E_INVALID_VM_STATE error All online states except Running Paused and Stuck are transitional they represent temporary conditions of the virtual machine that will last as long as the operation that initiated such a condition The Stuck state is a special case It means that execution of the machine has reached the Guru Meditation condition This condition indicates an
2. If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 5 77 17 onShowWindow void IInternalSessionControl onShowWindow in boolean check out boolean canShow out long long winId check canShow winld Called by IMachine canShowConsoleWindow and by IMachine showConsoleWindow in order to notify console listeners ICanShowWindowEvent and IShowWindowEvent If this method fails the following error codes may be reported e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 5 77 18 onStorageControllerChange void IInternalSessionControl onStorageControllerChange Triggered when settings of a storage controller of the associated virtual machine have changed If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 161 5 Classes interfaces 5 77 19 onStorageDeviceChange void IInternalSessionControl onStorageDeviceChange in IMediumAttachment mediumAttachment in boolean remove in boolean silent mediumAttachment The medium attachment which changed remove TRUE if the device is removed FALSE if it was added silent TRUE if the device is is silently reconfigured without notifying the guest about it Triggered when attach
3. Note Do not expect the session state state to return to Unlocked immediately after you invoke this method particularly if you have started a new VM process The session state will automatically return to Unlocked once the VM is no longer executing which can of course take a very long time If this method fails the following error codes may be reported e E_UNEXPECTED Session is not locked 5 121 ISessionStateChangedEvent IMachineEvent Note This interface extends IMachineEvent and therefore supports all its methods and attributes as well The state of the session for the given machine was changed See also IMachine sessionState 5 121 1 Attributes 5 121 1 1 state read only SessionState ISessionStateChangedEvent state New session state 5 122 ISharedFolder Note With the web service this interface is mapped to a structure Attributes that return this interface will not return an object but a complete structure containing the attributes listed below as structure members The ISharedFolder interface represents a folder in the host computer s file system accessible from the guest OS running inside a virtual machine using an associated logical name There are three types of shared folders e Global IVirtualBox sharedFolders shared folders available to all virtual machines e Permanent IMachine sharedFolders VM specific shared folders available to the give
4. Note This interface extends Framebuffer and therefore supports all its methods and attributes as well The IFramebufferOverlay interface represents an alpha blended overlay for displaying status icons above an IFramebuffer It is always created not visible so that it must be explicitly shown It only covers a portion of the IFramebuffer determined by its width height and co ordinates It is always in packed pixel little endian 32bit ARGB in that order format and may be written to directly Do re read the width though after setting it as it may be adjusted increased to make it more suitable for the front end 5 36 1 Attributes 5 36 1 1 x read only unsigned long IFramebufferOverlay x X position of the overlay relative to the frame buffer 103 5 Classes interfaces 5 36 1 2 y read only unsigned long IFramebufferOverlay y Y position of the overlay relative to the frame buffer 5 36 1 3 visible read write boolean IFramebufferOverlay visible Whether the overlay is currently visible 5 36 1 4 alpha read write unsigned long IFramebufferOverlay alpha The global alpha value for the overlay This may or may not be supported by a given front end 5 36 2 move void IFramebufferOverlay move in unsigned long x in unsigned long y Changes the overlay s position relative to the IFramebuffer 5 37 IFsObjlnfo Abstract parent interface for VirtualBox file system object inf
5. valEax CPUID leaf value for register eax valEbx CPUID leaf value for register ebx valEcx CPUID leaf value for register ecx valEdx CPUID leaf value for register edx Returns the CPU cpuid information for the specified leaf 5 69 13 getProcessorDescription wstring IHost getProcessorDescription in unsigned long cpuld cpuld Identifier of the CPU Note The current implementation might not necessarily return the description for this exact CPU Query the model string of a specified host CPU 5 69 14 getProcessorFeature boolean IHost getProcessorFeature in ProcessorFeature feature feature CPU Feature identifier Query whether a CPU feature is supported or not 5 69 15 getProcessorSpeed unsigned long IHost getProcessorSpeed in unsigned long cpuld cpuld Identifier of the CPU Query the approximate maximum speed of a specified host CPU in Megahertz 5 69 16 insertUSBDeviceFilter void IHost insertUSBDeviceFilter in unsigned long position in IHostUSBDeviceFilter filter position Position to insert the filter to filter USB device filter to insert 146 5 Classes interfaces Inserts the given USB device to the specified position in the list of filters Positions are numbered starting from 0 If the specified position is equal to or greater than the number of elements in the list the filter is added at the end of the collection Note Duplicates are not allowed s
6. 5 62 1 Attributes 5 62 1 1 status read only ProcessStatus IGuestProcessStateChangedEvent status New guest process status 122 5 Classes interfaces 5 62 1 2 error read only IVirtualBoxErrorInfo IGuestProcessStateChangedEvent error Error information in case of new session status is indicating an error The attribute IVirtualBoxErrorInfo resultDetail will contain the runtime IPRT error code from the guest See include iprt err h and include VBox err h for details 5 63 IGuestPropertyChangedEvent IMachineEvent Note This interface extends IMachineEvent and therefore supports all its methods and attributes as well Notification when a guest property has changed 5 63 1 Attributes 5 63 1 1 name read only wstring IGuestPropertyChangedEvent name The name of the property that has changed 5 63 1 2 value read only wstring IGuestPropertyChangedEvent value The new property value 5 63 1 3 flags read only wstring IGuestPropertyChangedEvent flags The new property flags 5 64 IGuestSession A guest session represents one impersonated user account in the guest so every operation will use the same credentials specified when creating the session object via IGuest createSession There can be a maximum of 32 sessions at once per VM whereas session 0 is reserved for the root session This root session is controlling all other guest sessions and also is responsible for actions w
7. IMachine machine String name machine getName Boolean attribute getters can sometimes be called isAttribute due to JAX WS naming conventions 3 2 Changing machine settings Sessions As said in the previous section to read a machine s attribute one invokes the corresponding get method One would think that to change settings of a machine it would suffice to call the corresponding set method for example to set a VM s memory to 1024 MB one would call setMemorySize 1024 Try that and you will get an error The machine is not mutable So unfortunately things are not that easy VirtualBox is a complicated environment in which multiple processes compete for possibly the same resources especially machine settings As a result machines must be locked before they can either be modified or started This is to prevent multiple processes from making conflicting changes to a machine it should for example not be allowed to change the memory size of a virtual machine while it is running You can t add more memory to a real computer while it is running either at least not to an ordinary PC Also two processes must not change settings at the same time or start a machine at the same time These requirements are implemented in the Main API by way of sessions in particu lar the ISession interface Each process which talks to VirtualBox needs its own instance of ISession In the web service yo
8. The actual event handler implementation is quite tedious as it has to implement a complete API interface Especially on Windows it is a lot of work to implement the complicated IDispatch 43 2 Environment specific notes interface requiring to load COM type information and using it in the IDispatch method imple mentation Overall this is quite tedious compared to passive event handling Passive event handling uses a similar event loop structure which requires calling the following function in a loop and processing the returned event appropriately rc IEventSource_GetEvent pEventSource pListener cTimeoutMS amp pEvent After processing the event it needs to be marked as processed with the following method call rc IEventSource_EventProcessed pEventSource pListener pEvent This is vital for vetoable events as they would be stuck otherwise waiting whether the veto comes or not It does not do any harm for other event types and in the end is cheaper than checking if the event at hand is vetoable or not The general event handling concepts are described in the API specification see chapter 3 4 VirtualBox events page 48 including how to aggregate multiple event sources for processing in one event loop As mentioned the sample illustrates the practical aspects of how to use both types of event handling active and passive from a C application Additional hints are in the comments documenting the helper methods in VBoxCA
9. e VBOX_E_OBJECT_NOT_FOUND osTypeld is invalid e VBOX_E_FILE_ERROR Resulting settings file name is invalid or the settings file already exists or could not be created due to an I O error e E_INVALIDARG name is empty or null 5 151 7 createMedium IMedium IVirtualBox createMedium in wstring format in wstring location in AccessMode accessMode in DeviceType aDeviceTypeType format Identifier of the storage format to use for the new medium location Location of the storage unit for the new medium accessMode Whether to open the image in read write or read only mode For a DVD device type this is ignored and read only mode is always assumed aDeviceTypeType Must be one of HardDisk DVD or Floppy Creates a new base medium object that will use the given storage format and location for medium data The actual storage unit is not created by this method In order to do it and before you are able to attach the created medium to virtual machines you must call one of the following methods to allocate a format specific storage unit at the specified location e IMedium createBaseStorage e IMedium createDiffStorage Some medium attributes such as IMedium id may remain uninitialized until the medium storage unit is successfully created by one of the above methods Depending on the given device type the file at the storage location must be in one of the media formats understood by Vir
10. o 75 5 16 3 detachFramebuffer oso Ra a A 75 SAGA APIS coa a ee eS Powe Ee Ee me 75 S 1G 5 perScreenkesglunon se s sede k a AE E 76 5 16 6 invalidateAndUpdate lt ou scese bee ctet eee eee Kopi 76 5 16 7 invalidateAnd pdateScreen wk A e e 76 5 16 8 notifyHiDPIOutputPolicyChange o o o 77 5 16 9 notifyScaleFactorChange oo e eee eee 77 516 10 gueryFramebuffer ociosos eee Bee ee 77 5 16 11 guerySourceBitMap 220 ooo 77 5 16 12 setSeamlessMode oso et BR tet at wt 77 5 16 13 setVideoModeHidt ee 78 5 16 14 takeScreenShot concisa 78 5 16 15 takeScreenShotToArray o i ho ee ceod ee ee eee Kopi 79 5 16 16 viewportGhang d ecards AE ER a 79 IDisplaySourceRittiap cocina SS bee ELE ERO 80 SAIZI ES oca a e ee 80 5172 QUEFBUMAPIDDO oe c c52 ee Ba oe Ow SO See ew ae re 80 IDn DBASE soe eee a RS Re A eA OS OS eee aw 4 SS 80 SISI PES a see oe ee ee ee a eae we ee BE oer we a we A 80 5 18 2 addFormals 444222 4 44888 Sea eee a a ES 81 5 183 isFormatSuppred iden 81 5 164 rem veFormats s esise e ee oei A AA a 81 IDnDModeChangedEvent IEvent o 81 5 19 1 Atmibutes concordar 81 IDnDSource IDnDBase 81 5 20 11 dragleRendidd coord o a 82 i MOP aea Ske el e Boss Be we wee bea ee ee a amp He we ER 82 BALS PECOREDALA nner ces cece ded EOP RAE EE Se EDS 82 IDnDTarget IDnDBase e ee ee 82
11. userName User name string can be empty password Password string can be empty domain Domain name guest logon scheme specific can be empty allowinteractiveLogon Flag whether the guest should alternatively allow the user to interac tively specify different credentials This flag might not be supported by all versions of the Additions Store login credentials that can be queried by guest operating systems with Additions installed The credentials are transient to the session and the guest may also choose to erase them Note that the caller cannot determine whether the guest operating system has queried or made use of the credentials If this method fails the following error codes may be reported e VBOX_E_VM_ERROR VMM device is not available 5 38 8 updateGuestAdditions IProgress IGuest updateGuestAdditions in wstring source in wstring arguments in AdditionsUpdateFlag flags source Path to the Guest Additions ISO file to use for the update arguments Optional command line arguments to use for the Guest Additions installer Useful for retrofitting features which weren t installed before in the guest flags AdditionsUpdateFlag flags Automatically updates already installed Guest Additions in a VM At the moment only Windows guests are supported Because the VirtualBox Guest Additions drivers are not WHQL certified yet there might be warning dialogs during the actual Guest Additions update These need to be con
12. 5 103 1 4 advertiseDefaultIPv6RouteEnabled read only boolean INATNetworkSettingEvent advertiseDefaultIPv6RouteEnabled 5 103 1 5 needDhcpServer read only boolean INATNetworkSettingEvent needDhcpServer 259 5 Classes interfaces 5 104 INATNetworkStartStopEvent INATNetworkChangedEvent Note This interface extends INATNetworkChangedEvent and therefore supports all its methods and attributes as well 5 104 1 Attributes 5 104 1 1 startEvent read only boolean INATNetworkStartStopEvent startEvent IsStartEvent is true when NAT network is started and false on stopping 5 105 INATRedirectEvent IMachineEvent Note This interface extends IMachineEvent and therefore supports all its methods and attributes as well Notification when NAT redirect rule added or removed 5 105 1 Attributes 5 105 1 1 slot read only unsigned long INATRedirectEvent slot Adapter which NAT attached to 5 105 1 2 remove read only boolean INATRedirectEvent remove Whether rule remove or add 5 105 1 3 name read only wstring INATRedirectEvent name Name of the rule 5 105 1 4 proto read only NATProtocol INATRedirectEvent proto Protocol TCP or UDP of the redirect rule 5 105 1 5 hostIP read only wstring INATRedirectEvent hostIP Host ip address to bind socket on 260 5 Classes interfaces 5 105 1 6 hostPort read only long INATRedirectEvent hostPort Host port to
13. 5 16 8 notifyHiDPlOutputPolicyChange void IDisplay notifyHiDPIOutputPolicyChange in boolean fUnscaledHiDPI fUnscaledHiDPI Notify OpenGL HGCM host service about HiDPI monitor scaling policy change 5 16 9 notifyScaleFactorChange void IDisplay notifyScaleFactorChange in unsigned long screenId in unsigned long u32ScaleFactorWMultiplied in unsigned long u32ScaleFactorHMultiplied screenld u32ScaleFactorWMultiplied u32ScaleFactorHMultiplied Notify OpenGL HGCM host service about graphics content scaling factor change 5 16 10 queryFramebuffer IFramebuffer IDisplay queryFramebuffer in unsigned long screenId screenld Queries the graphics updates targets for a screen 5 16 11 querySourceBitmap Note This method is not supported in the web service void IDisplay querySourceBitmap in unsigned long screenld out IDisplaySourceBitmap displaySourceBitmap screenld displaySourceBitmap Obtains the guest screen bitmap parameters 5 16 12 setSeamlessMode void IDisplay setSeamlessMode in boolean enabled enabled Enables or disables seamless guest display rendering seamless desktop integration mode Note Calling this method has no effect if IGuest getFacilityStatus with facility Seamless does not return Active 77 5 Classes interfaces 5 16 13 setVideoModeHint void IDisplay setVideoModeHint in unsigned long display in boolean enabl
14. Array of scancodes 114 5 Classes interfaces 5 52 IGuestMonitorChangedEvent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well Notification when the guest enables one of its monitors 5 52 1 Attributes 5 52 1 1 changeType read only GuestMonitorChangedEventType IGuestMonitorChangedEvent changeType What was changed for this guest monitor 5 52 1 2 screenld read only unsigned long IGuestMonitorChangedEvent screenId The monitor which was changed 5 52 1 3 originX read only unsigned long IGuestMonitorChangedEvent originX Physical X origin relative to the primary screen Valid for Enabled and NewOrigin 5 52 1 4 originY read only unsigned long IGuestMonitorChangedEvent originY Physical Y origin relative to the primary screen Valid for Enabled and NewOrigin 5 52 1 5 width read only unsigned long IGuestMonitorChangedEvent width Width of the screen Valid for Enabled 5 52 1 6 height read only unsigned long IGuestMonitorChangedEvent height Height of the screen Valid for Enabled 5 53 lIGuestMouseEvent ReusableEvent Note This interface extends IReusableEvent and therefore supports all its methods and attributes as well Notification when guest mouse event happens 115 5 Classes interfaces 5 53 1 Attributes 5 53 1 1 mode read only GuestMouseEventMode IGuestMouseEvent mode If this even
15. LogDbgGroups The debug logger s group settings 5 82 1 10 logDbgDestinations read only wstring IMachineDebugger LogDbgDestinations The debug logger s destination settings 5 82 1 11 logRelFlags read only wstring IMachineDebugger LogRelFlags The release logger flags 215 5 Classes interfaces 5 82 1 12 logRelGroups read only wstring IMachineDebugger LogRelGroups The release logger s group settings 5 82 1 13 logRelDestinations read only wstring IMachineDebugger logRelDestinations The relase logger s destination settings 5 82 1 14 HWVirtExEnabled read only boolean IMachineDebugger HWVirtExEnabled Flag indicating whether the VM is currently making use of CPU hardware virtualization exten sions 5 82 1 15 HWVirtExNestedPagingEnabled read only boolean IMachineDebugger HWVirtExNestedPagingEnabled Flag indicating whether the VM is currently making use of the nested paging CPU hardware virtualization extension 5 82 1 16 HWVirtExVPIDEnabled read only boolean IMachineDebugger HWVirtExVPIDEnabled Flag indicating whether the VM is currently making use of the VPID VT x extension 5 82 1 17 HWVirtExUXEnabled read only boolean IMachineDebugger HWVirtExUXEnabled Flag indicating whether the VM is currently making use of the unrestricted execution feature of VT x 5 82 1 18 OSName read only wstring IMachineDebugger 0SName Query the guest OS kernel name as dete
16. Resuming the execution can lead to unpredictable results Non fatal errors and warnings are indicated by the fatal parameter set to false If the virtual machine is in the Paused state by the time the error notification is received it means that the user can try to resume the machine execution after attempting to solve the problem that caused the error In this case the notification handler is supposed to show an appropriate message to the user depending on the value of the id parameter that offers several actions such as Retry Save or Power Off If the user wants to retry the notification handler should continue the machine execution using the IConsole resume call If the machine execution is not Paused during this notification then it means this notification is a warning for example about a fatal condition that can happen very soon no immediate action is required from the user the machine continues its normal execution Note that in either case the notification handler must not perform any action directly on a thread where this notification is called Everything it is allowed to do is to post a message to another thread that will then talk to the user and take the corresponding action Currently the following error identifiers are known e HostMemoryLow e HostAudioNotResponding e VDIStorageFull e 3DSupportIncompatibleAdditions 5 117 1 Attributes 5 117 1 1 fatal read only boolean IRuntimeErrorEvent fatal Whet
17. The following sections list incompatible changes that the Main API underwent since the origi nal release of this SDK Reference with VirtualBox 2 0 A change is deemed incompatible only if it breaks existing client code e g changes in method parameter lists renamed or removed interfaces and similar In other words the list does not contain new interfaces methods or attributes or other changes that do not affect existing client code 13 1 Incompatible API changes with version 5 0 e The methods for saving state adopting a saved state file discarding a saved state taking a snapshot restoring a snapshot and deleting a snapshot have been moved from IConsole to IMachine This straightens out the logical placement of methods and was necessary to resolve a long standing issue preventing 32 bit API clients from invoking those operations in the case where no VM is running IMachine saveState replaces IConsole saveState IMachine adoptSavedState replaces IConsole adoptSavedState IMachine discardSavedState replaces IConsole discardSavedState IMachine takeSnapshot replaces IConsole takeSnapshot IMachine deleteSnapshot replaces IConsole deleteSnapshot IMachine deleteSnapshotAndAlIChildren replaces IConsole deleteSnapshotAndAl1Children IMachine deleteSnapshotRange replaces IConsole deleteSnapshotRange IMachine restoreSnapshot replaces IConsole restoreSn
18. Waits until the given operation is done with a given timeout in milliseconds specify 1 for an indefinite wait See for event queue considerations If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Failed to wait for operation completion 5 116 lReusableEvent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well Base abstract interface for all reusable events 5 116 1 Attributes 5 116 1 1 generation read only unsigned long IReusableEvent generation Current generation of event incremented on reuse 5 116 2 reuse void IReusableEvent reuse Marks an event as reused increments generation fields shall no longer be considered valid 278 5 Classes interfaces 5 117 IRuntimeErrorEvent lEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when an error happens during the virtual machine execution There are three kinds of runtime errors e fatal e non fatal with retry e non fatal warnings Fatal errors are indicated by the fatal parameter set to true In case of fatal errors the virtual machine execution is always paused before calling this notification and the notification handler is supposed either to immediately save the virtual machine state using IMachine saveState or power it off using IConsole powerDown
19. in unsigned long idx idx Which log file name to query O current log file Queries for the VM log file name of an given index Returns an empty string if a log file with that index doesn t exists 5 80 53 querySavedGuestScreeninto void IMachine querySavedGuestScreenInfo in unsigned long screenId out unsigned long originX out unsigned long originY out unsigned long width out unsigned long height out boolean enabled screenld Saved guest screen to query info from originX The X position of the guest monitor top left corner originY The Y position of the guest monitor top left corner width Guest width at the time of the saved state was taken height Guest height at the time of the saved state was taken enabled Whether the monitor is enabled in the guest Returns the guest dimensions from the saved state 201 5 Classes interfaces 5 80 54 querySavedScreenshotinfo BitmapFormat IMachine querySavedScreenshotInfo in unsigned long screenld out unsigned long width out unsigned long height screenld Saved guest screen to query info from width Image width height Image height Returns available formats and size of the screenshot from saved state 5 80 55 readLog octet IMachine readLog in unsigned long idx in long long offset in long long size idx Which log file to read O current log file offset Offset in the log file size Chunk size to read in the log file
20. of the tarball Attempts to open an extension pack file in preparation for installation 5 30 6 queryAllPluginsForFrontend wstring IExtPackManager queryAllPlugInsForFrontend in wstring frontendName frontendName The name of the frontend or component Gets the path to all the plug in modules for a given frontend This is a convenience method that is intended to simplify the plug in loading process for a frontend 93 5 Classes interfaces 5 30 7 uninstall IProgress IExtPackManager uninstall in wstring name in boolean forcedRemoval in wstring displayInfo name The name of the extension pack to uninstall forcedRemoval Forced removal of the extension pack This means that the uninstall hook will not be called displaylnfo Platform specific display information Reserved for future hacks Uninstalls an extension pack removing all related files 5 31 IExtPackPlugin Note This interface is not supported in the web service Interface for keeping information about a plug in that ships with an extension pack 5 31 1 Attributes 5 31 1 1 name read only wstring IExtPackPlugIn name The plug in name 5 31 1 2 description read only wstring IExtPackPlugIn description The plug in description 5 31 1 3 frontend read only wstring IExtPackPlugIn frontend The name of the frontend or component name this plug in plugs into 5 31 1 4 modulePath read only wstring
21. 5 87 1 18 logicalSize read only long long IMedium logicalSize Logical size of this medium in bytes as reported to the guest OS running inside the virtual machine this medium is attached to The logical size is defined when the medium is created and cannot be changed later Note For media whose state is state is Inaccessible the value of this property is the last known logical size For NotCreated media the returned value is zero 5 87 1 19 autoReset read write boolean IMedium autoReset Whether this differencing medium will be automatically reset each time a virtual machine it is attached to is powered up This attribute is automatically set to true for the last differencing image of an immutable medium see MediumType See reset for more information about resetting differencing media Note Reading this property on a base non differencing medium will always false Changing the value of this property in this case is not supported 5 87 1 20 lastAccessError read only wstring IMedium lastAccessError Text message that represents the result of the last accessibility check performed by refreshState An empty string is returned if the last accessibility check was successful or has not yet been called As a result if state is Inaccessible and this attribute is empty then refreshState has yet to be called this is the default value of media after VirtualBox initialization A no
22. DetachAllReturn None except that all the hard disk medium objects which were detached from the machine will be returned as an array This allows for quickly passing them to the deleteConfig API for closing and deletion With Full the call will behave like with DetachAllReturnHardDisksOnly except that all media will be returned in the array including removable media like DVDs and floppies This might be useful if the user wants to inspect in detail which media were attached to the machine Be careful when passing the media array to deleteConfig in that case because users will typically want to preserve ISO and RAW image files A typical implementation will use DetachAllReturnHardDisksOnly and then pass the result ing IMedium array to deleteConfig This way the machine is completely deleted with all its saved states and hard disk images but images for removable drives such as ISO and RAW files will remain on disk This API does not verify whether the media files returned in the array are still attached to other machines i e shared between several machines If such a shared image is passed to deleteConfig however closing the image will fail there and the image will be silently skipped 213 5 Classes interfaces This API may however move media from this machine s media registry to other media reg istries see Medium for details on media registries For machines created with VirtualBox 4 0 or late
23. Oracle VM VirtualBox Programming Guide and Reference Version 5 0 10 2004 2015 Oracle Corporation http www virtualbox org Contents 1 Introduction 1 1 Modularity the building blocks of VirtualBox 1 2 Two guises of the same Main API the web service or COM XPCOM 1 3 About web services in general occ o oo ereo ss 14 Running the webservice ow ck ee ee ea 1 4 1 Command line options of VDOXWebsIV o o 1 4 2 Authenticating at web service logon o o 2 Environment specific notes 2 1 Using the object oriented web service OOWS o o o o ooo 2 1 1 The object oriented web service for JAXWS 2 1 2 The object oriented web service for Python 2 1 3 The object oriented web service for PHP 2 2 Using the raw web service with any language o 2 2 1 Raw web service example for Java with Axis 2 2 2 Raw web service example for Perl 2 2 3 Programming considerations for the raw web service 2 0 Using CON XPCOM directly ooo iio eae REED OE ee de eae aS 291 Pylon COMAPI ok eka kk ah A we et we 2 3 2 Common Python bindings layer o o a Woe gt sos ss a e a ne ao Event QUEUE processing se croso o aa 2 3 5 Visual Basic and Visual Basic Script VBS on Windows hosts 2 3 6 C binding to VirtualBox API o o
24. Synchronization mode between the host OS clipboard and the guest OS clipboard 5 80 1 62 dnDMode read write DnDMode IMachine dnDMode Sets or retrieves the current drag n drop mode 5 80 1 63 teleporterEnabled read write boolean IMachine teleporterEnabled When set to true the virtual machine becomes a target teleporter the next time it is powered on This can only set to true when the VM is in the PoweredOff or Aborted state 5 80 1 64 teleporterPort read write unsigned long IMachine teleporterPort The TCP port the target teleporter will listen for incoming teleportations on O means the port is automatically selected upon power on The actual value can be read from this property while the machine is waiting for incoming teleportations 5 80 1 65 teleporterAddress read write wstring IMachine teleporterAddress The address the target teleporter will listen on If set to an empty string it will listen on all addresses 5 80 1 66 teleporterPassword read write wstring IMachine teleporterPassword The password to check for on the target teleporter This is just a very basic measure to prevent simple hacks and operators accidentally beaming a virtual machine to the wrong place Note that you SET a plain text password while reading back a HASHED password Setting a hashed password is currently not supported 5 80 1 67 paravirtProvider read write ParavirtProvider IMachine paravirtProvider The parav
25. The new CPU execution cap value 1 100 5 11 ICanShowWindowE vent IVetoEvent Note This interface extends IVetoEvent and therefore supports all its methods and attributes as well Notification when a call to IMachine canShowConsoleWindow is made by a front end to check if a subsequent call to IMachine showConsoleWindow can succeed The callee should give an answer appropriate to the current machine state using event veto This answer must remain valid at least until the next machine state change 5 11 1 Attributes 5 11 1 1 midIDoesNotLikeEmptyInterfaces read only boolean ICanShowWindowEvent midlDoesNotLikeEmptyInterfaces 5 12 IClipboardModeChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when the shared clipboard mode changes 5 12 1 Attributes 5 12 1 1 clipboardMode read only ClipboardMode IClipboardModeChangedEvent clipboardMode The new clipboard mode 62 5 Classes interfaces 5 13 IConsole The IConsole interface represents an interface to control virtual machine execution A console object gets created when a machine has been locked for a particular session client process using IMachine lockMachine or IMachine launchVMProcess The console object can then be found in the session s ISession console attribute Methods of the IConsole interface allow the caller to query the curr
26. boolean ISerialPort enabled Flag whether the serial port is enabled If disabled the serial port will not be reported to the guest OS 5 118 1 3 lOBase read write unsigned long ISerialPort I0Base Base I O address of the serial port 5 118 1 4 IRQ read write unsigned long ISerialPort IRQ IRQ number of the serial port 5 118 1 5 hostMode read write PortMode ISerialPort hostMode How is this port connected to the host Note Changing this attribute may fail if the conditions for path are not met 280 5 Classes interfaces 5 118 1 6 server read write boolean ISerialPort server Flag whether this serial port acts as a server creates a new pipe on the host or as a client uses the existing pipe This attribute is used only when hostMode is PortMode_HostPipe or PortMode_TCP 5 118 1 7 path read write wstring ISerialPort path Path to the serial port s pipe on the host when hostMode is PortMode_HostPipe the host serial device name when hostMode is PortMode_HostDevice or the TCP port server or host name port client when hostMode is PortMode_TCP For those cases setting a null or empty string as the attribute s value is an error Otherwise the value of this property is ignored 5 119 ISerialPortChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when a property of one of the virtual se
27. is called on a running virtual machine a live snapshot will be created The old behavior was to temporarily pause the virtual machine while creating an online snapshot The IVRDPServer IRemoteDisplayInfo and IConsoleCallback interfaces were changed to reflect VRDP server ability to bind to one of available ports from a list of ports The IVRDPServer port attribute has been replaced with IVRDPServer ports which is a comma separated list of ports or ranges of ports An IRemoteDisplayInfo port attribute has been added for querying the actual port VRDP server listens on An IConsoleCallback onRemoteDisplayInfoChange notification callback has been added The parameter lists for the following functions were modified IHost removeHostOnlyNetworkInterface IHost removeUSBDeviceFilter In the OOWS bindings for JAX WS the behavior of structures changed for one we imple mented natural structures field access so you can just call a get method to obtain a field Secondly setters in structures were disabled as they have no expected effect and were at best misleading 13 8 Incompatible API changes with version 3 0 e In the object oriented web service bindings for JAX WS proper inheritance has been in troduced for some classes so explicit casting is no longer needed to call methods from a parent class In particular IHardDisk and other classes now properly derive from IMedium e All object identifiers machine
28. out unsigned long cpuUser out unsigned long cpuKernel out unsigned long cpuldle out unsigned long memTotal out unsigned long memFree out unsigned long memBalloon out unsigned long memShared out unsigned long memCache out unsigned long pagedTotal out unsigned long memAllocTotal out unsigned long memFreeTotal out unsigned long memBalloonTotal out unsigned long memSharedTotal cpuUser Percentage of processor time spent in user mode as seen by the guest cpuKernel Percentage of processor time spent in kernel mode as seen by the guest cpuldle Percentage of processor time spent idling as seen by the guest memTotal Total amount of physical guest RAM memFree Free amount of physical guest RAM memBalloon Amount of ballooned physical guest RAM memShared Amount of shared physical guest RAM memCache Total amount of guest disk cache memory pagedTotal Total amount of space in the page file memAllocTotal Total amount of memory allocated by the hypervisor memFreeTotal Total amount of free memory available in the hypervisor memBalloonTotal Total amount of memory ballooned by the hypervisor memSharedTotal Total amount of shared memory in the hypervisor Internal method do not use as it might change at any time 109 5 Classes interfaces 5 38 7 setCredentials void IGuest setCredentials in wstring userName in wstring password in wstring domain in boolean allowInteractiveLogon
29. tcpport The TCP port to connect to 1 65535 password The password maxDowntime The maximum allowed downtime given as milliseconds 0 is not a valid value Recommended value 250 ms The higher the value is the greater the chance for a successful teleportation A small value may easily result in the teleportation process taking hours and eventually fail Note The current implementation treats this a guideline not as an absolute rule Teleport the VM to a different host machine or process todo Explain the details If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine not running or paused 5 14 IDHCPServer The IDHCPServer interface represents the VirtualBox DHCP server configuration To enumerate all the DHCP servers on the host use the IVirtualBox DHCPServers attribute 5 14 1 Attributes 5 14 1 1 eventSource read only IEventSource IDHCPServer eventSource 5 14 1 2 enabled read write boolean IDHCPServer enabled specifies if the DHCP server is enabled 5 14 1 3 IPAddress read only wstring IDHCPServer IPAddress specifies server IP 5 14 1 4 networkMask read only wstring IDHCPServer networkMask specifies server network mask 71 5 Classes interfaces 5 14 1 5 networkName read only wstring IDHCPServer networkName specifies internal network name the server is used for 5 14 1 6 lowerlP read only wstring IDHCPServer Low
30. tributes as well Notification when the guest OS executes the KBD_CMD_SET_LEDS command to alter the state of the keyboard LEDs 166 5 Classes interfaces 5 79 1 Attributes 5 79 1 1 numLock read only boolean IKeyboardLedsChangedEvent numLock NumLock status 5 79 1 2 capsLock read only boolean IKeyboardLedsChangedEvent capsLock CapsLock status 5 79 1 3 scrollLock read only boolean IKeyboardLedsChangedEvent scrollLock ScrollLock status 5 80 IMachine The Machine interface represents a virtual machine or guest created in VirtualBox This interface is used in two contexts First of all a collection of objects implementing this interface is stored in the IVirtualBox machines attribute which lists all the virtual machines that are currently registered with this VirtualBox installation Also once a session has been opened for the given virtual machine e g the virtual machine is running the machine object associated with the open session can be queried from the session object see Session for details The main role of this interface is to expose the settings of the virtual machine and provide methods to change various aspects of the virtual machine s configuration For machine objects stored in the IVirtualBox machines collection all attributes are read only unless explicitly stated otherwise in individual attribute and method descriptions In order to change a machine setting a ses
31. www apache org The following exam ples assume that you have Axis 1 4 installed The VirtualBox SDK ships with an example for Axis that again is called clienttest java and that imitates a few of the commands of VBoxManage over the wire Then perform the following steps 1 Create a working directory somewhere Under your VirtualBox installation directory find the sdk webservice samples java axis directory and copy the file clienttest java to your working directory 2 Open a terminal in your working directory Execute the following command 4See https www php net soap 30 2 Environment specific notes java org apache axis wsdl WSDL2Java path to vboxwebService wsdl The vboxwebService wsdl file should be located in the sdk webservice directory If this fails your Apache Axis may not be located on your system classpath and you may have to adjust the CLASSPATH environment variable Something like this export CLASSPATH path to axis 1_4 lib CLASSPATH Use the directory where the Axis JAR files are located Mind the quotes so that your shell passes the character to the java executable without expanding Alternatively add a corresponding classpath argument to the java call above If the command executes successfully you should see an org directory with subdirecto ries containing Java source files in your working directory These classes represent the interfaces that the VirtualBox web ser
32. 5 135 1 Attributes 5 135 1 1 minGuestRAM read only unsigned long ISystemProperties minGuestRAM Minimum guest system memory in Megabytes 5 135 1 2 maxGuestRAM read only unsigned long ISystemProperties maxGuestRAM Maximum guest system memory in Megabytes 5 135 1 3 minGuestVRAM read only unsigned long ISystemProperties minGuestVRAM Minimum guest video memory in Megabytes 292 5 Classes interfaces 5 135 1 4 maxGuestVRAM read only unsigned long ISystemProperties maxGuestVRAM Maximum guest video memory in Megabytes 5 135 1 5 minGuestCPUCount read only unsigned long ISystemProperties minGuestCPUCount Minimum CPU count 5 135 1 6 maxGuestCPUCount read only unsigned long ISystemProperties maxGuestCPUCount Maximum CPU count 5 135 1 7 maxGuestMonitors read only unsigned long ISystemProperties maxGuestMonitors Maximum of monitors which could be connected 5 135 1 8 infoVDSize read only long long ISystemProperties infoVDSize Maximum size of a virtual disk image in bytes Informational value does not reflect the limits of any virtual disk image format 5 135 1 9 serialPortCount read only unsigned long ISystemProperties serialPortCount Maximum number of serial ports associated with every Machine instance 5 135 1 10 parallelPortCount read only unsigned long ISystemProperties parallelPortCount Maximum number of parallel ports associated with every
33. 5 65 1 1 session read only IGuestSession IGuestSessionEvent session Guest session that is subject to change 139 5 Classes interfaces 5 66 IGuestSessionRegisteredEvent IGuestSessionEvent Note This interface extends IGuestSessionEvent and therefore supports all its methods and attributes as well Notification when a guest session was registered or unregistered 5 66 1 Attributes 5 66 1 1 registered read only boolean IGuestSessionRegisteredEvent registered If true the guest session was registered otherwise it was unregistered 5 67 IGuestSessionStateChangedEvent IGuestSessionEvent Note This interface extends IGuestSessionEvent and therefore supports all its methods and attributes as well Notification when a guest session changed its state 5 67 1 Attributes 5 67 1 1 id read only unsigned long IGuestSessionStateChangedEvent id Session ID of guest session which was changed 5 67 1 2 status read only GuestSessionStatus IGuestSessionStateChangedEvent status New session status 5 67 1 3 error read only IVirtualBoxErrorInfo IGuestSessionStateChangedEvent error Error information in case of new session status is indicating an error The attribute IVirtualBoxErrorInfo resultDetail will contain the runtime IPRT error code from the guest See include iprt err h and include VBox err h for details 5 68 IGuestUserStateChangedEvent IEvent Note This
34. 5118 1 Attributes ocn rra 280 5 119 ISerialPortChangedEvent IEvent o o 281 LIA ARDE oo a He eae a ee ee 281 5 120 IBESSION ck eee RAR DEER EE ERG Oe DAA DE ee Re a 281 5120 1 Attributes 0 a ee a ee 282 5 1202 unlockMachine cts 2G SS Rd a EE EER RES 283 5 121 ISessionStateChangedEvent IMachineEvent 000000 283 Bele A AIR ok ed oe SS a a Re ee ee Ww a a 283 5 122 ISharedFolder o occ ek we we aa aa ee G 283 5122 11 AUIDIMES 2 4 6 bw oe eS a ES SEE ORES CE ERODE 284 5 123 ISharedFolderChangedEvent IEvent 1 2 00 ee eee eens 285 D1231 AES ora EE we eee eke a we aS 285 5 124 IShowWindowEvent IEvent 285 51241 o oa ee co ee Se Sess he eg Bb Ww ee ales E 286 5 125 Snapshot lt ccicoss raros taras aaa aia 286 5 1251 Attributes ca a we a aa eB 287 5 125 2 serChidrenGount oo e ss ee ae SE Se ee ew ae a e 288 5 126 ISnapshotChangedEvent ISnapshotEvent o oo aa 288 51201 ARTDUIES 2 heehee OS eRe aS RE AAA 288 5 127 ISnapshotDeletedEvent ISnapshotEvVent lt so seod oo o e 288 14 Contents E a ee aw a I we we ws SRR ee A 288 5 128 ISnapshotEvent IMachineEvent 2 000 eee eee eee 289 Sell PAID 2 eee he A Oe oe ep el i A 289 5 129 ISnapshotRestoredEvent ISnapshotEvent o oo ooo 289 E a A E 289 5 130 ISnapshotTakenEvent ISnapshotEvent o oo e 289 E a A be wh wwe Bae A a He
35. Diff Differencing image Only allowed for child images NoCreateDir Special flag which suppresses automatic creation of the subdirectory Only used when passing the medium variant as an input parameter 356 6 Enumerations enums 6 68 MouseButtonState Mouse button state LeftButton RightButton MiddleButton WheelUp WheelDown XButton1 XButton2 MouseStateMask 6 69 NATAliasMode AliasLog AliasProxyOnly AliasUseSamePorts 6 70 NATProtocol Protocol definitions used with NAT port forwarding rules UDP Port forwarding uses UDP protocol TCP Port forwarding uses TCP protocol 6 71 NetworkAdapterPromiscModePolicy The promiscuous mode policy of an interface Deny Deny promiscuous mode requests AllowNetwork Allow promiscuous mode but restrict the scope it to the internal network so that it only applies to other VMs AllowAll Allow promiscuous mode include unrelated traffic going over the wire and internally on the host 357 6 Enumerations enums 6 72 NetworkAdapterType Network adapter type Null Null value never used by the API Am79C970A AMD PCNet PCI II network card Am79C970A Am79C973 AMD PCNet FAST III network card Am79C973 182540EM Intel PRO 1000 MT Desktop network card 82540EM 182543GC Intel PRO 1000 T Server network card 82543GC 182545EM Intel PRO 1000 MT Server network card 82545EM Virtio Virtio network device 6 73 NetworkAttachmentType Network attachment type
36. IProgress IMedium createBaseStorage in long long logicalSize in MediumVariant variant logicalSize Maximum logical size of the medium in bytes variant Exact image variant which should be created as a combination of MediumVariant flags Starts creating a hard disk storage unit fixed dynamic according to the variant flags in in the background The previous storage unit created for this object if any must first be deleted using deleteStorage otherwise the operation will fail Before the operation starts the medium is placed in Creating state If the create operation fails the medium will be placed back in NotCreated state After the returned progress object reports that the operation has successfully completed the medium state will be set to Created the medium will be remembered by this VirtualBox instal lation and may be attached to virtual machines If this method fails the following error codes may be reported 232 5 Classes interfaces e VBOX_E_NOT_SUPPORTED The variant of storage creation operation is not supported See IMediumFormat capabilities 5 87 9 createDiffStorage IProgress IMedium createDiffStorage in IMedium target in MediumVariant variant target Target medium variant Exact image variant which should be created as a combination of MediumVariant flags Starts creating an empty differencing storage unit based on this medium in the format and at the location defined by the t
37. Identifier of the session process This attribute contains the platform dependent identifier of the process whose session was used with lockMachine call The returned value is only valid if sessionState is Locked or Unlocking by the time this property is read 5 80 1 53 state read only MachineState IMachine state Current execution state of this machine 5 80 1 54 lastStateChange read only long long IMachine lastStateChange Time stamp of the last execution state change in milliseconds since 1970 01 01 UTC 175 5 Classes interfaces 5 80 1 55 stateFilePath read only wstring IMachine stateFilePath Full path to the file that stores the execution state of the machine when it is in the Saved state Note When the machine is not in the Saved state this attribute is an empty string 5 80 1 56 logFolder read only wstring IMachine logFolder Full path to the folder that stores a set of rotated log files recorded during machine execution The most recent log file is named VBox log the previous log file is named VBox log 1 and so on up to VBox log 3 in the current version 5 80 1 57 currentSnapshot read only ISnapshot IMachine currentSnapshot Current snapshot of this machine This is null if the machine currently has no snapshots If it is not null then it was set by one of takeSnapshot deleteSnapshot or restoreSnapshot depending on which was called last See ISnapshot for details 5 8
38. Null Null value also means not attached NAT Bridged Internal HostOnly Generic NATNetwork 6 74 ParavirtProvider The paravirtualized guest interface provider This enumeration represents possible values for the IMachine paravirtProvider attribute None No provider is used Default A default provider is automatically chosen according to the guest OS type Legacy Used for VMs which didn t used to have any provider settings Usually interpreted as None for most VMs Minimal A minimal set of features to expose to the paravirtualized guest HyperV Microsoft Hyper V KVM Linux KVM 358 6 Enumerations enums 6 75 PathStyle The path style of a system Values matches the RTPATH_STR_F STYLE XXX defines in iprt path h DOS DOS style paths with forward and backward slashes drive letters and UNC Known from DOS OS 2 and Windows UNIX UNIX style paths with forward slashes only Unknown The path style is not known most likely because the guest additions aren t active yet 6 76 PointingHIDType Type of pointing device used in a virtual machine None No mouse PS2Mouse PS 2 auxiliary device a k a mouse USBMouse USB mouse relative pointer USBTablet USB tablet absolute pointer Also enables a relative USB mouse in addition ComboMouse Combined device working as PS 2 or USB mouse depending on guest behavior Using this device can have negative performance implications USBMultiTouch USB multi to
39. This setting determines the maximum amount of time in milliseconds the video capture will work for The capture stops as the defined time interval has elapsed If this value is zero the capturing will not be limited by time This setting cannot be changed while video capturing is enabled 5 80 1 32 videoCaptureMaxFileSize read write unsigned long IMachine videoCaptureMaxFileSize This setting determines the maximal number of captured video file size in MB The capture stops as the captured video file size has reached the defined If this value is zero the capturing will not be limited by file size This setting cannot be changed while video capturing is enabled 5 80 1 33 videoCaptureOptions read write wstring IMachine videoCaptureOptions This setting contains any additional video capture options required in comma separated key value format This setting cannot be changed while video capturing is enabled 5 80 1 34 BlOSSettings read only IBIOSSettings IMachine BIOSSettings Object containing all BIOS settings 172 5 Classes interfaces 5 80 1 35 firmwareType read write FirmwareType IMachine firmwareType Type of firmware such as legacy BIOS or EFI used for initial bootstrap in this VM 5 80 1 36 pointingHIDType read write PointingHIDType IMachine pointingHIDType Type of pointing HID such as mouse or tablet used in this VM The default is typically PS2Mouse but can vary depending on the requirements of
40. Virtual machine does not have a USB controller 5 13 5 clearAllDiskEncryptionPasswords void IConsole clearAllDiskEncryptionPasswords Clears all provided supplied disk encryption passwords 5 13 6 createSharedFolder void IConsole createSharedFolder in wstring name in wstring hostPath in boolean writable in boolean automount name Unique logical name of the shared folder 66 5 Classes interfaces hostPath Full path to the shared folder in the host file system writable Whether the share is writable or readonly automount Whether the share gets automatically mounted by the guest or not Creates a transient new shared folder by associating the given logical name with the given host path adds it to the collection of shared folders and starts sharing it Refer to the description of ISharedFolder to read more about logical names If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine in Saved state or currently changing state e VBOX_E_FILE_ERROR Shared folder already exists or not accessible 5 13 7 detachUSBDevice IUSBDevice IConsole detachUSBDevice in uuid id id UUID of the USB device to detach Detaches an USB device with the given UUID from the USB controller of the virtual machine After this method succeeds the VirtualBox server re initiates all USB filters as if the device were just physically attached to the host but filters of this
41. and attributes as well Snapshot properties name and or description have been changed See also ISnapshot 5 126 1 Attributes 5 126 1 1 midlDoesNotLikeEmptyInterfaces read only boolean ISnapshotChangedEvent midlDoesNotLikeEmptyInterfaces 5 127 ISnapshotDeletedEvent ISnapshotEvent Note This interface extends ISnapshotEvent and therefore supports all its methods and attributes as well Snapshot of the given machine has been deleted Note This notification is delivered after the snapshot object has been uninitialized on the server so that any attempt to call its methods will return an error See also ISnapshot 5 127 1 Attributes 5 127 1 1 midlDoesNotLikeEmptyInterfaces read only boolean ISnapshotDeletedEvent midlDoesNotLikeEmptyInterfaces 288 5 Classes interfaces 5 128 ISnapshotEvent IMachineEvent Note This interface extends IMachineEvent and therefore supports all its methods and attributes as well Base interface for all snapshot events 5 128 1 Attributes 5 128 1 1 snapshotld read only uuid ISnapshotEvent snapshotId ID of the snapshot this event relates to 5 129 ISnapshotRestoredEvent ISnapshotEvent Note This interface extends ISnapshotEvent and therefore supports all its methods and attributes as well Snapshot of the given machine has been restored See also ISnapshot 5 129 1 Attributes 5 129 1 1 midlDoesNotLikeE
42. boolean IEventSource fireEvent in IEvent event in long timeout event Event to deliver timeout Maximum time to wait for event processing if event is waitable in ms O no wait 1 indefinite wait Fire an event for this source 5 25 5 getEvent IEvent IEventSource getEvent in IEventListener listener in long timeout listener Which listener to get data for timeout Maximum time to wait for events in ms 0 no wait 1 indefinite wait Get events from this peer s event queue for passive mode Calling this method regularly is required for passive event listeners to avoid system overload see registerListener for details If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Listener is not registered or autounregistered 5 25 6 registerListener void IEventSource registerListener in IEventListener listener in VBoxEventType interesting in boolean active listener Listener to register interesting Event types listener is interested in One can use wildcards like Any to specify wildcards matching more than one event active Which mode this listener is operating in In active mode IEventListener handleEvent is called directly In passive mode an internal event queue is created for this this IEventListener For each event coming in it is added to queues for all interested registered passive listeners It is then up to the external co
43. eee 145 5 69 10 fndUSBDeviceByld 0 wee ee eae Gee ee h 145 5 09 11 generateMACAdd ress 2 6c ease ad wee eee ae 145 5 609 122 getProcessorCPUIDLESE oc ee eS RO ee wwe 145 5 69 13 getProcessorDescription ee 146 5 69 14 getProcessorFeature s SS Bw eR ee wa 146 5 69 15 setProcessorSpeed onc es be ee ee ea ee aS 146 5 69 16 insertUSBDeviceFilter 2 5 6 cee ee ee 146 5 69 17 removeHostOnlyNetworkInterface o o o 147 5 69 18 removeUSBDeviceFilter oo 0 147 THostNameResolutionConfigurationChangeEvent IEvent 148 6 70 1 Atmibutes 24 54 4460 2 4 a a a a 148 IHostNetworkInterface 44 4 6 56 de ke a 148 5 71 1 Attributes 2 2 044822 28444 RRA EARS REDRESS 148 71 2 WACPRECISCOVED sca a aw Ele we Ae oe Be ee 149 5 71 3 enableDynamiclPConfig o lt 2 cae da eden ee ee ean 149 S 7LA eriablestaticlPGonhg oes so ee ak a a a e 150 5 7 1 5 enableStaticPConligv icons ee ee eS 150 IHostPCIDevicePlugEvent IMachineEvent 0 0 0000 eee 150 Sal ADUS lt a se och a e ee See 150 IHostUSBDevice IUSBDevice 151 5 731 ANDES a ee Re eee pee bd COOP RA SE CO Oe Rees 151 IHostUSBDeviceFilter IUSBDeviceFilter 0 a 0 eee 151 Baek a ooren haa oo we ee ee He a a a EE 151 THostVideolnputDevice 44 026888444445 4a eee eae aaa as 151 S751 e cs ae we Ae es eee ae a wa ee ete ets A 151 IInternalMachineControl 44 2664004444
44. key Name of the data key to get Returns associated machine specific extra data If the requested data key does not exist this function will succeed and return an empty string in the value argument If this method fails the following error codes may be reported e VBOX_E_FILE_ERROR Settings file not accessible e VBOX_E_XML_ERROR Could not parse the settings file 5 80 30 getExtraDataKeys wstring IMachine getExtraDataKeys Returns an array representing the machine specific extra data keys which currently have values defined 5 80 31 getGuestProperty void IMachine getGuestProperty in wstring name out wstring value out long long timestamp out wstring flags name The name of the property to read value The value of the property If the property does not exist then this will be empty timestamp The time at which the property was last modified as seen by the server process flags Additional property parameters passed as a comma separated list of name value type entries Reads an entry from the machine s guest property store If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open 5 80 32 getGuestPropertyTimestamp long long IMachine getGuestPropertyTimestamp in wstring property property The name of the property to read Reads a property timestamp from the machine s guest property store If this method fails th
45. priately and has to set the follow up machine state if this call failed See also IMachine saveState If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine state is not one of the expected values e VBOX_E_FILE_ERROR Failed to create directory for saved state file 5 77 30 uninitialize void IInternalSessionControl uninitialize Uninitializes closes this session Used by VirtualBox to close the corresponding remote ses sion when the direct session dies or gets closed If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation 5 77 31 updateMachineState void IInternalSessionControl updateMachineState in MachineState machineState machineState Updates the machine state in the VM process Must be called only in certain cases see the method implementation If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 5 78 lKeyboard The IKeyboard interface represents the virtual machine s keyboard Used in IConsole keyboard Use this interface to send keystrokes or the Ctrl Alt Del sequence to the virtual machine 5 78 1 Attributes 5 78 1 1 keyboardLEDs read only KeyboardLED IKeyboard keyboardLEDs Current status of the guest keyboard LEDs 165
46. processEventQueue uint32_t cMsTimeout can be used for both blocking and non blocking operations For the Python bindings a common layer provides the method 38 2 Environment specific notes VirtualBoxManager waitForEvents ms with similar semantics Things get somewhat more complicated for situations where an application using VirtualBox cannot directly control the main event loop and the main event queue is separated from the event queue of the programming librarly for example in case of Qt on Unix platforms In such a case the application developer is advised to use a platform toolkit specific event injection mechanism to force event queue checks either based on periodical timer events delivered to the main thread or by using custom platform messages to notify the main thread when events are available See the VBoxSDL and Qt VirtualBox frontends as examples 2 3 5 Visual Basic and Visual Basic Script VBS on Windows hosts On Windows hosts one can control some of the VirtualBox Main API functionality from VBS scripts and pretty much everything from Visual Basic programs VBS is scripting language available in any recent Windows environment As an example the following VBS code will print VirtualBox version set vb CreateObject VirtualBox VirtualBox Wscript Echo VirtualBox version amp vb version See bindings mscom vbs sample vboxinfo vbs for the complete sample Visual Basic is a popular high level language
47. read only boolean IStorageController bootable Returns whether it is possible to boot from disks attached to this controller 5 133 IStorageControllerChangedEvent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well Notification when a medium attachment changes 5 133 1 Attributes 5 133 1 1 midlDoesNotLikeEmptyInterfaces read only boolean IStorageControllerChangedEvent midlDoesNotLikeEmptyInterfaces 291 5 Classes interfaces 5 134 IStorageDeviceChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when a storage device is attached or removed 5 134 1 Attributes 5 134 1 1 storageDevice read only IMediumAttachment IStorageDeviceChangedEvent storageDevice Storage device that is subject to change 5 134 1 2 removed read only boolean IStorageDeviceChangedEvent removed Flag whether the device was removed or added to the VM 5 134 1 3 silent read only boolean IStorageDeviceChangedEvent silent Flag whether the guest should be notified about the change 5 135 ISystemProperties The ISystemProperties interface represents global properties of the given VirtualBox installation These properties define limits and default values for various attributes and parameters Most of the properties are read only but some can be changed by a user
48. tions for this virtual system This is handy for writing values which aren t directly supported by VirtualBox One example would be the License type of VirtualSystemDescriptionType 5 154 3 getDescription void IVirtualSystemDescription getDescription out VirtualSystemDescriptionType types out wstring refs out wstring OVFValues out wstring VBoxValues out wstring extraConfigValues types refs OVFValues VBoxValues extraConfigValues Returns information about the virtual system as arrays of instruction items In each array the items with the same indices correspond and jointly represent an import instruction for VirtualBox The list below identifies the value sets that are possible depending on the VirtualSystemDescriptionType enum value in the array item in aTypes In each case the array item with the same index in OVFValues will contain the original value as contained in the OVF file just for informational purposes and the corresponding item in aVBoxValues will contain a suggested value to be used for VirtualBox Depending on the description type the aExtraConfigValues array item may also be used e OS the guest operating system type There must be exactly one such array item on import The corresponding item in aVBoxValues contains the suggested guest operating system for VirtualBox This will be one of the values listed in IVirtualBox guestOSTypes The corresponding item in OVFVal
49. unsigned long scanTime count Number of contacts in the event contacts Each array element contains packed information about one contact Bits 0 15 X coordinate in pixels Bits 16 31 Y coordinate in pixels Bits 32 39 contact identifier Bit 40 in contact flag which indicates that there is a contact with the touch surface Bit 41 in range flag the contact is close enough to the touch surface All other bits are reserved for future use and must be set to 0 scanTime Timestamp of the event in milliseconds Only relative time between events is impor tant Sends a multi touch pointer event The coordinates are expressed in pixels and start from 1 1 which corresponds to the top left corner of the virtual display 247 5 Classes interfaces Note The guest may not understand or may choose to ignore this event See also multiTouchSupported If this method fails the following error codes may be reported e E_ACCESSDENIED Console not powered up e VBOX_E_IPRT_ERROR Could not send event to virtual device 5 93 3 putEventMultiTouchString void IMouse putEventMultiTouchString in long count in wstring contacts in unsigned long scanTime count See also putEventMultiTouch contacts Contains information about all contacts id1 x1 y1 inContact1 inRangel idN xN yN inContactN inRang For example for two contacts 0 10 20 1 1 1 30 40 1 1 scanTime See also putEventMult
50. void IMachine setNoBandwidthGroupForDevice in wstring name in long controllerPort in long device name Name of the storage controller controllerPort Storage controller port device Device slot in the given port Sets no bandwidth group for an existing storage device The device must already exist see attachDevice for how to attach a new device The controllerPort and device parameters specify the device slot and have have the same meaning as with attachDevice If this method fails the following error codes may be reported e E_INVALIDARG SATA device SATA port IDE port or IDE slot out of range e VBOX_E_INVALID_OBJECT_STATE Attempt to modify an unregistered virtual machine e VBOX_E_INVALID_VM_STATE Invalid machine state 5 80 77 setSettingsFilePath IProgress IMachine setSettingsFilePath in wstring settingsFilePath settingsFilePath New settings file path will be used to determine the new location for the attached media if it is in the same directory or below as the original settings file Currently it is an error to change this property on any machine Later this will allow setting a new path for the settings file with automatic relocation of all files including snapshots and disk images which are inside the base directory This operation is only allowed when there are no pending unsaved settings Note Setting this property to null or to an empty string is forbidden When setting this property t
51. wstring pattern pattern The selection pattern A bit similar to filename globbing Reset VM statistics 5 82 20 setRegister void IMachineDebugger setRegister in unsigned long cpuld in wstring name in wstring value cpuld The identifier of the Virtual CPU name The register name case is ignored value The new register value Hexadecimal decimal and octal formattings are supported in addition to any special formattings returned by the getters Gets one register This feature is not implemented in the 4 0 0 release but may show up in a dot release 220 5 Classes interfaces 5 82 21 setRegisters void IMachineDebugger setRegisters in unsigned long cpuld in wstring names in wstring values cpuld The identifier of the Virtual CPU names Array containing the register names case ignored values Array paralell to the names holding the register values See setRegister for formatting guidelines Sets zero or more registers atomically This feature is not implemented in the 4 0 0 release but may show up in a dot release 5 82 22 unloadPlugin void IMachineDebugger unloadPlugIn in wstring name name The plug in name or DLL Special name all unloads all plug ins Unloads a DBGF plug in 5 82 23 writePhysicalMemory void IMachineDebugger writePhysicalMemory in long long address in unsigned long size in octet bytes address The guest physical address siz
52. 000 ee eda aaa ae 152 5 76 1 authenticateExternal oo os oore ee ee AA 152 5 76 2 autoCaptureUSBDevices ecos ee aai 152 SIOS DOCINPOWEIUP oon Ge Sw we beat ae a a a EA G 152 5 76 4 beginPoweringDown 2 00 ee ee ee ee 152 5 76 5 captureUSBDevice s s os t tt Se wR AAA 153 B77 5 78 aus Contents 5 766 detachAUUSBDeviees o oo sos ke Sa eo ew IEG Pe ae eee 153 5 76 7 detachUSBDevice os 44 24444459 428 008 44444 S54 153 5706 ESE coc oO ee eh we Re a a een ae i 153 5 76 9 endPowerUp ociosa naaa 804 444445 154 5 70 10 endPoweringDown gt c s s ss a bbe we a ee ee e 154 5 76 11 finishOnlineMergeMedium o e 02 0000 eee 154 TEIZ MCRAE o oee a o we woe Bae A a a ae E 154 5 76 13 ONSESSIONENd o cecce cee bee a BOS dara Ee ER OE eS 154 5 70 14 pullGiestProperties as ee A ee ew e 155 5 76 15 pushGuesiProperty oi eee eega a pE ee ba ee ee 155 5 76 16 reportVmStatistics 3 5 4 bee eed ae aaa 155 5 70 17 ruinUSBDevicePilters occ hk wR ee eS 156 5 7616 wilockWedia ws d caca 382254448 44444 4 a 156 OD gpdare SiE 0 ek a we A ee A 157 linternalSessionControl o its a 88 45508 a a 157 STAA AIDES A OOO RE Dee Eee 157 S 77 ACESS Guest Prope y 2 kee ee eb Pewee EE Ee DOS 157 S 77 0 assionRemoteMachine 2 2 2 2 ee a A 158 5 77 4 cancelSaveStateWithReason o e e 158 S 77 5 BrableVMINISCAlIStTOS os ra a a e 158 5 77 6 enumerateGuestProperti s cocos oe ee eee rtr 159 5 77 7 onBandwidthGroupCha
53. 122 1 1 name read only wstring ISharedFolder name Logical name of the shared folder 5 122 1 2 hostPath read only wstring ISharedFolder hostPath Full path to the shared folder in the host file system 5 122 1 3 accessible read only boolean ISharedFolder accessible Whether the folder defined by the host path is currently accessible or not For example the folder can be inaccessible if it is placed on the network share that is not available by the time this property is read 5 122 1 4 writable read only boolean ISharedFolder writable Whether the folder defined by the host path is writable or not 284 5 Classes interfaces 5 122 1 5 autoMount read only boolean ISharedFolder autoMount Whether the folder gets automatically mounted by the guest or not 5 122 1 6 lastAccessError read only wstring ISharedFolder lastAccessError Text message that represents the result of the last accessibility check Accessibility checks are performed each time the accessible attribute is read An empty string is returned if the last accessibility check was successful A non empty string indicates a failure and should normally describe a reason of the failure for example a file read error 5 123 ISharedFolderChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when a shared folder is added or removed The scop
54. 147 5 Classes interfaces 5 70 IHostNameResolutionConfigurationChangeEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well 5 70 1 Attributes 5 70 1 1 midIDoesNotLikeEmptyInterfaces read only boolean IHostNameResolutionConfigurationChangeEvent midlDoesNotLikeEmptyInterfaces 5 71 lHostNetworkinterface Represents one of host s network interfaces IP V6 address and network mask are strings of 32 hexadecimal digits grouped by four Groups are separated by colons For example fe80 0000 0000 0000 021e c2ff fed2 b030 5 71 1 Attributes 5 71 1 1 name read only wstring IHostNetworkInterface name Returns the host network interface name 5 71 1 2 shortName read only wstring IHostNetworkInterface shortName Returns the host network interface short name 5 71 1 3 id read only uuid IHostNetworkInterface id Returns the interface UUID 5 71 1 4 networkName read only wstring IHostNetworkInterface networkName Returns the name of a virtual network the interface gets attached to 5 71 1 5 DHCPEnabled read only boolean IHostNetworkInterface DHCPEnabled Specifies whether the DHCP is enabled for the interface 5 71 1 6 IPAddress read only wstring IHostNetworkInterface IPAddress Returns the IP V4 address of the interface 148 5 Classes interfaces 5 71 1 7 networkMask read only wstring IHostNetworkInterface netwo
55. 18 fileCopyToGuest IProgress IGuestSession fileCopyToGuest in wstring source in wstring destination in FileCopyFlag flags source Path to the file on the host side that should be copied to the guest Host path style destination Where to put the file in the guest file not directory Guest style path flags Zero or more FileCopyFlag values Copies a file from the host to the guest Note Will overwrite the destination file unless FileCopyFlag NoReplace is specified If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Error starting the copy operation 131 5 Classes interfaces 5 64 19 fileCreateTemp IGuestFile IGuestSession fileCreateTemp in wstring templateName in unsigned long mode in wstring path in boolean secure templateName Template for the name of the file to create This must contain at least one X character The first group of consecutive X characters in the template will be replaced by a random alphanumeric string to produce a unique name mode The UNIX style access mode mask to create the file with Whether how all three access groups and associated access rights are realized is guest OS dependent The API does the best it can on each OS This parameter is ignore if the secure parameter is set to true Note It is strongly recommended to use 0600 path The path to the directory in which the temporary f
56. 2 release void IManagedObjectRef release Releases this managed object reference and frees the resources that were allocated for it in the webservice server process After calling this method the identifier of the reference can no longer be used 5 87 IMedium The IMedium interface represents virtual storage for a machine s hard disks CD DVD or floppy drives It will typically represent a disk image on the host for example a VDI or VMDK file representing a virtual hard disk or an ISO or RAW file representing virtual removable media but can also point to a network location e g for iSCSI targets Instances of IMedium are connected to virtual machines by way of medium attachments which link the storage medium to a particular device slot of a storage controller of the virtual machine In the VirtualBox API virtual storage is therefore always represented by the following chain of object links e IMachine storageControllers contains an array of storage controllers IDE SATA SCSI SAS or a floppy controller these are instances of IStorageController IMachine mediumAttachments contains an array of medium attachments instances of IMediumAttachment created by IMachine attachDevice each containing a storage con troller from the above array a port device specification and an instance of IMedium rep resenting the medium storage image file For removable media the storage medium is optional a medium attachment with
57. 229 riasa ee 4 244445505 190 5 80 21 enumerateGuestProperti S lt co osos aeh 190 80 22 CXPONTO 22 20 a a ed Se ee a 191 500 23 MndSnam hot o e e oe oe ea aa a aa ee E E BO ee ee a ee 191 5 80 24 getBootOrder s 44 cerere 44a e ae a aa i 04 191 6 30 25 getCPUDLeal oee cesa Bee RY aaa e 192 5 80 26 getCPUProperty osai r ee A ee eee a 192 8027 POr PUSEST OS o e a kw k Ew ee ER ee e S 192 5 80 28 getEffectiveParavirtProvider 1 6 ee ee 192 20029 e a a 18 e oe oe eee tee oh ca ie OH ST ek pm RRL pecan aaa el ogy ane 193 DOU ou COLES DATAKGYS coo eb age Wa eer eee ae ere a 193 5 80 31 getGruestProperty 193 5 80 32 SerGuestPropertyTimesiamp s o ooa e a ee Be ee a eH 193 5 80 33 setGuestPropertyValue 2 022 ss 48a e 46 28 e444 e aaa 194 5 80 34 ga nHWVUTEXPIOPCY o osos ade ee Pe ee ee 194 5 80 35 BeIMedi 2 4344 5448 88 4444 oso eee E e e e wands 194 5 80 36 perMeditm Hachment os a ce au Da a ee e 194 5 80 37 getMediumAttachmentsOfController a aooaa o 195 580 38 vetNetworkAdapter oos sece a a E 195 5 00 39 getParallelPort ooo e e aa OS Ee ee ew eee a 195 3 00 40 SerSeriglP Ort ge eae ans e a es a HER we a A 195 5 80 41 getStorageControllerByInstance o o 196 5 80 42 getStorageControllerByNaMe o o o 196 5 8043 getUSBControllerByNaMe lt lt a 196 5 80 44 getUSBControllerCountByType o a 196 580 45 horPluglBU 1 092 1 Pe e AS 196 5 8046 h
58. 25 2 1 1 4 Object management The current OOWS for JAX WS has certain memory management related limitations When you no longer need an object call its IManagedObjectRef release method explicitly which frees appropriate managed reference as is required by the raw web service see chapter 2 2 3 3 Managed object references page 34 for details This limitation may be reconsidered in a future version of the VirtualBox SDK 2 1 2 The object oriented web service for Python VirtualBox comes with two flavors of a Python API one for web service discussed here and one for the COM XPCOM API discussed in chapter 2 3 1 Python COM API page 36 The client code is mostly similar except for the initialization part so it is up to the application developer to choose the appropriate technology Moreover a common Python glue layer exists abstracting out concrete platform access details see chapter 2 3 2 Common Python bindings layer page 36 As indicated in chapter 1 2 Two guises of the same Main API the web service or COM XPCOM page 22 the COM XPCOM API gives better performance without the SOAP overhead and does not require a web server to be running On the other hand the COM XPCOM Python API requires a suitable Python bridge for your Python installation VirtualBox ships the most important ones for each platform On Windows you can use the Main API from Python if the Win32 extensions package for Python is installed Version of Pyth
59. 29 b Y Alternatively you can use the web service directly without the object oriented client layer We shall refer to this as the raw web service You will then have neither native object orientation nor full type safety since web services are neither object oriented nor stateful However in this way you can write client code even in languages for which we do not ship object oriented client code all you need is a programming language with a toolkit that can parse WSDL and generate client wrapper code from it We describe this further in chapter 2 2 Using the raw web service with any language page 30 with samples for Java and Perl 2 Internally for portability and easier maintenance the Main API is implemented using the Component Object Model COM an interprocess mechanism for software components originally introduced by Microsoft for Microsoft Windows On a Windows host VirtualBox will use Microsoft COM on other hosts where COM is not present it ships with XPCOM a free software implementation of COM originally created by the Mozilla project for their browsers So if you are familiar with COM and the C programming language or with any other programming language that can handle COM XPCOM objects such as Java Visual Basic or C then you can use the COM XPCOM API directly VirtualBox comes with all necessary files and documentation to build fully functional COM applications For an introduction please see chap
60. 310 Slay o soora bud ee a a ee Pa eee 310 5 148 IVRDEServerInfoChangedEvent IEvent o 000 cee ee eae 312 5146 1 POS ete oe ee ea ee aed we ee eee a we ee eee E A 312 5 149 IVetoEvent Event 2 0 ns 312 5149 1 addApproval gt gt A a ww Bd wee en eee Se ee 312 5 149 2 addveto nc ek ee Reda eR AA SS DR RED AAs 312 51493 Sete II E 312 5149 4 ESOS ok EERE ER ESE OE PO EEE OP Ee ROS 312 5149 5 tehppreved cs cs aoa es Re ee RR A Bo 313 5 1496 6 oe ee a a ee Re ee Bae 313 5 150 IVideoCaptureChangedEvent IEvent o e 313 5150 1 ADUSS gt o coeant io de A EE ee 313 5 151 MirtialBoX coords a a a S 313 CASTA AES a da a a ee 313 5 151 2 checkFirmwarePresent ccoo ara a a a 316 5 151 3 composeMachineFllename 2 6 lt lt lt lt uo 317 5 151 4 Create Appllante ociosas a aa 317 3 1515 create DE CP SSIRL o e i a a AA e E 317 5 1516 careateMachine so cae o ee aa Bae 318 5 151 7 createMediumi a Sh wa a ee E e e 319 5 151 8 createNATNetwork 2 o rero 320 5 151 9 createSharedPolder oa ke 00 we 320 5 151 10findDHCPServerByNetworkName o o 320 5 151 A lhind Machine coso eh eee ae dda aaa a aan 321 5 151 12findNATNetworkByName 2 000 cee eee eens 321 SSL 13getExtr Data oscura tae a PA ae eee a ee ee 321 5 151 per etraDarakeye osos a a ao e ea p eR ee 321 5 151 15eerGuestOS ype gt o swe hk ee ea Ea ee he a eae hao 321 S151 LESA
61. 5 28 1 5 edition read only wstring IExtPackBase edition Edition indicator This is usually empty Can for instance be used to help distinguishing between two editions of the same extension pack where only the license service contract or something differs 90 5 Classes interfaces 5 28 1 6 VRDEModule read only wstring IExtPackBase VRDEModule The name of the VRDE module if the extension pack sports one 5 28 1 7 plugins read only IExtPackPlugIn IExtPackBase plugIns Note This attribute is not supported in the web service Plug ins provided by this extension pack 5 28 1 8 usable read only boolean IExtPackBase usable Indicates whether the extension pack is usable or not There are a number of reasons why an extension pack might be unusable typical examples would be broken installation file or that it is incompatible with the current VirtualBox version 5 28 1 9 whyUnusable read only wstring IExtPackBase whyUnusable String indicating why the extension pack is not usable This is an empty string if usable and always a non empty string if not usable 5 28 1 10 showLicense read only boolean IExtPackBase showLicense Whether to show the license before installation 5 28 1 11 license read only wstring IExtPackBase license The default HTML license text for the extension pack Same as calling queryLicense with preferredLocale and preferredLanguage as empty strings and format set
62. 5 64 10 directoryRemove void IGuestSession directoryRemove in wstring path path Path to the directory that should be removed Guest path style Removes a guest directory if empty Note Symbolic links in the final component will not be followed instead an not a directory error is reported 5 64 11 directoryRemoveRecursive IProgress IGuestSession directoryRemoveRecursive in wstring path in DirectoryRemoveRecFlag flags path Path of the directory that is to be removed recursively Guest path style flags Zero or more DirectoryRemoveRecFlag flags Note WARNING SPECIFYING DirectoryRemoveRecFlag ContentAndDir IS MANDA TORY AT THE MOMENT Removes a guest directory recursively Note WARNING THE FLAGS ARE NOT CURRENTLY IMPLEMENTED THE IMPLE MENTATION WORKS AS IF FLAGS WAS SET TO ContentAndDir Note If the final path component is a symbolic link this method will fail as it can only be applied to directories 5 64 12 environmentDoesBaseVariableExist boolean IGuestSession environmentDoesBaseVariableExist in wstring name name Name of the environment variable to look for This cannot be empty nor can it contain any equal signs Checks if the given environment variable exists in the session s base environment environmentBase If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED If the guest additions doe
63. 5 Classes interfaces 5 78 1 2 eventSource read only IEventSource IKeyboard eventSource Event source for keyboard events 5 78 2 putCAD void IKeyboard putCAD Sends the Ctrl Alt Del sequence to the keyboard This function is nothing special it is just a convenience function calling putScancodes with the proper scancodes If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Could not send all scan codes to virtual keyboard 5 78 3 putScancode void IKeyboard putScancode in long scancode scancode Sends a scancode to the keyboard If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Could not send scan code to virtual keyboard 5 78 4 putScancodes unsigned long IKeyboard putScancodes in long scancodes scancodes Sends an array of scancodes to the keyboard If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Could not send all scan codes to virtual keyboard 5 78 5 releaseKeys void IKeyboard releaseKeys Causes the virtual keyboard to release any keys which are currently pressed Useful when host and guest keyboard may be out of sync If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Could not release some or all keys 5 79 IKeyboardLedsChangedE vent IEvent Note This interface extends IEvent and therefore supports all its methods and at
64. 8 207 De L EETESTADARA o ros eS SO a ge A a e 207 SUL 2 SCUTUCBEPTOPEITY ok SoS eee A a a 208 5 80 73 setGuestProperiy Valle occ 6444454544 4 e604 5544 208 580 74 setHWVInExProperty os 6 a aw Bod wee See ee ee 209 5 80 75 setHotPluggablePorDevic o lt s i cae ad dee eee eee eran as 209 5 80 76 setNoBandwidthGroupForDevice o o a 210 5 80 77 setsettinesFlePath soccer cosas a 210 5 80 78 setStorageControllerBootable o oo 210 5 80 79 showConsoleWindow o o e e 211 5 00 00 takeSnapehot lt a ee a RE e 211 300 81 bEMporarpEJScIDEVICE oie a ee aA 212 500 02 UEMOIMEMEAMD s o eos e a a a e a 212 500 83 MOESTISC O o aaa id A aa 213 IMachineDataChangedEvent IMachineEvent 214 DPLI e A NE 214 IMachineDebugger 2 4 4 2088444494 6044 28 444 444 40 214 SBRI ADES a Eb ae Pde ee a S 214 5322 IES as adnee ee A AA 217 5929 AMPLIOS os oa a a e 217 S824 dumpuestStack gt 065500 asia aa Se eS 217 53825 dumpHostProcdssGOre os ls s aci we a A 217 5 02 0 CMMPREAE rre SS ee ee ew wee Grae a 218 BiG POUR CIEE sce oo ie a A eg amp Gd e EE 218 SOAS FEMELEI ook kh a OE Se OE ORES CS EE RAS 218 50297 BSUSTA S oscar eee edt ae a eS EERE EDS TO 218 By MING ee Sava ae a a aw EGE ow See She Be aa aaa a 218 Sos Ue cae ba eRe Pen eee a eas 219 52 le MOP IEE oe se oo 4 oO a a ee AS 219 5 82 13 modifyLogDestinations s ec orori d ea dorur ee eee eee 219 532 14 MmoOdiLo
65. Both arrays have the same number of elements with each element at the given index in the first array corresponding to an element at the same index in the second array If there is at least one property name in names that is not valid the method will fail before changing the values of any other properties from the names array Using this method over setProperty is preferred if you need to set several properties at once since it is more efficient The list of all properties supported by the given medium format can be obtained with IMediumFormat describeProperties Setting the property value to null or an empty string is equivalent to deleting the existing value A default value if it is defined for this property will be used by the format backend in this case 5 87 24 setProperty void IMedium setProperty in wstring name in wstring value name Name of the property to set value Property value to set Sets the value of the custom medium property with the given name The list of all properties supported by the given medium format can be obtained with IMediumFormat describeProperties Note Setting the property value to null or an empty string is equivalent to deleting the existing value A default value if it is defined for this property will be used by the format backend in this case If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Requested property does n
66. COIEASLASS ok ec ek ak a EG ee 322 5 151 7eetMachinesByGroups lt lt e cecco ctae awari nnt eS 322 S151 iBopenMaching os eoe es k eiee a aa Re aR a Ao R E 322 A o ss acct eee aa SPS ee e eee ae 322 3 15 LABS ter Machine oec oss o we bea ee a es a WOR we a A 323 5151 2 remioveDHGPSGrver e coca AA OS EE eS 324 5 151 22removeNATNetwork 2 0 aa eee 324 5 151 23removeSharedFolder 444 4 44044445448 2 Ge ee 324 5 151 L2SRERIADITA 3 8 ka es eA A ee RS 324 MLS reo 1 e eis a Sis ce yw we ee ew 325 5 152 IWirtialBoxClient 2444 22244444488 04404 24 e444 488088 325 B1521 ADUS ee es BR SE ee a eS 325 5 152 2 checkMachineError osu 666 a ee ee eee 326 5 153 TyirtialBowErrorinio s ea eee aa ce es BE ae ee 326 SISSI AUIOWERS oo bee ia e BEd SHO EE ES GE PERE RS 326 5 154 TirtialSystembescriptiot s s s tiei r we ee doe a we ee 327 16 Contents a ea a aw ww a we we ws SRI ee ew 328 5154 2 addDescipton lt o e osci eee eG ESSERE Eee eA ra ES 328 5 1543 POOIESCTPUON essa eh ee ee ee ae E E 328 5 1544 eerbescriprionBylype sa ea erreia dae a a 330 5 1545 getValu sByTyp gt s ek sa a da as ee ee ee 330 5 1546 sethinalValdes lt c coaire bos SS ee ee wae Se 331 5 155 IWebsessionManager oo ew ew we a a a a E E EOE RO G 331 5 1551 SetSessionObject o cce corresse POS Ce A AEE es Se ODS 331 E A tts ks ore SS ee E 331 SL LOGON a A Se eee wale we ee 332 Enumerations enums 333 Gl AccessMode ccce 449 244424 44 44544 GAN ee
67. Communication Manager 7 4 HGCM Service Implementation The HGCM service is a shared library with a specific set of entry points The library must export the VBoxHGCMSvcLoad entry point extern C DECLCALLBACK DECLEXPORT int VBoxHGCMSvcLoad VBOXHGCMSVCFNTABLE ptable The service must check the ptable gt cbSize and ptable gt u32Version fields of the input structure and fill the remaining fields with function pointers of entry points and the size of the required client buffer size The HGCM service gets a dedicated thread which calls service entry points synchronously that is the service will be called again only when a previous call has returned However the guest calls can be processed asynchronously The service must call a completion callback when the operation is actually completed The callback can be issued from another thread as well Service entry points are listed in the VBox hgcmsvc h in the VBOXHGCMSVCFNTABLE structure Entry Description pf The service is being unloaded nUn load pfn A client u32CLientID is connected to the service The pvClient parameter points Con to an allocated memory buffer which can be used by the service to store the client nect information pfnDis A client is being disconnected con nect pfn A guest client calls a service function The callHandle must be used in the Call VBOXHGCMSVCHELPERS pfnCallComplete callback when the call has been process
68. Could not parse the settings file 5 76 11 finishOnlineMergeMedium void IInternalMachineControl finishOnlineMergeMedium Gets called by IInternalSessionControl onlineMergeMedium All necessary state informa tion is available at the called object 5 76 12 lockMedia void IInternalMachineControl LockMedia Locks all media attached to the machine for writing and parents of attached differencing media if any for reading This operation is atomic so that if it fails no media is actually locked This method is intended to be called when the machine is in Starting or Restoring state The locked media will be automatically unlocked when the machine is powered off or crashed 5 76 13 onSessionEnd IProgress IInternalMachineControl onSessionEnd in ISession session session Session that is being closed Triggered by the given session object when the session is about to close normally 154 5 Classes interfaces 5 76 14 pullGuestProperties void IInternalMachineControl pullGuestProperties out wstring names out wstring values out long long timestamps out wstring flags names The names of the properties returned values The values of the properties returned The array entries match the corresponding entries in the name array timestamps The time stamps of the properties returned The array entries match the corre sponding entries in the name array flags The flags of the properties re
69. Ew we 137 5 64 32 processGet 2c ee eee a BROS EE SES ES RES 138 5 64 35 SqmlinkCIBAbe ons ae See Sw we eR de a wa ge E 138 5 65 5 66 5 67 5 68 5 69 370 5 71 use Sua 5 74 B75 5 76 Contents 64 54 SymlinkEXIStS lt lt oidor a E a e ww EEG Pe ae ew 138 5 04 35 symlinkRead 2 cs ga hee a aaa a 139 SGA SG WHEE ooe c a ee e a E 139 203 e sonarai etera dag debe EEE A 139 IGuestSessionEvent IEvent 6 6 a we ee ees 139 S651 PUEDO lt a bb a a 139 IGuestSessionRegisteredEvent IGuestSessionEveMt 140 5 06 1 Atributos 222080 weeded eed dew dee ee Pe omens 140 IGuestSessionStateChangedEvent IGuestSessionEvent 140 5 67 1 Attributes irice reperar ad a Ree ee Pa eee a 140 IGuestUserStateChangedEvent IEvent aaao ee eee eee eee 140 DGI ARIES sa cesena enaa act a wee ee ee a e dd 141 VAS e ars SRS RRB Aa dds be eit ada 141 Bol PRATER ooer a kA ew ED eee en vind eee ae ee ee 141 5 69 2 createHostOnlyNetworkInterface o o 143 5 69 3 createUSBDeviceFilter 6 4 64 44 5504446 aaa a 144 5 69 4 findHostDVDDrive ui ee ba eb bed Powe eee Ee meee 144 560 5 fAndHostFloppy Drite oe s pira aa aw we 144 5 69 6 findHostNetworkInterfaceByld aoaaa 02 ee 144 5 69 7 findHostNetworkInterfaceByName o o 144 5 69 8 findHostNetworkInterfacesOfType o ooo o 145 5 69 9 findUSBDeviceByAddress a o o e
70. FileSeekOrigin whence offset Offset to seek relative to the position specified by whence whence One of the FileSeekOrigin seek starting points Changes the current file position of this file The file current position always applies to the read method Same for the write method it except when the accessMode is FileAccessMode AppendOnly or FileAccessMode AppendRead 5 34 8 setACL void IFile setACL in wstring acl in unsigned long mode acl The ACL specification string To be defined mode UNIX style mode mask to use if acl is empty As mention in IGuestSession directoryCreate this is realized on a best effort basis and the exact behavior depends on the Guest OS Sets the ACL of this file If this method fails the following error codes may be reported e E_NOTIMPL The method is not implemented yet 5 34 9 setSize void IFile setSize in long long size size The new file size Changes the file size If this method fails the following error codes may be reported e E_NOTIMPL The method is not implemented yet 5 34 10 write unsigned long IFile write in octet data in unsigned long timeoutMS data Array of bytes to write The size of the array also specifies how much to write timeoutMS Timeout in ms to wait for the operation to complete Pass O for an infinite timeout Writes bytes to this file 98 5 Classes interfaces 5 34 11 writeAt unsigned long IFile writeAt i
71. Guest Additions update inside the guest was started This can be necessary due to needed inter action with the guest OS during the installation phase 6 7 AudioCodecType The exact variant of audio codec hardware presented to the guest see AudioAdapter audioCodec Null null value Never used by the API SB16 SB16 this is the only option for the SB16 device STAC9700 A STAC9700 AC 97 codec AD1980 An AD1980 AC 97 codec Recommended for Linux guests STAC9221 A STAC9221 HDA codec 334 6 Enumerations enums 6 8 AudioControllerType Virtual audio controller type AC97 SB16 HDA 6 9 AudioDriverType Host audio driver type Null Null value also means dummy audio driver WinMM Windows multimedia Windows hosts only OSS Open Sound System Linux hosts only ALSA Advanced Linux Sound Architecture Linux hosts only DirectSound DirectSound Windows hosts only CoreAudio CoreAudio Mac hosts only MMPM Reserved for historical reasons Pulse PulseAudio Linux hosts only SolAudio Solaris audio Solaris hosts only 6 10 AuthType VirtualBox authentication type Null Null value also means no authentication External Guest 6 11 AutostopType Autostop types used with IMachine autostopType Disabled Stopping the VM during system shutdown is disabled SaveState The state of the VM will be saved when the system shuts down PowerOff The VM is powered off when the system shuts down AcpiShutd
72. ISO 9960 CD DVD image After this method succeeds the medium will be added to the DVDImages array attribute e With a Floppy device type the file must be an RAW floppy image After this method succeeds the medium will be added to the floppyImages array attribute After having been opened the medium can be re found by this method and can be attached to virtual machines See Medium for more details The UUID of the newly opened medium will either be retrieved from the storage location if the format supports it e g for hard disk images or a new UUID will be randomly generated e g for ISO and RAW files If for some reason you need to change the medium s UUID use IMedium setIds If a differencing hard disk medium is to be opened by this method the operation will suc ceed only if its parent medium and all ancestors if any are already known to this VirtualBox installation for example were opened by this method before This method attempts to guess the storage format of the specified medium by reading medium data at the specified location If accessMode is ReadWrite which it should be for hard disks and floppies the image is opened for read write access and must have according permissions as VirtualBox may actually write status information into the disk s metadata sections Note that write access is required for all typical hard disk usage in VirtualBox since VirtualBox may need to write metadata such as a UUID int
73. IStorageController bus The bus type of the storage controller IDE SATA SCSI SAS or Floppy 5 132 1 8 controllerType read write StorageControllerType IStorageController controllerType The exact variant of storage controller hardware presented to the guest Depending on this value VirtualBox will provide a different virtual storage controller hardware to the guest For SATA SAS and floppy controllers only one variant is available but for IDE and SCSI there are several For SCSI controllers the default type is LsiLogic 5 132 1 9 useHostlOCache read write boolean IStorageController useHostI0Cache If true the storage controller emulation will use a dedicated I O thread enable the host I O caches and use synchronous file APIs on the host This was the only option in the API before VirtualBox 3 2 and is still the default for IDE controllers If false the host I O cache will be disabled for image files attached to this storage controller Instead the storage controller emulation will use asynchronous I O APIs on the host This makes it possible to turn off the host I O caches because the emulation can handle unaligned access to the file This should be used on OS X and Linux hosts if a high I O load is expected or many virtual machines are running at the same time to prevent I O cache related hangs This option new with the API of VirtualBox 3 2 and is now the default for non IDE storage controllers 5 132 1 10 bootable
74. Reads the VM log file The chunk size is limited so even if you ask for a big piece there might be less data returned 5 80 56 readSavedScreenshotToArray octet IMachine readSavedScreenshotToArray in unsigned long screenld in BitmapFormat bitmapFormat out unsigned long width out unsigned long height screenld Saved guest screen to read from bitmapFormat The requested format width Image width height Image height Screenshot in requested format is retrieved to an array of bytes 5 80 57 readSavedThumbnailToArray octet IMachine readSavedThumbnailToArray in unsigned long screenId in BitmapFormat bitmapFormat out unsigned long width out unsigned long height screenld Saved guest screen to read from bitmapFormat The requested format 202 5 Classes interfaces width Bitmap width height Bitmap height Thumbnail is retrieved to an array of bytes in the requested format 5 80 58 removeAllCPUIDLeaves void IMachine removeALLCPUIDLeaves Removes all the virtual CPU cpuid leaves 5 80 59 removeCPUIDLeaf void IMachine removeCPUIDLeaf in unsigned long id id CPUID leaf index Removes the virtual CPU cpuid leaf for the specified index If this method fails the following error codes may be reported e E_INVALIDARG Invalid id 5 80 60 removeSharedFolder void IMachine removeSharedFolder in wstring name name Logical name of the shared folder to remov
75. Supports absolute coordinates 249 5 Classes interfaces 5 94 1 2 supportsRelative read only boolean IMouseCapabilityChangedEvent supportsRelative Supports relative coordinates 5 94 1 3 supportsMultiTouch read only boolean IMouseCapabilityChangedEvent supportsMultiTouch Supports multi touch events coordinates 5 94 1 4 needsHostCursor read only boolean IMouseCapabilityChangedEvent needsHostCursor If host cursor is needed 5 95 IMousePointerShape The guest mouse pointer description 5 95 1 Attributes 5 95 1 1 visible read only boolean IMousePointerShape visible Flag whether the pointer is visible 5 95 1 2 alpha read only boolean IMousePointerShape alpha Flag whether the pointer has an alpha channel 5 95 1 3 hotX read only unsigned long IMousePointerShape hotX The pointer hot spot X coordinate 5 95 1 4 hotY read only unsigned long IMousePointerShape hotY The pointer hot spot Y coordinate 5 95 1 5 width read only unsigned long IMousePointerShape width Width of the pointer shape in pixels 250 5 Classes interfaces 5 95 1 6 height read only unsigned long IMousePointerShape height Height of the pointer shape in pixels 5 95 1 7 shape read only octet IMousePointerShape shape Shape bitmaps The shape buffer contains a 1bpp bits per pixel AND mask followed by a 32bpp XOR color mask For pointers without alpha channel the X
76. TEXT and STRING plain ASCII text depending on the source s active ANSI page if any If for whatever reason a certain default format should not be supported or a new format should be registered IDnDSource and IDnDTarget have methods derived from IDnDBase which provide adding removing and enumerating specific formats 381 9 Drag and Drop Note Registering new or removing default formats on the guest side currently is not implemented 382 10 VirtualBox external authentication modules VirtualBox supports arbitrary external modules to perform authentication The module is used when the authentication method is set to external for a particular VM VRDE access and the library was specified with VBoxManage setproperty vrdeauthlibrary Web ser vice also use the authentication module which was specified with VBoxManage setproperty websrvauthlibrary This library will be loaded by the VM or web service process on demand i e when the first remote desktop connection is made by a client or when a client that wants to use the web service logs on External authentication is the most flexible as the external handler can both choose to grant access to everyone like the null authentication method would and delegate the request to the guest authentication component When delegating the request to the guest component the handler will still be called afterwards with the option to override the result An authenticatio
77. Usually 0 is stdin 1 is stdout and 2 is stderr flags A combination of ProcessInputFlag flags data Array of bytes to write The size of the array also specifies how much to write timeoutMS Timeout in ms to wait for the operation to complete Pass 0 for an infinite timeout Writes data to a running process Scriptable version of write 5 115 IProgress The Progress interface is used to track and control asynchronous tasks within VirtualBox An instance of this is returned every time VirtualBox starts an asynchronous task in other words a separate thread which continues to run after a method call returns For example IMachine saveState which saves the state of a running virtual machine can take a long time to complete To be able to display a progress bar a user interface such as the VirtualBox graphical user interface can use the Progress object returned by that method Note that Progress is a read only interface in the sense that only the VirtualBox internals behind the Main API can create and manipulate progress objects whereas client code can only use the IProgress object to monitor a task s progress and if cancelable is true cancel the task by calling cancel A task represented by IProgress consists of either one or several sub operations that run se quentially one by one see operation and operationCount Every operation is identified by a number starting from 0 and has a separate description You can fi
78. VBOX_E_FILE_ERROR Settings file not accessible e VBOX_E_XML_ERROR Could not parse the settings file e E_ACCESSDENIED Modification request refused 5 151 25 setSettingsSecret void IVirtualBox setSettingsSecret in wstring password password The cipher key Unlocks the secret data by passing the unlock password to the server The server will cache the password for that machine If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine is not mutable 5 152 IVirtualBoxClient Note This interface is not supported in the web service Convenience interface for client applications Treat this as a singleton i e never create more than one instance of this interface At the moment only available for clients of the local API not usable via the webservice Once the session logic is redesigned this might change 5 152 1 Attributes 5 152 1 1 virtualBox read only IVirtualBox IVirtualBoxClient virtualBox Reference to the server side API root object 5 152 1 2 session read only ISession IVirtualBoxClient session Create a new session object and return the reference to it 325 5 Classes interfaces 5 152 1 3 eventSource read only IEventSource IVirtualBoxClient eventSource Event source for VirtualBoxClient events 5 152 2 checkMachineError void IVirtualBoxClient checkMachineError in IMachine machine machine The machine objec
79. a drag n drop operation Ignore Do nothing Copy Copy the item to the target Move Move the item to the target Link Link the item from within the target 6 32 DnDMode Drag and drop interchange mode Disabled HostToGuest GuestToHost Bidirectional 6 33 ExportOptions Export options used with IAppliance write CreateManifest Write the optional manifest file mf which is used for integrity checks prior import ExportDVDimages Export DVD images Default is not to export them as it is rarely needed for typical VMs StripAlIMACs Do not export any MAC address information Default is to keep them to avoid losing information which can cause trouble after import at the price of risking duplicate MAC addresses if the import options are used to keep them StripAllNonNATMACs Do not export any MAC address information except for adapters using NAT Default is to keep them to avoid losing information which can cause trouble after import at the price of risking duplicate MAC addresses if the import options are used to keep them 6 34 FaultToleranceState Used with IMachine faultToleranceState Inactive No fault tolerance enabled Master Fault tolerant master VM Standby Fault tolerant standby VM 342 6 Enumerations enums 6 35 FileAccessMode File open access mode for use with IGuestSession fileOpenQ and IGuestSession fileOpenEx ReadOnly Open the file only with read access WriteOnly Open the file only w
80. ae eee a we ee 359 Processinputhlag coo 44 454 aa e aaa 360 PEOCEESTIPUESERTOS e io eee i a we a a ee e 360 ProcessOutputFlag so 22d Aw Eee re baw SE d bee BEE ES 360 Process PROTEY o 2 ar A ye a Gk e a 361 PROCERSStAIMS eo ee A he a e Ge 361 Process WailPOr RIA ooe e Ges ew we a ae We E E OE 361 Process Walthesult o oon avew se eee eee bs COOH RELL SERRE 362 ProcessorFeature ocaso eee r aaa EERE Ree 362 REASON copia e asada toh eas a ee EG da eS Se Pe ee OE G 362 SCOPE fo wade e eS ARR SESSLER SERS A ee eis aes 363 SESSIE s aos ecto a ce a Bb a ww we een des js A 363 MESSIONIVPE 2 4444 ma nGS4 BREEDER REALE LESS DES EG aa 363 BECMNGSVETSION osaa ee a eR SE Ee a ER O kee 363 Storag BUS gt oes aon Gop ee eee eg ag Re eee ae ae a 364 StorageConiraller Type o e hw we ee ae a He Re A 365 SymlinkReadhlag eee ee eee Ne TOA EE EE Oo RS 365 EVID TY no ee a ge ee a Se eR Redd a ed 365 18 Contents 696 ToudiContactSie o sa KO aw ew B wwe SOR Re ee le ees 6 97 USEConiectionSpeed 4 4444 ee see 8459454 5 ee 4444 Daa Se 698 USBControllerIyp i e e eey 644 a eee Be eee ee nme 4 6 99 USBDeviceFilterAction 44 668 bed 0 ae 6100 USBDevi eState a chee kv a Rs a we eee Gl eee SS 6 101 VBoxEvemtType gt e s 2k ee ea a ER Re ee ee ee 6102 VFS p cos rr A AA ER E 6 103 VirtualSystemDescriptionType o e 6 104 VirtualSystemDescriptionValueType o ooo ee Host Guest Communication Manager 7 1 Virtual hardwa
81. almost all aspects of virtual machine execution As an example use the following commands to instantiate the VirtualBox object and start a VM vbox win32com client Dispatch VirtualBox VirtualBox session win32com client Dispatch VirtualBox Session mach vbox findMachine uuid or name of machine to start progress mach launchVMProcess session gui progress waitForCompletion 1 Also see bindings glue python samples vboxshell py for more advanced usage scenari ous However unless you have specific requirements we strongly recommend to use the generic glue layer described in the next section to access MS COM objects 2 3 2 Common Python bindings layer As different wrappers ultimately provide access to the same underlying APL and to simplify porting and development of Python application using the VirtualBox Main API we developed a common glue layer that abstracts out most platform specific details from the application and allows the developer to focus on application logic The VirtualBox installer automatically sets up this glue layer for the system default Python install See below for details on how to set up the glue layer if you want to use a different Python installation 36 2 Environment specific notes In this layer the class VirtualBoxManager hides most platform specific details It can be used to access both the local COM and the web service based API The following code can be used by an application to
82. and ACLs from the existing file or replace them OpenExistingTruncated Opens and truncate an existing file fails if no file exists Was ot AppendOrCreate Opens an existing file and places the file pointer at the end of the file creates the file if it does not exist This action implies write access Was oa Note Deprecated Only here for historical reasons Do not use 6 38 FileOpenExFlags Open flags for IGuestSession fileOpenEx None No flag set 6 39 FileSeekOrigin What a file seek IFile seek is relative to Begin Seek from the beginning of the file Current Seek from the current file position End Seek relative to the end of the file To seek to the position two bytes from the end of the file specify 2 as the seek offset 6 40 FileSharingMode File sharing mode for IGuestSession fileODpenEx Read Only share read access to the file Write Only share write access to the file ReadWrite Share both read and write access to the file but deny deletion Delete Only share delete access denying read and write ReadDelete Share read and delete access to the file denying writing WriteDelete Share write and delete access to the file denying reading All Share all access i e read write and delete to the file 344 6 Enumerations enums 6 41 FileStatus File statuses Undefined File is in an undefined state Opening Guest file is opening Open Guest file has
83. be reported e VBOX_E_VM_ERROR VMM device is not available 5 20 2 drop IProgress IDnDSource drop in wstring format in DnDAction action format The mime type the data must be in action The action to use Informs the source that a drop event occurred for a pending drag and drop operation If this method fails the following error codes may be reported e VBOX_E_VM_ERROR VMM device is not available 5 20 3 receiveData octet IDnDSource receiveData Receive the data of a previously drag and drop event from the source If this method fails the following error codes may be reported e VBOX_E_VM_ERROR VMM device is not available 5 21 IDnDTarget IDnDBase Note This interface extends IDnDBase and therefore supports all its methods and attributes as well Abstract interface for handling drag n drop targets 5 21 1 cancel boolean IDnDTarget cancel Requests cancelling the current operation The target can veto the request in case the operation is not cancelable at the moment If this method fails the following error codes may be reported e VBOX_E_VM_ERROR VMM device is not available 82 5 Classes interfaces 5 21 2 drop DnDAction IDnDTarget drop in unsigned long screenld in unsigned long x in unsigned long y in DnDAction defaultAction in DnDAction allowedActions in wstring formats out wstring format screenld The screen ID where the Drag and Drop
84. capable of accessing COM objects The following VB code will iterate over all available virtual machines Dim vb As VirtualBox IVirtualBox vb CreateObject VirtualBox VirtualBox machines For Each m In vb Machines m m amp amp m Name Next See bindings mscom vb sample vboxinfo vb for the complete sample 2 3 6 C binding to VirtualBox API The VirtualBox API originally is designed as object oriented using XPCOM or COM as the mid dleware which translates natively to C This means that in order to use it from C there needs to be some helper code to bridge the language differences and reduce the differences between platforms 2 3 6 1 Cross platform C binding to VirtualBox API Starting with version 4 3 VirtualBox offers a C binding which allows using the same C client sources for all platforms covering Windows Linux Mac OS X and Solaris It is the preferred way to write API clients even though the old style is still available The difference results from the way VBS treats COM safearrays which are used to keep lists in the Main API VBS expects every array element to be a VARIANT which is too strict a limitation for any high performance API We may lift this restriction for interface APIs in a future version or alternatively provide conversion APIs 39 2 Environment specific notes 2 3 6 2 Getting started The following sections describe how to use the VirtualBox API in a C program The necessary f
85. codes may be reported e E_NOTIMPL The method is not implemented yet 138 5 Classes interfaces 5 64 35 symlinkRead wstring IGuestSession symlinkRead in wstring symlink in SymlinkReadFlag flags symlink Path to the symbolic link to read flags Zero or more SymlinkReadFlag values Reads the target value of a symbolic link in the guest If this method fails the following error codes may be reported e E_NOTIMPL The method is not implemented yet 5 64 36 waitFor GuestSessionWaitResult IGuestSession waitFor in unsigned long waitFor in unsigned long timeoutMS waitFor Specifies what to wait for see GuestSessionWaitForFlag for more information timeoutMS Timeout in ms to wait for the operation to complete Pass 0 for an infinite timeout Waits for one or more events to happen 5 64 37 waitForArray GuestSessionWaitResult IGuestSession waitForArray in GuestSessionWaitForFlag waitFor in unsigned long timeoutMS waitFor Specifies what to wait for see GuestSessionWaitForFlag for more information timeoutMS Timeout in ms to wait for the operation to complete Pass 0 for an infinite timeout Waits for one or more events to happen Scriptable version of waitFor 5 65 IGuestSessionEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Base abstract interface for all guest session events 5 65 1 Attributes
86. conventions page 32 please have the following notes in mind 1 Any COM method call becomes a plain function call in the raw web service with the object as an additional first parameter before the real parameters listed in the docu mentation So when the documentation says that the IVirtualBox interface supports the createMachine method see IVirtualBox createMachine the web service op eration is IVirtualBox_createMachine and a managed object reference to an IVirtualBox object must be passed as the first argument 2 For attributes in interfaces there will be at least one get function there will also be a set function unless the attribute is readonly The attribute name will be appended to the get or set prefix with a capitalized first letter So the version readonly attribute of the IVirtualBox interface can be retrieved by calling IVirtualBox_getVersion vbox with vbox being the VirtualBox object 3 Whenever the API documentation says that a method or an attribute getter returns an object it will returned a managed object reference in the web service instead As said above managed object references should be released if the web service client does not log off again immediately 2 2 1 Raw web service example for Java with Axis Axis is an older web service toolkit created by the Apache foundation If your distribution does not have it installed you can get a binary from http
87. createLegacyMachine API has been re moved To reduce code duplication and for consistency with the aforementioned media APIs IVirtualBox getMachine has been merged with IVirtualBox findMachine and IMachine getSnapshot has been merged with IMachine findSnapshot Q IVirtualBox unregisterMachine was replaced with IMachine unregister with additional functionality for cleaning up machine files IMachine deleteSettings has been replaced by IMachine delete which allows specifying which disk images are to be deleted as part of the deletion and because it can take a while it also returns a IProgress object reference so that the completion of the asynchronous activities can be monitored IConsole forgetSavedState has been renamed to IConsole discardSavedState e All event callbacks APIs were replaced with a new generic event mechanism that can be used both locally COM XPCOM and remotely web services Also the new mechanism is usable from scripting languages and a local Java See events for details The new concept will require changes to all clients that used event callbacks additionsActive was replaced with additionsRunLevelQ and getAdditionsStatus in order to support a more detailed status of the current Guest Additions loading readiness state IGuest additionsVersion no longer returns the Guest Additions interface version but the installed Guest Additions version and revision in form
88. directly If you do not require remote procedure calls such as those offered by the VirtualBox web ser vice and if you know Python or C as well as COM you might find it preferable to program VirtualBox s Main API directly via COM COM stands for Component Object Model and is a standard originally introduced by Mi crosoft in the 1990s for Microsoft Windows It allows for organizing software in an object oriented way and across processes code in one process may access objects that live in another process COM has several advantages it is language neutral meaning that even though all of VirtualBox is internally written in C programs written in other languages could communicate with it COM also cleanly separates interface from implementation so that external programs need not know anything about the messy and complicated details of VirtualBox internals On a Windows host all parts of VirtualBox will use the COM functionality that is native to Windows On other hosts including Linux VirtualBox comes with a built in implementation of XPCOM as originally created by the Mozilla project which we have enhanced to support interprocess communication on a level comparable to Microsoft COM Internally VirtualBox has an abstraction layer that allows the same VirtualBox code to work both with native COM as well as our XPCOM implementation 2 3 1 Python COM API On Windows Python scripts can use COM and VirtualBox interfaces to control
89. e argv 0 arguments Array of arguments passed to the new process Note Starting with VirtualBox 5 0 this array starts with argument 0 instead of argu ment 1 as in previous versions Whether the zeroth argument can be passed to the guest depends on the VBoxService version running there If you depend on this check that the protocolVersion is 3 or higher environmentChanges Set of environment changes to complement environmentChanges Takes precedence over the session ones The changes are in putenv format i e VAR VALUE for setting and VAR for unsetting The changes are applied to the base environment of the impersonated guest user environmentBase when creating the process This is done on the guest side of things in order to be compatible with older guest additions That is one of the motivations for not passing in the whole environment here flags Process creation flags see ProcessCreateFlag for detailed description of available flags timeoutMS Timeout in ms for limiting the guest process running time Pass O for an infi nite timeout On timeout the guest process will be killed and its status will be put to an appropriate value See ProcessStatus for more information priority Process priority to use for execution see ProcessPriority for available priority levels 137 5 Classes interfaces Note This is silently ignored if not supported by guest additions affinity Proces
90. event occurred x X position of the event y Y position of the event defaultAction The default action to use allowedActions The actions which are allowed formats The supported MIME types format The resulting format of this event Informs the target about a drop event If this method fails the following error codes may be reported e VBOX_E_VM_ERROR VMM device is not available 5 21 3 enter DnDAction IDnDTarget enter in unsigned long screenld in unsigned long y in unsigned long x in DnDAction defaultAction in DnDAction allowedActions in wstring formats screenld The screen ID where the drag and drop event occurred y Y position of the event x X position of the event defaultAction The default action to use allowedActions The actions which are allowed formats The supported MIME types Informs the target about a drag and drop enter event If this method fails the following error codes may be reported e VBOX_E_VM_ERROR VMM device is not available 83 5 Classes interfaces 5 21 4 leave void IDnDTarget leave in unsigned long screenId screenld The screen ID where the drag and drop event occurred Informs the target about a drag and drop leave event If this method fails the following error codes may be reported e VBOX_E_VM_ERROR VMM device is not available 5 21 5 move DnDAction IDnDTarget move in unsigned long screenld in unsigned long x in u
91. fails the following error codes may be reported e E_ UNEXPECTED Virtual machine not registered e E_ACCESSDENIED Process not started by OpenRemoteSession e VBOX_E_INVALID_OBJECT_STATE Session already open or being opened e VBOX_E_VM_ERROR Failed to assign machine to session 5 80 49 mountMedium void IMachine mountMedi um in wstring name in long controllerPort in long device in IMedium medium in boolean force name Name of the storage controller to attach the medium to controllerPort Port to attach the medium to 199 5 Classes interfaces device Device slot in the given port to attach the medium to medium Medium to mount or null for an empty drive force Allows to force unmount mount of a medium which is locked by the device slot in the given port to attach the medium to Mounts a medium IMedium identified by the given UUID id to the given storage controller IStorageController identified by name at the indicated port and device The device must already exist see attachDevice for how to attach a new device This method is intended only for managing removable media where the device is fixed but media is changeable at runtime such as DVDs and floppies It cannot be used for fixed media such as hard disks The controllerPort and device parameters specify the device slot and have have the same meaning as with attachDevice The specified device slot can have a medium mounted w
92. findHostFloppyDrive in wstring name name Name of the host floppy drive to search for Searches for a host floppy drive with the given name If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any host floppy drive 5 69 6 findHostNetworkinterfaceByld IHostNetworkInterface IHost findHostNetworkInterfaceById in uuid id id GUID of the host network interface to search for Searches through all host network interfaces for an interface with the given GUID Note The method returns an error if the given GUID does not correspond to any host network interface 5 69 7 findHostNetworkinterfaceByName IHostNetworkInterface IHost findHostNetworkInterfaceByName in wstring name name Name of the host network interface to search for Searches through all host network interfaces for an interface with the given name Note The method returns an error if the given name does not correspond to any host network interface 144 5 Classes interfaces 5 69 8 findHostNetworkinterfacesOfType IHostNetworkInterface IHost findHostNetworkInterfacesOfType in HostNetworkInterfaceType type type type of the host network interfaces to search for Searches through all host network interfaces and returns a list of interfaces of the specified type 5 69 9 findUSBDeviceByAddress IHostUSBDevice IHost findUSBDeviceByAdd
93. force unmount of a medium which is locked by the device slot in the given port medium is attached to Unmounts any currently mounted medium IMedium identified by the given UUID id to the given storage controller IStorageController identified by name at the indicated port and device The device must already exist This method is intended only for managing removable media where the device is fixed but media is changeable at runtime such as DVDs and floppies It cannot be used for fixed media such as hard disks The controllerPort and device parameters specify the device slot and have have the same meaning as with attachDevice The specified device slot must have a medium mounted which will be unmounted If there is no mounted medium it will do nothing See IMedium for more detailed information about attaching unmounting media If this method fails the following error codes may be reported 212 5 Classes interfaces E_INVALIDARG SATA device SATA port IDE port or IDE slot out of range e VBOX_E_INVALID_OBJECT_STATE Attempt to unmount medium that is not removable not DVD or floppy e VBOX_E_INVALID_VM_STATE Invalid machine state e VBOX_E_OBJECT_IN_USE Medium already attached to this or another virtual machine e VBOX_E_OBJECT_NOT_FOUND Medium not attached to specified port device controller 5 80 83 unregister IMedium IMachine unregister in CleanupMode cleanupMode cleanupMode How to clean up af
94. guestIP The IP address of the guest which the NAT engine will forward matching packets to An empty IP address is acceptable in which case the NAT engine will forward packets to the first DHCP lease x x x 15 guestPort The port number to forward Adds a new NAT port forwarding rule 5 97 3 getNetworkSettings void INATEngine getNetworkSettings out unsigned long mtu out unsigned long sockSnd out unsigned long sockRcv out unsigned long TcpWndSnd out unsigned long TcpWndRcv mtu sockSnd sockRcv TcpWndSnd TcpWndRcv Returns network configuration of NAT engine See setNetworkSettings for parameter de scriptions 254 5 Classes interfaces 5 97 4 removeRedirect void INATEngine removeRedirect in wstring name name The name of the rule to delete Removes a port forwarding rule that was previously registered 5 97 5 setNetworkSettings void INATEngine setNetworkSettings in unsigned long mtu in unsigned long sockSnd in unsigned long sockRcv in unsigned long TcpWndSnd in unsigned long TcpWndRcv mtu MTU maximum transmission unit of the NAT engine in bytes sockSnd Capacity of the socket send buffer in bytes when creating a new socket sockRev Capacity of the socket receive buffer in bytes when creating a new socket TcpWndSnd Initial size of the NAT engine s sending TCP window in bytes when establishing a new TCP connection TcpWndRecv Initial size of the NAT engine
95. interface name and a method name joined together by an underscore This is because there are only functions operations in WSDL but no classes interfaces or methods In addition all calls to the VirtualBox web service except for logon see below take a managed object reference as the first argument representing the object upon which the underlying method is invoked Managed object references are explained in detail below see chapter 2 2 3 3 Managed object references page 34 So when one would normally code in the pseudo code of an object oriented language to invoke a method upon an object IMachine machine result machine getName In the VirtualBox web service this looks something like this again pseudo code IMachineRef machine result IMachine_getName machine 32 2 Environment specific notes 2 To make the web service stateful and objects persistent between method calls the VirtualBox web service introduces a session manager by way of the IWebsessionManager interface which manages object references Any client wishing to interact with the web service must first log on to the session manager and in turn receives a managed object ref erence to an object that supports the VirtualBox interface the basic interface in the Main API In other words as opposed to other web services the VirtualBox web service is both object oriented and stateful 2 2 3 2 Example A typical web service client s
96. is the same as IErrorInfo GetSource In XPCOM there is no equivalent 5 153 1 5 text read only wstring IVirtualBoxErrorInfo text Text description of the error Note In MS COM it is the same as IErrorInfo GetDescription In XPCOM it is the same as nsIException message 5 153 1 6 next read only IVirtualBoxErrorInfo IVirtualBoxErrorInfo next Next error object if there is any or null otherwise Note In MS COM there is no equivalent In XPCOM it is the same as nsIExcep tion inner 5 154 IVirtualSystemDescription Represents one virtual system machine in an appliance This interface is used in the TAppliance virtualSystemDescriptions array After IAppliance interpret has been called that array contains information about how the virtual systems described in the OVF should best be imported into VirtualBox virtual machines See IAppliance for the steps required to import an OVF into VirtualBox 327 5 Classes interfaces 5 154 1 Attributes 5 154 1 1 count read only unsigned long IVirtualSystemDescription count Return the number of virtual system description entries 5 154 2 addDescription void IVirtualSystemDescription addDescription in VirtualSystemDescriptionType type in wstring VBoxValue in wstring extraConfigValue type VBoxValue extraConfigValue This method adds an additional description entry to the stack of already available descrip
97. lock as opposed to lockRead is exclusive there may be only one client holding a write lock and there may be no read locks while the write lock is held As a result read locking fails if a write lock is held and write locking fails if either a read or another write lock is held When a medium is locked for writing it cannot be modified from within VirtualBox and it is not guaranteed that the values of its properties are up to date Any method that changes the properties of this medium or contents of the storage unit will return an error unless explicitly stated otherwise When a virtual machine is started up it locks for writing all media it uses to write data to If any medium could not be locked for writing the startup procedure will fail If a medium has differencing images then while the machine is running only the last leaf differencing image is locked for writing whereas its parents are locked for reading only A medium is also locked for writing when it is the target of a write operation such as cloneTo or mergeTo The medium locked for writing must be unlocked by abandoning the returned token object see IToken Write locks cannot be nested This method sets the medium state see state to LockedWrite on success The medium s previous state must be either Created or Inaccessible Locking an inaccessible medium is not an error this method performs a logical lock that prevents modifications of thi
98. machine are ignored to avoid a possible automatic re attachment See also IUSBDeviceFilters deviceFilters USBDeviceState If this method fails the following error codes may be reported e VBOX_E_PDM_ERROR Virtual machine does not have a USB controller e E_INVALIDARG USB device not attached to this virtual machine 5 13 8 findUSBDeviceByAddress IUSBDevice IConsole findUSBDeviceByAddress in wstring name name Address of the USB device as assigned by the host to search for Searches for a USB device with the given host address See also IUSBDevice address If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any USB device 5 13 9 findUSBDeviceByld IUSBDevice IConsole findUSBDeviceById in uuid id id UUID of the USB device to search for Searches for a USB device with the given UUID See also IUSBDevice id If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Given id does not correspond to any USB device 67 5 Classes interfaces 5 13 10 getDeviceActivity DeviceActivity IConsole getDeviceActivity in DeviceType type type Gets the current activity type of given devices or device groups If this method fails the following error codes may be reported e E_INVALIDARG Invalid device type 5 13 11 getGuestEnteredACPIMode boolean IConsole getGuestEnteredA
99. medium the state is Inaccessible as opposed to truly inaccessible media the value of lastAccessError will be an empty string in that case Note As of version 3 1 this no longer performs an accessibility check automatically call refreshState for that 5 87 1 4 variant read only MediumVariant IMedium variant Returns the storage format variant information for this medium as an array of the flags de scribed at MediumVariant Before refreshState is called this method returns an undefined value 5 87 1 5 location read only wstring IMedium location Location of the storage unit holding medium data The format of the location string is medium type specific For medium types using regular files in a host s file system the location string is the full file name 5 87 1 6 name read only wstring IMedium name Name of the storage unit holding medium data The returned string is a short version of the location attribute that is suitable for represent ing the medium in situations where the full location specification is too long such as lists and comboboxes in GUI frontends This string is also used by frontends to sort the media list alpha betically when needed For example for locations that are regular files in the host s file system the value of this attribute is just the file name extension without the path specification Note that as opposed to the location attribute the name attribute
100. medium attached to it has more than one child medium differencing images because otherwise merging would be impossible This might be the case if there is more than one child snapshot or differencing images were created for other reason e g implicitly because of multiple machine attachments The virtual machine s state is changed to DeletingSnapshot DeletingSnapshotOnline or DeletingSnapshotPaused while this operation is in progress Note Merging medium contents can be very time and disk space consuming if these media are big in size and have many children However if the snapshot being deleted is the last head snapshot on the branch the operation will be rather quick If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE The running virtual machine prevents deleting this snap shot This happens only in very specific situations usually snapshots can be deleted with out trouble while a VM is running The error message text explains the reason for the failure 5 80 15 deleteSnapshotAndaAllChildren IProgress IMachine deleteSnapshotAndALlChildren in uuid id id UUID of the snapshot to delete including all its children Starts deleting the specified snapshot and all its children asynchronously See Snapshot for an introduction to snapshots The conditions and many details are the same as with deleteSnapshot This operation is very fast if the snapsho
101. not yet implemented and is currently silently ignored We will document the protocolVersion number for this feature once it appears so don t use it till then UnquotedArguments Work around for Windows and OS 2 applications not following normal argument quoting and escaping rules The arguments are passed to the application without any extra quoting just a single space between each Note Present since VirtualBox 4 3 28 and 5 0 beta 3 6 79 ProcessinputFlag Guest process input flags None No flag set EndOfFile End of file input reached 6 80 ProcessinputStatus Process input statuses Undefined Undefined state Broken Input pipe is broken Available Input pipe became available for writing Written Data has been successfully written Overflow Too much input data supplied data overflow 6 81 ProcessOutputFlag Guest process output flags for specifying which type of output to retrieve None No flags set Get output from stdout StdErr Get output from stderr 360 6 Enumerations enums 6 82 ProcessPriority Process priorities Invalid Invalid priority do not use Default Default process priority determined by the OS 6 83 ProcessStatus Process execution statuses Undefined Process is in an undefined state Starting Process is being started Started Process has been started Paused Process has been paused Terminating Process is being terminated TerminatedNormally Process t
102. o 3 Basic VirtualBox concepts some examples 3 1 Obtaining basic machine information Reading attributes 3 2 Changing machine settings Sessions lt o s oc o o o 3 3 Launching virtual machines DA VirtualBox events o A Ee OA we AEP Se h 4 The VirtualBox shell 5 Classes interfaces BA lAdditonsFaciliiy aaa a A eee Be SLI Anributes escas ee EER SAS a a Ree 5 2 IAdditionsStateChangedEvent IEvent o S21 AWDUES oe a ig aee betes idasa dade e aang Boo e see say o a a ww we EE Ew eo ee ee ae a A Sal ANIME ios be be oe RS ee he ee ee wD S34 addPasswordi e le Giese Sod eek ae wh BE ee e 5 3 3 create VPSExplorer o srs ce Gao be EEE Eee RS 5 3 4 getMediumIdsForPasswordId o oo 022 eee 53 6 getPasswordids o ocurridas Oe ee ee a S36 PeNNamings lt a Ra ee we A 537 importMachines de ir RR ee e e 5 4 dd 5 6 5 7 5 8 S Contents SoG EPEE oos e es ae ww a we ae Soh RE agra E 56 S30 ME 2624 45 SS See As ete eae 56 TAIG WE ss ee we we a ee ok ee ee ete le ww 56 IAudioAdapter 2 2444 5 4 4 2820044444400 088844444440 57 Sl ADES ake Sala de se Hoe O 57 Done SePropen vooo ee ber go EE ie eerie eae ee er 58 See SOPOR cue ele ee es ee we ew ew ee ewe h E E R a E ENE S 58 IBIOSSELIMES lt lt kk ke ERS REDE OEE CARA Re ET oe SRS 58 A AUTES ce gs a as oe ee A me ea eae awa oe 58 IBandwidthControl coros eee eS ee eee ee ea
103. o oo 13 4 Incompatible API changes with version 4 1 o o 13 5 Incompatible API changes with version 4 0 o o 13 6 Incompatible API changes with version 3 2 o ooo 13 7 Incompatible API changes with version 3 1 o 13 8 Incompatible API changes with version 3 0 o ooo 19 378 379 379 379 379 380 380 380 380 380 381 381 381 Contents 13 9 Incompatible API changes with version 2 2 13 10 Incompatible API changes with version 2 1 20 1 Introduction VirtualBox comes with comprehensive support for third party developers This Software Devel opment Kit SDK contains all the documentation and interface files that are needed to write code that interacts with VirtualBox 1 1 Modularity the building blocks of VirtualBox VirtualBox is cleanly separated into several layers which can be visualized like in the picture below VirtualBox Main API Linux i Resource dd i Solaris _ Monitor Server Virtual Devices binary ideals y E IR ompatible qe VirtualBox hypervisor interface cross platform bapan ar abstraction layer Windows Linux OS X Solaris FreeBSD por Windows Kernel mode The orange area represents code that runs in kernel mode the blue area represents userspace code At the bottom of the stack resides the hypervisor the core of the virtualization engine con trolling exec
104. of the user running the web service daemon Unless vboxwebsrv runs as root PAM authenti cation can fail because sometimes the file etc shadow which is used by PAM is not read able On most Linux distribution PAM uses a suid root helper internally so make sure you test this before deploying it One can override this behavior by setting the environment variable VBOX_PAM_ALLOW_INACTIVE which will suppress failures when unable to read the shadow pass word file Please use this variable carefully and only if you fully understand what you re doing 26 2 Environment specific notes The Main API described in chapter 5 Classes interfaces page 52 and chapter 6 Enumerations enums page 333 is mostly identical in all the supported programming environments which have been briefly mentioned in the introduction of this book As a result the Main API s general concepts described in chapter 3 Basic VirtualBox concepts some examples page 47 are the same whether you use the object oriented web service OOWS for JAX WS or a raw web service connection via say Perl or whether you use C COM bindings Some things are different depending on your environment however These differences are explained in this chapter 2 1 Using the object oriented web service DOWS As explained in chapter 1 2 Two guises of the same Main API the web service or COM XPCOM page 22 VirtualBox ships with client side libraries for Java Python and PHP that al
105. offset y Framebuffer y offset width Viewport width height Viewport height Signals that framebuffer window viewport has changed If this method fails the following error codes may be reported e E_INVALIDARG The specified viewport data is invalid 79 5 Classes interfaces 5 17 IDisplaySourceBitmap Note This interface is not supported in the web service 5 17 1 Attributes 5 17 1 1 screenld read only unsigned long IDisplaySourceBitmap screenId 5 17 2 queryBitmaplInfo Note This method is not supported in the web service void IDisplaySourceBitmap queryBitmapInfo out ptr octet address out unsigned long width out unsigned long height out unsigned long bitsPerPixel out unsigned long bytesPerLine out BitmapFormat bitmapFormat address width height bitsPerPixel bytesPerLine bitmapFormat Information about the screen bitmap 5 18 IDnDBase Base abstract interface for drag n drop 5 18 1 Attributes 5 18 1 1 formats read only wstring IDnDBase formats Returns all supported drag n drop formats 5 18 1 2 protocolVersion read only unsigned long IDnDBase protocolVersion Returns the protocol version which is used to communicate with the guest 80 5 Classes interfaces 5 18 2 addFormats void IDnDBase addFormats in wstring formats formats Collection of formats to add Adds MIME Content type formats to the supported f
106. path path The host path of the capture device to detach Detaches the emulated USB webcam from the VM 5 23 lEvent Abstract parent interface for VirtualBox events Actual events will typically implement a more specific interface which derives from this see below Introduction to VirtualBox events Generally speaking an event represented by this interface signals that something happened while an event listener see IEventListener represents an entity that is interested in certain events In order for this to work with unidirectional protocols i e web services the concepts of passive and active listener are used Event consumers can register themselves as listeners providing an array of events they are in terested in see IEventSource registerListener When an event triggers the listener is notified about the event The exact mechanism of the notification depends on whether the listener was registered as an active or passive listener e An active listener is very similar to a callback it is a function invoked by the API As opposed to the callbacks that were used in the API before VirtualBox 4 0 however events are now objects with an interface hierarchy e Passive listeners are somewhat trickier to implement but do not require a client func tion to be callable which is not an option with scripting languages or web service clients Internally the IEventSource implementation maintains an event queue for each passive liste
107. pfnSafeArrayOutParamALloc ULONG pData ULONG cElements IArrayDemo_ReturnArray pThis ComSafeArrayAsOutTypeParam psa ULONG g_pVBoxFuncs gt pfnSafeArrayCopyOutParamHelper void amp pData amp cElements VT_I4 psa g_pVBoxFuncs gt pfnSafeArrayDestroy psa This covers the necessary functionality for all array element types except interface references These need special helpers to manage the reference counting correctly The following code snippet gets the list of VMs and passes the first IMachine reference to another API function assuming that there is at least one element in the array to simplify the example SAFEARRAY psa g_pVBoxFuncs gt pfnSafeArray0utParamAlloc IMachine machines NULL ULONG machineCnt 0 ULONG i IVirtualBox_get_Machines virtualBox ComSafeArrayAsOutIfaceParam machinesSA IMachine g_pVBoxFuncs gt pfnSafeArrayCopyOutI faceParamHelper IUnknown amp machines GmachineCnt machinesSA g_pVBoxFuncs gt pfnSafeArrayDestroy machinesSA Now machines contains the IMachine references and machineCnt the number of elements in the array SAFEARRAY psa g_pVBoxFuncs gt pfnSafeArrayCreateVector VT_IUNKNOWN 0 1 g_pVBoxFuncs gt pfnSafeArrayCopyInParamHelper psa void amp machines 0 sizeof machines 0 IVirtualBox_GetMachineStates ComSafeArrayAsInParam psa g_pVBoxFuncs gt pfnSafeArrayDestroy psa for i 0 i lt machineCnt i IMachi
108. platform When setting this attribute a full path must be specified Setting this property to null or an empty string or the special value Machines for compatibility reasons will restore that default value If the folder specified herein does not exist it will be created automatically as needed See also IVirtualBox createMachine IVirtualBox openMachine 5 135 1 15 loggingLevel read write wstring ISystemProperties LoggingLevel Specifies the logging level in current use by VirtualBox 5 135 1 16 mediumFormats read only IMediumFormat ISystemProperties mediumFormats List of all medium storage formats supported by this VirtualBox installation Keep in mind that the medium format identifier MediumFormat id used in other API calls like IVirtualBox createMedium to refer to a particular medium format is a case insensitive string This means that for example all of the following strings VDI ydi Val refer to the same medium format Note that the virtual medium framework is backend based therefore the list of supported formats depends on what backends are currently installed See also IMediumFormat 294 5 Classes interfaces 5 135 1 17 defaultHardDiskFormat read write wstring ISystemProperties defaultHardDiskFormat Identifier of the default medium format used by VirtualBox The medium format set by this attribute is used by VirtualBox when the medium format was not specified e
109. py w 20n On Mac OS X only the Python versions bundled with the OS are officially supported This means Python 2 3 for 10 4 Python 2 5 for 10 5 and Python 2 5 and 2 6 for 10 6 3See http sourceforge net project showfiles php group_id 78018 29 2 Environment specific notes See chapter 4 The VirtualBox shell page 50 for more details on the shell s functionality For you as a VirtualBox application developer the vboxshell sample could be interesting as an exam ple of how to write code targeting both local and remote cases COM XPCOM and SOAP The common part of the shell is the same the only difference is how it interacts with the invocation layer You can use the connect shell command to connect to remote VirtualBox servers in this case you can skip starting the local web server 2 1 3 The object oriented web service for PHP VirtualBox also comes with object oriented web service OOWS wrappers for PHP5 These wrappers rely on the PHP SOAP Extension which can be installed by configuring PHP with enable soap 2 2 Using the raw web service with any language The following examples show you how to use the raw web service without the object oriented client side code that was described in the previous chapter Generally when reading the documentation in chapter 5 Classes interfaces page 52 and chapter 6 Enumerations enums page 333 due to the limitations of SOAP and WSDL lined out in chapter 2 2 3 1 Fundamental
110. registered or on unregistered machines after calling unregister 204 5 Classes interfaces If this method fails the following error codes may be reported e VBOX_E_FILE_ERROR Settings file not accessible e VBOX_E_XML_ERROR Could not parse the settings file e E_ACCESSDENIED Modification request refused 5 80 65 saveState IProgress IMachine saveState Saves the current execution state of a running virtual machine and stops its execution After this operation completes the machine will go to the Saved state Next time it is powered up this state will be restored and the machine will continue its execution from the place where it was saved This operation differs from taking a snapshot to the effect that it doesn t create new differenc ing media Also once the machine is powered up from the state saved using this method the saved state is deleted so it will be impossible to return to this state later Note On success this method implicitly calls saveSettings to save all current ma chine settings including runtime changes to the DVD medium etc Together with the impossibility to change any VM settings when it is in the Saved state this guar antees adequate hardware configuration of the machine when it is restored from the saved state file Note The machine must be in the Running or Paused state otherwise the operation will fail See also takeSnapshot If this meth
111. request when here enabled as well it will be forwarded to the other progress object If there is an error in the other progress this error isn t automatically transfered to this progress object So you have to check any operation error within the other progress object after this method returns 277 5 Classes interfaces 5 115 6 waitForCompletion void IProgress waitForCompletion in long timeout timeout Maximum time in milliseconds to wait or 1 to wait indefinitely Waits until the task is done including all sub operations with a given timeout in milliseconds specify 1 for an indefinite wait Note that the VirtualBox XPCOM COM native event queues of the calling thread are not pro cessed while waiting Neglecting event queues may have dire consequences degrade perfor mance resource hogs deadlocks etc this is specially so for the main thread on platforms using XPCOM Callers are advised wait for short periods and service their event queues between calls or to create a worker thread to do the waiting If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Failed to wait for task completion 5 115 7 waitForOperationCompletion void IProgress waitForOperationCompletion in unsigned long operation in long timeout operation Number of the operation to wait for Must be less than operationCount timeout Maximum time in milliseconds to wait or 1 to wait indefinitely
112. return values in order to get floating point values For example double returnData returnDataIndices 0 i returnScales 0 will retrieve the floating point value of i th sample of the first met ric returnSequenceNumbers Sequence numbers of the first elements of value sequences of par ticular metrics returned in returnData For aggregate metrics it is the sequence number of the sample the aggregate started calculation from returnDatalndices Indices of the first elements of value sequences of particular metrics re turned in returnData returnDataLengths Lengths of value sequences of particular metrics Queries collected metrics data for a set of objects The data itself and related metric information are returned in seven parallel and one flat tened array of arrays Elements of returnMetricNames returnObjects returnUnits returnScales returnSequenceNumbers returnDataIndices and returnDataLengths with the same index describe one set of values corresponding to a single metric The returnData parameter is a flattened array of arrays Each start and length of a sub array is indicated by returnDataIndices and returnDataLengths The first value for metric metricNames i is at returnData returnIndices i Note Null or empty metric name array means all metrics Null or empty object array means all existing objects If metric name array contains a single element and object array contains many the single metric name array element i
113. t changed verbose or v Normally the web service outputs only brief messages to the console each time a request is served With this option the web service prints much more de tailed data about every request and the COM methods that those requests are mapped to internally which can be useful for debugging client programs pidfile or P Name of the PID file which is created when the daemon was started logfile or F lt file gt If this is specified the web service not only prints its output to the console but also writes it to the specified file The file is created if it does not exist if it does exist new output is appended to it This is useful if you run the web service unattended and need to debug problems after they have occurred logrotate or R Number of old log files to keep defaults to 10 Log rotation is disabled if set to 0 logsize or S Maximum size of log file in bytes defaults to 100MB Log rotation is triggered if the file grows beyond this limit loginterval or 1 Maximum time interval to be put in a log file before rotation is triggered in seconds and defaults to one day 1 4 2 Authenticating at web service logon As opposed to the COM XPCOM variant of the Main API a client that wants to use the web service must first log on by calling the IWebsessionManager logon API that is specific to the web service Logon is necessary for the web service to be stateful internally it m
114. the OVF file without a path since the image file should be in the same location as the OVF file itself whereas the item in aVBoxValues will contain a qualified path specification to where VirtualBox uses the hard disk image This means that on import the image will be copied and converted from the ovf location to the vbox location on export this will be handled the other way round The matching item in the aExtraConfigValues array must contain a string of the fol lowing format controller lt index gt channel lt c gt In this string lt index gt must be an integer specifying the hard disk controller to connect the image to That number must be the index of an array item with one of the hard disk controller types HardDiskController SCSI HardDiskControllerSATA HardDiskControllerIDE In addition lt c gt must specify 329 5 Classes interfaces the channel to use on that controller For IDE controllers this can be O or 1 for master or slave respectively For compatibility with VirtualBox versions before 3 2 the values 2 and 3 for secondary master and secondary slave are also supported but no longer exported For SATA and SCSI controllers the channel can range from 0 29 CDROM a virtual CD ROM drive The matching item in aExt raConfigValue contains the same attachment information as with HardDiskImage items CDROM a virtual floppy drive The matching item in aExtraConfigValue cont
115. the following were removed x the supportsSeamless attribute x the supportsGraphics attribute The function IGuest getFacilityStatusQ was added It quickly provides a facility s status without the need to get the facility collection with IGuest facilities The attribute IGuest facilities was added to provide an easy to access collection of all currently known guest facilities that is it contains all facilies where at least one status update was made since the guest was started The interface AdditionsFacility was added to represent a single facility returned by IGuest facilities AdditionsFacilityStatus was added to represent a facility s overall status AdditionsFacilityType and AdditionsFacilityClass were added to represent the facility s type and class 13 5 Incompatible API changes with version 4 0 e A new Java glue layer replacing the previous OOWS JAX WS bindings was intro duced The new library allows for uniform code targeting both local COM XPCOM and remote SOAP transports Now instead of IWebsessionManager the new class VirtualBoxManager must be used See chapter 11 Using Java API page 385 for details e The confusingly named and impractical session APIs were changed In existing client code the following changes need to be made Replace any IVirtualBox openSession uuidMachine API call with the machine s IMachine lockMachine call and a LockType Write argument The func tionality is unchange
116. the guest operating system 5 80 1 37 keyboardHIDType read write KeyboardHIDType IMachine keyboardHIDType Type of keyboard HID used in this VM The default is typically PS2Keyboard but can vary depending on the requirements of the guest operating system 5 80 1 38 HPETEnabled read write boolean IMachine HPETEnabled This attribute controls if High Precision Event Timer HPET is enabled in this VM Use this property if you want to provide guests with additional time source or if guest requires HPET to function correctly Default is false 5 80 1 39 chipsetType read write ChipsetType IMachine chipsetType Chipset type used in this VM 5 80 1 40 snapshotFolder read write wstring IMachine snapshotFolder Full path to the directory used to store snapshot data differencing media and saved state files of this machine The initial value of this property is lt path_to_ settings file gt lt machine_uuid gt Currently it is an error to try to change this property on a machine that has snapshots because this would require to move possibly large files to a different location A separate method will be available for this purpose later Note Setting this property to null or to an empty string will restore the initial value Note When setting this property the specified path can be absolute full path or relative to the directory where the machine settings file is located When reading this
117. the machine state After having called this method you can obtain this second mutable machine object using the ISession machine attribute If you only want to check the machine state or control machine execution without actually changing machine settings e g to get access to VM statistics or take a snapshot or save the machine state then set the LockType argument to Shared If no other session has obtained a lock you will obtain an exclusive write lock as described above However if another session has already obtained such a lock then a link to that existing session will be established which allows you to control that existing session To find out which type of lock was obtained you can inspect ISession type which will have been set to either WriteLock or Shared In either case you can get access to the IConsole object which controls VM execution Also in all of the above cases one must always call ISession unlockMachine to release the lock on the machine or the machine s state will eventually be set to Aborted To change settings on a machine the following sequence is typically performed 1 2 3 4 5 Call this method to obtain an exclusive write lock for the current session Obtain a mutable IMachine object from ISession machine Change the settings of the machine by invoking IMachine methods Call saveSettings 0 Release the write lock by calling ISession unlockMachine If this method
118. the raw web service you need to keep a number of things in mind or you will sooner or later run into issues that are not immediately obvious By contrast the object oriented client side libraries described in chapter 2 1 Using the object oriented web service OOWS page 27 take care of these things automatically and thus greatly simplify using the web service 2 2 3 1 Fundamental conventions If you are familiar with other web services you may find the VirtualBox web service to behave a bit differently to accommodate for the fact that VirtualBox web service more or less maps the VirtualBox Main COM API The following main differences had to be taken care of e Web services as expressed by WSDL are not object oriented Even worse they are nor mally stateless or in web services terminology loosely coupled Web service operations are entirely procedural and one cannot normally make assumptions about the state of a web service between function calls In particular this normally means that you cannot work on objects in one method call that were created by another call e By contrast the VirtualBox Main API being expressed in COM is object oriented and works entirely on objects which are grouped into public interfaces which in turn have attributes and methods associated with them For the VirtualBox web service this results in three fundamental conventions 1 All function names in the VirtualBox web service consist of an
119. type Type of the group 5 7 1 3 reference read only unsigned long IBandwidthGroup reference How many devices medium attachments use this group 5 7 1 4 maxBytesPerSec read write long long IBandwidthGroup maxBytesPerSec The maximum number of bytes which can be transfered by all entities attached to this group during one second 5 8 IBandwidthGroupChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when one of the bandwidth groups changed 5 8 1 Attributes 5 8 1 1 bandwidthGroup read only IBandwidthGroup IBandwidthGroupChangedEvent bandwidthGroup The changed bandwidth group 5 9 ICPUChangedE vent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well Notification when a CPU changes 5 9 1 Attributes 5 9 1 1 CPU read only unsigned long ICPUChangedEvent CPU The CPU which changed 5 9 1 2 add read only boolean ICPUChangedEvent add Flag whether the CPU was added or removed 61 5 Classes interfaces 5 10 ICPUExecutionCapChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when the CPU execution cap changes 5 10 1 Attributes 5 10 1 1 executionCap read only unsigned long ICPUExecutionCapChangedEvent executionCap
120. use the glue layer This code assumes vboxapi py from VirtualBox distribution being in PYTHONPATH or installed system wide from vboxapi import VirtualBoxManager This code initializes VirtualBox manager with default style and parameters virtualBoxManager VirtualBoxManager None None Alternatively one can be more verbose and initialize glue with web service backend and provide authentication information virtualBoxManager VirtualBoxManager WEBSERVICE url http myhost com 18083 user me password secret We supply the VirtualBoxManager constructor with 2 arguments style and parameters Style defines which bindings style to use could be MSCOM XPCOM or WEBSERVICE and if set to None defaults to usable platform bindings MS COM on Windows XPCOM on other platforms The second argument defines parameters passed to the platform specific module as we do in the second example where we pass username and password to be used to authenticate against the web service After obtaining the VirtualBoxManager instance one can perform operations on the IVirtu alBox class For example the following code will a start virtual machine by name or ID from vboxapi import VirtualBoxManager mgr VirtualBoxManager None None vbox mgr vbox name Linux mach vbox findMachine name session mgr getSession0bject vbox progress mach launchVMProcess session g
121. which takes a string name as an argument and returns Hello with a space and that name appended the request message could look like this lt xml version 1 0 encoding UTF 8 gt lt SOAP ENV Envelope xmlns SOAP ENV http schemas xmlsoap org soap envelope 34 2 Environment specific notes xmlns SOAP ENC http schemas xmlsoap org soap encoding xmlns xsi http ww w3 org 2001 XMLSchema instance xmlns xsd http ww w3 org 2001 XMLSchema xmlns test http test gt lt SOAP ENV Body gt lt test SayHello gt lt name gt Peter lt name gt lt test SayHello gt lt SOAP ENV Body gt lt SOAP ENV Envelope gt A similar message the response message would be sent back from the web service to the client containing the return value Hello Peter Most programming languages provide automatic support to generate such messages whenever code in that programming language makes such a request In other words these programming languages allow for writing something like this in pseudo C code webServiceClass service localhost 18083 server and port string result service SayHello Peter invoke remote procedure and would for these two pseudo lines automatically perform these steps 1 prepare a connection to a web service running on port 18083 of localhost 2 for the SayHello function of the web service generate a SOAP message like in the above example by en
122. will not necessary be unique for a list of media of the given type and format 5 87 1 7 deviceType read only DeviceType IMedium deviceType Kind of device DVD Floppy HardDisk which is applicable to this medium 226 5 Classes interfaces 5 87 1 8 hostDrive read only boolean IMedium hostDrive True if this corresponds to a drive on the host 5 87 1 9 size read only long long IMedium size Physical size of the storage unit used to hold medium data in bytes Note For media whose state is Inaccessible the value of this property is the last known size For NotCreated media the returned value is zero 5 87 1 10 format read only wstring IMedium format Storage format of this medium The value of this attribute is a string that specifies a backend used to store medium data The storage format is defined when you create a new medium or automatically detected when you open an existing medium and cannot be changed later The list of all storage formats supported by this VirtualBox installation can be obtained using ISystemProperties mediumFormats 5 87 1 11 mediumFormat read only IMediumFormat IMedium mediumFormat Storage medium format object corresponding to this medium The value of this attribute is a reference to the medium format object that specifies the backend properties used to store medium data The storage format is defined when you create a new medium or automatically detect
123. wstring networkName networkName 5 151 9 createSharedFolder void IVirtualBox createSharedFolder in wstring name in wstring hostPath in boolean writable in boolean automount name Unique logical name of the shared folder hostPath Full path to the shared folder in the host file system writable Whether the share is writable or readonly automount Whether the share gets automatically mounted by the guest or not Creates a new global shared folder by associating the given logical name with the given host path adds it to the collection of shared folders and starts sharing it Refer to the description of ISharedFolder to read more about logical names Note In the current implementation this operation is not implemented 5 151 10 findDHCPServerByNetworkName IDHCPServer IVirtualBox findDHCPServerByNetworkName in wstring name name server name Searches a DHCP server settings to be used for the given internal network name If this method fails the following error codes may be reported e E_INVALIDARG Host network interface name already exists 320 5 Classes interfaces 5 151 11 findMachine IMachine IVirtualBox findMachine in wstring nameOrId nameOrld What to search for This can either be the UUID or the name of a virtual machine Attempts to find a virtual machine given its name or UUID Note Inaccessible machines cannot be found by name only by UUID because their
124. 0 1 58 snapshotCount read only unsigned long IMachine snapshotCount Number of snapshots taken on this machine Zero means the machine doesn t have any snap shots 5 80 1 59 currentStateModified read only boolean IMachine currentStateModified Returns true if the current state of the machine is not identical to the state stored in the current snapshot The current state is identical to the current snapshot only directly after one of the following calls are made e restoreSnapshot e takeSnapshot issued on a powered off or saved machine for which settingsModified returns false The current state remains identical until one of the following happens e settings of the machine are changed e the saved state is deleted e the current snapshot is deleted an attempt to execute the machine is made Note For machines that don t have snapshots this property is always false 176 5 Classes interfaces 5 80 1 60 sharedFolders read only ISharedFolder IMachine sharedFolders Collection of shared folders for this machine permanent shared folders These folders are shared automatically at machine startup and available only to the guest OS installed within this machine New shared folders are added to the collection using createSharedFolder Existing shared folders can be removed using removeSharedFolder 5 80 1 61 clipboardMode read write ClipboardMode IMachine clipboardMode
125. 32 Beye COMPA oi eon ee ae a 232 5 87 8 resteBaseStorage co ooo e cereau a EE a eS 232 5370 CERCDISIOLASE cose ER BE eee el a es 233 5 87 10 deleteStorage lt coica cacare taaa e A a a i 233 53 87 11 peine phonSetingS 2 o A ee E 234 507 12 CORP POPEMIGS a A o a A 234 JT Lo POL PFOBETES o o SoS BE RO we wk A E a 234 5 87 14 getSnapshotids lt o c cio ece eee a e eS 235 Bie der PER ai e EE a aE le Re E a we A 235 Soa ME WOR rs ak ade ee bE a we ee ee ee a 235 35 87 17 Meee a eee he a AOE OL een dasa a 236 5 87 18 refreshStat 2 ee ee ease ce eae i ES aaa a ae 237 ERTO PESEE cria See eee SESS aa Pas a eee a aw Bais 237 Beye CORRES o Moh wae aw a Yo we A eee ee a ee S 238 5 87 21 setlds 2 444 24844404 48 eR dee kaa Eee eee eee kad 238 5 87 22 SECLOCAUOM o o le een ee aod eR ad RR a 238 507 20 SECPLOPOIOSS oc be Gs bee bee eee EERE EE ES 239 Braa BECP POPE sees ek ele as EHR wl Re eR ec oe ee es 239 IMediumAttachment lt o s god ee ee ag Pe eee el als Sa ae 240 GOA e seeen O De ws a 242 IMediumChangedEvent IEvent 6 6 ee eee 243 5 99 1 Ateributes 222 020 e444 AAA aa a 243 IMediumConfigChangedEvent IEvent oo oo 0000 244 5 90 1 Attributes 324 0422 Beda a aaa a a RAR 244 DVIS A E 244 5 91 1 Attributes ccssar 2284444488040 daa aaa 244 5 91 2 describeFileExtensions lt o o 0 245 SOL describeProperlles s oe sn noe a 245 IMediumRegisteredEvent IEvent o 24
126. 5 S02 Arbus ce eed beeen booed Od BOOS RE ERE PS Re RS 246 MISO 2 e eee ew hee eg oe le we eS ated a Bde ee 246 12 Contents BOG ADES oc a a ae a I we we a SOR RI ee ee 246 5 93 2 putEventMultiTouch 2 662 044 455 224084 baer raaas 247 5 93 3 putEventMultiTouchString o 2 2222 eee 248 5 93 4 putiMouseEyent ss sc cestri anartre a rer ass 248 5 92 5 putMouseEventAbsolute o o o ccc we we a a a ee 249 5 94 IMouseCapabilityChangedEvent IEvent sasaaa 249 S94 RUE Lere ke eke esra ddae es al ee a 249 5 95 IMousePointerShape gt 2 6 20 ec eee eee He ewe ee EE Oe ERS 250 595 1 Attributes so csoda ak k eR Re sa 250 5 96 IMousePointerShapeChangedEvent IEvent o o o 251 5 96 1 Attributes 222 4 0 88 8 444448 a a a a a 251 597 INATE EME sas oe de we ee is he OO A e eS 252 5 97 1 Attributes 840522 2 444 44444844 e 0 44448485 252 597 2 a a sos eA a ww daa O 254 5 97 3 setNerworkGettmgs oc 254 5 97 4 removeRedirect ss ci a Re ee a 255 5 97 95 SetNetworkSentings ocres rd beeen ee ee ee ean 255 5 98 INATNetwotk oo oca ek eee we Re E ee ew ee 255 SOSI AID WIAS pn ee Sg ee a a OO ee ee a eae 255 538 2 addLocalMappi g occ ss we ae A e e 257 5 98 3 addPortPorwardRule 2 066 ee es 257 5 98 4 removePortForwardRule o 257 AO MEMO 252 a de a a we lee ae eG ee ee 257 So SOP ncaa a ae ee AA 257 5 99 INATNetworkAlterEvent INATNetworkChangedEvent 25
127. 5 137 1 1 name read write wstring IUSBController name The USB Controller name 5 137 1 2 type read write USBControllerType IUSBController type The USB Controller type 5 137 1 3 USBStandard read only unsigned short IUSBController USBStandard USB standard version which the controller implements This is a BCD which means that the major version is in the high byte and minor version is in the low byte 5 138 USBControllerChangedEvent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well Notification when a property of the virtual USB controllers changes Interested callees should use IUSBController methods and attributes to find out what has changed 5 138 1 Attributes 5 138 1 1 midlDoesNotLikeEmptyInterfaces read only boolean IUSBControllerChangedEvent midlDoesNotLikeEmptyInterfaces 5 139 IUSBDevice The IUSBDevice interface represents a virtual USB device attached to the virtual machine A collection of objects implementing this interface is stored in the IConsole USBDevices attribute which lists all USB devices attached to a running virtual machine s USB controller 5 139 1 Attributes 5 139 1 1 id read only uuid IUSBDevice id Unique USB device ID This ID is built from vendorld productld revision and serial Number 300 5 Classes interfaces 5 139 1 2 vendorld read only unsigned short IUSBDevice vendorId Vendor I
128. 5 145 3 setVRDEProperty void IVRDEServer setVRDEProperty in wstring key in wstring value key Name of the key to set value Value to assign to the key Sets a VRDE specific property string If you pass null or empty string as a key value the given key will be deleted 5 146 IVRDEServerChangedE vent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well Notification when a property of the VRDE server changes Interested callees should use IVRDE Server methods and attributes to find out what has changed 309 5 Classes interfaces 5 146 1 Attributes 5 146 1 1 midlDoesNotLikeEmptyInterfaces read only boolean IVRDEServerChangedEvent midlDoesNotLikeEmptyInterfaces 5 147 IVRDEServerinfo Note With the web service this interface is mapped to a structure Attributes that return this interface will not return an object but a complete structure containing the attributes listed below as structure members Contains information about the remote desktop VRDE server capabilities and status This is used in the IConsole VRDEServerlnfo attribute 5 147 1 Attributes 5 147 1 1 active read only boolean IVRDEServerInfo active Whether the remote desktop connection is active 5 147 1 2 port read only long IVRDEServerInfo port VRDE server port number If this property is equal to 0 then the VRDE server failed to start usual
129. 5 48 1 1 status read only FileStatus IGuestFileStateChangedEvent status New guest file status 113 5 Classes interfaces 5 48 1 2 error read only IVirtualBoxErrorInfo IGuestFileStateChangedEvent error Error information in case of new session status is indicating an error The attribute IVirtualBoxErrorInfo resultDetail will contain the runtime IPRT error code from the guest See include iprt err h and include VBox err h for details 5 49 IGuestFileWriteEvent IGuestFilelOEvent Note This interface extends IGuestFilelOEvent and therefore supports all its methods and attributes as well Notification when data has been written to a guest file 5 49 1 Attributes 5 49 1 1 midlDoesNotLikeEmptyInterfaces read only boolean IGuestFileWriteEvent midlDoesNotLikeEmptyInterfaces 5 50 IGuestFsObjlnfo IFsObjlnfo Note This interface extends IFsObjInfo and therefore supports all its methods and attributes as well Represents the guest implementation of the IFsObjInfo object 5 50 1 Attributes 5 50 1 1 midlDoesNotLikeEmptyInterfaces read only boolean IGuestFsObjInfo midlDoesNotLikeEmptyInterfaces 5 51 lIGuestKeyboardEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when guest keyboard event happens 5 51 1 Attributes 5 51 1 1 scancodes read only long IGuestKeyboardEvent scancodes
130. 6 IBandwidthControl Controls the bandwidth groups of one machine used to cap I O done by a VM This includes network and disk I O 59 5 Classes interfaces 5 6 1 Attributes 5 6 1 1 numGroups read only unsigned long IBandwidthControl numGroups The current number of existing bandwidth groups managed 5 6 2 createBandwidthGroup void IBandwidthControl createBandwidthGroup in wstring name in BandwidthGroupType type in long long maxBytesPerSec name Name of the bandwidth group type The type of the bandwidth group network or disk maxBytesPerSec The maximum number of bytes which can be transfered by all entities at tached to this group during one second Creates a new bandwidth group 5 6 3 deleteBandwidthGroup void IBandwidthControl deleteBandwidthGroup in wstring name name Name of the bandwidth group to delete Deletes a new bandwidth group 5 6 4 getAllBandwidthGroups IBandwidthGroup IBandwidthControl getAllBandwidthGroups Get all managed bandwidth groups 5 6 5 getBandwidthGroup IBandwidthGroup IBandwidthControl getBandwidthGroup in wstring name name Name of the bandwidth group to get Get a bandwidth group by name 5 7 IBandwidthGroup Represents one bandwidth group 5 7 1 Attributes 5 7 1 1 name read only wstring IBandwidthGroup name Name of the group 60 5 Classes interfaces 5 7 1 2 type read only BandwidthGroupType IBandwidthGroup
131. 64 8 directoryExists boolean IGuestSession directoryExists in wstring path in boolean followSymlinks path Path to the directory to check if exists Guest path style followSymlinks If true symbolic links in the final component will be followed and the ex istance of the symlink target made the question for this method If false a symbolic link in the final component will make the method return false because a symlink isn t a directory Checks whether a directory exists in the guest or not If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Error while checking existence of the directory specified 5 64 9 directoryOpen IGuestDirectory IGuestSession directory0Open in wstring path in wstring filter in DirectoryOpenFlag flags path Path to the directory to open Guest path style filter Optional directory listing filter to apply This uses the DOS NT style wildcard characters 2 and flags Zero or more DirectoryOpenFlag flags Opens a directory in the guest and creates a IGuestDirectory object that can be used for further operations Note This method follows symbolic links by default at the moment this may change in the future If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Directory to open was not found e VBOX_E_IPRT_ERROR Error while opening the directory 128 5 Classes interfaces
132. 8 5 99 1 Attributes 2042 2222445 B28 A AAA eee awe 258 5 100 INATNetworkChangedEvent IEvent 2 00000 eee eee eae 258 5 1001 ABIES coca ee Se ee a DROS EO ee A 258 5 101 INATNetworkCreationDeletionEvent INATNetworkAlterEvent 258 SIOL AGTDIESS s Soh been ebb a A ROE 258 5 102 INATNetworkPortForwardEvent INATNetworkAlterEvent 258 S102 A AUT IDIMES lt lt ye kok ge oe he co ed WS a 258 5 103 INATNetworkSettingEvent INATNetworkAlterEvent 259 B1031 Artes oscars es m ee eee ew wed 259 5 104 INATNetworkStartStopEvent INATNetworkChangedEvent 260 LORA ANDES a A aoe AA EE a as oh ere ee T a G 260 5 105 INATRedirectEvent IMachineEvent 260 105 1 Attributes cocos dera a a 260 5 106 INetworkAdapter so oritta recep ada a a ds 261 ELIO LAURA AA S 261 3 1002 SerProperies o a e ee a 263 5 106 3 petProperny cr a a Pw RA 264 5 1064 SEIPPOPery gt ross Sw eke ee Ge EEE RRR EEE SS RES 264 5 107 INetworkAdapterChangedEvent Event o oo oo 264 SA01 ADES a a a ow ee ke Be a a a G 264 5 108 IPClAddress lt r ee Ra a aaa a 264 D1081 ANDES o ee Sse ea a ee a ee ew A 265 5 1082 ASLODE 2 nnana aa Bebe EEE REALE EES a 265 S193 DOMO kG SS ag A A id 265 5 109 IPCIDeviceAttachment 2 ee 265 5 109 1 PUES o a la es a eG 265 S110 IParallclbott lt lt ocio mee DRE a 266 SVU AUDIOS eepe ken Aaa 266 13 Contents 5 111 IParallelPortChange
133. ATEngine aliasMode 5 97 1 7 DNSPassDomain read write boolean INATEngine DNSPassDomain Whether the DHCP server should pass the DNS domain used by the host 5 97 1 8 DNSProxy read write boolean INATEngine DNSProxy Whether the DHCP server and the DNS traffic by NAT should pass the address of the DNS proxy and process traffic using DNS servers registered on the host 5 97 1 9 DNSUseHostResolver read write boolean INATEngine DNSUseHostResolver Whether the DHCP server and the DNS traffic by NAT should pass the address of the DNS proxy and process traffic using the host resolver mechanism 253 5 Classes interfaces 5 97 1 10 redirects read only wstring INATEngine redirects Array of NAT port forwarding rules in string representation in the following format name protocol id host ip host port guest ip guest port 5 97 2 addRedirect void INATEngine addRedirect in wstring name in NATProtocol proto in wstring hostIP in unsigned short hostPort in wstring guestIP in unsigned short guestPort name The name of the rule An empty name is acceptable in which case the NAT engine auto generates one using the other parameters proto Protocol handled with the rule hostIP IP of the host interface to which the rule should apply An empty ip address is acceptable in which case the NAT engine binds the handling socket to any interface hostPort The port number to listen on
134. BControllerType type chipset The chipset type to get the value for type The USB controller type to get the value for Returns the maximum number of USB controller instances which can be configured for each VM This corresponds to the number of USB controllers one can have Value may depend on chipset type used 5 135 7 getMaxNetworkAdapters unsigned long ISystemProperties getMaxNetworkAdapters in ChipsetType chipset chipset The chipset type to get the value for Maximum total number of network adapters associated with every IMachine instance 5 135 8 getMaxNetworkAdaptersOfType unsigned long ISystemProperties getMaxNetworkAdaptersOfType in ChipsetType chipset in NetworkAttachmentType type chipset The chipset type to get the value for type Type of attachment Maximum number of network adapters of a given attachment type associated with every IMachine instance 298 5 Classes interfaces 5 135 9 getMaxPortCountForStorageBus unsigned long ISystemProperties getMaxPortCountForStorageBus in StorageBus bus bus The storage bus type to get the value for Returns the maximum number of ports the given storage bus supports 5 135 10 getMinPortCountForStorageBus unsigned long ISystemProperties getMinPortCountForStorageBus in StorageBus bus bus The storage bus type to get the value for Returns the minimum number of ports the given storage bus supports 5 135 11 getStorageControllerH
135. BOX_E_INVALID_OBJECT_STATE Session type is not direct 5 77 28 resumeWithReason void IInternalSessionControl resumewithReason in Reason reason reason Specify the best matching reason code please Internal method for triggering a VM resume with a specified reason code The reason code can be interpreted by device drivers and thus it might behave slightly differently than a normal VM resume See also IConsole resume If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine not in Paused state e VBOX_E_VM_ERROR Virtual machine error in resume operation 5 77 29 saveStateWithReason boolean IInternalSessionControl saveStateWithReason in Reason reason in IProgress progress in wstring stateFilePath in boolean pauseVM reason Specify the best matching reason code please 164 5 Classes interfaces progress Progress object to track the operation completion stateFilePath File path the VM process must save the execution state to pauseVM The VM should be paused before saving state It is automatically unpaused on error in the vanilla save state case Internal method for triggering a VM save state with a specified reason code The reason code can be interpreted by device drivers and thus it might behave slightly differently than a normal VM save state This call is fully synchronous and the caller is expected to have set the machine state appro
136. BoxSVCAvailabilityChangedEvent OnBandwidthGroupChanged See IBandwidthGroupChangedEvent OnGuestMonitorChanged See IGuestMonitorChangedEvent OnStorageDeviceChanged See IStorageDeviceChangedEvent OnClipboardModeChanged See IClipboardModeChangedEvent OnDnDModeChanged See IDnDModeChangedEvent OnNATNetworkChanged See INATNetworkChangedEvent OnNATNetworkStartStop See INATNetworkStartStopEvent OnNATNetworkAlter See INATNetworkAlterEvent OnNATNetworkCreationDeletion See INATNetworkCreationDeletionEvent OnNATNetworkSetting See INATNetworkSettingEvent OnNATNetworkPortForward See INATNetworkPortForwardEvent OnGuestSessionStateChanged See IGuestSessionStateChangedEvent OnGuestSessionRegistered See IGuestSessionRegisteredEvent OnGuestProcessRegistered See IGuestProcessRegisteredEvent OnGuestProcessStateChanged See IGuestProcessStateChangedEvent OnGuestProcessInputNotify See IGuestProcessInputNotifyEvent OnGuestProcessOutput See IGuestProcessOutputEvent OnGuestFileRegistered See IGuestFileRegisteredEvent OnGuestFileStateChanged See IGuestFileStateChangedEvent OnGuestFileOffsetChanged See IGuestFileOffsetChangedEvent OnGuestFileRead See IGuestFileReadEvent OnGuestFileWrite See IGuestFileWriteEvent OnVideoCaptureChanged See IVideoCaptureChangedEvent OnGuestUserStateChanged See IGuestUserStateChangedEvent OnGuestMultiTouch See IGuestMouseEvent OnHostNameResolutionConfigurationChange See IHostNameResolutionConfigurationChangeEvent OnSnapsho
137. CPIMode Checks if the guest entered the ACPI mode GO working or G1 sleeping If this method returns false the guest will most likely not respond to external ACPI events If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine not in Running state 5 13 12 getPowerButtonHandled boolean IConsole getPowerButtonHandled Checks if the last power button event was handled by guest If this method fails the following error codes may be reported e VBOX_E_PDM_ERROR Checking if the event was handled by the guest OS failed 5 13 13 pause void IConsole pause Pauses the virtual machine execution If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine not in Running state e VBOX_E_VM_ERROR Virtual machine error in suspend operation 5 13 14 powerButton void IConsole powerButton Sends the ACPI power button event to the guest If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine not in Running state e VBOX_E_PDM_ERROR Controlled power off failed 68 5 Classes interfaces 5 13 15 powerDown IProgress IConsole powerDown Initiates the power down procedure to stop the virtual machine execution The completion of the power down procedure is tracked using the returned IProgress object After the operation is complete the machine will go to th
138. ClientID Client identifier data callInfo u32Function SHFL_FN_READ The function code data callInfo cParms SHFL_CPARMS_READ Number of parameters Initialize parameters data root type VMMDevHGCMParmType_32bit data root u value32 pMap gt root data handle type VMMDevHGCMParmType_64bit data handle u value64 hFile data offset type VMMDevHGCMParmType_64bit data offset u value64 offset data cb type VMMDevHGCMParmType_32bit data cb u value32 xpcbBuffer data buffer type VMMDevHGCMParmType_LinAddr_Out data buffer u Pointer size xpcbBuffer data buffer u Pointer u linearAddr uintptr_t pBuffer rc VbglHGCMCall handle S amp data callInfo sizeof data if RT_SUCCESS rc rc data callinfo result xpcbBuffer data cb u value32 This is returned by the HGCM service 7 3 2 Guest application interface Applications call the VirtualBox Guest Additions driver to utilize the HGCM interface There are IOCTL s which correspond to the Vbglx functions e VBOXGUEST_IOCTL_HGCM_ CONNECT e VBOXGUEST_IOCTL_HGCM_DISCONNECT e VBOXGUEST_IOCTL_HGCM_CALL These IOCTL s get the same input buffer as VbglHGCMx functions and the output buffer has the same format as the input buffer The same address can be used as the input and output buffers For example see the guest part of shared clipboard which runs as an application and uses the HGCM interface 377 7 Host Guest
139. D 5 139 1 3 productld read only unsigned short IUSBDevice productld Product ID 5 139 1 4 revision read only unsigned short IUSBDevice revision Product revision number This is a packed BCD represented as unsigned short The high byte is the integer part and the low byte is the decimal 5 139 1 5 manufacturer read only wstring IUSBDevice manufacturer Manufacturer string 5 139 1 6 product read only wstring IUSBDevice product Product string 5 139 1 7 serialNumber read only wstring IUSBDevice serialNumber Serial number string 5 139 1 8 address read only wstring IUSBDevice address Host specific address of the device 5 139 1 9 port read only unsigned short IUSBDevice port Host USB port number the device is physically connected to 5 139 1 10 version read only unsigned short IUSBDevice version The major USB version of the device 1 2 or 3 301 5 Classes interfaces 5 139 1 11 portVersion read only unsigned short IUSBDevice portVersion The major USB version of the host USB port the device is physically connected to 1 2 or 3 For devices not connected to anything this will have the same value as the version attribute 5 139 1 12 speed read only USBConnectionSpeed IUSBDevice speed The speed at which the device is currently communicating 5 139 1 13 remote read only boolean IUSBDevice remote Whether the device is physically connected to a r
140. DARG name is null or empty 5 107 INetworkAdapterChangedE vent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well Notification when a property of one of the virtual network adapters changes Interested callees should use INetworkAdapter methods and attributes to find out what has changed 5 107 1 Attributes 5 107 1 1 networkAdapter read only INetworkAdapter INetworkAdapterChangedEvent networkAdapter Network adapter that is subject to change 5 108 IPClAddress Address on the PCI bus 264 5 Classes interfaces 5 108 1 Attributes 5 108 1 1 bus read write short IPCIAddress bus Bus number 5 108 1 2 device read write short IPCIAddress device Device number 5 108 1 3 devFunction read write short IPCIAddress devFunction Device function number 5 108 2 asLong long IPCIAddress asLong Convert PCI address into long 5 108 3 fromLong void IPCIAddress fromLong in long number number Make PCI address from long 5 109 IPCIDeviceAttachment Note With the web service this interface is mapped to a structure Attributes that return this interface will not return an object but a complete structure containing the attributes listed below as structure members Information about PCI attachments 5 109 1 Attributes 5 109 1 1 name read only wstring IPCIDeviceAttachment name Device na
141. Drives List of floppy drives available on the host 5 69 1 3 USBDevices read only IHostUSBDevice IHost USBDevices List of USB devices currently attached to the host Once a new device is physically attached to the host computer it appears in this list and remains there until detached method will set the result code to E_NOTIMPL Note If USB functionality is not available in the given edition of VirtualBox this 141 5 Classes interfaces 5 69 1 4 USBDeviceFilters read only IHostUSBDeviceFilter IHost USBDeviceFilters List of USB device filters in action When a new device is physically attached to the host computer filters from this list are applied to it in order they are stored in the list The first matched filter will determine the action performed on the device Unless the device is ignored by these filters filters of all currently running virtual machines IUSBDeviceFilters deviceFilters are applied to it Note If USB functionality is not available in the given edition of VirtualBox this method will set the result code to E_NOTIMPL See also IHostUSBDeviceFilter USBDeviceState 5 69 1 5 networkinterfaces read only IHostNetworkInterface IHost networkInterfaces List of host network interfaces currently defined on the host 5 69 1 6 nameServers read only wstring IHost nameServers The list of nameservers registered in host s name resolving system 5 69 1 7
142. EStOS cor a a ee ee 347 GuestMouseEventMode cc ccc cee sosa EE EE ee eS 347 CSIESTSESSIONOTAIUS 0 oe sa rk ek o a a A A ge he 347 GuestSessionWaitForFlag o ee 347 GuestSessionWaitResult o o ee 348 OMESCUSETOTATE lt lt sea a E Ad Rw 348 HWVirtExProperny Type sca soria rias a A 350 HostNetworkinterfaceMediumType o o a 350 HostNetworkinterfaceStatug oo e 6 6b 4a eae eee eee eee eae 351 HostNetworkinteriateTe os ee ee Pe 351 IMpOMtOPNGNS gt s oe meee EER Re HE OEE Pewee BRE RE REDE 351 KeyboardHIDType coccion bee ee ee ema a a e Bo 351 Ke boardi ED a a aA doe AAA PO Oe ee es Raa 351 LOC pdas Ro aaa th be ee we a OR Eee le la es 352 MAChInESEAE is cen bau ee be ee ees bab bees oe EES Ga 352 MediumFormatCapabilities o oo ee ee 355 WISE lt o ee sa BO ee ee a ee ee wee 355 MeditmType w SR RR ee Eo oa a See eee aaa 356 PCV eee ee oe a Be te ae wl ee 356 MouseButtonState 528 42 422 2609 8864 64 RE DES 357 NATAAGM ONE scsi a Rede ee wee ae ee a oO 357 NATProtocol co a eee a OS ee eee i Boars 357 NetworkAdapterPromiscModePolicy 2 ee ee ee 357 NetworkAdapterType oo ec cesa eee eee bea dana BEE tamaa 358 N tworkAttachmentIype o s osos ala les a aoi wl BR Re ae Baw ee es 358 ParavirtProvider cai a a 358 Pablo cio a aa a eas 359 Pamung HIVI YE cece ee eeu A a a 359 PortVWode o 2b ee ee eRe eee dee a e a a a S ES 359 ProcessCreatePlag soko a Eee
143. FaultReset This setting determines whether a triple fault within a guest will trigger an internal error condition and stop the VM default or reset the virtual CPU and continue execution 336 6 Enumerations enums 6 16 ChipsetType Type of emulated chipset mostly southbridge Null null value Never used by the API PIIX3 A PIIX3 PCI IDE ISA Xcelerator chipset ICH9 A ICH9 I O Controller Hub chipset 6 17 CleanupMode Cleanup mode used with IMachine unregister UnregisterOnly Unregister only the machine but neither delete snapshots nor detach media DetachAllReturnNone Delete all snapshots and detach all media but return none this will keep all media registered DetachAllReturnHardDisksOnly Delete all snapshots detach all media and return hard disks for closing but not removable media Full Delete all snapshots detach all media and return all media for closing 6 18 ClipboardMode Host Guest clipboard interchange mode Disabled HostToGuest GuestToHost Bidirectional 6 19 CloneMode Clone mode used with IMachine cloneTo O MachineState Clone the state of the selected machine MachineAndChildStates Clone the state of the selected machine and its child snapshots if present AllStates Clone all states including all snapshots of the machine regardless of the machine object used 6 20 CloneOptions Clone options used with IMachine cloneTo Link Create a clone VM where all virtual disks are l
144. GuestSession copyFrom to IGuestSession fileCopyFromGuest Renamed the CopyFileFlag enum to FileCopyFlag Renamed the IGuestSession environment attribute to IGuestSession environmentChanges to better reflect what it does Changed the IGuestProcess environment to a stub returning E NOTIMPL since it wasn t doing what was advertised returned changes not the actual environment Renamed IGuestSession environmentSet to IGuestSession environmentScheduleSet to better reflect what it does Renamed IGuestSession environmentUnset to IGuestSession environmentScheduleUnset to better reflect what it does Removed IGuestSession environmentGet it was only getting changes while giving the impression it was actual environment variables and it did not represent scheduled unset operations Removed IGuestSession environmentClear as it duplicates assigning an empty array to the IGuestSession environmentChanges formerly known as IGuestSes sion environment Changed the IGuestSession processCreate and IGuestSession processCreateEx meth ods to accept arguments starting with argument zero argv 0 instead of argument one argv 1 Not yet implemented on the guest additions side so argv 0 will probably be ignored for a short while Added a followSymlink parameter to the following methods x IGuestSession directoryExists x IGuestSession fileExists 390 13 Main API change log x IGuestSession f
145. He Ae es 289 5 131 IStateChangedEvent IEvent 6 6 ee ee 289 E PUES a es es aks le ee Se me eee wal ge eR 290 5 132 IStorageGontvollay se cc moeide ee eS ee ee a Sas 290 S132 Anvibites 22 sad eee eR Sao EDGR ea eee ee eee eas 290 5 133 IStorageControllerChangedEvent IEvent o oo o o 291 A A A 291 5 134 IStorageDeviceChangedEvent IEvent o e e 292 S 134 1 Atibutes oasis edi 292 5 129 ISystemProperies ua Aaa a 292 S1351 AMADWES oc ee be ee eae ee a 292 5 135 2 getDefaultloCacheSettingForStorageController 297 5 135 3 getDeviceTypesForStorageB s lt lt 6 ee tara 297 5 135 4 getMaxDevicesPerPortForStorageBUS o 298 5 135 5 getMaxInstancesOfStorageBUS o e e 298 5 135 6 getMaxInstancesOfUSBControllerType o ooo o o 298 5 135 7 setMaxNetworkAdapters lt lt lt ee a ee eee 298 5 135 8 getMaxNetworkAdaptersOfTYpe o ooo o 298 3 135 9 getMaxPortCountPorStorageBus o o o 299 5 135 10getMinPortCountForStorageBus o o 299 5 135 11getStorageControllerHotplugCapable o 299 3 LSO TIGRE eiii ARE A A 299 S IB6 L abandon o a a a E e 299 5 1862 AMI asco a ee EEE Ee eS 299 S137 USB Gombuller rosca ele els ea a ao wl E A 300 SIS7 BIMIDIIES ks Se se ba oe Sw eR OG ee Ha area 300 5 138 IUSBControllerChangedEvent IEvent o 300 AE o oce
146. HostUSBDeviceCollection IHostUSBDeviceFilterCollection IProgressCollection ISharedFolderCollection ISnapshotCollection IUSBDeviceCollection IUSBDeviceFilterCollection e Since Host Interface Networking was renamed to bridged networking and host only networking was introduced all associated interfaces needed renaming as well In detail The HostNetworkInterfaceType enum has been renamed to HostNetworkInterfaceMediumType The IHostNetworkInterface type attribute has been renamed to IHostNetworkInterface mediumType INetworkAdapter attachToHostInterface has been renamed to INetworkAdapter attachToBridgedInterfa In the IHost interface createHostNetworkInterface has been renamed to createHostOnlyNetworkInterface Similarly removeHostNetworkInterface has been renamed to removeHostOnlyNetworkInterface 13 10 Incompatible API changes with version 2 1 e With VirtualBox 2 1 error codes were added to many error infos that give the caller a machine readable numeric feedback in addition to the error string that has always been available This is an ongoing process and future versions of this SDK reference will docu ment the error codes for each method call The hard disk and other media interfaces were completely redesigned This was necessary to account for the support of VMDK VHD and other image types since backwards compat ibility had to be broken anyway we seized the moment
147. I front end e headless VBoxHeadless VRDE Server front end e capture VBoxHeadless VRDE Server front end with video capturing enabled e sdl VirtualBox SDL front end gui separate VirtualBox Qt GUI front end together with a separate headless pro cess sdl separate VirtualBox SDL front end together with a separate headless process emergencystop reserved value used for aborting the currently running VM or session owner In this case the session parameter may be null if it is non null it isn t used in any way and the progress return value will be always null The operation completes immediately e use the per VM default frontend if set otherwise the global default defined in the system properties If neither are set the API will launch a gui session which may fail if there is no windowing environment available See defaultFrontend and ISystemProperties defaultFrontend environment Environment to pass to the VM process Spawns a new process that will execute the virtual machine and obtains a shared lock on the machine for the calling session If launching the VM succeeds the new VM process will create its own session and write lock the machine for it preventing conflicting changes from other processes If the machine is already locked because it is already running or because another session has a write lock launching the VM process will therefore fail Reversely future attempts to obtain a write lock will a
148. IExtPackBase and therefore supports all its methods and attributes as well Interface for querying information about an extension pack as well as accessing COM objects within it 89 5 Classes interfaces 5 27 1 queryObject unknown IExtPack queryObject in wstring objUuid objUuid The object ID What exactly this is Queries the Unknown interface to an object in the extension pack main module This allows plug ins and others to talk directly to an extension pack 5 28 lExtPackBase Note This interface is not supported in the web service Interface for querying information about an extension pack as well as accessing COM objects within it 5 28 1 Attributes 5 28 1 1 name read only wstring IExtPackBase name The extension pack name This is unique 5 28 1 2 description read only wstring IExtPackBase description The extension pack description 5 28 1 3 version read only wstring IExtPackBase version The extension pack version string This is restricted to the dotted version number and op tionally a build indicator No tree revision or tag will be included in the string as those things are available as separate properties An optional publisher tag may be present like for IVirtualBox version Examples 1 2 3 1 2 3 BETA1 and 1 2 3_RC2 5 28 1 4 revision read only unsigned long IExtPackBase revision The extension pack internal revision number
149. IExtPackPlugIn modulePath The module path 5 32 lExtraDataCanChangeEvent IVetoEvent Note This interface extends IVetoEvent and therefore supports all its methods and attributes as well Notification when someone tries to change extra data for either the given machine or if null global extra data This gives the chance to veto against changes 94 5 Classes interfaces 5 32 1 Attributes 5 32 1 1 machineld read only uuid IExtraDataCanChangeEvent machinelId ID of the machine this event relates to Null for global extra data changes 5 32 1 2 key read only wstring IExtraDataCanChangeEvent key Extra data key that has changed 5 32 1 3 value read only wstring IExtraDataCanChangeEvent value Extra data value for the given key 5 33 IExtraDataChangedEvent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well Notification when machine specific or global extra data has changed 5 33 1 Attributes 5 33 1 1 machineld read only uuid IExtraDataChangedEvent machinelId ID of the machine this event relates to Null for global extra data changes 5 33 1 2 key read only wstring IExtraDataChangedEvent key Extra data key that has changed 5 33 1 3 value read only wstring IExtraDataChangedEvent value Extra data value for the given key 5 34 IFile Abstract parent interface for files handled by Vir
150. IFile close Closes this file After closing operations like reading data writing data or querying information will not be possible anymore 5 34 3 querylnfo IFsObjInfo IFile queryInfo Queries information about this file If this method fails the following error codes may be reported e E_NOTIMPL The method is not implemented yet 5 34 4 querySize long long IFile querySize Queries the current file size If this method fails the following error codes may be reported e E_NOTIMPL The method is not implemented yet 5 34 5 read octet IFile read in unsigned long toRead in unsigned long timeoutMS toRead Number of bytes to read timeoutMS Timeout in ms to wait for the operation to complete Pass O for an infinite timeout Reads data from this file If this method fails the following error codes may be reported e E_NOTIMPL The method is not implemented yet 5 34 6 readAt octet IFile readAt in long long offset in unsigned long toRead in unsigned long timeoutMS offset Offset in bytes to start reading toRead Number of bytes to read timeoutMS Timeout in ms to wait for the operation to complete Pass 0 for an infinite timeout Reads data from an offset of this file If this method fails the following error codes may be reported e E_NOTIMPL The method is not implemented yet 97 5 Classes interfaces 5 34 7 seek long long IFile seek in long long offset in
151. IGuestOSType id attribute which contains an identifier of the guest OS this object describes If this method fails the following error codes may be reported e E_INVALIDARG id is not a valid Guest OS type 321 5 Classes interfaces 5 151 16 getMachineStates MachineState IVirtualBox getMachineStates in IMachine machines machines Array with the machine references Gets the state of several machines in a single operation 5 151 17 getMachinesByGroups IMachine IVirtualBox getMachinesByGroups in wstring groups groups What groups to match The usual group list rules apply i e passing an empty list will match VMs in the toplevel group likewise the empty string Gets all machine references which are in one of the specified groups 5 151 18 openMachine IMachine IVirtualBox openMachine in wstring settingsFile settingsFile Name of the machine settings file Opens a virtual machine from the existing settings file The opened machine remains unregis tered until you call registerMachine The specified settings file name must be fully qualified The file must exist and be a valid machine XML settings file whose contents will be used to construct the machine object Note IMachine settingsModified will return false for the opened machine until any of machine settings are changed If this method fails the following error codes may be reported e VBOX_E_FILE_ERROR Settings fil
152. IPConfig O THostNetworkInterface dhcpRediscover IHostNetworkInterface DHCPRediscover THost Acceleration3DAvailable IHost acceleration3DAvailable IGuestOSType recommendedPae IGuestOSType recommendedPAE IGuestOSType recommendedDvdStorageController IGuestOSType recommendedDVDStorageController IGuestOSType recommendedDvdStorageBus IGuestOSType recommendedDVDStorageBus IGuestOSType recommendedHdStorageController IGuestOSType recommendedHDStorageController IGuestOSType recommendedHdStorageBus IGuestOSType recommendedHDStorageBus IGuestOSType recommendedUsbHid IGuestOSType recommendedUSBHID IGuestOSType recommendedHpet IGuestOSType recommendedHPET IGuestOSType recommendedUsbTablet IGuestOSType recommendedUSBTablet IGuestOSType recommendedRtcUseUtc IGuestOSType recommendedRTCUseUTC IGuestOSType recommendedUsb IGuestOSType recommendedUSB INetworkAdapter natDriver INetworkAdapter NATEngine IUSBController enabledEhci IUSBController enabledEHCT INATEngine tftpPrefix INATEngine TFTPPrefix INATEngine tftpBootFile INATEngine TFTPBootFile INATEngine tftpNextServer INATEngine TFTPNextServer INATEngine dnsPassDomain INATEngine DNSPassDomain INATEngine dnsProxy INATEngine DNSProxy INATEngine dnsUseHostResolver INATEngine DNSUseHostResolver VBoxEventType OnHostPciDevicePlug VBoxEventType OnHostPCIDevicePlug ICPUChangedEvent cpu ICPUChangedEvent CPU INATRedirectEvent hostlp INATRedirectEvent hostIP INATRedirec
153. M service the client supplies a function code and a number of parameters for the function 7 1 Virtual hardware implementation HGCM uses the VMM virtual PCI device to exchange data between the guest and the host The guest always acts as an initiator of requests A request is constructed in the guest physical memory which must be locked by the guest The physical address is passed to the VMM device using a 32 bit out edx eax instruction The physical memory must be allocated below 4GB by 64 bit guests The host parses the request header and data and queues the request for a host HGCM service The guest continues execution and usually waits on a HGCM event semaphore When the request has been processed by the HGCM service the VMM device sets the comple tion flag in the request header sets the HGCM event and raises an IRQ for the guest The IRQ handler signals the HGCM event semaphore and all HGCM callers check the completion flag in the corresponding request header If the flag is set the request is considered completed 7 2 Protocol specification The HGCM protocol definitions are contained in the VBox VBoxGuest h 7 2 1 Request header HGCM request structures contains a generic header VMMDevHGCMRequestHeader Name Description size Size of the entire request version Version of the header must be set to 0x10001 type Type of the request rc HGCM return code which will be set by the VMM device reserved1 A re
154. Machine instance 5 135 1 11 maxBootPosition read only unsigned long ISystemProperties maxBootPosition Maximum device position in the boot order This value corresponds to the total number of devices a machine can boot from to make it possible to include all possible devices to the boot list See also IMachine setBootOrder 5 135 1 12 rawModeSupported read only boolean ISystemProperties rawModeSupported Indicates whether VirtualBox was built with raw mode support When this reads as False the HWVirtExPropertyType Enabled setting will be ignored and assumed to be True 293 5 Classes interfaces 5 135 1 13 exclusiveHwVirt read write boolean ISystemProperties exclusiveHwVirt Exclusive use of hardware virtualization by VirtualBox When enabled VirtualBox assumes it can obtain full and exclusive access to the VI x or AMD V feature of the host To share hardware virtualization with other hypervisors this property must be disabled Note This is ignored on OS X the kernel mediates hardware access there 5 135 1 14 defaultMachineFolder read write wstring ISystemProperties defaultMachineFolder Full path to the default directory used to create new or open existing machines when a machine settings file name contains no path Starting with VirtualBox 4 0 by default this attribute contains the full path of folder named VirtualBox VMs in the user s home directory which depends on the host
155. NOT_FOUND File to was not found e VBOX_E_IPRT_ERROR Error querying file size 5 64 24 fsObjExists boolean IGuestSession fsObjExists in wstring path in boolean followSymlinks path Path to the file system object to check the existance of Guest path style followSymlinks If true symbolic links in the final component will be followed and the method will instead check if the target exists If false symbolic links in the final component will satisfy the method and it will return true in exists Checks whether a file system object file directory etc exists in the guest or not If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Error while checking existence of the file specified 5 64 25 fsObjMove IProgress IGuestSession fsObjMove in wstring source in wstring destination in FsObjMoveFlags flags source Path to the file to move Guest path style destination Where to move the file to file not directory Guest path style flags Zero or more FsObjMoveFlags values Moves a file system object file directory symlink etc from one guest location to another This differs from fsObjRename in that it can move accross file system boundraries In that case it will perform a copy and then delete the original For directories this can take a while and is subject to races If this method fails the following error codes may be reported e E_NOTIMPL Not yet implemen
156. OM names the get method like this get_Attribute whereas XPCOM uses this syn tax GetAttribute and accordingly for set methods To hide these differences the VirtualBox glue code provides the COMGETTER attrib and COMSETTER attrib macros So COMGETTER version note two pairs of brackets expands to get_Version on Windows and GetVersion on other platforms 2 Unicode conversions While the rest of the modern world has pretty much settled on encoding strings in UTF 8 COM unfortunately uses UCS 16 encoding This requires a lot of conversions in particular between the VirtualBox Main API and the Qt GUI which like the rest of Qt likes to use UTF 8 To facilitate these conversions VirtualBox provides the com Bstr and com Utf8Str classes which support all kinds of conversions back and forth 3 COM autopointers Possibly the greatest pain of using COM reference counting is alleviated by the ComPtr lt gt template provided by the ptr h file in the glue layer 2 3 4 Event queue processing Both VirtualBox client programs and frontends should periodically perform processing of the main event queue and do that on the application s main thread In case of a typical GUI Windows Mac OS application this happens automatically in the GUI s dispatch loop However for CLI only application the appropriate actions have to be taken For C applications the VirtualBox SDK provided glue method int EventQueue
157. OR mask pixels are 32 bit values Isb BGRO msb For pointers with alpha channel the XOR mask consists of lIsb BGRA msb 32 bit values An AND mask is provided for pointers with alpha channel so if the client does not support alpha the pointer could be displayed as a normal color pointer The AND mask is a 1bpp bitmap with byte aligned scanlines The size of the AND mask therefore is cbAnd width 7 8 height The padding bits at the end of each scanline are undefined The XOR mask follows the AND mask on the next 4 byte aligned offset uint8_t pu8Xor pu8And cbAnd 3 amp 3 Bytes in the gap between the AND and the XOR mask are undefined The XOR mask scanlines have no gap between them and the size of the XOR mask is cbXor width 4 height Note If shape size is 0 then the shape is not known or did not change This can happen if only the pointer visibility is changed 5 96 IMousePointerShapeChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when the guest mouse pointer shape has changed The new shape data is given 5 96 1 Attributes 5 96 1 1 visible read only boolean IMousePointerShapeChangedEvent visible Flag whether the pointer is visible 5 96 1 2 alpha read only boolean IMousePointerShapeChangedEvent alpha Flag whether the pointer has an alpha channel 5 96 1 3 xhot read only unsi
158. PICGlue o VirtualBox_i o CC o ldl lpthread 2 3 6 10 Conversion of code using legacy C binding This section aims to make the task of converting code using the legacy C binding to the new style a breeze by pointing out some key steps One necessary change is adjusting your Makefile to reflect the different include paths See above There are now 3 relevant include directories and most of it is pointing to the C binding directory The XPCOM include directory is still relevant for platforms where the XPCOM mid dleware is used but most of the include files live elsewhere now so it s good to have it last Additionally the VirtualBox_i c file needs to be compiled and linked to the program it con tains the IIDs relevant for the VirtualBox API making sure they are not replicated endlessly if the code refers to them frequently The C API client code should include VBoxCAPIGlue h instead of VBoxXPCOMCGlue h or VBoxCAPI_v4_3 h as this makes sure the correct macros and internal translations are selected All API method calls anything mentioning vtbl should be rewritten using the convenience macros for calling methods as these hide the internal details are generally easier to use and shorter to type You should remove as many as possible nsISupports or similar typecasts as the new style should use the correct type in most places increasing the type safety in case of an error in the source code To gloss over the platform differen
159. PI_v4_3 h The code complexity of active event handling and its inherenly platform compiler specific aspects should be motivation to use passive event handling whereever possible 2 3 6 8 C API uninitialization Uninitialization is performed by g_pVBoxFuncs gt pfnClientUninitialize If your program can exit from more than one place it is a good idea to install this function as an exit handler with Standard C s atexit just after calling g_pVBoxFuncs gt pfnClientInitialize e g include lt stdlib h gt include lt stdio h gt Make sure g_pVBoxFuncs gt pfnClientUninitialize is called at exit no matter if we return from the initial call to main or call exit somewhere else Note that atexit registered functions are not called upon abnormal termination i e when calling abort or signal KK XA XX if atexit g_pVBoxFuncs gt pfnClientUninitialize 0 fprintf stderr failed to register g_pVBoxFuncs gt pfnClientUninitialize n exit EXIT_FAILURE Another idea would be to write your own void myexit int status function calling g_pVBoxFuncs gt pfnClientUninitialize followed by the real exit and use it instead of exit throughout your program and at the end of main If you expect the program to be terminated by a signal e g user types CTRL C sending SIGINT you might want to install a signal handler setting a flag noting that a signal was sent and then calling g_pVBoxFuncs gt pfnClientUnin
160. RDE connection 5 13 1 12 eventSource read only IEventSource IConsole eventSource Event source for console events 5 13 1 13 attachedPClDevices read only IPCIDeviceAttachment IConsole attachedPCIDevices Array of PCI devices attached to this machine 5 13 1 14 useHostClipboard read write boolean IConsole useHostClipboard Whether the guest clipboard should be connected to the host one or whether it should only be allowed access to the VRDE clipboard This setting may not affect existing guest clipboard connections which are already connected to the host clipboard 5 13 1 15 emulatedUSB read only IEmulatedUSB IConsole emulatedUSB Interface that manages emulated USB devices 5 13 2 addDiskEncryptionPassword void IConsole addDiskEncryptionPassword in wstring id in wstring password in boolean clearOnSuspend id The identifier used for the password Must match the identifier used when the encrypted medium was created password The password clearOnSuspend Flag whether to clear the password on VM suspend due to a suspending host for example The password must be supplied again before the VM can resume Adds a password used for hard disk encryption decryption If this method fails the following error codes may be reported e VBOX_E_PASSWORD_INCORRECT The password provided wasn t correct for at least one disk using the provided ID 65 5 Classes interfaces 5 13 3 addDiskEncryptio
161. S and Floppy see bus Depending on which of these four is used certain sub types may be available and can be selected in controllerType Depending on these settings the guest operating system might see significantly different vir tual hardware 5 132 1 Attributes 5 132 1 1 name read write wstring IStorageController name Name of the storage controller as originally specified with IMachine addStorageController This then uniquely identifies this controller with other method calls such as IMachine attachDevice and IMachine mountMedium 5 132 1 2 maxDevicesPerPortCount read only unsigned long IStorageController maxDevicesPerPortCount Maximum number of devices which can be attached to one port 5 132 1 3 minPortCount read only unsigned long IStorageController minPortCount Minimum number of ports that portCount can be set to 5 132 1 4 maxPortCount read only unsigned long IStorageController maxPortCount Maximum number of ports that portCount can be set to 5 132 1 5 instance read write unsigned long IStorageController instance The instance number of the device in the running VM 290 5 Classes interfaces 5 132 1 6 portCount read write unsigned long IStorageController portCount The number of currently usable ports on the controller The minimum and maximum number of ports for one controller are stored in minPortCount and maxPortCount 5 132 1 7 bus read only StorageBus
162. SaLi omel lt a EGE a 82 ELA WOP escaner ar eee 83 Sul EU e a E e a e de 83 521 4 leave 2c cac aaa acee eee eed aaa a a a a 84 SL MOVE a GREE a e A Gee 84 a E A a ee ee ee a 84 DE RS Bs oe eck oa a we ww wee la a Ee ae ee 84 S221 AWE os naan ae ea be booed O46 BOOS EE ES EES RRS 85 S222 webcam e ken AAA 85 5 49 5 24 9 29 5 26 eed 5 28 5 29 5 30 5al 5 32 3 33 5 34 339 Contents Beenie WEBER voos eaaa Pe ww BRIE Pa oe S 85 TEMODE occ ARR REG RE EEE RAR REE Oe AA 85 D231 ADMES sb oe oe ae ae he a a a d a ee S 86 5 23 2 serProcessed caia aa decididas 4444444 64054445 44 86 D233 wallProces d sosyo s ww Bee Bede ee a ee 87 Ereni istenei da ROS Oe ee ee a 87 5 24 1 handleFvent coc co o ee ee G 87 JEFEDESQUEC DORR EDDA EE HE DOE A mS 87 3 23 Ll PesteAesregator osas amp SG SG Foe ado ad ee 87 5 29 24 A 22k c ddo eR eS OES ce Pale Se a 87 5 25 3 eventProcessed face eae aa Ba beh ee a AES 88 D254 TREE VERE oo ias aa ah we ee we oe wa nln Be 88 Dago BOEVEN o oes eee NE 88 5 25 0 tr gisterlitener o vod x ss kaa wa lee eee Ee eee 88 5 25 7 unreeister Istene oo a ae A AAA a 89 IEventSourceChangedEvent IEvent 89 526 1 AQUIDI S ss baw had eh ed Saad A 89 IExtPack IExtPackBase oaoa ee 89 527 1 queryObjpect ooo ei e eb ee OO ee eee wae ee i 90 lExPackBas 6 6 ie ee a a e e e 90 5291 JAWS 2 3 SSG ee ede a ES eS 90 5 26 2 QUEIPLICEM E canina
163. Sat 59 O AMUIDULES 2 1 45 2 248 SR Soe EDD a a eas 60 56 2 treateBandwidthGroup ere ceee seta 6 be eee nes 60 5 43 deleteBandwidthGroup 2 2 0 44444 00 28440045 08 60 5 64 getAliBandwidthGroups lt o cco eae eee ee ee ve 60 5 6 5 getBandwidthGroup 2 o44483 808 0 ee es e005 awe 60 TBA GOW oe a II a i E E e 60 Sf ARIES coran rre rd ere eee eee canes 60 IBandwidthGroupChangedEvent IEvent o o 61 So AMADUES ria a ees 61 ICPUCHhangedEvent Event 2 a ee a ee 61 59 1 AIDIMES treceau ee eee a ES eS 61 ICPUExecutionCapChangedEvent IEvent o o 62 SOL ARIES dra Ge wee we ee Se 62 ICanShowWindowEvent IVetoEvent 62 SILI ADES o e e ee ee ee ee a a eS BRO ede eh ae 4 62 IClipboardModeChangedEvent IEvent o oo o 62 SIZI AUNES eck he RO ed G 62 COMA 00 awe a SG Ae SE a ee SS ee eee aoe ara sd 63 SISI ALEA oe ke ee OS Oe ee a ER EE e 63 5 13 2 addDiskEncryptionPassword o oo 65 5 13 3 addDiskEncryptionPasswordS o o 66 SAGA attachUsSBDevits 20006050 e ee ee Hae Sree 66 5 13 5 clearAllDiskEncryptionPasswords o o 66 513 createSbharedFolder eos o coc ee A ae 66 5 13 7 detachUSBDevICE 2 220 lt 0 0 deal e a 67 5 13 8 findUSBDeviceByAddress 0 ee 67 5 13 9 findUShDeviceByld 3 oa cm 5444 ba does es ee ee een ds 67 SA13 DO BOReVICCARIIVIY rc ek a w
164. SettingForStorageController boolean ISystemProperties getDefaultIoCacheSettingForStorageController in StorageControllerType controllerType controllerType The storage controller type to get the setting for Returns the default I O cache setting for the given storage controller 5 135 3 getDeviceTypesForStorageBus DeviceType ISystemProperties getDeviceTypesForStorageBus in StorageBus bus bus The storage bus type to get the value for Returns list of all the supported device types DeviceType for the given type of storage bus 297 5 Classes interfaces 5 135 4 getMaxDevicesPerPortForStorageBus unsigned long ISystemProperties getMaxDevicesPerPortForStorageBus in StorageBus bus bus The storage bus type to get the value for Returns the maximum number of devices which can be attached to a port for the given storage bus 5 135 5 getMaxinstancesOfStorageBus unsigned long ISystemProperties getMaxInstancesOfStorageBus in ChipsetType chipset in StorageBus bus chipset The chipset type to get the value for bus The storage bus type to get the value for Returns the maximum number of storage bus instances which can be configured for each VM This corresponds to the number of storage controllers one can have Value may depend on chipset type used 5 135 6 getMaxInstancesOfUSBControllerType unsigned long ISystemProperties getMaxInstancesOfUSBControllerType in ChipsetType chipset in US
165. Succeeded return AuthResultAccessGranted return AuthResultAccessDenied A note regarding the UUID implementation of the pUuid argument VirtualBox uses a consis tent binary representation of UUIDs on all platforms For this reason the integer fields comprising the UUID are stored as little endian values If you want to pass such UUIDs to code which as sumes that the integer fields are big endian often also called network byte order you need to adjust the contents of the UUID to e g achieve the same string representation The required changes are e reverse the order of byte 0 1 2 and 3 e reverse the order of byte 4 and 5 e reverse the order of byte 6 and 7 Using this conversion you will get identical results when converting the binary UUID to the string representation The guestJudgement argument contains information about the guest authentication status For the first call it is always set to AuthGuestNotAsked In case the AuthEntry function returns AuthResultDelegateToGuest a guest authentication will be attempted and another call to the AuthEntry is made with its result This can be either granted denied or no judgement the guest component chose for whatever reason to not make a decision In case there is a problem with the guest authentication module e g the Additions are not installed or not running or the guest did not respond within a timeout the not reacted status will be returned 384 11 Usin
166. Suggested URL to download this firmware from file Filename of firmware only valid if result TRUE Check if this VirtualBox installation has a firmware of the given type available either system wide or per user Optionally this may return a hint where this firmware can be downloaded from 316 5 Classes interfaces 5 151 3 composeMachineFilename wstring IVirtualBox composeMachineFilename in wstring name in wstring group in wstring createFlags in wstring baseFolder name Suggested machine name group Machine group name for the new machine or machine group It is used to determine the right subdirectory createFlags Machine creation flags see createMachine optional baseFolder Base machine folder optional Returns a recommended full path of the settings file name for a new virtual machine This API serves two purposes e It gets called by createMachine if null or empty string which is recommended is spec ified for the settingsFile argument there which means that API should use a recom mended default file name e It can be called manually by a client software before creating a machine e g if that client wants to pre create the machine directory to create virtual hard disks in that directory together with the new machine settings file In that case the file name should be stripped from the full settings file path returned by this function to obtain the machine directory See IMachine na
167. SystemDescriptionValueType which type which This is the same as getDescriptionByType except that you can specify which value types should be returned See VirtualSystemDescriptionValueType for possible values 330 5 Classes interfaces 5 154 6 setFinalValues void IVirtualSystemDescription setFinalVaLues in boolean enabled in wstring VBoxValues in wstring extraConfigValues enabled VBoxValues extraConfigValues This method allows the appliance s user to change the configuration for the virtual system descriptions For each array item returned from getDescription you must pass in one boolean value and one configuration value Each item in the boolean array determines whether the particular configuration item should be enabled You can only disable items of the types HardDiskControllerIDE HardDiskCon trollerSATA HardDiskControllerSCSI HardDiskImage CDROM Floppy NetworkAdapter USB Controller and SoundCard For the vbox and extra configuration values if you pass in the same arrays as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription the configuration remains unchanged Please see the documentation for getDescription for valid configuration values for the individual array item types If the corresponding item in the aEnabled array is false the configuration value is ignored 5 155 IWebsessionManager Note This interface is supported in the web ser
168. VALID_VM_STATE Virtual machine state neither PoweredOff nor Aborted 5 80 5 applyDefaults void IMachine applyDefaults in wstring flags flags Additional flags to be defined later Applies the defaults for the configured guest OS type This is primarily for getting sane settings straight after creating a new VM but it can also be applied later Note This is primarily a shortcut centralizing the tedious job of getting the recom mended settings and translating them into settings updates The settings are made at the end of the call but not saved If this method fails the following error codes may be reported e E_NOTIMPL This method is not implemented yet 181 5 Classes interfaces 5 80 6 attachDevice void IMachine attachDevice in wstring name in long controllerPort in long device in DeviceType type in IMedium medium name Name of the storage controller to attach the device to controllerPort Port to attach the device to For an IDE controller O specifies the primary con troller and 1 specifies the secondary controller For a SCSI controller this must range from O to 15 for a SATA controller from O to 29 for an SAS controller from 0 to 7 device Device slot in the given port to attach the device to This is only relevant for IDE con trollers for which O specifies the master device and 1 specifies the slave device For all other controller types this must be 0 type De
169. VF network and hardware adapters virtual disk images memory size and so on The GUI can then give the user the option to confirm and or change these suggestions If desired call IVirtualSystemDescription setFinalValues for each virtual system ma chine to override the suggestions made by the interpret routine Finally call importMachines to create virtual machines in VirtualBox as instances of IMachine that match the information in the virtual system descriptions After this call succeeded the UUIDs of the machines created can be found in the machines array at tribute Exporting VirtualBox machines into an OVF appliance involves the following steps 1 2 As with importing first call IVirtualBox createAppliance to create an empty Appliance object For each machine you would like to export call IMachine exportTo with the Appliance object you just created Each such call creates one instance of IVirtualSystemDescription inside the appliance 53 5 Classes interfaces 3 If desired call IVirtualSystemDescription setFinalValues for each virtual system ma chine to override the suggestions made by the IMachine exportTo routine 4 Finally call writeQ with a path specification to have the OVF file written 5 3 1 Attributes 5 3 1 1 path read only wstring IAppliance path Path to the main file of the OVF appliance which is either the ovf or the ova file passed to read for impor
170. a con sequence of this IMachine ReadSavedThumbnailPNGToArray has been removed IMachine QuerySavedScreenshotPNGSize has been renamed to IMachine QuerySavedScreenshotInfo which also returns an array of available screenshot formats IMachine ReadSavedScreenshotPNGToArray has been renamed to IMachine ReadSavedScreenshotToArray which has a new parameter bitmapFormat IMachine QuerySavedThumbnailSize has been removed The method IWebsessionManager getSessionObject now returns a new Session instance for every invocation This puts the behavior in line with other binding styles which never forced the equivalent of establishing another connection and logging in again to get an other instance 13 2 Incompatible API changes with version 4 3 e The explicit medium locking methods IMedium lockReadQ and IMedium lockWriteQ have been redesigned They return a lock token object reference now and calling the IToken abandon method or letting the reference count to this object drop to 0 will unlock it This eliminates the rather common problem that an API client crash left behind locks and also improves the safety API clients can t release locks they didn t obtain 391 13 Main API change log The parameter list of IAppliance write has been changed slightly to allow multiple flags to be passed IMachine delete has been renamed to IMachine deleteConfig to improve API client binding compatibility IMac
171. acceleration is recommended for this OS type 5 55 1 11 recommended3DAcceleration read only boolean IGuestOSType recommended3DAcceleration Returns true if 3D acceleration is recommended for this OS type 5 55 1 12 recommendedHDD read only long long IGuestOSType recommendedHDD Recommended hard disk size in bytes 5 55 1 13 adapterType read only NetworkAdapterType IGuestOSType adapterType Returns recommended network adapter for this OS type 118 5 Classes interfaces 5 55 1 14 recommendedPAE read only boolean IGuestOSType recommendedPAE Returns true if using PAE is recommended for this OS type 5 55 1 15 recommendedDVDStorageController read only StorageControllerType IGuestOSType recommendedDVDStorageController Recommended storage controller type for DVD CD drives 5 55 1 16 recommendedDVDStorageBus read only StorageBus IGuestOSType recommendedDVDStorageBus Recommended storage bus type for DVD CD drives 5 55 1 17 recommendedHDStorageController read only StorageControllerType IGuestOSType recommendedHDStorageController Recommended storage controller type for HD drives 5 55 1 18 recommendedHDStorageBus read only StorageBus IGuestOSType recommendedHDStorageBus Recommended storage bus type for HD drives 5 55 1 19 recommendedFirmware read only FirmwareType IGuestOSType recommendedFirmware Recommended firmware type 5 55 1 20 recommendedUSBHID rea
172. ains the same attachment information as with HardDiskImage items NetworkAdapter a network adapter The array item in aVBoxValues will specify the hardware for the network adapter whereas the array item in aExtraConfigValues will have a string of the type lt X gt format where lt X gt must be either NAT or Bridged USBController a USB controller There can be at most one such item If and only if such an item is present USB support will be enabled for the new virtual machine SoundCard a sound card There can be at most one such item If and only if such an item is present sound support will be enabled for the new virtual machine Note that the virtual machine in VirtualBox will always be presented with the standard VirtualBox soundcard which may be different from the virtual soundcard expected by the appliance 5 154 4 getDescriptionByType void IVirtualSystemDescription getDescriptionByType in VirtualSystemDescriptionType type out VirtualSystemDescriptionType types out wstring refs out wstring OVFValues out wstring VBoxValues out wstring extraConfigValues type types refs OVFValues VBoxValues extraConfigValues This is the same as getDescription except that you can specify which types should be re turned 5 154 5 getValuesByType wstring IVirtualSystemDescription getValuesByType in VirtualSystemDescriptionType type in Virtual
173. aintains a session for each client that connects to it The IWebsessionManager logon API takes a user name and a password as arguments which the web service then passes to a customizable authentication plugin that performs the actual authentication 25 1 Introduction For testing purposes it is recommended that you first disable authentication with this com mand VBoxManage setproperty websrvauthlibrary null Warning This will cause all logons to succeed regardless of user name or password This should of course not be used in a production environment Generally the mechanism by which clients are authenticated is configurable by way of the VBoxManage command VBoxManage setproperty websrvauthlibrary default null lt library gt This way you can specify any shared object dynamic link module that conforms with the specifications for VirtualBox external authentication modules as laid out in section VRDE au thentication of the VirtualBox User Manual the web service uses the same kind of modules as the VirtualBox VRDE server For technical details on VirtualBox external authentication modules see chapter 10 VirtualBox external authentication modules page 383 By default after installation the web service uses the VBoxAuth module that ships with VirtualBox This module uses PAM on Linux hosts to authenticate users Any valid user name password combination is accepted it does not have to be the username and password
174. al Upon successful completion the cloned medium will contain exactly the same sector data as the medium being cloned except that in the first case a new UUID for the clone will be randomly generated and in the second case the UUID will remain unchanged The parent argument defines which medium will be the parent of the clone In this case the clone will be a base image i e completely independent It is possible to specify an arbitrary medium for this parameter including the parent of the medium which is being cloned Even cloning to a child of the source medium is possible Note that when cloning to an existing image the parent argument is ignored After the returned progress object reports that the operation is successfully complete the tar get medium gets remembered by this VirtualBox installation and may be attached to virtual machines Note This medium will be placed to LockedRead state for the duration of this opera tion If this method fails the following error codes may be reported e E_NOTIMPL The specified cloning variant is not supported at the moment 231 5 Classes interfaces 5 87 6 close void IMedium close Closes this medium The medium must not be attached to any known virtual machine and must not have any known child media otherwise the operation will fail When the medium is successfully closed it is removed from the list of registered media but its storage unit is not deleted In part
175. alls to the web service will automatically be disconnected after the number of seconds specified here as if it had called the IWebSessionManager Logoff method provided by the web service itself It is normally vital that each web service client call this method as the web service can accumulate large amounts of memory when running especially if a web service client does not properly release managed object references As a result this timeout value should not be set too high especially on machines with a high load on the web service or the web service may eventually deny service check interval or i This specifies the interval in which the web service checks for timed out clients in seconds and defaults to 5 This normally does not need to be changed threads or T This specifies the maximum number or worker threads and defaults to 100 This normally does not need to be changed keepalive or k This specifies the maximum number of requests which can be sent in one web service connection and defaults to 100 This normally does not need to be changed authentication or A This specifies the desired web service authentication method If the parameter is not specified or the empty string is specified it does not change the authentication method otherwise it is set to the specified value Using this parameter is a good measure against accidental misconfiguration as the web service ensures periodically that it isn
176. ameter first parameter for specifying the storage bus which the storage controller must be using The method was not useful before as the instance numbers are only unique for a specfic storage bus The attribute IMachine sessionType has been renamed to IMachine sessionName This cleans up the confusing terminology as the session type is something different The attribute IMachine guestPropertyNotificationPatterns has been removed In practice it was not usable because it is too global and didn t distinguish between API clients Drag and drop APIs were changed as follows Methods for providing host to guest drag and drop functionality such as IGuest dragHGEnter IGuest dragHGMove IGuest dragHGLeave IGuest and IGuest dragHGPutData have been moved to an abstract base class called IDnDTarget VirtualBox implements this base class in the IGuestDnDTarget interface The implementation can be used by using the IGuest dnDTarget Q method Methods for providing guest to host drag and drop functionality such as dragHGDrop IGuest dragGHPending IGuest dragGHDropped and IGuest dragGHGetData have been moved to an abstract base class called IDnDSource VirtualBox implements this base class in the IGuestDnDSource interface The implementation can be used by using the IGuest dnDSource method The DragAndDropAction enumeration has been renamed to DnDAction The DragAndDropMode enumeration has be
177. apshot Small adjustments to the parameter lists have been made to reduce the number of API calls when taking online snapshots no longer needs explicit pausing and taking a snapshot also returns now the snapshot id useful for finding the right snapshot if there are non unique snapshot names Two new machine states have been introduced to allow proper distinction between sav ing state and taking a snapshot MachineState Saving now is used exclusively while the VM s state is being saved without any overlaps with snapshot functionality The new state MachineState Snapshotting is used when an offline snapshot is taken and likewise the new state MachineState OnlineSnapshotting is used when an online snapshot is taken e A new event has been introduced which signals when a snapshot has been restored ISnapshotRestoredEvent Previously the event ISnapshotDeletedEvent was signalled 388 13 Main API change log which isn t logical but could be distinguished from actual deletion by the fact that the snapshot was still there The method IVirtualBox createMedium replaces VirtualBox createHardDisk Adjusting existing code needs adding two parameters with value AccessMode_ReadWrite and DeviceType_HardDisk respectively The new method supports creating floppy and DVD images and less obviously further API functionality such as cloning floppy images The method IMachine getStorageControllerByInstance now has an additional par
178. arget argument The target medium must be in NotCreated state i e must not have an existing storage unit Upon successful completion this operation will set the type of the target medium to Normal and create a storage unit necessary to represent the differencing medium data in the given format according to the storage format of the target object After the returned progress object reports that the operation is successfully complete the tar get medium gets remembered by this VirtualBox installation and may be attached to virtual machines Note The medium will be set to LockedRead state for the duration of this operation If this method fails the following error codes may be reported e VBOX_E_OBJECT_IN_USE Medium not in NotCreated state 5 87 10 deleteStorage IProgress IMedium deleteStorage Starts deleting the storage unit of this medium The medium must not be attached to any known virtual machine and must not have any known child media otherwise the operation will fail It will also fail if there is no storage unit to delete or if deletion is already in progress or if the medium is being in use locked for read or for write or inaccessible Therefore the only valid state for this operation to succeed is Created Before the operation starts the medium is placed in Deleting state and gets removed from the list of remembered hard disks media registry If the delete operation fails the medium will be remember
179. array to receive region data count Number of RTRECT elements in the rectangles array Returns the visible region of this frame buffer If the rectangles parameter is null then the value of the count parameter is ignored and the number of elements necessary to describe the current visible region is returned in countCopied If rectangles is not null but count is less than the required number of elements to store region data the method will report a failure If count is equal or greater than the required number of elements then the actual number of elements copied to the provided array will be returned in countCopied 100 5 Classes interfaces Note The address of the provided array must be in the process space of this IFrame buffer object Note Method not yet implemented 5 35 3 notify3DEvent void IFramebuffer notify3DEvent in unsigned long type in octet data type event type Currently only VBOX3D_NOTIFY_EVENT TYPE VISIBLE 3DDATA is sup ported data event specific data depends on the supplied event type Notifies framebuffer about 3D backend event 5 35 4 notifyChange void IFramebuf fer notifyChange in unsigned long screenId in unsigned long xOrigin in unsigned long yOrigin in unsigned long width in unsigned long height screenld Logical guest screen number xOrigin Location of the screen in the guest yOrigin Location of the screen in the guest width Width o
180. ary replaces RemoteDisplayAuthLibrary The following methods have been implemented in IVRDEServer to support generic VRDE properties IVRDEServer setVRDEProperty IVRDEServer getVRDEProperty IVRDEServer VRDEProperties A few implementation specific attributes of the old IVRDPServer interface have been removed and replaced with properties x IVRDPServer Ports has been replaced with the TCP Ports property The property value is a string which contains a comma separated list of ports or ranges of ports Use a dash between two port numbers to specify a range Exam ple 5000 5010 5012 IVRDPServer NetAddress has been replaced with the TCP Address prop erty The property value is an IP address string Example 127 0 0 1 IVRDPServer VideoChannel has been replaced with the VideoChannel Enabled property The property value is either true or false IVRDPServer VideoChannelQuality has been replaced with the VideoChannel Quality property The property value is a string which contain a decimal number in range 10 100 Invalid values are ignored and the quality is set to the default value 75 Example 50 e The VirtualBox external authentication module interface has been updated and made more generic Because of that VRDPAuthType enumeration has been renamed to AuthType 398 13 Main API change log 13 6 Incompatible API changes with version 3 2 e The following interfaces were renamed for c
181. as a linked clone which uses its own differencing media sharing the parent media with the source machine The target machine object must have been created previously with IVirtualBox createMachine and all the settings will be transferred except the VM name and the hardware UUID You can set the VM name and the new hardware UUID when creating the target machine The network MAC addresses are newly created for all network adapters You can change that behaviour with the options parameter The operation is performed asynchronously so the machine object will be not be usable until the progress object signals completion If this method fails the following error codes may be reported e E_INVALIDARG target is null 5 80 11 createSharedFolder void IMachine createSharedFolder in wstring name in wstring hostPath in boolean writable in boolean automount name Unique logical name of the shared folder hostPath Full path to the shared folder in the host file system writable Whether the share is writable or read only automount Whether the share gets automatically mounted by the guest or not Creates a new permanent shared folder by associating the given logical name with the given host path adds it to the collection of shared folders and starts sharing it Refer to the description of ISharedFolder to read more about logical names If this method fails the following error codes may be reported e VBOX_E_OBJECT_IN_USE Sha
182. ase a new UUID for the clone will be randomly generated and in the second case the UUID will remain unchanged The parent argument defines which medium will be the parent of the clone Passing a null reference indicates that the clone will be a base image i e completely independent It is possible to specify an arbitrary medium for this parameter including the parent of the medium which is being cloned Even cloning to a child of the source medium is possible Note that when cloning to an existing image the parent argument is ignored After the returned progress object reports that the operation is successfully complete the tar get medium gets remembered by this VirtualBox installation and may be attached to virtual machines Note This medium will be placed to LockedRead state for the duration of this opera tion If this method fails the following error codes may be reported e E_NOTIMPL The specified cloning variant is not supported at the moment 5 87 5 cloneToBase IProgress IMedium cloneToBase in IMedium target in MediumVariant variant target Target medium variant MediumVariant flags Starts creating a clone of this medium in the format and at the location defined by the target argument The target medium must be either in NotCreated state i e must not have an existing storage unit or in Created state i e created and not locked and big enough to hold the data or else the copy will be parti
183. asswordids wstring IAppliance getPasswordIds Returns a list of password identifiers which must be supplied to import or export encrypted virtual machines 5 3 6 getWarnings wstring IAppliance getWarnings Returns textual warnings which occurred during execution of interpret 55 5 Classes interfaces 5 3 7 importMachines IProgress IAppliance importMachines in ImportOptions options options Options for the importing operation Imports the appliance into VirtualBox by creating instances of IMachine and other interfaces that match the information contained in the appliance as closely as possible as represented by the import instructions in the virtualSystemDescriptions array Calling this method is the final step of importing an appliance into VirtualBox see Appliance for an overview Since importing the appliance will most probably involve copying and converting disk images which can take a long time this method operates asynchronously and returns an IProgress object to allow the caller to monitor the progress After the import succeeded the UUIDs of the IMachine instances created can be retrieved from the machines array attribute 5 3 8 interpret void IAppliance interpret Interprets the OVF data that was read when the appliance was constructed After calling this method one can inspect the virtualSystemDescriptions array attribute which will then contain one IVirtualSystemDescript
184. ast element in that chain must always be a base medium Note that several differencing media may be linked to the same parent medium Differencing media can be distinguished from base media by querying the parent attribute base media do not have parents they would depend on so the value of this attribute is always null for them Using this attribute it is possible to walk up the medium tree from the child medium to its parent It is also possible to walk down the tree using the children attribute Note that the type of all differencing media is normal all other values are meaningless for them Base media may be of any type Automatic composition of the file name part Another extension to the location attribute is that there is a possibility to cause VirtualBox to compose a unique value for the file name part of the location using the UUID of the hard disk This applies only to hard disks in NotCreated state e g before the storage unit is created and works as follows You set the value of the location attribute to a location specification which only contains the path specification but not the file name part and ends with either a forward slash or a backslash character In response VirtualBox will generate a new UUID for the hard disk and compose the file name using the following pattern lt path gt lt uuid gt lt ext gt where lt path gt is the supplied path specification lt uuid gt is the newly generated UUID and lt ext
185. at resize does not create a full temporary copy of the medium so the additional disk space requirement is usually much lower than using the clone operation This medium will be placed to LockedWrite state for the duration of this operation Please note that the results can be either returned straight away or later as the result of the background operation via the object returned via the progress parameter If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED Medium format does not support resizing 5 87 21 setids void IMedium setIds in boolean setImageld in uuid imageld in boolean setParentId in uuid parentId setlmageld Select whether a new image UUID is set or not imageld New UUID for the image If an empty string is passed then a new UUID is automatically created provided that setImageld is true Specifying a zero UUID is not allowed setParentld Select whether a new parent UUID is set or not parentld New parent UUID for the image If an empty string is passed then a new UUID is automatically created provided setParentId is true A zero UUID is valid Changes the UUID and parent UUID for a hard disk medium 5 87 22 setLocation IProgress IMedium setLocation in wstring location location New location Changes the location of this medium Some medium types may support changing the storage unit location by simply changing the value of the associated property In t
186. ave more than one of them As before drives can only be changed while the VM is powered off Mounting or unmounting removable media at runtime is possible with IMachine mountMedium Newly created virtual machines have no storage controllers associated with them Even the IDE Controller needs to be created explicitly The floppy controller is now visible as a separate controller with a new storage bus type For each storage bus type you can query the device types which can be attached so that it is not necessary to hardcode any attachment rules This required matching changes e g in the callback interfaces the medium specific change notification was replaced by a generic medium change notification and removing associ ated enums e g DriveState In many places the incorrect use of the plural form media was replaced by medium to improve consistency Reading the IMedium state attribute no longer automatically performs an accessibility check a new method IMedium refreshState does this The attribute only returns the state now There were substantial changes related to snapshots triggered by the branched snap shots functionality introduced with version 3 1 IConsole discardSnapshot was re named to IConsole deleteSnapshot IConsole discardCurrentState and ICon sole discardCurrentSnapshotAndState were removed corresponding new functionality is in IConsole restoreSnapshot Also when IConsole takeSnapshot
187. be enabled 5 80 1 75 lOCacheSize read write unsigned long IMachine I0CacheSize Maximum size of the I O cache in MB 5 80 1 76 PCIDeviceAssignments read only IPCIDeviceAttachment IMachine PCIDeviceAssignments Array of PCI devices assigned to this machine to get list of all PCI devices attached to the machine use IConsole attachedPCIDevices attribute as this attribute is intended to list only devices additional to what described in virtual hardware config Usually this list keeps host s physical devices assigned to the particular machine 178 5 Classes interfaces 5 80 1 77 bandwidthControl read only IBandwidthControl IMachine bandwidthControl Bandwidth control manager 5 80 1 78 tracingEnabled read write boolean IMachine tracingEnabled Enables the tracing facility in the VMM including PDM devices drivers The VMM will consume about 0 5MB of more memory when enabled and there may be some extra overhead from tracepoints that are always enabled 5 80 1 79 tracingConfig read write wstring IMachine tracingConfig Tracepoint configuration to apply at startup when tracingEnabled is true The string speci fies a space separated of tracepoint group names to enable The special group all enables all tracepoints Check DBGFR3TracingConfig for more details on available tracepoint groups and such Note that on hosts supporting DTrace or similar a lot of the tracepoints may be implemented exclu
188. been successfully opened Closing Guest file closing Closed Guest file has been closed Down Service OS is stopping guest file was closed Error Something went wrong 6 42 FirmwareType Firmware type BIOS BIOS Firmware EFI EFI Firmware bitness detected basing on OS type EFI32 EFI firmware 32 bit EFI64 EFI firmware 64 bit EFIDUAL EFI firmware combined 32 and 64 bit 6 43 FramebufferCapabilities Framebuffer capability flags Updatelmage Requires NotifyUpdateImage NotifyUpdate must not be called VHWA Supports VHWA interface If set then IFramebuffer processVHWACommand can be called VisibleRegion Supports visible region If set then IFramebuffer setVisibleRegion can be called 6 44 FsObjMoveFlags File moving flags None No flag set Replace Replace the destination file symlink etc if it exists however this does not allow re placing any directories FollowLinks Follow symbolic links in the final components or not only applied to the given source and target paths not to anything else AllowDirectoryMoves Allow moving directories accross file system boundraries Because it is could be a big undertaking we require extra assurance that we should do it when re quested 345 6 Enumerations enums 6 45 FsObjRenameFlag Flags for use when renaming file system objects files directories symlink etc see IGuestSession fsObjRename NoReplace Do not replace any destination object Repla
189. ber of elements in each returned array is the same and corresponds to the number of supported properties The returned arrays are filled in only if the Properties flag is set All arguments must be non null See also DataType DataFlags 5 92 IMediumRegisteredEvent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well The given medium was registered or unregistered within this VirtualBox installation 245 5 Classes interfaces Note This event is not yet implemented 5 92 1 Attributes 5 92 1 1 mediumld read only uuid IMediumRegisteredEvent mediumId ID of the medium this event relates to 5 92 1 2 mediumType read only DeviceType IMediumRegisteredEvent mediumType Type of the medium this event relates to 5 92 1 3 registered read only boolean IMediumRegisteredEvent registered If true the medium was registered otherwise it was unregistered 5 93 IMouse The IMouse interface represents the virtual machine s mouse Used in IConsole mouse Through this interface the virtual machine s virtual mouse can be controlled 5 93 1 Attributes 5 93 1 1 absoluteSupported read only boolean IMouse absoluteSupported Whether the guest OS supports absolute mouse pointer positioning or not Note You can use the IMouseCapabilityChangedEvent event to be instantly informed about changes of this attribute during virtual machin
190. bind socket on 5 105 1 7 guestIP read only wstring INATRedirectEvent guestIP Guest ip address to redirect to 5 105 1 8 guestPort read only long INATRedirectEvent guestPort Guest port to redirect to 5 106 INetworkAdapter Represents a virtual network adapter that is attached to a virtual machine Each virtual machine has a fixed number of network adapter slots with one instance of this attached to each of them Call IMachine getNetworkAdapter to get the network adapter that is attached to a given slot in a given machine Each network adapter can be in one of five attachment modes which are represented by the NetworkAttachmentType enumeration see the attachmentType attribute 5 106 1 Attributes 5 106 1 1 adapterType read write NetworkAdapterType INetworkAdapter adapterType Type of the virtual network adapter Depending on this value VirtualBox will provide a differ ent virtual network hardware to the guest 5 106 1 2 slot read only unsigned long INetworkAdapter slot Slot number this adapter is plugged into Corresponds to the value you pass to IMachine getNetworkAdapter to obtain this instance 5 106 1 3 enabled read write boolean INetworkAdapter enabled Flag whether the network adapter is present in the guest system If disabled the virtual guest hardware will not contain this network adapter Can only be changed when the VM is not running 5 106 1 4 MACAddress read write wstr
191. box getMachines get 0 getName System out println nAttempting to start VM m start it mgr startVm m null 7000 u vbox getVersion n if ws mgr disconnect mgr cleanup For more a complete example see TestVBox java shipped with the SDK It contains excep tion handling and error printing code which is important for reliable larger scale projects It is good practice in long running API clients to process the system events every now and then in the main thread does not work in other threads As a rule of thumb it makes sense to process them every few 100msec to every few seconds This is done by calling mgr waitForEvents 0 This avoids that a large number of system events accumulate which can need a significant amount of memory and as they also play a role in object cleanup it helps freeing additional memory in a timely manner which is used by the API implementation itself Java s garbage collection approach already needs more memory due to the delayed freeing of memory used by no longer accessible objects and not processing the system events exacerbates the memory usage The TestVBox java example code sprinkles such lines over the code to achieve the desired effect In multi threaded applications it can be called from the main thread periodically Sometimes it s possible to use the non zero timeout variant of the method which then waits the specified number of milli
192. but for AC 97 there are several 5 4 1 6 audioDriver read write AudioDriverType IAudioAdapter audioDriver Audio driver the adapter is connected to This setting can only be changed when the VM is not running 57 5 Classes interfaces 5 4 1 7 propertiesList read only wstring IAudioAdapter propertiesList Array of names of tunable properties which can be supported by audio driver 5 4 2 getProperty wstring IAudioAdapter getProperty in wstring key key Name of the key to get Returns an audio specific property string If the requested data key does not exist this function will succeed and return an empty string in the value argument 5 4 3 setProperty void IAudioAdapter setProperty in wstring key in wstring value key Name of the key to set value Value to assign to the key Sets an audio specific property string If you pass null or empty string as a key value the given key will be deleted 5 5 IBIOSSettings The IBIOSSettings interface represents BIOS settings of the virtual machine This is used only in the IMachine BIOSSettings attribute 5 5 1 Attributes 5 5 1 1 logoFadeln read write boolean IBIOSSettings logoFadeln Fade in flag for BIOS logo animation 5 5 1 2 logoFadeOut read write boolean IBIOSSettings LogoFadeOut Fade out flag for BIOS logo animation 5 5 1 3 logoDisplayTime read write unsigned long IBIOSSettings logoDisplayTime BIOS logo display time i
193. butes 5 142 1 1 device read only IUSBDevice IUSBDeviceStateChangedEvent device Device that is subject to state change 5 142 1 2 attached read only boolean IUSBDeviceStateChangedEvent attached true if the device was attached and false otherwise 5 142 1 3 error read only IVirtualBoxErrorInfo IUSBDeviceStateChangedEvent error null on success or an error message object on failure 5 143 IVBoxSVCAvailabilityChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when VBoxSVC becomes unavailable due to a crash or similar unexpected cir cumstances or available again 5 143 1 Attributes 5 143 1 1 available read only boolean IVBoxSVCAvailabilityChangedEvent available Whether VBoxSVC is available now 306 5 Classes interfaces 5 144 IVFSExplorer The VFSExplorer interface unifies access to different file system types This includes local file systems as well remote file systems like S3 For a list of supported types see VFSType An instance of this is returned by IAppliance createVFSExplorer 5 144 1 Attributes 5 144 1 1 path read only wstring IVFSExplorer path Returns the current path in the virtual file system 5 144 1 2 type read only VFSType IVFSExplorer type Returns the file system type which is currently in use 5 144 2 cd IProgress IVFSExplorer cd in wstring dir dir The name of t
194. calling WebsessionManager logon Upon logon the websession manager creates one instance of IVirtualBox which can be used for directly performing calls to its methods or used as a parameter for calling some methods of IWebsessionManager Creating Main API session objects is performed using IWebsessionManager getSessionObject Technically there is always only one VirtualBox object which is shared between all web sessions and clients as it is a COM singleton However each session receives its own managed object reference to it 2 Whenever a web service clients invokes an operation whose COM implementation creates COM objects For example IVirtualBox createMachine creates a new instance of IMachine the COM object returned by the COM method call is then wrapped into a managed object reference by the web server and this reference is returned to the web service client Internally in the web service process each managed object reference is simply a small data structure containing a COM pointer to the real COM object the web session ID and the object ID This structure is allocated on creation and stored efficiently in hashes so that the web service can look up the COM object quickly whenever a web service client wishes to make a method call The random session ID also ensures that one web service client cannot intercept the objects of another Managed object references are not destroyed automatically and must be releas
195. calls powerUp The subsequent operations mirror the IConsole powerUp progress object Because IConsole powerUp may require some extra sub operations the IProgress operationCount may change at the completion of operation For details on the teleportation progress operation see IConsole powerUp The environment argument is a string containing definitions of environment variables in the following format NAME VALUE n NAME VALUE n where n is the new line character These environment variables will be appended to the environment of the VirtualBox server process If an environment variable exists both in the server process and in this list the value from this list takes precedence over the server s variable If the value of the environment variable is omitted this variable will be removed from the resulting environment If the environment string is null or empty the server environment is inherited by the started process as is If this method fails the following error codes may be reported e E_UNEXPECTED Virtual machine not registered e E_INVALIDARG Invalid session type type e VBOX_E_OBJECT_NOT_FOUND No machine matching machineld found e VBOX_E_INVALID_OBJECT_STATE Session already open or being opened VBOX_E_IPRT_ERROR Launching process for machine failed e VBOX_E_VM_ERROR Failed to assign machine to session 5 80 48 lockMachine void IMachine LockMachine in ISession session in LockType
196. cation type is set to external in the VM RemoteDisplay configuration and will be called from within the IWebsessionManager logon implementation As opposed to VRDEAuthLibrary there is no per VM setting for this as the webservice is a global resource if it is running Only for this setting for the webservice setting this value to a literal null string disables authentication meaning that IWebsessionManager logon will always succeed no matter what user name and password are supplied The initial value of this property is VBoxAuth meaning that the webservice will use the same authentication library that is used by default for VRDE again see VRDEAuthLibrary The format and calling convention of authentication libraries is the same for the webservice as it is for VRDE Note Setting this property to null or empty string will restore the initial value 5 135 1 24 defaultVRDEExtPack read write wstring ISystemProperties defaultVRDEExtPack The name of the extension pack providing the default VRDE This attribute is for choosing between multiple extension packs providing VRDE If only one is installed it will automatically be the default one The attribute value can be empty if no VRDE extension pack is installed For details about VirtualBox Remote Desktop Extension and how to implement one please refer to the VirtualBox SDK 5 135 1 25 logHistoryCount read write unsigned long ISystemProperties logHi
197. ccessful operation completion the storage units of all media in the chain between this source medium and the target medium including the source medium itself will be automati cally deleted and the relevant medium objects including this medium will become uninitialized This means that any attempt to call any of their methods or attributes will fail with the Object not ready E_ACCESSDENIED error Applied to the above example the forward merge of 236 5 Classes interfaces Base to Dif f_2 will delete and uninitialize both Base and Diff_1 media Note that Diff_2 in this case will become a base medium itself since it will no longer be based on any other medium Considering the above all of the following conditions must be met in order for the merge operation to succeed e Neither this source medium nor any intermediate differencing medium in the chain be tween it and the target medium is attached to any virtual machine e Neither the source medium nor the target medium is an Immutable medium e The part of the medium tree from the source medium to the target medium is a linear chain i e all medium in this chain have exactly one child which is the next medium in this chain The only exception from this rule is the target medium in the forward merge operation it is allowed to have any number of child media because the merge operation will not change its logical contents as it is seen by the guest OS or by children e None of t
198. ce void IMachine setBandwidthGroupForDevice in wstring name in long controllerPort in long device in IBandwidthGroup bandwidthGroup name Name of the storage controller controllerPort Storage controller port device Device slot in the given port bandwidthGroup New value for the bandwidth group or null for no group Sets the bandwidth group of an existing storage device The device must already exist see attachDevice for how to attach a new device The controllerPort and device parameters specify the device slot and have have the same meaning as with attachDevice If this method fails the following error codes may be reported e E_INVALIDARG SATA device SATA port IDE port or IDE slot out of range e VBOX_E_INVALID_OBJECT_STATE Attempt to modify an unregistered virtual machine e VBOX_E_INVALID_VM_STATE Invalid machine state 5 80 68 setBootOrder void IMachine setBootOrder in unsigned long position in DeviceType device position Position in the boot order 1 to the total number of devices the machine can boot from as returned by ISystemProperties maxBootPosition device The type of the device used to boot at the given position Puts the given device to the specified position in the boot order To indicate that no device is associated with the given position Null should be used todo setHardDiskBootOrder setNetworkBootOrder If this method fails the following error codes may be rep
199. ce This will attempt to replace any destination object other except directories The de fault is to fail if the destination exists 6 46 FsObjType File system object file types Unknown Used either if the object has type that is not in this enum or if the type has not yet been determined or set Fifo FIFO or named pipe depending on the platform terminology DevChar Character device Directory Directory DevBlock Block device File Regular file Symlink Symbolic link Socket Socket WhiteOut A white out file Found in union mounts where it is used for hiding files after deletion I think 6 47 GraphicsControllerType Graphics controller type used with IMachine unregister Null Reserved value invalid VBoxVGA Default VirtualBox VGA device VMSVGA VMware SVGA II device 6 48 GuestMonitorChangedEventType How the guest monitor has been changed Enabled The guest monitor has been enabled by the guest Disabled The guest monitor has been disabled by the guest NewOrigin The guest monitor origin has changed in the guest 346 6 Enumerations enums 6 49 GuestMonitorStatus The current status of the guest display Disabled The guest monitor is disabled in the guest Enabled The guest monitor is enabled in the guest 6 50 GuestMouseEventMode The mode relative absolute multi touch of a pointer event todo A clear pattern seems to be emerging that we should usually have multiple input devices a
200. ce is mapped to a structure Attributes that return this interface will not return an object but a complete structure containing the attributes listed below as structure members 5 55 1 Attributes 5 55 1 1 familyld read only wstring IGuestOSType familyId Guest OS family identifier string 5 55 1 2 familyDescription read only wstring IGuestOSType familyDescription Human readable description of the guest OS family 5 55 1 3 id read only wstring IGuestOSType id Guest OS identifier string 117 5 Classes interfaces 5 55 1 4 description read only wstring IGuestOSType description Human readable description of the guest OS 5 55 1 5 is64Bit read only boolean IGuestOSType is64Bit Returns true if the given OS is 64 bit 5 55 1 6 recommendedlOAPIC read only boolean IGuestOSType recommendedIOAPIC Returns true if IO APIC recommended for this OS type 5 55 1 7 recommendedVirtEx read only boolean IGuestOSType recommendedVirtEx Returns true if VI x or AMD V recommended for this OS type 5 55 1 8 recommendedRAM read only unsigned long IGuestOSType recommendedRAM Recommended RAM size in Megabytes 5 55 1 9 recommendedVRAM read only unsigned long IGuestOSType recommendedVRAM Recommended video RAM size in Megabytes 5 55 1 10 recommended2DVideoAcceleration read only boolean IGuestOSType recommended2DVideoAcceleration Returns true if 2D video
201. ces API client code should no longer rely on XPCOM spe cific interface names such as nsISupports nsIException and nsIEventQueue and replace them by the platform independent interface names IUnknown and IErrorInfo for the first two respectively Event queue handling should be replaced by using the platform independent way described in chapter 2 3 6 7 Event handling page 43 Finally adjust the string and array handling to use the new helpers as these make sure the code works without changes with both COM and XPCOM which are significantly different in 45 2 Environment specific notes this area The code should be double checked if it uses the correct way to manage memory and is freeing it only after the last use 2 3 6 11 Legacy C binding to VirtualBox API for XPCOM Note This section applies to Linux Mac OS X and Solaris hosts only and describes deprecated use of the API from C Starting with version 2 2 VirtualBox offers a C binding for its API which works only on plat forms using XPCOM Refer to the old SDK documentation included in the SDK packages for version 4 3 6 or earlier it still applies unchanged The fundamental concepts are similar but the syntactical details are quite different to the newer cross platform C binding which should be used for all new code as the support for the old C binding will go away in a major release after version 4 3 46 3 Basic VirtualBox concepts some examples The followi
202. chine in wstring settingsFile in wstring name in wstring groups in wstring osTypeld in wstring flags settingsFile Fully qualified path where the settings file should be created empty string or null for a default folder and file based on the name argument and the primary group see composeMachineFilename name Machine name groups Array of group names null or an empty array have the same meaning as an array with just the empty string or i e create a machine without group association osTypeld Guest OS Type ID flags Additional property parameters passed as a comma separated list of name value type entries The following ones are recognized forceOverwrite 1 to overwrite an existing machine settings file UUID lt uuid gt to specify a machine UUID and directoryIncludesUUID 1 to switch to a special VM directory naming scheme which should not be used unless necessary Creates a new virtual machine by creating a machine settings file at the given location VirtualBox machine settings files use a custom XML dialect Starting with VirtualBox 4 0 a vbox extension is recommended but not enforced and machine files can be created at arbitrary locations However it is recommended that machines are created in the default machine folder e g home user VirtualBox VMs name name vbox see ISystemProperties defaultMachineFolder If you specify null or empty string which is recommended for the set
203. chine getParallelPort in unsigned long slot slot Returns the parallel port associated with the given slot Slots are numbered sequen tially starting with zero The total number of parallel ports per machine is defined by the ISystemProperties parallelPortCount property so the maximum slot number is one less than that property s value If this method fails the following error codes may be reported e E_INVALIDARG Invalid slot number 5 80 40 getSerialPort ISerialPort IMachine getSerialPort in unsigned long slot slot Returns the serial port associated with the given slot Slots are numbered sequen tially starting with zero The total number of serial ports per machine is defined by the ISystemProperties serialPortCount property so the maximum slot number is one less than that property s value If this method fails the following error codes may be reported e E_INVALIDARG Invalid slot number 195 5 Classes interfaces 5 80 41 getStorageControllerByinstance IStorageController IMachine getStorageControllerByInstance in StorageBus connectionType in unsigned long instance connectionType instance Returns a storage controller of a specific storage bus with the given instance number If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND A storage controller with given instance number doesn t exist 5 80 42 getStorageControllerByName IStorageCo
204. chineStateChangedEvent IMachineEvent Note This interface extends IMachineEvent and therefore supports all its methods and attributes as well Machine state change event 5 85 1 Attributes 5 85 1 1 state read only MachineState IMachineStateChangedEvent state New execution state 222 5 Classes interfaces 5 86 IManagedObjectRef Note This interface is supported in the web service only not in COM XPCOM Managed object reference Only within the webservice a managed object reference which is really an opaque number allows a webservice client to address an object that lives in the address space of the webservice server Behind each managed object reference there is a COM object that lives in the webser vice server s address space The COM object is not freed until the managed object refer ence is released either by an explicit call to release or by logging off from the webservice IWebsessionManager logoffQ which releases all objects created during the webservice ses sion Whenever a method call of the VirtualBox API returns a COM object the webservice represen tation of that method will instead return a managed object reference which can then be used to invoke methods on that object 5 86 1 getinterfaceName wstring IManagedObjectRef getInterfaceName Returns the name of the interface that this managed object represents for example IMa chine as a string 5 86
205. coding all arguments of the remote procedure call which could involve all kinds of type conversions and complex marshalling for arrays and structures 3 connect to the web service via HTTP and send that message 4 wait for the web service to send a response message 5 decode that response message and put the return value of the remote procedure into the result variable Service descriptions in WSDL In the above explanations about SOAP it was left open how the programming language learns about how to translate function calls in its own syntax into proper SOAP messages In other words the programming language needs to know what opera tions the web service supports and what types of arguments are required for the operation s data in order to be able to properly serialize and deserialize the data to and from the web service For example if a web service operation expects a number in double floating point format for a particular parameter the programming language cannot send to it a string instead For this the Web Service Definition Language WSDL was invented another XML substandard that describes exactly what operations the web service supports and for each operation which parameters and types are needed with each request and response message WSDL descriptions can be incredibly verbose and one of the few good things that can be said about this standard is that it is indeed supported by most programming languages So if i
206. controller with given name exists already e E_INVALIDARG Invalid controllerType 5 80 3 addUSBController IUSBController IMachine addUSBController in wstring name in USBControllerType type name type 180 5 Classes interfaces Adds a new USB controller to the machine and returns it as an instance of IUSBController If this method fails the following error codes may be reported e VBOX_E_OBJECT_IN_USE A USB controller with given type exists already e E_INVALIDARG Invalid controllerType 5 80 4 adoptSavedState void IMachine adoptSavedState in wstring savedStateFile savedStateFile Path to the saved state file to adopt Associates the given saved state file to the virtual machine On success the machine will go to the Saved state Next time it is powered up it will be restored from the adopted saved state and continue execution from the place where the saved state file was created The specified saved state file path may be absolute or relative to the folder the VM normally saves the state to usually snapshotFolder Note It s a caller s responsibility to make sure the given saved state file is compatible with the settings of this virtual machine that represent its virtual hardware memory size storage disk configuration etc If there is a mismatch the behavior of the virtual machine is undefined If this method fails the following error codes may be reported e VBOX_E_IN
207. cted by the DBGF This feature is not implemented in the 4 0 0 release but may show up in a dot release 5 82 1 19 OSVersion read only wstring IMachineDebugger 0SVersion Query the guest OS kernel version string as detected by the DBGF This feature is not implemented in the 4 0 0 release but may show up in a dot release 5 82 1 20 PAEEnabled read only boolean IMachineDebugger PAEEnabled Flag indicating whether the VM is currently making use of the Physical Address Extension CPU feature 216 5 Classes interfaces 5 82 1 21 virtualTimeRate read write unsigned long IMachineDebugger virtualTimeRate The rate at which the virtual time runs expressed as a percentage The accepted range is 2 to 20000 5 82 1 22 VM read only long long IMachineDebugger VM Gets the user mode VM handle with a reference Must be passed to VMR3ReleaseUVM when done This is only for internal use while we carve the details of this interface 5 82 2 detectOS wstring IMachineDebugger detect0S Tries to re detect the guest OS kernel This feature is not implemented in the 4 0 0 release but may show up in a dot release 5 82 3 dumpGuestCore void IMachineDebugger dumpGuestCore in wstring filename in wstring compression filename The name of the output file The file must not exist compression Reserved for future compression method indicator Takes a core dump of the guest See include VBox dbgfcorefmt h fo
208. ctive for different types of reporting so we should really have different event types for relative including wheel absolute not including wheel and multi touch events Relative Relative event Absolute Absolute event 6 51 GuestSessionStatus Guest session status This enumeration represents possible values of the IGuestSession status attribute Undefined Guest session is in an undefined state Starting Guest session is being started Started Guest session has been started Terminating Guest session is being terminated Terminated Guest session terminated normally TimedOutKilled Guest session timed out and was killed TimedOutAbnormally Guest session timed out and was not killed successfully Down Service OS is stopping guest session was killed Error Something went wrong 6 52 GuestSessionWaitForFlag Guest session waiting flags Multiple flags can be combined None No waiting flags specified Do not use this Start Wait for the guest session being started Terminate Wait for the guest session being terminated Status Wait for the next guest session status change 347 6 Enumerations enums 6 53 GuestSessionWaitResult Guest session waiting results Depending on the session waiting flags for more information see GuestSessionWaitForFlag the waiting result can vary based on the session s current status To wait for a guest session to terminate after it has been created by IGuest createSession one would
209. ctly When a hard disk is being attached directly it is associated with the virtual machine and used for hard disk operations when the machine is running When a hard disk is being attached indirectly a new differencing hard disk linked to it is implicitly created and this differencing hard disk is associated with the machine and used for hard disk operations This also means that if IMachine attachDevice performs a direct attachment then the same hard disk will be returned in response to the subsequent IMachine getMedium call however if an indirect attachment is performed then IMachine getMedium will return the implicitly created differencing hard disk not the original one passed to IMachine attachDevice In detail e Normal base hard disks that do not have children i e differencing hard disks linked to them and that are not already attached to virtual machines in snapshots are attached directly Otherwise they are attached indirectly because having dependent children or being part of the snapshot makes it impossible to modify hard disk contents without break ing the integrity of the dependent party The IMedium readOnly attribute allows to quickly determine the kind of the attachment for the given hard disk Note that if a normal base hard disk is to be indirectly attached to a virtual machine with snapshots then a special procedure called smart attachment is performed see below Normal differencing hard disks are like normal ba
210. ctx global constants VBoxEventType_Any False registered True end time time dur while time time lt end ev agg getEvent listener 1000 processEent ev agg unregisterListener listener Without using aggregators consumer have to poll on both sources or start multiple threads to block on those sources 49 4 The VirtualBox shell VirtualBox comes with an extensible shell which allows you to control your virtual machines from the command line It is also a nontrivial example of how to use the VirtualBox APIs from Python for all three COM XPCOM WS styles of the API You can easily extend this shell with your own commands Create a subdirectory named config VirtualBox shexts below your home directory respectively VirtualBox shexts on a Windows system and Library VirtualBox shexts on OS X and put a Python file imple menting your shell extension commands in this directory This file must contain an array named commands containing your command definitions commands cmd1 Command cmdl help cmdl cmd2 Command cmd2 help cmd2 For example to create a command for creating hard drive images the following code can be used def createHdd ctx args Show some meaningful error message on wrong input if len args lt 3 print usage createHdd sizeM location type return 0 Get arguments size int args 1 loc args 2 if len args gt 3 format args 3 else A
211. d Status The process has changed its status The status then can be retrieved via IProcess status Error Error while executing the process Timeout The waiting operation timed out Also use if the guest process has timed out in the guest side kill attempted Stdin The process signalled that stdin became available for writing StdOut Data on stdout became available for reading StdErr Data on stderr became available for reading WaitFlagNotSupported A waiting flag specified in the IProcess waitFor call is not supported by the guest 6 86 ProcessorFeature CPU features HWVirtEx PAE LongMode NestedPaging 6 87 Reason Internal event reason type Unspecified Null value means no known reason HostSuspend Host is being suspended power management event HostResume Host is being resumed power management event HostBatteryLow Host is running low on battery power management event Snapshot A snapshot of the VM is being taken 362 6 Enumerations enums 6 88 Scope Scope of the operation A generic enumeration used in various methods to define the action or argument scope Global Machine Session 6 89 SessionState Session state This enumeration represents possible values of IMachine sessionState and ISession state attributes Null Null value never used by the API Unlocked In IMachine sessionState this means that the machine is not locked for any sessions In ISession state this means
212. d but instead of opening a direct session on a machine all documentation now refers to obtaining a write lock on a machine for the client ses sion Similarly replace any IVirtualBox openExistingSession uuidMachine call with the machine s IMachine lockMachine call and a LockType Shared argu ment Whereas it was previously impossible to connect a client session to a run ning VM process in a race free manner the new API will atomically either write lock the machine for the current session or establish a remote link to an exist ing session Existing client code which tried calling both openSession and openExistingSession can now use this one call instead Third replace any IVirtualBox openRemoteSession uuidMachine call with the machine s IMachine launchVMProcess call The functionality is un changed 396 13 Main API change log The SessionState enum was adjusted accordingly Open is now Locked Closed is now Unlocked Closing is now Unlocking e Virtual machines created with VirtualBox 4 0 or later no longer register their media in the global media registry in the VirtualBox xml file Instead such machines list all their media in their own machine XML files As a result a number of media related APIs had to be modified again Neither IVirtualBox createHardDisk nor IVirtualBox openMedium register media automatically any more IMachine at
213. d in most cases use the same programming language web services use Internet standards such as HTTP and XML to communicate In order to successfully use a web service a number of things are required primarily a web service accepting connections service descriptions and then a client that connects to that web service The connections are governed by the SOAP standard which describes how messages are to be exchanged between a service and its clients the service descriptions are governed by WSDL In the case of VirtualBox this translates into the following three components 1 The VirtualBox web service the server this is the vboxwebs rv executable shipped with VirtualBox Once you start this executable which acts as a HTTP server on a specific TCP IP port clients can connect to the web service and thus control a VirtualBox installa tion 2 VirtualBox also comes with WSDL files that describe the services provided by the web ser vice You can find these files in the sdk bindings webservice directory These files are understood by the web service toolkits that are shipped with most programming languages and enable you to easily access a web service even if you don t use our object oriented client layers VirtualBox is shipped with pregenerated web service glue code for several languages Python Perl Java 3 A client that connects to the web service in order to control the VirtualBox installation Unless you play wit
214. d object will result in an error 5 13 1 7 debugger read only IMachineDebugger IConsole debugger Debugging interface 5 13 1 8 USBDevices read only IUSBDevice IConsole USBDevices Collection of USB devices currently attached to the virtual USB controller Note The collection is empty if the machine is not running 5 13 1 9 remoteUSBDevices read only IHostUSBDevice IConsole remoteUSBDevices List of USB devices currently attached to the remote VRDE client Once a new device is phys ically attached to the remote host computer it appears in this list and remains there until de tached 5 13 1 10 sharedFolders read only ISharedFolder IConsole sharedFolders Collection of shared folders for the current session These folders are called transient shared folders because they are available to the guest OS running inside the associated virtual machine only for the duration of the session as opposed to IMachine sharedFolders which represent permanent shared folders When the session is closed e g the machine is powered down these folders are automatically discarded New shared folders are added to the collection using createSharedFolder Existing shared folders can be removed using removeSharedFolder 64 5 Classes interfaces 5 13 1 11 VRDEServerlinfo read only IVRDEServerInfo IConsole VRDEServerInfo Interface that provides information on Remote Desktop Extension V
215. d only boolean IGuestOSType recommendedUSBHID Returns true if using USB Human Interface Devices such as keyboard and mouse recom mended 5 55 1 21 recommendedHPET read only boolean IGuestOSType recommendedHPET Returns true if using HPET is recommended for this OS type 5 55 1 22 recommendedUSBTablet read only boolean IGuestOSType recommendedUSBTablet Returns true if using a USB Tablet is recommended 119 5 Classes interfaces 5 55 1 23 recommendedRTCUseUTC read only boolean IGuestOSType recommendedRTCUseUTC Returns true if the RTC of this VM should be set to UTC 5 55 1 24 recommendedChipset read only ChipsetType IGuestOSType recommendedChipset Recommended chipset type 5 55 1 25 recommendedAudioController read only AudioControllerType IGuestOSType recommendedAudioController Recommended audio controller type 5 55 1 26 recommendedAudioCodec read only AudioCodecType IGuestOSType recommendedAudioCodec Recommended audio codec type 5 55 1 27 recommendedFloppy read only boolean IGuestOSType recommendedFloppy Returns true a floppy drive is recommended for this OS type 5 55 1 28 recommendedUSB read only boolean IGuestOSType recommendedUSB Returns true a USB controller is recommended for this OS type 5 55 1 29 recommendedTFReset read only boolean IGuestOSType recommendedTFReset Returns true if using VCPU reset on triple fault is recommended for this OS typ
216. d only wstring IHostVideoInputDevice name User friendly name 151 5 Classes interfaces 5 75 1 2 path read only wstring IHostVideoInputDevice path The host path of the device 5 75 1 3 alias read only wstring IHostVideoInputDevice alias An alias which can be used for IConsole webcamAttach 5 76 linternalMachineControl Note This interface is not supported in the web service 5 76 1 authenticateExternal void IInternalMachineControl authenticateExternal in wstring authParams out wstring result authParams The auth parameters credentials etc result The authentification result Verify credentials using the external auth library 5 76 2 autoCaptureUSBDevices void IInternalMachineControl autoCaptureUSBDevices Requests a capture all matching USB devices attached to the host When the request is com pleted the VM process will get a IInternalSessionControl onUSBDeviceAttach notification per every captured device 5 76 3 beginPowerUp void IInternalMachineControl beginPowerUp in IProgress progress progress Tells VBoxSVC that IConsole powerUp is under ways and gives it the progress object that should be part of any pending IMachine launchVMProcess operations The progress object may be called back to reflect an early cancelation so some care have to be taken with respect to any cancelation callbacks The console object will call endPowerUp to signal the c
217. d to given slot bus 5 80 36 getMediumAttachment IMediumAttachment IMachine getMediumAttachment in wstring name in long controllerPort in long device name controllerPort device Returns a medium attachment which corresponds to the controller with the given name on the given port and device slot If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND No attachment exists for the given controller port device combination 194 5 Classes interfaces 5 80 37 getMediumAttachmentsOfController IMediumAttachment IMachine getMediumAttachmentsOfController in wstring name name Returns an array of medium attachments which are attached to the the controller with the given name If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND A storage controller with given name doesn t exist 5 80 38 getNetworkAdapter INetworkAdapter IMachine getNetworkAdapter in unsigned long slot slot Returns the network adapter associated with the given slot Slots are numbered sequen tially starting with zero The total number of adapters per machine is defined by the ISystemProperties getMaxNetworkAdapters property so the maximum slot number is one less than that property s value If this method fails the following error codes may be reported e E_INVALIDARG Invalid slot number 5 80 39 getParallelPort IParallelPort IMa
218. d to it or this method will fail Note You cannot attach a device to a newly created machine until this machine s settings are saved to disk using saveSettings Note If the medium is being attached indirectly a new differencing medium will implicitly be created for it and attached instead If the changes made to the machine settings including this indirect attachment are later cancelled using discardSettings this implicitly created differencing medium will implicitly be deleted If this method fails the following error codes may be reported 182 5 Classes interfaces E_INVALIDARG SATA device SATA port IDE port or IDE slot out of range or file or UUID not found e VBOX_E_INVALID_OBJECT_STATE Machine must be registered before media can be at tached e VBOX_E_INVALID_VM_STATE Invalid machine state e VBOX_E_OBJECT_IN_USE A medium is already attached to this or another virtual ma chine 5 80 7 attachDeviceWithoutMedium void IMachine attachDeviceWithoutMedium in wstring name in long controllerPort in long device in DeviceType type name Name of the storage controller to attach the device to controllerPort Port to attach the device to For an IDE controller 0 specifies the primary con troller and 1 specifies the secondary controller For a SCSI controller this must range from O to 15 for a SATA controller from O to 29 for an SAS controller from 0 to 7 device D
219. d when one need to be able to wait for particular event processed for example for vetoable changes or if event refers to some resource which need to be kept immutable until all consumers confirmed events 5 23 2 setProcessed void IEvent setProcessed Internal method called by the system when all listeners of a particular event have called IEventSource eventProcessed This should not be called by client code 86 5 Classes interfaces 5 23 3 waitProcessed boolean IEvent waitProcessed in long timeout timeout Maximum time to wait for event processing in ms 0 no wait 1 indefinite wait Wait until time outs or this event is processed Event must be waitable for this operation to have described semantics for non waitable returns true immediately 5 24 lEventListener Event listener An event listener can work in either active or passive mode depending on the way it was registered See Event for an introduction to VirtualBox event handling 5 24 1 handleEvent void IEventListener handleEvent in IEvent event event Event available Handle event callback for active listeners It is not called for passive listeners After calling handleEventQ on all active listeners and having received acknowledgement from all passive listeners via IEventSource eventProcessed the event is marked as processed and IEvent waitProcessed will return immediately 5 25 lEventSource Event source Generally any ob
220. dE vent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well The configuration of the given medium was changed location properties child parent or anything else Note This event is not yet implemented 5 90 1 Attributes 5 90 1 1 medium read only IMedium IMediumConfigChangedEvent medium ID of the medium this event relates to 5 91 IMediumFormat The IMediumFormat interface represents a medium format Each medium format has an associated backend which is used to handle media stored in this format This interface provides information about the properties of the associated backend Each medium format is identified by a string represented by the id attribute This string is used in calls like IVirtualBox createMedium to specify the desired format The list of all supported medium formats can be obtained using ISystemProperties mediumFormats See also Medium 5 91 1 Attributes 5 91 1 1 id read only wstring IMediumFormat id Identifier of this format The format identifier is a non null non empty ASCII string Note that this string is case insensitive This means that for example all of the following strings VDI ydi Val refer to the same medium format This string is used in methods of other interfaces where it is necessary to specify a medium format such as IVirtualBox createMedium 5 91 1 2 name read only ws
221. dEvent Event lt 4 6 600684 4 4 oe os 267 Bo Attributes 2 5 4 4 sa see eee ee da DA Se oa eee RS 267 5 112 IPerformanceCollector 2 ee 267 STILL ARTIE cocaina tacita 440444 6405 4R Gas 268 51122 ASabIENISTEES ssp dk ww Hee a ee ee ae G 268 5 112 3 enabled o kg ee Ba ER er ee E a a 269 5 1124 DOLEWISIOS ke es ee we a a a a 269 5112 5 gqueyMetmicsDala coccion 269 5 1126 setupMemiog occ A AAA 270 5 113 Performance Mere a id a we a 271 CIIL ADES os ee Ss e a a a 271 AMEN 272 STAL ARTBMES 4 2 0 500423 tba 444444 aaa aa 272 AMAS TEL o ii daa a ae ee ee a 273 5 1143 terminate so so nocere eei a 273 LM MIO s oee e ces A a wg BP a d 273 SLAS WAOANA y o oc ee eR RE Oe Pewee EEE OP Ee ROS 273 RAS METE ad cocks ek a a Reh goal dl al Be a 274 cL WESTIN A bgp WS a a A a a 274 BL LS IPrOEIESS cc Gk he a See SS Bw me ew a Oe ee 274 Del loc AROS a bk bh Ge eee a EEE EE eS 275 A Caneel AIN 277 5 1153 setG rrentOperationPrOgreSS so coo 277 5 1154 SetNextOperatlO o occiso a aaa e 277 5 115 5 waitForAsyncProgressCompletion o o 277 5 115 6 waithorCompletion 2 oz o coords 45444445504 278 5 115 7 waitForOperationCompletion o o 1 278 5 116 IReusableEvent IEvent lt c coen coe eeraa npe t eee He 278 5 116 1 Attributes ee ptd na kepere ni 278 SEAE 2 ii bee Deed A EE eA 278 5 117 IRuntimeErrorEvent lEvent 279 ALFA IOUS da ee we A A a a 279 ALS ISERSPORE cocina a a aa 280
222. data This data can be stored within the source directly or can be retrieved on demand by the source itself Other interfaces don t care where the data from this source actually came from The target on the other hand is the side which provides the source a visual representation where the user can drop the data the source offers This representation can be a window or just a certain part of it for example The source and the target have abstract interfaces called IDnDSource and IDnDTarget VirtualBox also provides implementations of both interfaces called IGuestDnDSource and IGuestDnDTarget Both implementations are also used in the VirtualBox Manager frontend 9 2 Supported formats As the target needs to perform specific actions depending on the data the source provided the target first needs to know what type of data it actually is going to retrieve It might be that the source offers data the target cannot or intentionally does not want to support VirtualBox handles those data types by providing so called MIME types these MIME types were originally defined in RFC2046 and are also called Content types IGuestDnDSource and IGuestDnDTarget support the following MIME types by default e text uri list A list of URIs Uniform Resource Identifier see RFC3986 pointing to the file and or directory paths already transferred from the source to the target e text plain charset utf 8 and UTF8_STRING text in UTE 8 format e text plain
223. dditions You may use IVirtualBox getGuestOSType to obtain an IGuestOSType object representing details about the given Guest OS type Note If Guest Additions are not installed this value will be the same as IMachine OSTypeld 106 5 Classes interfaces 5 38 1 2 additionsRunLevel read only AdditionsRunLevelType IGuest additionsRunLevel Current run level of the installed Guest Additions 5 38 1 3 additionsVersion read only wstring IGuest additionsVersion Version of the installed Guest Additions in the same format as IVirtualBox version 5 38 1 4 additionsRevision read only unsigned long IGuest additionsRevision The internal build revision number of the installed Guest Additions See also IVirtualBox revision 5 38 1 5 dnDSource read only IGuestDnDSource IGuest dnDSource Retrieves the drag n drop source implementation for the guest side that is handling and retrieving drag n drop data from the guest 5 38 1 6 dnDTarget read only IGuestDnDTarget IGuest dnDTarget Retrieves the drag n drop source implementation for the host side This will allow the host to handle and initiate a drag n drop operation to copy data from the host to the guest 5 38 1 7 eventSource read only IEventSource IGuest eventSource Event source for guest events 5 38 1 8 facilities read only IAdditionsFacility IGuest facilities Returns a collection of current known facilities Only r
224. de to call the listener s IEventListener handleEvent method When done with an event the external code must call eventProcessed 88 5 Classes interfaces Register an event listener Note To avoid system overload the VirtualBox server process checks if pas sive event listeners call getEvent frequently enough In the current implemen tation if more than 500 pending events are detected for a passive event listener it is forcefully unregistered by the system and further getEvent calls will return VBOX_E_OBJECT_NOT_ FOUND 5 25 7 unregisterListener void IEventSource unregisterListener in IEventListener listener listener Listener to unregister Unregister an event listener If listener is passive and some waitable events are still in queue they are marked as processed automatically 5 26 lEventSourceChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when an event source state changes listener added or removed 5 26 1 Attributes 5 26 1 1 listener read only IEventListener IEventSourceChangedEvent listener Event listener which has changed 5 26 1 2 add read only boolean IEventSourceChangedEvent add Flag whether listener was added or removed 5 27 lExtPack IExtPackBase Note This interface is not supported in the web service Note This interface extends
225. describe the hardware and software configuration of the virtual machine in detail i e network settings versions of the installed software and so on 5 80 1 7 id read only uuid IMachine id UUID of the virtual machine 5 80 1 8 groups read write wstring IMachine groups Array of machine group names of which this machine is a member and are synonyms for the toplevel group Each group is only listed once however they are listed in no particular order and there is no guarantee that there are no gaps in the group hierarchy i e group group subgroup subsubgroup is a valid result 5 80 1 9 OSTypeld read write wstring IMachine 0STypeld User defined identifier of the Guest OS type You may use IVirtualBox getGuestOSType to obtain an IGuestOSType object representing details about the given Guest OS type Note This value may differ from the value returned by IGuest OSTypeld if Guest Additions are installed to the guest OS 5 80 1 10 hardwareVersion read write wstring IMachine hardwareVersion Hardware version identifier Internal use only for now 169 5 Classes interfaces 5 80 1 11 hardwareUUID read write uuid IMachine hardwareUUID The UUID presented to the guest via memory tables hardware and guest properties For most VMs this is the same as the id but for VMs which have been cloned or teleported it may be the same as the source VM The latter is because the guest sh
226. device passthrough 189 5 Classes interfaces 5 80 19 discardSavedState void IMachine discardSavedState in boolean fRemoveFile fRemoveFile Whether to also remove the saved state file Forcibly resets the machine to Powered Off state if it is currently in the Saved state previ ously created by saveState Next time the machine is powered up a clean boot will occur Note This operation is equivalent to resetting or powering off the machine without doing a proper shutdown of the guest operating system as with resetting a running phyiscal computer it can can lead to data loss If fRemoveFile is true the file in the machine directory into which the machine state was saved is also deleted If this is false then the state can be recovered and later re inserted into a machine using adoptSavedState The location of the file can be found in the stateFilePath attribute If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine not in state Saved 5 80 20 discardSettings void IMachine discardSettings Discards any changes to the machine settings made since the session has been opened or since the last call to saveSettings or discardSettings Note Calling this method is only valid on instances returned by ISession machine and on new machines created by IVirtualBox createMachineQ or opened by IVirtualBox openMachine but not yet reg
227. dium base Base medium of this medium If this is a differencing medium its base medium is the medium the given medium branch starts from For all other types of media this property returns the medium object itself i e the same object this property is read on 5 87 1 17 readOnly read only boolean IMedium readOnly Returns true if this medium is read only and false otherwise A medium is considered to be read only when its contents cannot be modified without breaking the integrity of other parties that depend on this medium such as its child media or snapshots of virtual machines where this medium is attached to these machines If there are no children and no such snapshots then there is no dependency and the medium is not read only The value of this attribute can be used to determine the kind of the attachment that will take place when attaching this medium to a virtual machine If the value is false then the medium will be attached directly If the value is true then the medium will be attached indirectly by creating a new differencing child medium for that See the interface description for more information Note that all Immutable media are always read only while all Writethrough media are always not Note The read only condition represented by this attribute is related to the medium type and usage not to the current medium state and not to the read only state of the storage unit 228 5 Classes interfaces
228. domainName read only wstring IHost domainName Domain name used for name resolving 5 69 1 8 searchStrings read only wstring IHost searchStrings Search string registered for name resolving 5 69 1 9 processorCount read only unsigned long IHost processorCount Number of logical CPUs installed in the host system 5 69 1 10 processorOnlineCount read only unsigned long IHost processorOnlineCount Number of logical CPUs online in the host system 5 69 1 11 processorCoreCount read only unsigned long IHost processorCoreCount Number of physical processor cores installed in the host system 142 5 Classes interfaces 5 69 1 12 processorOnlineCoreCount read only unsigned long IHost processorOnlineCoreCount Number of physical processor cores online in the host system 5 69 1 13 memorySize read only unsigned long IHost memorySize Amount of system memory in megabytes installed in the host system 5 69 1 14 memoryAvailable read only unsigned long IHost memoryAvailable Available system memory in the host system 5 69 1 15 operatingSystem read only wstring IHost operatingSystem Name of the host system s operating system 5 69 1 16 OSVersion read only wstring IHost 0SVersion Host operating system s version string 5 69 1 17 UTCTime read only long long IHost UTCTime Returns the current host time in milliseconds since 1970 01 01 UTC 5 69 1 18 acceleration3DAva
229. dr but the buffer is Type_LinAddr_ Out used only for guest to host data 6 VMMDevHGCMParm Same as VMMDevHGCMParmType_LinAddr but the buffer is Type_LinAddr_ Locked already locked by the guest 7 VMMDevHGCMParm Same as VMMDevHGCMParmType_LinAddr_In but the buffer is Type_LinAddr Locked In already locked by the guest 1 VMMDevHGCMParm Same as VMMDevHGCMParmType_LinAddr_Out but the buffer Type _LinAddr Locked_Out is already locked by the guest 1 The 7 2 5 Cancel This request cancels a call request VMMDevHGCMCancel Name Description header The generic HGCM request header with type equal to VUMDevReq_HGCMCancel 64 7 3 Guest software interface The guest HGCM clients can call HGCM services from both drivers and applications 7 3 1 The guest driver interface The driver interface is implemented in the VirtualBox guest additions driver VBoxGuest which works with the VMM virtual device Drivers must use the VBox Guest Library VBGL which provides an API for HGCM clients VBox VBoxGuestLib h and VBox VBoxGuest h DECLVBGL int VbglHGCMConnect VBGLHGCMHANDLE pHandle VBoxGuestHGCMConnectInfo pData Connects to the service VBoxGuestHGCMConnectInfo data 375 7 Host Guest Communication Manager memset amp data sizeof VBoxGuestHGCMConnectInfo data result VINF_SUCCESS data Loc type VMMDevHGCMLoc_LocalHost_Existing strcpy data Loc u host achName VBoxSharedFolders
230. e 5 56 IGuestProcess IProcess Note This interface extends IProcess and therefore supports all its methods and at tributes as well Implementation of the IProcess object for processes the host has started in the guest 5 56 1 Attributes 5 56 1 1 midlDoesNotLikeEmptyInterfaces read only boolean IGuestProcess midlDoesNotLikeEmptyInterfaces 120 5 Classes interfaces 5 57 IGuestProcessEvent IGuestSessionEvent Note This interface extends IGuestSessionEvent and therefore supports all its methods and attributes as well Base abstract interface for all guest process events 5 57 1 Attributes 5 57 1 1 process read only IGuestProcess IGuestProcessEvent process Guest process object which is related to this event 5 57 1 2 pid read only unsigned long IGuestProcessEvent pid Guest process ID PID 5 58 IGuestProcesslOEvent IGuestProcessEvent Note This interface extends IGuestProcessEvent and therefore supports all its methods and attributes as well Base abstract interface for all guest process input output IO events 5 58 1 Attributes 5 58 1 1 handle read only unsigned long IGuestProcessI0Event handle Input output IO handle involved in this event Usually 0 is stdin 1 is stdout and 2 is stderr 5 58 1 2 processed read only unsigned long IGuestProcessI0Event processed Processed input or output in bytes 5 59 IGuestProcessInputNotifyEvent IGue
231. e Removes the permanent shared folder with the given name previously created by createSharedFolder from the collection of shared folders and stops sharing it If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine is not mutable e VBOX_E_OBJECT_NOT_FOUND Shared folder name does not exist 5 80 61 removeStorageController void IMachine removeStorageController in wstring name name Removes a storage controller from the machine with all devices attached to it If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND A storage controller with given name doesn t exist e VBOX_E_NOT_SUPPORTED Medium format does not support storage deletion only for implicitly created differencing media should not happen 203 5 Classes interfaces 5 80 62 removeUSBController void IMachine removeUSBController in wstring name name Removes a USB controller from the machine If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND A USB controller with given type doesn t exist 5 80 63 restoreSnapshot IProgress IMachine restoreSnapshot in ISnapshot snapshot snapshot The snapshot to restore the VM state from Starts resetting the machine s current state to the state contained in the given snapshot asyn chronously All current settings of the machine will be reset and c
232. e and additionally needs to be passed a pointer to the objecti as the first argument to serve as the this pointer Using the C binding all method invocations return a numeric result code of type HRESULT with a few exceptions which normally are not relevant If an interface is specified as returning an object a pointer to a pointer to the appropriate object must be passed as the last argument The method will then store an object pointer in that location Likewise attributes properties can be queried or set using method invocations using spe cially named methods For each attribute there exists a getter method the name of which is composed of get_ followed by the capitalized attribute name Unless the attribute is read only an analogous set_ method exists Let s apply these rules to get the IVirtualBox reference an ISession instance reference and read the lVirtualBox revision attribute rc IVirtualBoxClient_get_VirtualBox vboxclient amp vbox if FAILED rc vbox PrintErrorInfo argv 0 FATAL could not get VirtualBox reference rc return EXIT_FAILURE rc IVirtualBoxClient_get_Session vboxclient amp session if FAILED rc session PrintErrorInfo argv 0 FATAL could not get Session reference rc return EXIT_FAILURE rc IVirtualBox_get_Revision vbox amp revision if SUCCEEDED rc printf Revision u n revision The convenience macros for calling a method are nam
233. e Filter name See IUSBDeviceFilter name for more info Creates a new USB device filter All attributes except the filter name are set to empty any match active is false the filter is not active The created filter can then be added to the list of filters using insertDeviceFilter See also deviceFilters If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE The virtual machine is not mutable 5 141 3 insertDeviceFilter void IUSBDeviceFilters insertDeviceFilter in unsigned long position in IUSBDeviceFilter filter position Position to insert the filter to filter USB device filter to insert Inserts the given USB device to the specified position in the list of filters Positions are numbered starting from 0 If the specified position is equal to or greater than the number of elements in the list the filter is added to the end of the collection Note Duplicates are not allowed so an attempt to insert a filter that is already in the collection will return an error See also deviceFilters If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine is not mutable e E_INVALIDARG USB device filter not created within this VirtualBox instance e VBOX_E_INVALID_OBJECT_STATE USB device filter already in list 5 141 4 removeDeviceFilter IUSBDeviceFilter IUSBDeviceFilters removeDeviceFilter in unsigned long po
234. e GG ee e 68 5 13 11 getGuestEnteredACPIMode ooe cco ee bbe ee ee ee ee trii 68 5 13 12 parPowerButronaadied eae a ed aw E 68 SAS lo DATE ge ab hk aa Oe ee ee a a 68 3 13 14 POET BONE y oo ia ask a a eg E ee a 68 5 13 15 PORRO 2 one eee cae ggg bbb POOR EES EE EE REE 69 51316 powerUp bi oop ee ee A eee pada s 69 SSI power prsascd wo ne ee Pe ete Se a ke ae h 69 5 13 18 removeDiskEncryptionPassword o o o 70 5 13 19 removebhacedRold r essa eee a 70 SALI PESE cs AAA Ra BAL a bob a 70 dla al TESIS e Ro A a 70 5 13 22 sleepBulto ooo a Ss 70 S1323 POIROT e a o e e A id ak 71 IDRUPSEIVED esos a Ee SES a A A EE Eo ORD OE 71 SILI AUTES ee el a ee ee we A de wl dt 71 5 15 5 16 S17 5 18 5 20 5 41 3 22 Contents 5 142 addGlobalOpiom s sesos a a ea e ww IEG a E 72 5 143 add mSlotOption 2 0 6 eee seana 224008 wan 72 SIPRI geMacOphonS ees seac ek ee ee ewe 72 5 14 5 wervindlotOptions aca 242225 4444444444880 aa 73 5 14 5 removeVmSlotOptions lt ssa coc we ee ee eee 73 5 14 7 setConfiguration 06 02 56 6 bs eS OSS ee ee ea ee ee 73 pe A mm TE E A E a E 73 Slee SOP ereraa e He SHE AA ES wae 74 IOMPBCIONE oie ae ee es eas BSS ee Oe ada a Be ee E 74 5 15 1 AMMDUIEE lt a a eRe ee Pa eee 74 SASS dlo cocoa aaa dads 74 DISS A a oe aes eS eee ah a we le ee ee ee we et apne BE 74 IDisplay AA 74 516 1 attachFramebuffer gt lt a xs a a a e ncn a ee 75 5 16 2 complete vHWACommadd
235. e PoweredOff state If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine must be Running Paused or Stuck to be powered down 5 13 16 powerUp IProgress IConsole powerUp Starts the virtual machine execution using the current machine state that is its current exe cution state current settings and current storage devices Note This method is only useful for front ends that want to actually execute virtual machines in their own process like the VirtualBox or VBoxSDL front ends Unless you are intending to write such a front end do not call this method If you simply want to start virtual machine execution using one of the existing front ends for example the VirtualBox GUI or headless server use IMachine launchVMProcess instead these front ends will power up the machine automatically for you If the machine is powered off or aborted the execution will start from the beginning as if the real hardware were just powered on If the machine is in the Saved state it will continue its execution the point where the state has been saved If the machine IMachine teleporterEnabled property is enabled on the machine being pow ered up the machine will wait for an incoming teleportation in the TeleportingIn state The returned progress object will have at least three operations where the last three are defined as 1 powering up and starting TCP server 2 waiting fo
236. e The number of bytes to read bytes The bytes to write Writes guest physical memory access handles MMIO are ignored This feature is not implemented in the 4 0 0 release but may show up in a dot release 5 82 24 writeVirtualMemory void IMachineDebugger writeVirtualMemory in unsigned long cpuld in long long address in unsigned long size in octet bytes cpuld The identifier of the Virtual CPU address The guest virtual address size The number of bytes to read bytes The bytes to write Writes guest virtual memory access handles MMIO are ignored This feature is not implemented in the 4 0 0 release but may show up in a dot release 221 5 Classes interfaces 5 83 IMachineEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Base abstract interface for all machine events 5 83 1 Attributes 5 83 1 1 machineld read only uuid IMachineEvent machineld ID of the machine this event relates to 5 84 IMachineRegisteredEvent IMachineEvent Note This interface extends IMachineEvent and therefore supports all its methods and attributes as well The given machine was registered or unregistered within this VirtualBox installation 5 84 1 Attributes 5 84 1 1 registered read only boolean IMachineRegisteredEvent registered If true the machine was registered otherwise it was unregistered 5 85 IMa
237. e VirtualBox object gets created for the first time all known media are in the Inaccessible state but the value of the lastAccessError attribute is an empty string because no actual accessibility check has been made yet After calling refreshState a medium is considered accessible if its storage unit can be read In that case the state attribute has a value of Created If the storage unit cannot be read for example because it is located on a disconnected network resource or was accidentally deleted outside VirtualBox the medium is considered inaccessible which is indicated by the Inaccessible state The exact reason why the medium is inaccessible can be obtained by reading the lastAccessError attribute Medium types There are five types of medium behavior which are stored in the type attribute see MediumType and which define the medium s behavior with attachments and snapshots 224 5 Classes interfaces All media can be also divided in two groups base media and differencing media A base medium contains all sectors of the medium data in its own storage and therefore can be used independently In contrast a differencing medium is a delta to some other medium and con tains only those sectors which differ from that other medium which is then called a parent The differencing medium is said to be linked to that parent The parent may be itself a differencing medium thus forming a chain of linked media The l
238. e argument defines one of three scopes global shared folders Global permanent shared folders of the machine Machine or transient shared folders of the machine Session Interested callees should use query the corresponding collections to find out what has changed 5 123 1 Attributes 5 123 1 1 scope read only Scope ISharedFolderChangedEvent scope Scope of the notification 5 124 IShowWindowE vent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when a call to IMachine showConsoleWindow requests the console window to be activated and brought to foreground on the desktop of the host PC This notification should cause the VM console process to perform the requested action as described above If it is impossible to do it at a time of this notification this method should return a failure Note that many modern window managers on many platforms implement some sort of focus stealing prevention logic so that it may be impossible to activate a window without the help of the currently active application which is supposedly an initiator of this notification In this case this method must return a non zero identifier that represents the top level window of the VM console process The caller if it represents a currently active process is responsible to use this identifier in a platform dependent manner to perform actual window activation This meth
239. e eS 111 S391 ARU BMES 2 Be Ke a BO Re a a S 111 IGuestDnDSouree IDnDSource ocios ee eR ee ee eS 111 BAO Attributes 2 245 2444242000 404 00d A a a ea nae 111 IGuestDuDTarget IDnD Target 3 5 sss oe AAA 111 SALI UES onc ie AA ARA Oe et ae a 111 IGuestFile File 111 SALI SAWS ss 6 ha 6 GE ee Hed a EE SPOS 112 IGuestFileEvent IGuestSessionEvent 112 SIS ADMET a di e Ba DD Oe a ee 112 IGuestFilelOEvent IGuestFileEvent 112 o oue 6 a age eee WS Sod SE ee E E E Rt eed as a a we 112 IGuestFileOffsetChangedEvent IGuestFilelOFvent 112 5051 ARTES so seor ace ak ale EE a iw Break keke E R a e g 113 IGuestFileReadEvent IGuestFilelOEvent 2 000000 eee 113 5 46 1 Attributes ee ee 113 IGuestFileRegisteredEvent IGuestFileEvent 113 BAZI Attributes escocia asa aa e 113 IGuestFileStateChangedEvent IGuestFileEvent 113 5 49 1 Attributes s n aa mos meaa i e e a ss a 113 IGuestFileWriteEvent IGuestFilelOEvent 114 5497 ADUS oscilar a a das 114 IGuestFsObjinfo IFSObjlnfo o ooo e e 114 SONT ADUS ai ad e a ar 114 IGuestKeyboardEvent Event 6 04 0 2 ee eee ee ss 114 A e oon aana e ee SE AAs be Eee bees 114 IGuestMonitorChangedEvent IEvent o ee ee 115 Boe ADUS lo Sas aa OOD ERS eee eo a See 115 IGuestMouseEvent IRe
240. e eee aaa ae 333 62 AdditionsPaciliyClaBs 5 0 45 4444 2 bo ew RRA ee eee ee 333 6 3 AdcditionsPacilityStatus 0 04 6 66550408 eee ee bee ee ees 333 6 4 AdditionsPacilitylype onene ae i a e e 334 6 5 lt AdditionsRunLevellype 25 04 6655 04 ebb eee a eS 334 6 6 AdditionsUpdatePlag ooe soco ek ee era a a ee A 334 6 7 AudioGodecEype s 455500046 bee ee OW See as 334 6 6 s adieControllerType c esoe si eee ead dS OED eee eee aaa 335 69 AudoDriveriype ee ee o a eee a we ew ath wt wt wt aed 335 OLO SUITE 42 4244 aee484 2484494444 A a eee ae 335 GIL MMbestepiepe 2 2 4 06t ss e ER Oe a Pe eS 335 6 12 BIOSBootMenuMod c eert 886449 5S 44 ee ee setae Raa SS 336 6 13 BandwidthiGrowply pe e e c s ss ee a ee eS 336 6 14 Bitmaphormat 4 52220 66 eee eee od bdwadw A 336 BLS CPUProperiy ly pe cocoa ee eS A A ES 336 616 Chipsettype ora SS DOE ee Sew ees 337 BAP Glennie hinde a bei eee a we we we a el mt al a E EEEE 337 G18 ClipboardMode 2 s o heen ieee seg ebb Owen ee ee ee me S 337 619 CloneMode 2 024444 2544644 24084449 5446468 2 e440 Sa a sas 337 620 CIOREORHONE s oe 2 kate eA a Ye ee eee bce PRG ee 337 621 DetaFlags cocer AGRE RE EES ARE ee eae Baas 338 O22 DAV Ges ec dc e eh ee ee ee we ee RAS 338 A 2 otis aa Sooo be eboodadagadepd eed biad sas 338 Gad Devcelype cscs a a a a Bide ee ee ee eee E A 338 G25 DPP o cb ead a Oo Sa RR ae oS a 339 6 20 DhepOptENOding ooo a a da a A E 341 6 27 DirectoryOopyllage heeciwee
241. e execution See also putMouseEventAbsolute 5 93 1 2 relativeSupported read only boolean IMouse relativeSupported Whether the guest OS supports relative mouse pointer positioning or not Note You can use the IMouseCapabilityChangedEvent event to be instantly informed about changes of this attribute during virtual machine execution See also putMouseEvent 246 5 Classes interfaces 5 93 1 3 multiTouchSupported read only boolean IMouse multiTouchSupported Whether the guest OS has enabled the multi touch reporting device Note You can use the IMouseCapabilityChangedEvent event to be instantly informed about changes of this attribute during virtual machine execution See also putMouseEvent 5 93 1 4 needsHostCursor read only boolean IMouse needsHostCursor Whether the guest OS can currently switch to drawing it s own mouse cursor on demand Note You can use the IMouseCapabilityChangedEvent event to be instantly informed about changes of this attribute during virtual machine execution See also putMouseEvent 5 93 1 5 pointerShape read only IMousePointerShape IMouse pointerShape The current mouse pointer used by the guest 5 93 1 6 eventSource read only IEventSource IMouse eventSource Event source for mouse events 5 93 2 putEventMultiTouch void IMouse putEventMultiTouch in long count in long long contacts in
242. e following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open 193 5 Classes interfaces 5 80 33 getGuestPropertyValue wstring IMachine getGuestPropertyVaLue in wstring property property The name of the property to read Reads a value from the machine s guest property store If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open 5 80 34 getHWVirtExProperty boolean IMachine getHWVirtExProperty in HWVirtExPropertyType property property Property type to query Returns the value of the specified hardware virtualization boolean property If this method fails the following error codes may be reported e E_INVALIDARG Invalid property 5 80 35 getMedium IMedium IMachine getMedium in wstring name in long controllerPort in long device name Name of the storage controller the medium is attached to controllerPort Port to query device Device slot in the given port to query Returns the virtual medium attached to a device slot of the specified bus Note that if the medium was indirectly attached by mountMedium to the given device slot then this method will return not the same object as passed to the mountMedium call See IMedium for more detailed information about mounting a medium If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND No medium attache
243. e is inaccessible only the following properties can be used on it e parent e id e settingsFilePath e accessible e accessError An attempt to access any other property or method will return an error The only possible action you can perform on an inaccessible machine is to unregister it using the unregister call or to check for the accessibility state once more by querying this property Note In the current implementation once this property returns true the machine will never become inaccessible later even if its settings file cannot be successfully read written any more at least until the VirtualBox server is restarted This limi tation may be removed in future releases 5 80 1 4 accessError read only IVirtualBoxErrorInfo IMachine accessError Error information describing the reason of machine inaccessibility Reading this property is only valid after the last call to accessible returned false i e the ma chine is currently inaccessible Otherwise a null IVirtualBoxErrorInfo object will be returned 5 80 1 5 name read write wstring IMachine name Name of the virtual machine Besides being used for human readable identification purposes everywhere in VirtualBox the virtual machine name is also used as a name of the machine s settings file and as a name of the subdirectory this settings file resides in Thus every time you change the value of this property the settings file will be renamed o
244. e machine is not running and has no saved execution state it has either never been started or been shut down successfully Saved The machine is not currently running but the execution state of the machine has been saved to an external file when it was running from where it can be resumed Teleported The machine was teleported to a different host or process and then powered off Take care when powering it on again may corrupt resources it shares with the teleportation target e g disk and network 353 6 Enumerations enums Aborted The process running the machine has terminated abnormally This may indicate a crash of the VM process in host execution context or the VM process has been terminated externally Running The machine is currently being executed Paused Execution of the machine has been paused Stuck Execution of the machine has reached the Guru Meditation condition This indicates a severe error in the hypervisor itself Teleporting The machine is about to be teleported to a different host or process It is possible to pause a machine in this state but it will go to the TeleportingPausedWM state and it will not be possible to resume it again unless the teleportation fails LiveSnapshotting A live snapshot is being taken The machine is running normally but some of the runtime configuration options are inaccessible Also if paused while in this state it will transition to OnlineSnapshotting and it will not be res
245. e nada rid a a aa 165 DIA PECA ra a a BS a i mee RL A A alow le eee 166 5 78 93 PulScamcode oo o 2002 coe a ee 166 DRA PUESCAACOTSS a oe we bea te a es a Re we a EEA G 166 5 76 95 releaseKeys ccc doen eee See HOS COA EEE OS ORES 166 IKeyboardLedsChangedEvent Event 2 6 osos aod ee ee ee a 166 5 80 Contents BO ea fio aoe oA a ae we Re we we DER ee a S 167 Ii 2 bee 24 ARES AER RERE TSE RES EER Ded ae e E 167 SUL AUDIT oe t be ae EO te eh we ee ee ee el Ta i 167 5 80 2 addStorageController ooo naa 180 530 3 sddUSpConiroller 2 5 5 se bbe WE a ee ee eS 180 5 80 4 adoptSavedState coord eee a 181 300 0 Apperson Gis we we oe Be A a a ae G 181 S006 am achiDevi s o4 ce06 5 ee bees POS AA 182 5 80 7 attachDeviceWithoutMediUM lt z s so o o e 183 5 00 8 attachPlostPClDevice 2 2 25 6 cas ho ee eee oe Bae Gee 3 184 5 80 9 canShowConsoleWindoW o e e eens 184 S BOTO OE ooe a a a A a MS 185 5 80 11 crestesharedPolder oia 282044404445 185 SOS delte E 185 5 80 13 deleteGuestProperty cerco eased eee eee eee se aaa 186 5 90 14 deleteSnapshot gt oso aoc ee a a al eed 186 5 80 15 deleteSnapshotAndAllChildren 187 580 16 d leteSnapshotRange gt os zroet ss soma aak we 188 580 17 d tachDgvice s oeeo e eb oe OO e e Ee eee ale De 188 380 18 detachiHostPCIDedOS onson ii ee ra a a e O 189 5 80 19 diseardSavedState lt o ccce beere eiea a eo eS 190 5 80 20 discardSettings 1 444424
246. e name invalid not found or sharing violation 5 151 19 openMedium IMedium IVirtualBox openMedium in wstring location in DeviceType deviceType in AccessMode accessMode in boolean forceNewUuid location Location of the storage unit that contains medium data in one of the supported storage formats deviceType Must be one of HardDisk DVD or Floppy accessMode Whether to open the image in read write or read only mode For a DVD device type this is ignored and read only mode is always assumed forceNewUuid Allows the caller to request a completely new medium UUID for the image which is to be opened Useful if one intends to open an exact copy of a previously opened image as this would normally fail due to the duplicate UUID 322 5 Classes interfaces Finds existing media or opens a medium from an existing storage location Once a medium has been opened it can be passed to other VirtualBox methods in particular to IMachine attachDevice Depending on the given device type the file at the storage location must be in one of the media formats understood by VirtualBox e With a HardDisk device type the file must be a hard disk image in one of the formats supported by VirtualBox see ISystemProperties mediumFormats After this method succeeds if the medium is a base medium it will be added to the hardDisks array at tribute e With a DVD device type the file must be an
247. e screen top left corner 75 5 Classes interfaces width Desired image width height Desired image height Draws a 32 bpp image of the specified size from the given buffer to the given point on the VM display If this method fails the following error codes may be reported e E_NOTIMPL Feature not implemented e VBOX_E_IPRT_ERROR Could not draw to screen 5 16 5 getScreenResolution void IDisplay getScreenResolution in unsigned long screenId out unsigned long width out unsigned long height out unsigned long bitsPerPixel out long xOrigin out long yOrigin out GuestMonitorStatus guestMonitorStatus screenld width height bitsPerPixel xOrigin yOrigin guestMonitorStatus Queries certain attributes such as display width height color depth and the X and Y origin for a given guest screen The parameters xOrigin and yOrigin return the X and Y coordinates of the framebuffer s origin All return parameters are optional 5 16 6 invalidateAndUpdate void IDisplay invalidateAndUpdate Does a full invalidation of the VM display and instructs the VM to update it If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Could not invalidate and update screen 5 16 7 invalidateAndUpdateScreen void IDisplay invalidateAndUpdateScreen in unsigned long screenId screenld The guest screen to redraw Redraw the specified VM screen 76 5 Classes interfaces
248. e stamp of the snapshot in milliseconds since 1970 01 01 UTC 5 125 1 5 online read only boolean ISnapshot online true if this snapshot is an online snapshot and false otherwise When this attribute is true the IMachine stateFilePath attribute of the machine object as sociated with this snapshot will point to the saved state file Otherwise it will be an empty string 5 125 1 6 machine read only IMachine ISnapshot machine Virtual machine this snapshot is taken on This object stores all settings the machine had when taking this snapshot Note The returned machine object is immutable i e no any settings can be changed 287 5 Classes interfaces 5 125 1 7 parent read only ISnapshot ISnapshot parent Parent snapshot a snapshot this one is based on or null if the snapshot has no parent i e is the first snapshot 5 125 1 8 children read only ISnapshot ISnapshot children Child snapshots all snapshots having this one as a parent By inspecting this attribute starting with a machine s root snapshot which can be obtained by calling IMachine findSnapshot with a null UUID a machine s snapshots tree can be iterated over 5 125 2 getChildrenCount unsigned long ISnapshot getChildrenCount Returns the number of direct children of this snapshot 5 126 ISnapshotChangedEvent ISnapshotEvent Note This interface extends ISnapshotEvent and therefore supports all its methods
249. e the VirtualBox OOWS for JAX WS which we will explain in more detail in the following chapters 2 1 1 3 Logging on to the web service Before a web service client can do anything useful two objects need to be created as can be seen in the clienttest constructor 1 An instance of IWebsessionManager which is an interface provided by the web service to manage web sessions that is stateful connections to the web service with persistent objects upon which methods can be invoked In the OOWS for JAX WS the IWebsessionManager class must be constructed explicitly and a URL must be provided in the constructor that specifies where the web service the server awaits connections The code in clienttest java connects to http localhost 18083 which is the default The port number by default 18083 must match the port number given to the vboxwebsrv command line see chapter 1 4 1 Command line options of vboxwebsrv page 24 Mn sdk bindings glue java 28 2 Environment specific notes 2 After that the code calls WebsessionManager logon which is the first call that actually communicates with the server This authenticates the client with the web service and returns an instance of VirtualBox the most fundamental interface of the VirtualBox web service from which all other functionality can be derived If logon doesn t work please take another look at chapter 1 4 2 Authenticating at web service logon page
250. ePolicy read write NetworkAdapterPromiscModePolicy INetworkAdapter promiscModePolicy The promiscuous mode policy of the network adapter when attached to an internal network host only network or a bridge 262 5 Classes interfaces 5 106 1 14 traceEnabled read write boolean INetworkAdapter traceEnabled Flag whether network traffic from to the network card should be traced Can only be toggled when the VM is turned off 5 106 1 15 traceFile read write wstring INetworkAdapter traceFile Filename where a network trace will be stored If not set VBox pid pcap will be used 5 106 1 16 NATEngine read only INATEngine INetworkAdapter NATEngine Points to the NAT engine which handles the network address translation for this interface This is active only when the interface actually uses NAT 5 106 1 17 bootPriority read write unsigned long INetworkAdapter bootPriority Network boot priority of the adapter Priority 1 is highest If not set the priority is considered to be at the lowest possible setting 5 106 1 18 bandwidthGroup read write IBandwidthGroup INetworkAdapter bandwidthGroup The bandwidth group this network adapter is assigned to 5 106 2 getProperties wstring INetworkAdapter getProperties in wstring names out wstring returnNames names Names of properties to get returnNames Names of returned properties Returns values for a group of properties in one call The na
251. ead write boolean INATNetwork advertiseDefaultIPv6RouteEnabled 5 98 1 8 needDhcpServer read write boolean INATNetwork needDhcpServer 5 98 1 9 eventSource read only IEventSource INATNetwork eventSource 5 98 1 10 portForwardRules4 read only wstring INATNetwork portForwardRules4 Array of NAT port forwarding rules in string representation in the following format name protocolid host ip host port guest ip guest port 5 98 1 11 localMappings read only wstring INATNetwork localMappings Array of mappings address offset e g 127 0 1 1 4 maps 127 0 1 1 to networkid 4 5 98 1 12 loopbacklp6 read write long INATNetwork LoopbackIp6 Offset in ipv6 network from network id for address mapped into loopback6 interface of the host 5 98 1 13 portForwardRules6 read only wstring INATNetwork portForwardRules6 Array of NAT port forwarding rules in string representation in the following format name protocolid host ip host port guest ip guest port 256 5 Classes interfaces 5 98 2 addLocalMapping void INATNetwork addLocalMapping in wstring hostid in long offset hostid offset 5 98 3 addPortForwardRule void INATNetwork addPortForwardRule in boolean isIpv6 in wstring ruleName in NATProtocol proto in wstring hostIP in unsigned short hostPort in wstring guestIP in unsigned short guestPort islpv6 ruleName p
252. ease Modifies the debug or release logger flags 5 82 15 modifyLogGroups void IMachineDebugger modifyLogGroups in wstring settings settings The group settings string See iprt log h for details To target the release logger prefix the string with release Modifies the group settings of the debug or release logger 5 82 16 queryOSKernelLog wstring IMachineDebugger queryOSKernelLog in unsigned long maxMessages maxMessages Max number of messages to return counting from the end of the log If 0 there is no limit Tries to get the kernel log dmesg of the guest OS 219 5 Classes interfaces 5 82 17 readPhysicalMemory octet IMachineDebugger readPhysicalMemory in long long address in unsigned long size address The guest physical address size The number of bytes to read Reads guest physical memory no side effects MMIO This feature is not implemented in the 4 0 0 release but may show up in a dot release 5 82 18 readVirtualMemory octet IMachineDebugger readVirtualMemory in unsigned long cpuld in long long address in unsigned long size cpuld The identifier of the Virtual CPU address The guest virtual address size The number of bytes to read Reads guest virtual memory no side effects MMIO This feature is not implemented in the 4 0 0 release but may show up in a dot release 5 82 19 resetStats void IMachineDebugger resetStats in
253. ed in boolean changeOrigin in long originX in long originY in unsigned long width in unsigned long height in unsigned long bitsPerPixel display The number of the guest display to send the hint to enabled True if this guest screen is enabled False otherwise changeOrigin True if the origin of the guest screen should be changed False otherwise originX The X origin of the guest screen originY The Y origin of the guest screen width height bitsPerPixel Asks VirtualBox to request the given video mode from the guest This is just a hint and it cannot be guaranteed that the requested resolution will be used Guest Additions are required for the request to be seen by guests The caller should issue the request and wait for a resolution change and after a timeout retry Specifying 0 for either width height or bitsPerPixel parameters means that the corre sponding values should be taken from the current video mode i e left unchanged If the guest OS supports multi monitor configuration then the display parameter specifies the number of the guest display to send the hint to 0 is the primary display 1 is the first secondary and so on If the multi monitor configuration is not supported display must be 0 If this method fails the following error codes may be reported e E_INVALIDARG The display is not associated with any monitor 5 16 14 takeScreenShot Note This method is not supported in the web s
254. ed pfn Called by the VirtualBox host components to perform functions which should be Host not accessible by the guest Usually this entry point is used by VirtualBox to Call configure the service pfn The VM state is being saved and the service must save relevant information using SaveS the SSM API VBox ssm h tate pfn The VM is being restored from the saved state and the service must load the saved Load information and be able to continue operations from the saved state State 378 8 RDP Web Control The VirtualBox RDP Web Control RDPWeb provides remote access to a running VM RDPWeb is a RDP Remote Desktop Protocol client based on Flash technology and can be used from a Web browser with a Flash plugin 8 1 RDPWeb features RDPWeb is embedded into a Web page and can connect to VRDP server in order to displays the VM screen and pass keyboard and mouse events to the VM 8 2 RDPWeb reference RDPWeb consists of two required components e Flash movie RDPClientUL swf e JavaScript helpers webclient js The VirtualBox SDK contains sample HTML code including e JavaScript library for embedding Flash content SWFObject js e Sample HTML page webclient3 html 8 2 1 RDPWeb functions RDPClientUI swf and webclient js work with each other JavaScript code is responsible for a proper SWF initialization delivering mouse events to the SWF and processing resize requests from the SWF On the other hand the SWF conta
255. ed again and placed back to Created state After the returned progress object reports that the operation is complete the medium state will be set to NotCreated and you will be able to use one of the storage creation methods to create it again See also close Note If the deletion operation fails it is not guaranteed that the storage unit still exists You may check the state value to answer this question If this method fails the following error codes may be reported e VBOX_E_OBJECT_IN_USE Medium is attached to a virtual machine e VBOX_E_NOT_SUPPORTED Storage deletion is not allowed because neither of storage cre ation operations are supported See IMediumFormat capabilities 233 5 Classes interfaces 5 87 11 getEncryptionSettings wstring IMedium getEncryptionSettings out wstring cipher cipher The cipher used for encryption Returns the encryption settings for this medium If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED Encryption is not configured for this medium 5 87 12 getProperties wstring IMedium getProperties in wstring names out wstring returnNames names Names of properties to get returnNames Names of returned properties Returns values for a group of properties in one call The names of the properties to get are specified using the names argument which is a list of comma separated property names or an empty string if all
256. ed by explicitly calling IManagedObjectRef release This is important as otherwise hundreds or thousands of managed object references and corresponding COM objects which can consume much more memory can pile up in the web service process and eventually cause it to deny service To reiterate The underlying COM object which the reference points to is only freed if the managed object reference is released It is therefore vital that web service clients properly clean up after the managed object references that are returned to them When a web service client calls IWebsessionManager logoff all managed object references created during the session are automatically freed For short lived sessions that do not create a lot of objects logging off may therefore be sufficient although it is certainly not best practice 2 2 3 4 Some more detail about web service operation SOAP messages Whenever a client makes a call to a web service this involves a complicated procedure internally These calls are remote procedure calls Each such procedure call typically consists of two message being passed where each message is a plain text HTTP request with a standard HTTP header and a special XML document following This XML document encodes the name of the procedure to call and the argument names and values passed to it To give you an idea of what such a message looks like assuming that a web service provides a procedure called SayHello
257. ed by prepending the method name with the interface name using _as the separator 41 2 Environment specific notes So far only attribute getters were illustrated but generic method calls are straightforward too IMachine machine NULL BSTR vmname Calling IMachine findMachine rc IVirtualBox_FindMachine vbox vmname amp machine As a more complicated example of a method invocation let s call IMachine launchVMProcess which returns an IProgress object Note again that the method name is capitalized IProgress progress rc IMachine_LaunchWMProcess machine this x session arg 1 sessionType arg 2 env arg 3 amp progress Out y All objects with their methods and attributes are documented in chapter 5 Classes interfaces page 52 2 3 6 5 String handling When dealing with strings you have to be aware of a string s encoding and ownership Internally the API uses UTF 16 encoded strings A set of conversion functions is provided to convert other encodings to and from UTF 16 The type of a UTF 16 character is BSTR or its constant counterpart CBSTR which is an array type represented by a pointer to the start of the zero terminated string There are functions for converting between UTF 8 and UTF 16 strings available through g pVBoxFuncs int pfnUtf16ToUtf8 CBSTR pwszString char ppszString int pfnUtf8ToUtf16 const char pszString BSTR ppw
258. ed folder to remove Removes a transient shared folder with the given name previously created by createSharedFolder from the collection of shared folders and stops sharing it If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine in Saved state or currently changing state e VBOX_E_FILE_ERROR Shared folder does not exists 5 13 20 reset void IConsole reset Resets the virtual machine If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine not in Running state e VBOX_E_VM_ERROR Virtual machine error in reset operation 5 13 21 resume void IConsole resume Resumes the virtual machine execution If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine not in Paused state e VBOX_E_VM_ERROR Virtual machine error in resume operation 5 13 22 sleepButton void IConsole sleepButton Sends the ACPI sleep button event to the guest If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine not in Running state e VBOX_E_PDM_ERROR Sending sleep button event failed 70 5 Classes interfaces 5 13 23 teleport IProgress IConsole teleport in wstring hostname in unsigned long tcpport in wstring password in unsigned long maxDowntime hostname The name or IP of the host to teleport to
259. ed long IParallelPort I0Base Base I O address of the parallel port 5 110 1 4 IRQ read write unsigned long IParallelPort IRQ IRQ number of the parallel port 5 110 1 5 path read write wstring IParallelPort path Host parallel device name If this parallel port is enabled setting a null or an empty string as this attribute s value will result in the parallel port behaving as if not connected to any device 266 5 Classes interfaces 5 111 IParallelPortChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when a property of one of the virtual parallel ports changes Interested callees should use ISerialPort methods and attributes to find out what has changed 5 111 1 Attributes 5 111 1 1 parallelPort read only IParallelPort IParallelPortChangedEvent parallelPort Parallel port that is subject to change 5 112 IPerformanceCollector The IPerformanceCollector interface represents a service that collects and stores performance metrics data Performance metrics are associated with objects of interfaces like Host and IMachine Each object has a distinct set of performance metrics The set can be obtained with getMetrics Metric data is collected at the specified intervals and is retained internally The interval and the number of retained samples can be set with setupMetrics Both metric data and collection settin
260. ed storage devices of the associated virtual machine have changed If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 5 77 20 onUSBControllerChange void IInternalSessionControl onUSBControllerChange Triggered when settings of the USB controller object of the associated virtual machine have changed If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 5 77 21 onUSBDeviceAttach void IInternalSessionControl onUSBDeviceAttach in IUSBDevice device in IVirtualBoxErrorInfo error in unsigned long maskedInterfaces in wstring captureFilename device error maskedinterfaces captureFilename Triggered when a request to capture a USB device as a result of matched USB filters or di rect call to IConsole attachUSBDevice has completed A nullerror object means success otherwise it describes a failure If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 162 5 Classes interfaces 5 77 22 onUSBDeviceDetach void IInternalSessionControl onUSBDeviceDetach in uuid id in IVirtualBoxErrorInfo er
261. ed when you open an existing medium and cannot be changed later Note null is returned if there is no associated medium format object This can e g happen for medium objects representing host drives and other special medium objects 5 87 1 12 type read write MediumType IMedium type Type role of this medium The following constraints apply when changing the value of this attribute e If a medium is attached to a virtual machine either in the current state or in one of the snapshots its type cannot be changed e As long as the medium has children its type cannot be set to Writethrough e The type of all differencing media is Normal and cannot be changed The type of a newly created or opened medium is set to Normal except for DVD and floppy media which have a type of Writethrough 227 5 Classes interfaces 5 87 1 13 allowedTypes read only MediumType IMedium allowedTypes Returns which medium types can selected for this medium 5 87 1 14 parent read only IMedium IMedium parent Parent of this medium the medium this medium is directly based on Only differencing media have parents For base non differencing media null is returned 5 87 1 15 children read only IMedium IMedium children Children of this medium all differencing media directly based on this medium A null array is returned if this medium does not have any children 5 87 1 16 base read only IMedium IMe
262. ee ISnapshotTakenEvent OnSnapshotDeleted See ISnapshotDeletedEvent OnSnapshotChanged See ISnapshotChangedEvent OnGuestPropertyChanged See IGuestPropertyChangedEvent OnMousePointerShapeChanged See IMousePointerShapeChangedEvent OnMouseCapabilityChanged See IMouseCapabilityChangedEvent OnKeyboardLedsChanged See IKeyboardLedsChangedEvent OnStateChanged See IStateChangedEvent OnAdditionsStateChanged See IAdditionsStateChangedEvent OnNetworkAdapterChanged See INetworkAdapterChangedEvent OnSerialPortChanged See ISerialPortChangedEvent OnParallelPortChanged See IParallelPortChangedEvent OnStorageControllerChanged See IStorageControllerChangedEvent OnMediumChanged See IMediumChangedEvent OnVRDEServerChanged See IVRDEServerChangedEvent OnUSBControllerChanged See IUSBControllerChangedEvent OnUSBDeviceStateChanged See IUSBDeviceStateChangedEvent OnSharedFolderChanged See ISharedFolderChangedEvent OnRuntimeError See IRuntimeErrorEvent OnCanShowWindow See ICanShowWindowEvent OnShowWindow See IShowWindowEvent OnCPUChanged See ICPUChangedEvent OnVRDEServerlnfoChanged See IVRDEServerInfoChangedEvent 368 6 Enumerations enums OnEventSourceChanged See IEventSourceChangedEvent OnCPUExecutionCapChanged See ICPUExecutionCapChangedEvent OnGuestKeyboard See IGuestKeyboardEvent OnGuestMouse See IGuestMouseEvent OnNATRedirect See INATRedirectEvent OnHostPCIDevicePlug See IHostPCIDevicePlugEvent OnVBoxSVCAvailabilityChanged See IV
263. egion in ptr octet rectangles in unsigned long count rectangles Pointer to the RTRECT array count Number of RTRECT elements in the rectangles array Suggests a new visible region to this frame buffer This region represents the area of the VM display which is a union of regions of all top level windows of the guest operating system running inside the VM if the Guest Additions for this system support this functionality This information may be used by the frontends to implement the seamless desktop integration feature 102 5 Classes interfaces Note The address of the provided array must be in the process space of this IFrame buffer object Note The IFramebuffer implementation must make a copy of the provided array of rectangles Note Method not yet implemented 5 35 9 videoModeSupported boolean IFramebuf fer videoModeSupported in unsigned long width in unsigned long height in unsigned long bpp width height bpp Returns whether the frame buffer implementation is willing to support a given video mode In case it is not able to render the video mode or for some reason not willing it should return false Usually this method is called when the guest asks the VMM device whether a given video mode is supported so the information returned is directly exposed to the guest It is important that this method returns very quickly 5 36 IFramebufferOverlay IFramebuffer
264. egistry in the VirtualBox xml file which was shared between all machines and made transporting machines and their media from one host to another difficult Starting with VirtualBox 4 0 media are only added to a registry when they are attached to a machine using IMachine attachDevice For backwards compatibility which registry a medium is added to depends on which VirtualBox version created a machine e If the medium has first been attached to a machine which was created by VirtualBox 4 0 or later it is added to that machine s media registry in the machine XML settings file This way all information about a machine s media attachments is contained in a single file and can be transported easily e For older media attachments i e if the medium was first attached to a machine which was created with a VirtualBox version before 4 0 media continue to be registered in the global VirtualBox settings file for backwards compatibility See IVirtualBox openMedium for more information Media are removed from media registries by the close deleteStorage and mergeTo meth ods Accessibility checks VirtualBox defers media accessibility checks until the refreshState method is called explicitly on a medium This is done to make the VirtualBox object ready for serving requests as fast as possible and let the end user application decide if it needs to check media accessibility right away or not As a result when VirtualBox starts up e g th
265. emote VRDE client or to a local host machine 5 140 lUSBDeviceFilter The IUSBDeviceFilter interface represents an USB device filter used to perform actions on a group of USB devices This type of filters is used by running virtual machines to automatically capture selected USB devices once they are physically attached to the host computer A USB device is matched to the given device filter if and only if all attributes of the device match the corresponding attributes of the filter that is attributes are joined together using the logical AND operation On the other hand all together filters in the list of filters carry the semantics of the logical OR operation So if it is desirable to create a match like this vendor id OR this product id one needs to create two filters and specify any match see below for unused attributes All filter attributes used for matching are strings Each string is an expression representing a set of values of the corresponding device attribute that will match the given filter Currently the following filtering expressions are supported e Interval filters Used to specify valid intervals for integer device attributes Vendor ID Product ID and Revision The format of the string is int m m n 1 m Cm n x where m and n are integer numbers either in octal starting from 0 hexadecimal starting from 0x or decimal otherwise form so that m lt n If mis omitted before a da
266. emporarily disabled 5 140 1 3 vendorld read write wstring IUSBDeviceFilter vendorId Vendor ID filter The string representation for the exact matching has the form XXXX where X is the hex digit including leading zeroes 5 140 1 4 productlid read write wstring IUSBDeviceFilter productId Product ID filter The string representation for the exact matching has the form XXXX where X is the hex digit including leading zeroes 5 140 1 5 revision read write wstring IUSBDeviceFilter revision Product revision number filter The string representation for the exact matching has the form IIFF where I is the decimal digit of the integer part of the revision and F is the decimal digit of its fractional part including leading and trailing zeros Note that for interval filters it s best to use the hexadecimal form because the revision is stored as a 16 bit packed BCD value so the expression int 0x0100 0x0199 will match any revision from 1 0 to 1 99 5 140 1 6 manufacturer read write wstring IUSBDeviceFilter manufacturer Manufacturer filter 5 140 1 7 product read write wstring IUSBDeviceFilter product Product filter 303 5 Classes interfaces 5 140 1 8 serialNumber read write wstring IUSBDeviceFilter serialNumber Serial number filter 5 140 1 9 port read write wstring IUSBDeviceFilter port Host USB port filter 5 140 1 10 remote read write wstring IUSBDeviceFilter rem
267. empty nor can it contain any equal signs Schedules unsetting removing an environment variable when creating the next guest pro cess This affects the environmentChanges attribute 5 64 16 fileCopy IProgress IGuestSession fileCopy in wstring source in wstring destination in FileCopyFlag flags source The path to the file to copy in the guest Guest path style destination The path to the target file in the guest This cannot be a directory Guest path style flags Zero or more FileCopyFlag values Copies a file from one guest location to another 130 5 Classes interfaces Note Will overwrite the destination file unless FileCopyFlag NoReplace is specified If this method fails the following error codes may be reported e E_NOTIMPL Not yet implemented 5 64 17 fileCopyFromGuest IProgress IGuestSession fileCopyFromGuest in wstring source in wstring destination in FileCopyFlag flags source Path to the file on the guest side that should be copied to the host Guest path style destination Where to put the file on the host file not directory Host path style flags Zero or more FileCopyFlag values Copies a file from the guest to the host Note Will overwrite the destination file unless FileCopyFlag NoReplace is specified If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Error starting the copy operation 5 64
268. en renamed to DnDMode The attribute IMachine dragAndDropMode has been renamed to IMachine dnDMode The event IDragAndDropModeChangedEvent has been renamed to IDnDModeChangedEvent IDisplay and Framebuffer interfaces were changed to allow IFramebuffer object to reside in a separate frontend process IDisplay ResizeCompleted has been removed because the Framebuffer object does not provide the screen memory anymore IDisplay SetFramebuffer has been replaced with IDisplay AttachFramebuffer and IDisplay DetachFramebuffer IDisplay GetFramebuffer has been replaced with IDisplay QueryFramebuffer IDisplay GetScreenResolution has a new output parameter guestMonitorStatus which tells whether the monitor is enabled in the guest IDisplay TakeScreenShot and IDisplay TakeScreenShotToArray have a new pa rameter bitmapFormat As a consequence of this IDisplay TakeScreenShotPNGToArray has been removed IFramebuffer RequestResize has been replaced with IFramebuffer NotifyChange IFramebuffer NotifyUpdateImage added to support IFramebuffer objects in a dif ferent process 389 13 Main API change log IFramebuffer LockO IFramebuffer Unlock O IFramebuffer Address IFrame buffer UsesGuestVRAM have been removed because the IFramebuffer object does not provide the screen memory anymore e IGuestSession IGuestFile and IGuestProcess interfaces were chan
269. en the hard disk configuration is changed for the first time after the last IMachine saveSettings call and used by IMachine discardSettings to undo the recent hard disk changes When such a descendant is found in this backup copy it will be simply re attached back without creating a new differencing hard disk for it This optimization is necessary to make it possible to re attach the base or immutable hard disk to a different bus channel or device slot without losing the contents of the differencing hard disk actually attached to the machine in place of it 5 88 1 Attributes 5 88 1 1 medium read only IMedium IMediumAttachment medium Medium object associated with this attachment it can be null for removable devices 5 88 1 2 controller read only wstring IMediumAttachment controller Name of the storage controller of this attachment this refers to one of the controllers in IMachine storageControllers by name 5 88 1 3 port read only long IMediumAttachment port Port number of this attachment See IMachine attachDevice for the meaning of this value for the different controller types 5 88 1 4 device read only long IMediumAttachment device Device slot number of this attachment See IMachine attachDevice for the meaning of this value for the different controller types 5 88 1 5 type read only DeviceType IMediumAttachment type Device type of this attachment 5 88 1 6 passthrough read only boolean IMediumA
270. ent virtual machine exe cution state pause the machine or power it down save the machine state or take a snapshot attach and detach removable media and so on See also Session 5 13 1 Attributes 5 13 1 1 machine read only IMachine IConsole machine Machine object for this console session Note This is a convenience property it has the same value as ISession machine of the corresponding session object 5 13 1 2 state read only MachineState IConsole state Current execution state of the machine Note This property always returns the same value as the corresponding property of the IMachine object for this console session For the process that owns executes the VM this is the preferable way of querying the VM state because no IPC calls are made 5 13 1 3 guest read only IGuest IConsole guest Guest object 5 13 1 4 keyboard read only IKeyboard IConsole keyboard Virtual keyboard object Note If the machine is not running any attempt to use the returned object will result in an error 63 5 Classes interfaces 5 13 1 5 mouse read only IMouse IConsole mouse Virtual mouse object Note If the machine is not running any attempt to use the returned object will result in an error 5 13 1 6 display read only IDisplay IConsole display Virtual display object Note If the machine is not running any attempt to use the returne
271. enting this interface is contained in each IConsole display attribute and represents the visual output of the virtual machine The virtual display supports pluggable output targets represented by the IFramebuffer inter face Examples of the output target are a window on the host computer or an RDP session s display on a remote computer 74 5 Classes interfaces 5 16 1 attachFramebuffer uuid IDisplay attachFramebuf fer in unsigned long screenld in IFramebuffer framebuffer screenld framebuffer Sets the graphics update target for a screen 5 16 2 completeVHWACommand Note This method is not supported in the web service void IDisplay completeVHWACommand in ptr octet command command Pointer to VBOXVHWACMD containing the completed command Signals that the Video HW Acceleration command has completed 5 16 3 detachFramebuffer void IDisplay detachFramebuffer in unsigned long screenld in uuid id screenld id Removes the graphics updates target for a screen 5 16 4 drawToScreen Note This method is not supported in the web service void IDisplay drawToScreen in unsigned long screenld in ptr octet address in unsigned long x in unsigned long y in unsigned long width in unsigned long height screenld Monitor to take the screenshot from address Address to store the screenshot to x Relative to the screen top left corner y Relative to th
272. er VM setting overrides the default defined by ISystemProperties defaultFrontend at tribute and is overridden by a frontend type passed to launchVMProcess 5 80 1 85 USBProxyAvailable read only boolean IMachine USBProxyAvailable Returns whether there is an USB proxy available 5 80 1 86 VMProcessPriority read write wstring IMachine VMProcessPriority Sets the priority of the VM process It is a VM setting which can be changed both before starting the VM and at runtime The valid values are system specific and if a value is specified which does not get recognized then it will be remembered useful for preparing VM configs for other host OSes with a successful result The default value is the empty string which selects the default process priority 5 80 2 addStorageController IStorageController IMachine addStorageController in wstring name in StorageBus connectionType name connectionType Adds a new storage controller SCSI SAS or SATA controller to the machine and returns it as an instance of IStorageController name identifies the controller for subsequent calls such as getStorageControllerByName getStorageControllerByInstance removeStorageController attachDevice or mountMedium After the controller has been added you can set its exact type by setting the IStorageController controllerType If this method fails the following error codes may be reported e VBOX_E_OBJECT_IN_USE A storage
273. er as the result of the background operation via the object returned via the progress parameter If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED Encryption is not supported for this medium because it is at tached to more than one VM or has children 5 87 3 checkEncryptionPassword void IMedium checkEncryptionPassword in wstring password password The password to check Checks whether the supplied password is correct for the medium If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED Encryption is not configured for this medium e VBOX_E_PASSWORD_INCORRECT The given password is incorrect 5 87 4 cloneTo IProgress IMedium cloneTo in IMedium target in MediumVariant variant in IMedium parent target Target medium variant Exact image variant which should be created as a combination of MediumVariant flags parent Parent of the cloned medium Starts creating a clone of this medium in the format and at the location defined by the target argument The target medium must be either in NotCreated state i e must not have an existing storage unit or in Created state i e created and not locked and big enough to hold the data or else the copy will be partial Upon successful completion the cloned medium will contain exactly the 230 5 Classes interfaces same sector data as the medium being cloned except that in the first c
274. erIP specifies from IP address in server address range 5 14 1 7 upperlP read only wstring IDHCPServer upperIP specifies to IP address in server address range 5 14 1 8 globalOptions read only wstring IDHCPServer globalOptions 5 14 1 9 vmConfigs read only wstring IDHCPServer vmConfigs 5 14 2 addGlobalOption void IDHCPServer addGlobal0ption in DhcpOpt option in wstring value option value 5 14 3 addVmSlotOption void IDHCPServer addVmSlotOption in wstring vmname in long slot in DhcpOpt option in wstring value vmname slot option value 5 14 4 getMacOptions wstring IDHCPServer getMacOptions in wstring mac mac 72 5 Classes interfaces 5 14 5 getVmSlotOptions wstring IDHCPServer getVmSlotOptions in wstring vmname in long slot vmname slot 5 14 6 removeVmSlotOptions void IDHCPServer removeVmSlotOptions in wstring vmname in long slot vmname slot 5 14 7 setConfiguration void IDHCPServer setConfiguration in wstring IPAddress in wstring networkMask in wstring FromIPAddress in wstring ToIPAddress IPAddress server IP address networkMask server network mask FromlPAddress server From IP address for address range TolPAddress server To IP address for address range configures the server If this method fails the following error codes may be reported e E_INVALIDARG invalid configuration suppl
275. erminated normally TerminatedSignal Process terminated via signal TerminatedAbnormally Process terminated abnormally TimedOutKilled Process timed out and was killed TimedOutAbnormally Process timed out and was not killed successfully Down Service OS is stopping process was killed Error Something went wrong 6 84 ProcessWaitForFlag Process waiting flags Multiple flags can be combined None No waiting flags specified Do not use this Start Wait for the process being started Terminate Wait for the process being terminated StdIn Wait for stdin becoming available StdOut Wait for data becoming available on stdout StdErr Wait for data becoming available on stderr 361 6 Enumerations enums 6 85 ProcessWaitResult Process waiting results Depending on the process waiting flags for more information see ProcessWaitForFlag the waiting result can vary based on the processes current status To wait for a guest process to terminate after it has been created by IGuestSession processCreate or IGuestSession processCreateEx one would specify ProcessWaitFor_Terminate If a guest process has been started with ProcessCreateFlag WaitForStdOut a client can wait with ProcessWaitResult_StdOut for new data to arrive on stdout same applies for ProcessCre ateFlag WaitForStdErr and ProcessWaitResult_StdErr None No result was returned Not being used Start The process has been started Terminate The process has been terminate
276. erties freeDiskSpaceError Issue an error if the free disk space is below or in some disk intensive operation is expected to go below the given size in bytes 5 135 1 21 freeDiskSpacePercentError read write unsigned long ISystemProperties freeDiskSpacePercentError Issue an error if the free disk space is below or in some disk intensive operation is expected to go below the given percentage 295 5 Classes interfaces 5 135 1 22 VRDEAuthLibrary read write wstring ISystemProperties VRDEAuthLibrary Library that provides authentication for Remote Desktop clients The library is used if a virtual machine s authentication type is set to external in the VM RemoteDisplay configuration The system library extension DLL or so must be omitted A full path can be specified if not then the library must reside on the system s default library path The default value of this property is VBoxAuth There is a library of that name in one of the default VirtualBox library directories For details about VirtualBox authentication libraries and how to implement them please refer to the VirtualBox manual Note Setting this property to null or empty string will restore the initial value 5 135 1 23 webServiceAuthLibrary read write wstring ISystemProperties webServiceAuthLibrary Library that provides authentication for webservice clients The library is used if a virtual machine s authenti
277. erty type to set value New property value Sets a new value for the specified hardware virtualization boolean property If this method fails the following error codes may be reported e E_INVALIDARG Invalid property 5 80 75 setHotPluggableForDevice void IMachine setHotPluggableForDevice in wstring name in long controllerPort in long device in boolean hotPluggable name Name of the storage controller controllerPort Storage controller port device Device slot in the given port hotPluggable New value for the hot pluggable device flag Sets a flag in the device information which indicates that the attached device is hot pluggable or not This may or may not be supported by a particular controller and or drive and is silently ignored in the latter case Changing the setting while the VM is running is forbidden The device must already exist see attachDevice for how to attach a new device The controllerPort and device parameters specify the device slot and have have the same meaning as with attachDevice If this method fails the following error codes may be reported e E_INVALIDARG SATA device SATA port IDE port or IDE slot out of range e VBOX_E_INVALID_OBJECT_STATE Attempt to modify an unregistered virtual machine e VBOX_E_INVALID_VM_STATE Invalid machine state e VBOX_E_NOT_SUPPORTED Controller doesn t support hot plugging 209 5 Classes interfaces 5 80 76 setNoBandwidthGroupForDevice
278. ervice void IDisplay takeScreenShot in unsigned long screenld in ptr octet address in unsigned long width in unsigned long height in BitmapFormat bitmapFormat screenld address width 78 5 Classes interfaces height bitmapFormat Takes a screen shot of the requested size and format and copies it to the buffer allocated by the caller and pointed to by address The buffer size must be enough for a 32 bits per pixel bitmap i e width height 4 bytes Note This API can be used only locally by a VM process through the COM XPCOM C API as it requires pointer support It is not available for scripting languages Java or any webservice clients Unless you are writing a new VM frontend use takeScreenShotToArray 5 16 15 takeScreenShotToArray octet IDisplay takeScreenShotToArray in unsigned long screenld in unsigned long width in unsigned long height in BitmapFormat bitmapFormat screenld The guest monitor to take screenshot from width Desired image width height Desired image height bitmapFormat The requested format Takes a guest screen shot of the requested size and format and returns it as an array of bytes 5 16 16 viewportChanged void IDisplay viewportChanged in unsigned long screenld in unsigned long x in unsigned long y in unsigned long width in unsigned long height screenld Monitor to take the screenshot from X Framebuffer x
279. es IPC progress Progress object for this operation Triggers online merging of a hard disk Used internally when deleting a snapshot while a VM referring to the same hard disk chain is running If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open e VBOX_E_INVALID_OBJECT_STATE Session type is not direct 163 5 Classes interfaces 5 77 26 pauseWithReason void IInternalSessionControl pauseWithReason in Reason reason reason Specify the best matching reason code please Internal method for triggering a VM pause with a specified reason code The reason code can be interpreted by device drivers and thus it might behave slightly differently than a normal VM pause See also IConsole pause If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine not in Running state e VBOX_E_VM_ERROR Virtual machine error in suspend operation 5 77 27 reconfigureMediumAttachments void IInternalSessionControl reconfigureMediumAttachments in IMediumAttachment attachments attachments Array containing the medium attachments which need to be reconfigured Reconfigure all specified medium attachments in one go making sure the current state corre sponds to the specified medium If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open e V
280. es whether VirtualBox allows page fusion for this machine 64 bit hosts only 170 5 Classes interfaces 5 80 1 19 graphicsConirollerType read write GraphicsControllerType IMachine graphicsControllerType Graphics controller type 5 80 1 20 VRAMSize read write unsigned long IMachine VRAMSize Video memory size in megabytes 5 80 1 21 accelerate3DEnabled read write boolean IMachine accelerate3DEnabled This setting determines whether VirtualBox allows this machine to make use of the 3D graphics support available on the host 5 80 1 22 accelerate2DVideoEnabled read write boolean IMachine accelerate2DVideoEnabled This setting determines whether VirtualBox allows this machine to make use of the 2D video acceleration support available on the host 5 80 1 23 monitorCount read write unsigned long IMachine monitorCount Number of virtual monitors Note Only effective on Windows XP and later guests with Guest Additions installed 5 80 1 24 videoCaptureEnabled read write boolean IMachine videoCaptureEnabled This setting determines whether VirtualBox uses video recording to record VM session 5 80 1 25 videoCaptureScreens read write boolean IMachine videoCaptureScreens This setting determines for which screens video recording is enabled 5 80 1 26 videoCaptureFile read write wstring IMachine videoCaptureFile This setting determines the filename VirtualBox uses
281. ess in wstring networkMask IPAddress IP address networkMask network mask sets and enables the static IP V4 configuration for the given interface 5 71 5 enableStaticlIPConfig V6 void IHostNetworkInterface enableStaticIPConfigV6 in wstring IPV6Address in unsigned long IPV6NetworkMaskPrefixLength IPV6Address IP address IPV6NetworkMaskPrefixLength network mask sets and enables the static IP V6 configuration for the given interface 5 72 lIHostPCiDevicePlugEvent IMachineEvent Note This interface extends IMachineEvent and therefore supports all its methods and attributes as well Notification when host PCI device is plugged unplugged Plugging usually takes place on VM startup unplug when IMachine detachHostPCIDevice is called See also IMachine detachHostPCIDevice 5 72 1 Attributes 5 72 1 1 plugged read only boolean IHostPCIDevicePlugEvent plugged If device successfully plugged or unplugged 5 72 1 2 success read only boolean IHostPCIDevicePlugEvent success If operation was successful if false message attribute may be of interest 5 72 1 3 attachment read only IPCIDeviceAttachment IHostPCIDevicePlugEvent attachment Attachment info for this device 5 72 1 4 message read only wstring IHostPCIDevicePlugEvent message Optional error message 150 5 Classes interfaces 5 73 IHostUSBDevice IUSBDevice Note This interface extends IUSBD
282. ession A typical short web service session to retrieve the version number of the VirtualBox web service to be precise the underlying Main API version number looks like this 1 A client logs on to the web service by calling IWebsessionManager logon with a valid user name and password See chapter 1 4 2 Authenticating at web service logon page 25 for details about how authentication works 2 On the server side vboxwebsrv creates a session which persists until the client calls IWebsessionManager logoff or the session times out after a configurable period of in activity see chapter 1 4 1 Command line options of vboxwebsrv page 24 For the new session the web service creates an instance of IVirtualBox This interface is the most central one in the Main API and allows access to all other interfaces either through attributes or method calls For example VirtualBox contains a list of all virtual machines that are currently registered as they would be listed on the left side of the VirtualBox main program The web service then creates a managed object reference for this instance of IVirtualBox and returns it to the calling client which receives it as the return value of the logon call Something like this string oVirtualBox oVirtualBox webservice IWebsessionManager_logon user pass The managed object reference oVirtualBox is just a string consisting of digits and dashes However it is a string with a meani
283. est OS Note Currently only available for Windows guests since Windows 2000 SP2 Note On Windows guests this function currently only supports reporting contiguous idle times up to 49 7 days per user The event will be triggered if a guest user is not active for at least 5 seconds This threshold can be adjusted by either altering VBoxService s command line in the guest to vminfo user idle threshold lt ms gt or by setting the per VM guest property VirtualBox GuestAdd VBoxService vminfo user idle threshold lt ms gt with the RDONLYGUEST flag on the host In both cases VBoxService needs to be restarted in order to get the changes applied InUse A guest user continued using the guest OS after being idle Created A guest user has been successfully created Note This property is not implemented yet Deleted A guest user has been successfully deleted Note This property is not implemented yet SessionChanged To guest OS has changed the session of a user Note This property is not implemented yet CredentialsChanged To guest OS has changed the authentication credentials of a user This might include changed passwords and authentication types Note This property is not implemented yet RoleChanged To guest OS has changed the role of a user permanently e g granting denying administrative rights Note This property is not implemented ye
284. etails sharingMode The file sharing mode in the guest This parameter is currently ignore for all guest OSes It will in the future be implemented for Windows OS 2 and maybe Solaris guests only the others will ignore it Use FileSharingMode All creationMode The UNIX style access mode mask to create the file with if openAction requested the file to be created otherwise ignored Whether how all three access groups and as sociated access rights are realized is guest OS dependent The API does the best it can on each OS flags Zero or more FileOpenExFlags values Opens a file and creates a IGuestFile object that can be used for further operations extended version If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND File to open was not found e VBOX_E_IPRT_ERROR Error while opening the file 133 5 Classes interfaces 5 64 23 fileQuerySize long long IGuestSession fileQuerySize in wstring path in boolean followSymlinks path Path to the file which size is requested Guest path style followSymlinks It true symbolic links in the final path component will be followed to their target and the size of the target is returned If false symbolic links in the final path component will make the method call fail symblink is not a regular file Queries the size of a regular file in the guest If this method fails the following error codes may be reported e VBOX_E_OBJECT_
285. eted read only boolean IProgress completed Whether the task has been completed 5 115 1 8 canceled read only boolean IProgress canceled Whether the task has been canceled 275 5 Classes interfaces 5 115 1 9 resultCode read only long IProgress resultCode Result code of the progress task Valid only if completed is true 5 115 1 10 errorinfo read only IVirtualBoxErrorInfo IProgress erroriInfo Extended information about the unsuccessful result of the progress operation May be null if no extended information is available Valid only if completed is true and resultCode indicates a failure 5 115 1 11 operationCount read only unsigned long IProgress operationCount Number of sub operations this task is divided into Every task consists of at least one suboper ation 5 115 1 12 operation read only unsigned long IProgress operation Number of the sub operation being currently executed 5 115 1 13 operationDescription read only wstring IProgress operationDescription Description of the sub operation being currently executed 5 115 1 14 operationPercent read only unsigned long IProgress operationPercent Progress value of the current sub operation only in percent 5 115 1 15 operationWeight read only unsigned long IProgress operationWeight Weight value of the current sub operation only 5 115 1 16 timeout read write unsigned long IProgress timeout When non zero this spec
286. eturns facilities where a status is known e g facilities with an unknown status will not be returned 5 38 1 9 sessions read only IGuestSession IGuest sessions Returns a collection of all opened guest sessions 5 38 1 10 memoryBalloonSize read write unsigned long IGuest memoryBalloonSize Guest system memory balloon size in megabytes transient property 107 5 Classes interfaces 5 38 1 11 statisticsUpdatelnterval read write unsigned long IGuest statisticsUpdateInterval Interval to update guest statistics in seconds 5 38 2 createSession IGuestSession IGuest createSession in wstring user in wstring password in wstring domain in wstring sessionName user User name this session will be using to control the guest has to exist and have the appro priate rights to execute programs in the VM Must not be empty password Password of the user account to be used Empty passwords are allowed domain Domain name of the user account to be used if the guest is part of a domain Optional This feature is not implemented yet sessionName The session s friendly name Optional can be empty Creates a new guest session for controlling the guest The new session will be started asyn chronously meaning on return of this function it is not guaranteed that the guest session is in a started and or usable state To wait for successful startup use the IGuestSession waitFor call A guest session rep
287. evice and therefore supports all its methods and attributes as well The IHostUSBDevice interface represents a physical USB device attached to the host computer Besides properties inherited from IUSBDevice this interface adds the state property that holds the current state of the USB device See also IHost USBDevices IHost USBDeviceFilters 5 73 1 Attributes 5 73 1 1 state read only USBDeviceState IHostUSBDevice state Current state of the device 5 74 lHostUSBDeviceFilter IUSBDeviceFilter Note This interface extends IUSBDeviceFilter and therefore supports all its methods and attributes as well The IHostUSBDeviceFilter interface represents a global filter for a physical USB device used by the host computer Used indirectly in IHost USBDeviceFilters Using filters of this type the host computer determines the initial state of the USB device after it is physically attached to the host s USB controller Note The IUSBDeviceFilter remote attribute is ignored by this type of filters because it makes sense only for machine USB filters See also IHost USBDeviceFilters 5 74 1 Attributes 5 74 1 1 action read write USBDeviceFilterAction IHostUSBDeviceFilter action Action performed by the host when an attached USB device matches this filter 5 75 lIHostVideolnputDevice Represents one of host s video capture devices for example a webcam 5 75 1 Attributes 5 75 1 1 name rea
288. evice slot in the given port to attach the device to This is only relevant for IDE con trollers for which O specifies the master device and 1 specifies the slave device For all other controller types this must be 0 type Device type of the attached device For media opened by IVirtualBox 0penMediumo this must match the device type specified there Attaches a device and optionally mounts a medium to the given storage controller IStorageController identified by name at the indicated port and device This method is intended for managing storage devices in general while a machine is powered off It can be used to attach and detach fixed and removable media The following kind of media can be attached to a machine e For fixed and removable media you can pass in a medium that was previously opened using IVirtualBox openMedium e Only for storage devices supporting removable media such as DVDs and floppies with an empty drive or one of the medium objects listed in the IHost DVDDrives and IHost floppyDrives arrays to indicate a host drive For removable devices you can also use mountMedium to change the media while the machine is running In a VM s default configuration of virtual machines the secondary master of the IDE controller is used for a CD DVD drive IMediumAttachment will appear in the machine s list of medium attachments see mediumAttachments See Medium and IMediumAttachment for more information about at
289. example for Perl We also ship a small sample for Perl It uses the SOAP Lite perl module to communicate with the VirtualBox web service The sdk bindings webservice perl lib directory contains a pre generated Perl module that allows for communicating with the web service from Perl You can generate such a module yourself using the stubmaker tool that comes with SOAP Lite but since that tool is slow as well as sometimes unreliable we are shipping a working module with the SDK for your convenience Perform the following steps 1 If SOAP Lite is not yet installed on your system you will need to install the package first On Debian based systems the package is called libsoap lite perl on Gentoo it s dev perl SOAP Lite 2 Open a terminal in the sdk bindings webservice perl samples directory 31 2 Environment specific notes 3 To start the VirtualBox web service open a second terminal and change to the directory where the VirtualBox executables are located Then type vboxwebsrv v The web service now waits for connections and will run until you press Ctrl C in this second terminal The v argument causes it to log all connections to the terminal See chapter 1 4 Running the web service page 24 for details on how to run the web service 4 In the first terminal with the Perl sample run the clienttest pl script perl I lib clienttest pl 2 2 3 Programming considerations for the raw web service If you use
290. f in unsigned long id out unsigned long valEax out unsigned long valEbx out unsigned long valEcx out unsigned long valEdx id CPUID leaf index valEax CPUID leaf value for register eax valEbx CPUID leaf value for register ebx valEcx CPUID leaf value for register ecx valEdx CPUID leaf value for register edx Returns the virtual CPU cpuid information for the specified leaf Currently supported index values for cpuid Standard CPUID leafs 0 OxA Extended CPUID leafs Ox80000000 0x8000000A See the Intel and AMD programmer s manuals for detailed information about the cpuid in struction and its leafs If this method fails the following error codes may be reported e E_INVALIDARG Invalid id 5 80 26 getCPUProperty boolean IMachine getCPUProperty in CPUPropertyType property property Property type to query Returns the virtual CPU boolean value of the specified property If this method fails the following error codes may be reported e E_INVALIDARG Invalid property 5 80 27 getCPUStatus boolean IMachine getCPUStatus in unsigned long cpu cpu The CPU id to check for Returns the current status of the given CPU 5 80 28 getEffectiveParavirtProvider ParavirtProvider IMachine getEffectiveParavirtProvider Returns the effective paravirtualization provider for this VM 192 5 Classes interfaces 5 80 29 getExtraData wstring IMachine getExtraData in wstring key
291. f the guest display in pixels height Height of the guest display in pixels Requests a size change 5 35 5 notifyUpdate void IFramebuffer notifyUpdate in unsigned long x in unsigned long y in unsigned long width in unsigned long height xX y width height Informs about an update Gets called by the display object where this buffer is registered 101 5 Classes interfaces 5 35 6 notifyUpdatelmage void IFramebuf fer notifyUpdateImage in unsigned long x in unsigned long y in unsigned long width in unsigned long height in octet image x y width height image Array with 32BPP image data Informs about an update and provides 32bpp bitmap 5 35 7 processVHWACommand Note This method is not supported in the web service void IFramebuf fer processVHWACommand in ptr octet command command Pointer to VBOXVHWACMD containing the command to execute Posts a Video HW Acceleration Command to the frame buffer for processing The commands used for 2D video acceleration DDraw surface creation destroying blitting scaling color con version overlaying etc are posted from quest to the host to be processed by the host hardware Note The address of the provided command must be in the process space of this IFramebuffer object 5 35 8 setVisibleRegion Note This method is not supported in the web service void IFramebuffer setVisibleR
292. firmed man ually in order to continue the installation process This applies to Windows 2000 and Win dows XP guests and therefore these guests can t be updated in a fully automated fashion with out user interaction However to start a Guest Additions update for the mentioned Windows versions anyway the flag AdditionsUpdateFlag WaitForUpdateStartOnly can be specified See AdditionsUpdateFlag for more information If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED Guest OS is not supported for automated Guest Additions up dates or the already installed Guest Additions are not ready yet e VBOX_E_IPRT_ERROR Error while updating 110 5 Classes interfaces 5 39 IGuestDirectory IDirectory Note This interface extends IDirectory and therefore supports all its methods and attributes as well Implementation of the IDirectory object for directories in the guest 5 39 1 Attributes 5 39 1 1 midlDoesNotLikeEmptyInterfaces read only boolean IGuestDirectory midlDoesNotLikeEmptyInterfaces 5 40 IGuestDnDSource IDnDSource Note This interface extends IDnDSource and therefore supports all its methods and attributes as well Implementation of the IDnDSource object for source drag n drop operations on the guest 5 40 1 Attributes 5 40 1 1 midIDoesNotLikeEmptyInterfaces read only boolean IGuestDnDSource midlDoesNotLikeEmptyInterfaces 5 41 IGuestDnDTarget IDnDTa
293. g IProcess arguments The arguments this process is using for execution 5 114 1 2 environment read only wstring IProcess environment The initial process environment Not yet implemented 5 114 1 3 eventSource read only IEventSource IProcess eventSource Event source for process events 5 114 1 4 executablePath read only wstring IProcess executablePath Full path of the actual executable image 5 114 1 5 exitCode read only long IProcess exitCode The exit code Only available when the process has been terminated normally 5 114 1 6 name read only wstring IProcess name The friendly name of this process 5 114 1 7 PID read only unsigned long IProcess PID The process ID PID 272 5 Classes interfaces 5 114 1 8 status read only ProcessStatus IProcess status The current process status see ProcessStatus for more information 5 114 2 read octet IProcess read in unsigned long handle in unsigned long toRead in unsigned long timeoutMS handle Handle to read from Usually 0 is stdin toRead Number of bytes to read timeoutMS Timeout in ms to wait for the operation to complete Pass 0 for an infinite timeout Reads data from a running process 5 114 3 terminate void IProcess terminate Terminates kills a running process Note It can take up to 30 seconds to get a guest process killed In case a guest process could not be killed an appropriate error is ret
294. g Java API 11 1 Introduction VirtualBox can be controlled by a Java API both locally COM XPCOM and from remote SOAP clients As with the Python bindings a generic glue layer tries to hide all platform differences allowing for source and binary compatibility on different platforms 11 2 Requirements To use the Java bindings there are certain requirements depending on the platform First of all you need JDK 1 5 Java 5 or later Also please make sure that the version of the VirtualBox API jar file exactly matches the version of VirtualBox you use To avoid confusion the VirtualBox API provides versioning in the Java package name e g the package is named org virtualbox_3_2 for VirtualBox version 3 2 XPCOM for all platforms but Microsoft Windows A Java bridge based on JavaXPCOM is shipped with VirtualBox The classpath must contain vboxjxpcom jar and the vbox home property must be set to location where the VirtualBox binaries are Please make sure that the JVM bitness matches bitness of VirtualBox you use as the XPCOM bridge relies on native libraries Start your application like this java cp vboxjxpcom jar Dvbox home opt virtualbox MyProgram COM for Microsoft Windows We rely on Jacob a generic Java to COM bridge which has to be installed seperately See http sourceforge net projects jacob project for installation instructions Also the VirtualBox provided vboxjmscom jar must be in the class path Start
295. g deleted SettingUp Lengthy setup operation is in progress Snapshotting Taking an offline snapshot FirstOnline Pseudo state first online state for use in relational expressions LastOnline Pseudo state last online state for use in relational expressions FirstTransient Pseudo state first transient state for use in relational expressions LastTransient Pseudo state last transient state for use in relational expressions 354 6 Enumerations enums 6 64 MediumFormatCapabilities Medium format capability flags Uuid Supports UUIDs as expected by VirtualBox code CreateFixed Supports creating fixed size images allocating all space instantly CreateDynamic Supports creating dynamically growing images allocating space on demand CreateSplit2G Supports creating images split in chunks of a bit less than 2 GBytes Differencing Supports being used as a format for differencing media see IMedium createDiffStorage Asynchronous Supports asynchronous I O operations for at least some configurations File The format backend operates on files the IMedium location attribute of the medium specifies a file used to store medium data for a list of supported file extensions see IMediumFormat describeFileExtensions Properties The format backend uses the property interface to configure the storage location and properties the MediumFormat describeProperties method is used to get access to properties supported by the given
296. gE SS8 oo uk ich ee ee A a 219 5 82 15 modifyLogGronpS gt e o cni seee eaa a aes 219 382 16 quer O SKemello i ecs one beste aa e a a 219 5 82 17 readPhysical Memory oces ec eee ee eA cedre tnis 220 562 18 radyirtualMemory e oo s te o a a ww ge 220 11 5 83 5 84 5 85 5 86 5 87 5 88 5 89 5 90 5 91 5 92 5 93 Contents SBa e e kok OATS A a ww EG e ws DR ae Se 220 5 82 2 SCURCSIRIGr 0 2 2 2S baw hk ee AAA eee aS 220 5 0221 SCLBCSISIETS o o oe oe a ok ee cd de 221 5 82 22 unloadPlugin occ eea 38285 649444444448 204444444 221 5 82 23 writePhysicalMemory isso a a e 221 5 82 24 writeVirtualMemory 2 a e 221 IMachineEvent IEvent osoa a eee ee es 222 SELI ADUS coso ee he OOS OOM SEE EEE De 222 IMachineRegisteredEvent IMachineEvent 20000 eee 222 S204 e saocrad ee a Oe Pa eee 222 IMachineStateChangedEvent IMachineEvent 222 MI e ee 5 ae eee es eed eee at we ee ee ee we ee een EA 222 IManagedObjectRef on kaa ee be eee UA Rae Ee Ee EGS 223 586 1 generace Name mbr sa ow wee ee Bp ee ee 223 5 86 2 releas cocoa RRR eda aR RASS EDR RED ae eA Ss 223 A ease Sone caesar ss gs ge fy Be SOs He aka a ae A eH Sw ea ade at a es 223 Say o 6 ose nee base kode bed Powe eee eee st aaax 225 SETA changeEncryphon eoo s eds a ke ek A 230 5 87 3 checkEncryptionPassword o e eee 230 SOTA o AN 230 5 67 59 A AAA 231 5 87 60 close AP RAR SEE EE EDR aS 2
297. gacy settings version not currently supported v1_2 Legacy settings version not currently supported v1_3pre Legacy settings version not currently supported v1_3 Settings version 1 3 written by VirtualBox 2 0 12 v1_4 Intermediate settings version understood by VirtualBox 2 1 x v1_5 Intermediate settings version understood by VirtualBox 2 1 x v1_6 Settings version 1 6 written by VirtualBox 2 1 4 at least v1_7 Settings version 1 7 written by VirtualBox 2 2 x and 3 0 x v1_8 Intermediate settings version 1 8 understood by VirtualBox 3 1 x v1_9 Settings version 1 9 written by VirtualBox 3 1 x v1_10 Settings version 1 10 written by VirtualBox 3 2 x v1_11 Settings version 1 11 written by VirtualBox 4 0 x v1_12 Settings version 1 12 written by VirtualBox 4 1 x v1_13 Settings version 1 13 written by VirtualBox 4 2 x v1_14 Settings version 1 14 written by VirtualBox 4 3 x v1_15 Settings version 1 15 written by VirtualBox 5 0 x Future Settings version greater than 1 15 written by a future VirtualBox version 6 92 StorageBus The bus type of the storage controller IDE SATA SCSI SAS or Floppy see IStorageController bus Null null value Never used by the API IDE SATA SCSI Floppy SAS USB 364 6 Enumerations enums 6 93 StorageControllerType The exact variant of storage controller hardware presented to the guest see IStora
298. geController controllerType Null null value Never used by the API LsiLogic A SCSI controller of the LsiLogic variant BusLogic A SCSI controller of the BusLogic variant IntelAhci An Intel AHCI SATA controller this is the only variant for SATA PIIX3 An IDE controller of the PIIX3 variant PIIX4 An IDE controller of the PIIX4 variant ICH6 An IDE controller of the ICH6 variant 182078 A floppy disk controller this is the only variant for floppy drives LsiLogicSas A variant of the LsiLogic controller using SAS USB Special USB based storage controller 6 94 SymlinkReadFlag Symbolic link reading flags None No flags set NoSymlinks Don t allow symbolic links as part of the path 6 95 SymlinkType Symbolic link types This is significant when creating links on the Windows platform ignored elsewhere Unknown It is not known what is being targeted Directory The link targets a directory File The link targets a file or whatever else except directories 6 96 TouchContactState Touch event contact state None The touch has finished InContact Whether the touch is really touching the device InRange Whether the touch is close enough to the device to be detected ContactStateMask 365 6 Enumerations enums 6 97 USBConnectionSpeed USB device port speed state This enumeration represents speeds at which a USB device can communicate with the host The speed is a function of both the device itself and the
299. ged as follows Replaced IGuestSession directoryQueryInfo and IGuestSession fileQueryInfo with a new IGuestSession fsObjQueryInfo method that works on any type of file system ob ject Replaced IGuestSession fileRemove IGuestSession symlinkRemoveDirectory and IGuestSession symlinkRemoveFile with a new IGuestSession fsObjRemove method that works on any type of file system object except directories fileRemove also worked on any type of object too though that was not the intent of the method Replaced IGuestSession directoryRename and IGuestSession directoryRename with a new IGuestSession fsObjRename method that works on any type of file system ob ject directoryRename and fileRename may already have worked for any kind of object but that was never the intent of the methods Replaced the unimplemented IGuestSession directorySetACL and IGuestSes sion fileSetACL with a new IGuestSession fsObjSetACL method that works on all type of file system object Also added a UNIX style mode parameter as an alternative to the ACL Replaced IGuestSession fileRemove IGuestSession symlinkRemoveDirectory and IGuestSession symlinkRemoveFile with a new IGuestSession fsObjRemove method that works on any type of file system object except directories fileRemove also worked on any type of object though that was not the intent of the method Renamed IGuestSession copyTo to IGuestSession fileCopyToGuest Renamed I
300. gister Gets all the registers for the given CPU 5 82 9 getStats wstring IMachineDebugger getStats in wstring pattern in boolean withDescriptions pattern The selection pattern A bit similar to filename globbing withDescriptions Whether to include the descriptions Get the VM statistics in a XMLish format 5 82 10 info wstring IMachineDebugger info in wstring name in wstring args name The name of the info item args Arguments to the info dumper Interfaces with the info dumpers DBGFInfo This feature is not implemented in the 4 0 0 release but it may show up in a dot release 218 5 Classes interfaces 5 82 11 injectNMI void IMachineDebugger injectNMI Inject an NMI into a running VI x AMD V VM 5 82 12 loadPlugin wstring IMachineDebugger loadPluglIn in wstring name name The plug in name or DLL Special name all loads all installed plug ins Loads a DBGF plug in 5 82 13 modifyLogDestinations void IMachineDebugger modifyLogDestinations in wstring settings settings The destination settings string See iprt log h for details To target the release logger prefix the string with release Modifies the debug or release logger destinations 5 82 14 modifyLogFlags void IMachineDebugger modifyLogFlags in wstring settings settings The flags settings string See iprt log h for details To target the release logger prefix the string with rel
301. gned long IMousePointerShapeChangedEvent xhot The pointer hot spot X coordinate 251 5 Classes interfaces 5 96 1 4 yhot read only unsigned long IMousePointerShapeChangedEvent yhot The pointer hot spot Y coordinate 5 96 1 5 width read only unsigned long IMousePointerShapeChangedEvent width Width of the pointer shape in pixels 5 96 1 6 height read only unsigned long IMousePointerShapeChangedEvent height Height of the pointer shape in pixels 5 96 1 7 shape read only octet IMousePointerShapeChangedEvent shape Shape buffer arrays The shape buffer contains a 1 bpp bits per pixel AND mask followed by a 32 bpp XOR color mask For pointers without alpha channel the XOR mask pixels are 32 bit values Isb BGRO msb For pointers with alpha channel the XOR mask consists of Isbp BGRA msb 32 bit values An AND mask is used for pointers with alpha channel so if the callback does not support alpha the pointer could be displayed as a normal color pointer The AND mask is a 1 bpp bitmap with byte aligned scanlines The size of the AND mask therefore is cbAnd width 7 8 height The padding bits at the end of each scanline are undefined The XOR mask follows the AND mask on the next 4 byte aligned offset uint8_t pXor pAnd cbAnd 3 amp 3 Bytes in the gap between the AND and the XOR mask are unde fined The XOR mask scanlines have no gap between them and the size of the XOR mas
302. gs are not persistent they are discarded as soon as VBoxSVC process terminates Moreover metric settings and data associated with a particular VM only exist while VM is running They disappear as soon as VM shuts down It is not possible to set up metrics for machines that are powered off One needs to start VM first then set up metric collection parameters Metrics are organized hierarchically with each level separated by a slash character Gener ally the scheme for metric names is like this Category Metric SubMetric aggregation Category Metric together form the base metric name A base metric is the smallest unit for which a sampling interval and the number of retained samples can be set Only base metrics can be enabled and disabled All sub metrics are collected when their base metric is collected Collected values for any set of sub metrics can be queried with queryMetricsData For example CPU Load User avg metric name stands for the CPU category Load metric User submetric average aggregate An aggregate function is computed over all retained data Valid aggregate functions are e avg average e min minimum e max maximum When setting up metric parameters querying metric data enabling or disabling metrics wild cards can be used in metric names to specify a subset of metrics For example to select all CPU related metrics use CPU all averages can be queried using avg and s
303. gt is the default extension for the storage format of this hard disk After that you may call any of the methods that create a new hard disk storage unit and they will use the generated UUID and file name 5 87 1 Attributes 5 87 1 1 id read only uuid IMedium id UUID of the medium For a newly created medium this value is a randomly generated UUID Note For media in one of MediumState_NotCreated MediumState_Creating or Medi umState_Deleting states the value of this property is undefined and will most likely be an empty UUID 5 87 1 2 description read write wstring IMedium description Optional description of the medium For a newly created medium the value of this attribute is an empty string Medium types that don t support this attribute will return E NOTIMPL in attempt to get or set this attribute s value 225 5 Classes interfaces Note For some storage types reading this attribute may return an outdated last known value when state is Inaccessible or LockedWrite because the value of this at tribute is stored within the storage unit itself Also note that changing the attribute value is not possible in such case as well as when the medium is the LockedRead state 5 87 1 3 state read only MediumState IMedium state Returns the current medium state which is the last state set by the accessibility check per formed by refreshState If that method has not yet been called on the
304. h some of the samples shipped with VirtualBox this needs to be written by you lIn some ways web services promise to deliver the same thing as CORBA and DCOM did years ago However while these previous technologies relied on specific binary protocols and thus proved to be difficult to use between diverging platforms web services circumvent these incompatibilities by using text only standards like HTTP and XML On the downside and one could say typical of things related to XML a lot of standards are involved before a web service can be implemented Many of the standards invented around XML are used one way or another As a result web services are slow and verbose and the details can be incredibly messy The relevant standards here are called SOAP and WSDL where SOAP describes the format of the messages that are exchanged an XML document wrapped in an HTTP header and WSDL is an XML format that describes a complete API provided by a web service WSDL in turn uses XML Schema to describe types which is not exactly terse either However as you will see from the samples provided in this chapter the VirtualBox web service shields you from these details and is easy to use 23 1 Introduction 1 4 Running the web service The web service ships in an stand alone executable vboxwebsrv that when running acts as a HTTP server accepts SOAP connections and processes them remotely or from the same machine Note The web service execu
305. hacks Install the extension pack 5 30 IExtPackManager Note This interface is not supported in the web service Interface for managing VirtualBox Extension Packs todo Describe extension packs how they are managed and how to create one 5 30 1 Attributes 5 30 1 1 installedExtPacks read only IExtPack IExtPackManager installedExtPacks Note This attribute is not supported in the web service List of the installed extension packs 92 5 Classes interfaces 5 30 2 cleanup void IExtPackManager cleanup Cleans up failed installs and uninstalls 5 30 3 find Note This method is not supported in the web service IExtPack IExtPackManager find in wstring name name The name of the extension pack to locate Returns the extension pack with the specified name if found If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND No extension pack matching name was found 5 30 4 isExtPackUsable boolean IExtPackManager isExtPackUsable in wstring name name The name of the extension pack to check for Check if the given extension pack is loaded and usable 5 30 5 openExtPackFile Note This method is not supported in the web service IExtPackFile IExtPackManager openExtPackFile in wstring path path The path of the extension pack tarball This can optionally be followed by a SHA 256 hex digit
306. hanges stored in differencing media will be lost See ISnapshot for an introduction to snapshots After this operation is successfully completed new empty differencing media are created for all normal media of the machine If the given snapshot is an online snapshot the machine will go to the Saved so that the next time it is powered on the execution state will be restored from the state of the snapshot Note The machine must not be running otherwise the operation will fail Note If the machine state is Saved prior to this operation the saved state file will be implicitly deleted as if discardSavedState were called If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine is running 5 80 64 saveSettings void IMachine saveSettings Saves any changes to machine settings made since the session has been opened or a new ma chine has been created or since the last call to saveSettings or discardSettings For registered machines new settings become visible to all other VirtualBox clients after successful invocation of this method Note The method sends IMachineDataChangedEvent notification event after the con figuration has been successfully saved only for registered machines Note Calling this method is only valid on instances returned by ISession machine and on new machines created by IVirtualBox createMachine but not yet
307. he PCI bus of the virtual ma chine Please note that this operation is two phase as real attachment will happen when VM will start and most information will be delivered as IHostPCIDevicePlugEvent on IVirtualBox event source See also IHostPCIDevicePlugEvent If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine state is not stopped PCI hotplug not yet implemented e VBOX_E_PDM_ERROR Virtual machine does not have a PCI controller allowing attachment of physical devices e VBOX_E_NOT_SUPPORTED Hardware or host OS doesn t allow PCI device passthrough 5 80 9 canShowConsoleWindow boolean IMachine canShowConsoleWindow Returns true if the VM console process can activate the console window and bring it to fore ground on the desktop of the host PC Note This method will fail if a session for this machine is not currently open If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open 184 5 Classes interfaces 5 80 10 cloneTo IProgress IMachine cloneTo in IMachine target in CloneMode mode in CloneOptions options target Target machine object mode Which states should be cloned options Options for the cloning operation Creates a clone of this machine either as a full clone which means creating independent copies of the hard disk media save states and so on or
308. he collection using createSharedFolder Existing shared folders can be removed using removeSharedFolder Note In the current version of the product global shared folders are not implemented and therefore this collection is always empty 315 5 Classes interfaces 5 151 1 19 performanceCollector read only IPerformanceCollector IVirtualBox performanceCollector Associated performance collector object 5 151 1 20 DHCPServers read only IDHCPServer IVirtualBox DHCPServers DHCP servers 5 151 1 21 NATNetworks read only INATNetwork IVirtualBox NATNetworks 5 151 1 22 eventSource read only IEventSource IVirtualBox eventSource Event source for VirtualBox events 5 151 1 23 extensionPackManager read only IExtPackManager IVirtualBox extensionPackManager Note This attribute is not supported in the web service The extension pack manager 5 151 1 24 internalNetworks read only wstring IVirtualBox internalNetworks Names of all internal networks 5 151 1 25 genericNetworkDrivers read only wstring IVirtualBox genericNetworkDrivers Names of all generic network drivers 5 151 2 checkFirmwarePresent boolean IVirtualBox checkFirmwarePresent in FirmwareType firmwareType in wstring version out wstring url out wstring file firmwareType Type of firmware to check version Expected version number usually empty string presently ignored url
309. he directory to go in Change the current directory level 5 144 3 cdUp IProgress IVFSExplorer cdUp Go one directory upwards from the current directory level 5 144 4 entryList void IVFSExplorer entryList out wstring names out unsigned long types out long long sizes out unsigned long modes names The list of names for the entries types The list of types for the entries FsObjType sizes The list of sizes in bytes for the entries modes The list of file modes in octal form for the entries Returns a list of files directories after a call to update The user is responsible for keeping this internal list up do date 307 5 Classes interfaces 5 144 5 exists wstring IVFSExplorer exists in wstring names names The names to check Checks if the given file list exists in the current directory level 5 144 6 remove IProgress IVFSExplorer remove in wstring names names The names to remove Deletes the given files in the current directory level 5 144 7 update IProgress IVFSExplorer update Updates the internal list of files directories from the current directory level Use entryList to get the full list after a call to this method 5 145 IVRDEServer 5 145 1 Attributes 5 145 1 1 enabled read write boolean IVRDEServer enabled Flag if VRDE server is enabled 5 145 1 2 authType read write AuthType IVRDEServer authType VRDE authentica
310. he involved media are in LockedRead or LockedWrite state Note This source medium and all intermediates will be placed to Deleting state and the target medium will be placed to LockedWrite state and for the duration of this operation 5 87 18 refreshState MediumState IMedium refreshState If the current medium state see MediumState is one of Created Inaccessible or Locke dRead then this performs an accessibility check on the medium and sets the value of the state attribute accordingly that value is also returned for convenience For all other state values this does not perform a refresh but returns the state only The refresh if performed may take a long time several seconds or even minutes depending on the storage unit location and format because it performs an accessibility check of the storage unit This check may cause a significant delay if the storage unit of the given medium is for example a file located on a network share which is not currently accessible due to connectivity problems In that case the call will not return until a timeout interval defined by the host OS for this operation expires For this reason it is recommended to never read this attribute on the main UI thread to avoid making the UI unresponsive If the last known state of the medium is Created and the accessibility check fails then the state would be set to Inaccessible and lastAccessError may be used to ge
311. he session currently has a machine locked i e its state is Locked otherwise an error will be returned 5 120 1 3 name read write wstring ISession name Name of this session Important only for VM sessions otherwise it it will be remembered but not used for anything significant and can be left at the empty string which is the default The value can only be changed when the session state is SessionState_Unlocked Make sure that you use a descriptive name which does not conflict with the VM process session names GUI Qt GUI SDL and headless 5 120 1 4 machine read only IMachine ISession machine Machine object associated with this session 5 120 1 5 console read only IConsole ISession console Console object associated with this session Only sessions which locked the machine for a VM process have a non null console 282 5 Classes interfaces 5 120 2 unlockMachine void ISession unlockMachine Unlocks a machine that was previously locked for the current session Calling this method is required every time a machine has been locked for a particular session using the IMachine launchVMProcess or IMachine lockMachine calls Otherwise the state of the machine will be set to Aborted on the server and changes made to the machine settings will be lost Generally it is recommended to unlock all machines explicitly before terminating the applica tion regardless of the reason for the termination
312. he specified path must be absolute The specified path may not exist it will be created when necessary If this method fails the following error codes may be reported e E_NOTIMPL The operation is not implemented yet 5 80 78 setStorageControllerBootable void IMachine setStorageControllerBootable in wstring name in boolean bootable name bootable Sets the bootable flag of the storage controller with the given name If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND A storage controller with given name doesn t exist e VBOX_E_OBJECT_IN_USE Another storage controller is marked as bootable already 210 5 Classes interfaces 5 80 79 showConsoleWindow long long IMachine showConsoleWindow Activates the console window and brings it to foreground on the desktop of the host PC Many modern window managers on many platforms implement some sort of focus stealing prevention logic so that it may be impossible to activate a window without the help of the currently active application In this case this method will return a non zero identifier that represents the top level window of the VM console process The caller if it represents a currently active process is responsible to use this identifier in a platform dependent manner to perform actual window activation Note This method will fail if a session for this machine is not currently open If t
313. he value is null or empty the property will be deleted if it exists flags Additional property parameters passed as a comma separated list of name value type entries Sets changes or deletes an entry in the machine s guest property store If this method fails the following error codes may be reported e E_ACCESSDENIED Property cannot be changed e E_INVALIDARG Invalid flags e VBOX_E_INVALID_VM_STATE Virtual machine is not mutable or session not open e VBOX_E_INVALID_OBJECT_STATE Cannot set transient property when machine not run ning 5 80 73 setGuestPropertyValue void IMachine setGuestPropertyValue in wstring property in wstring value property The name of the property to set or change 208 5 Classes interfaces value The new value of the property to set or change If the property does not yet exist and value is non empty it will be created Sets or changes a value in the machine s guest property store The flags field will be left unchanged or created empty for a new property If this method fails the following error codes may be reported e E_ACCESSDENIED Property cannot be changed e VBOX_E_INVALID_VM_STATE Virtual machine is not mutable or session not open e VBOX_E_INVALID_OBJECT_STATE Cannot set transient property when machine not run ning 5 80 74 setHWVirtExProperty void IMachine setHwWVirtExProperty in HWVirtExPropertyType property in boolean value property Prop
314. her the error is fatal or not 5 117 1 2 id read only wstring IRuntimeErrorEvent id Error identifier 279 5 Classes interfaces 5 117 1 3 message read only wstring IRuntimeErrorEvent message Optional error message 5 118 ISerialPort The ISerialPort interface represents the virtual serial port device The virtual serial port device acts like an ordinary serial port inside the virtual machine This device communicates to the real serial port hardware in one of two modes host pipe or host device In host pipe mode the path attribute specifies the path to the pipe on the host computer that represents a serial port The server attribute determines if this pipe is created by the virtual machine process at machine startup or it must already exist before starting machine execution In host device mode the path attribute specifies the name of the serial port device on the host computer There is also a third communication mode the disconnected mode In this mode the guest OS running inside the virtual machine will be able to detect the serial port but all port write operations will be discarded and all port read operations will return no data See also IMachine getSerialPort 5 118 1 Attributes 5 118 1 1 slot read only unsigned long ISerialPort slot Slot number this serial port is plugged into Corresponds to the value you pass to IMachine getSerialPort to obtain this instance 5 118 1 2 enabled read write
315. hich require system level privileges Each guest session keeps track of the guest directories and files that it opened as well as guest processes it has created To work on guest files or directories a guest session offers methods to open or create such objects see fileOpen or directoryOpen for instance Similarly there a methods for creating guest processes There can be up to 2048 objects guest processes files and directories a time per guest session Exceeding the limit will result in an error When done with either of these objects including the guest session itself use the appropriate close method to let the object do its cleanup work Closing a session via close will try to close all the mentioned objects above unless these objects are still used by a client 123 5 Classes interfaces A set of environment variables changes is associated with each session environmentChanges These are applied to the base environment of the impersonated guest user when creating a new guest process For additional flexibility the processCreate and processCreateEx methods allows you to specify individual environment changes for each process you create With newer guest addition versions the base environment is also made available via environmentBase One reason for why we record changes to a base environment instead of working directly on an environment block is that we need to be compatible with older guest additions Another reaso
316. hich will be unmounted first Speci fying a zero UUID or an empty string for medium does just an unmount See IMedium for more detailed information about attaching media If this method fails the following error codes may be reported e E_INVALIDARG SATA device SATA port IDE port or IDE slot out of range e VBOX_E_INVALID_OBJECT_STATE Attempt to attach medium to an unregistered virtual machine e VBOX_E_INVALID_VM_STATE Invalid machine state e VBOX_E_OBJECT_IN_USE Medium already attached to this or another virtual machine 5 80 50 nonRotationalDevice void IMachine nonRotationalDevice in wstring name in long controllerPort in long device in boolean nonRotational name Name of the storage controller controllerPort Storage controller port device Device slot in the given port nonRotational New value for the non rotational device flag Sets a flag in the device information which indicates that the medium is not based on rotational technology i e that the access times are more or less independent of the position on the medium This may or may not be supported by a particular drive and is silently ignored in the latter case At the moment only hard disks which is a misnomer in this context accept this setting Changing the setting while the VM is running is forbidden The device must already exist see attachDevice for how to attach a new device The controllerPort and device parameters specify the dev
317. hine export has been renamed to IMachine exportTo to improve API client binding compatibility For IMachine launchVMProcess the meaning of the type parameter has changed slightly Empty string now means that the per VM or global default frontend is launched Most callers of this method should use the empty string now unless they really want to override the default and launch a particular frontend Medium management APIs were changed as follows The type of attribute IMedium variant changed from unsigned long to safe array MediumVariant It is an array of flags instead of a set of flags which were stored inside one variable The parameter list for IMedium cloneTo was modified The type of parameter vari ant was changed from unsigned long to safe array MediumVariant The parameter list for IMedium createBaseStorage was modified The type of pa rameter variant was changed from unsigned long to safe array MediumVariant The parameter list for IMedium createDiffStorage was modified The type of pa rameter variant was changed from unsigned long to safe array MediumVariant The parameter list for IMedium cloneToBase was modified The type of parameter variant was changed from unsigned long to safe array MediumVariant The type of attribute IMediumFormat capabilities changed from unsigned long to safe array MediumFormatCapabilities Itis an array of flags instead of a set of flags which were stored in
318. his case the operation is performed immediately and progress is returning a null reference Otherwise on success there is a progress object returned which signals progress and completion of the operation This distinction is necessary because for some formats the operation is very fast while for others it can be very slow moving the image file by copying all data and in the former case it d be a waste of resources to create a progress object which will immediately signal completion When setting a location for a medium which corresponds to a several regular file s in the host s file system the given file name may be either relative to the VirtualBox home folder or absolute Note that if the given location specification does not contain the file extension part then a proper default extension will be automatically appended by the implementation depending on the medium type If this method fails the following error codes may be reported 238 5 Classes interfaces e E_NOTIMPL The operation is not implemented yet e VBOX_E_NOT_SUPPORTED Medium format does not support changing the location 5 87 23 setProperties void IMedium setProperties in wstring names in wstring values names Names of properties to set values Values of properties to set Sets values for a group of properties in one call The names of the properties to set are passed in the names array along with the new values for them in the values array
319. his method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open 5 80 80 takeSnapshot IProgress IMachine takeSnapshot in wstring name in wstring description in boolean pause out uuid id name Short name for the snapshot description Optional description of the snapshot pause Whether the VM should be paused while taking the snapshot Only relevant when the VM is running and distinguishes between online t rue and live false snapshots When the VM is not running the result is always an offline snapshot id UUID of the snapshot which will be created Useful for follow up operations after the snapshot has been created Saves the current execution state and all settings of the machine and creates differencing images for all normal non independent media See ISnapshot for an introduction to snapshots This method can be called for a PoweredOff Saved see saveState Running or Paused virtual machine When the machine is PoweredOff an offline snapshot is created When the machine is Running a live snapshot is created and an online snapshot is created when Paused The taken snapshot is always based on the current snapshot of the associated virtual machine and becomes a new current snapshot Note This method implicitly calls saveSettings to save all current machine settings before taking an offline snapshot If this method fails the following erro
320. iTouchQ See also putEventMultiTouch 5 93 4 putMouseEvent void IMouse putMouseEvent in long dx in long dy in long dz in long dw in long buttonState dx Amount of pixels the mouse should move to the right Negative values move the mouse to the left dy Amount of pixels the mouse should move downwards Negative values move the mouse upwards dz Amount of mouse wheel moves Positive values describe clockwise wheel rotations negative values describe counterclockwise rotations dw Amount of horizontal mouse wheel moves Positive values describe a movement to the left negative values describe a movement to the right buttonState The current state of mouse buttons Every bit represents a mouse button as follows Bit O 0x01 left mouse buttonBit 1 0x02 right mouse buttonBit 2 0x04 middle mouse button A value of 1 means the corresponding button is pressed otherwise it is released Initiates a mouse event using relative pointer movements along x and y axis If this method fails the following error codes may be reported e E_ACCESSDENIED Console not powered up e VBOX_E_IPRT_ERROR Could not send mouse event to virtual mouse 248 5 Classes interfaces 5 93 5 putMouseEventAbsolute void IMouse putMouseEventAbsolute in long x in long y in long dz in long dw in long buttonState x X coordinate of the pointer in pixels starting from 1 y Y coordinate of the pointer in pixels star
321. ibutes 5 1 1 1 classType read only AdditionsFacilityClass IAdditionsFacility classType The class this facility is part of 5 1 1 2 lastUpdated read only long long IAdditionsFacility LastUpdated Time stamp of the last status update in milliseconds since 1970 01 01 UTC 5 1 1 3 name read only wstring IAdditionsFacility name The facility s friendly name 5 1 1 4 status read only AdditionsFacilityStatus IAdditionsFacility status The current status 5 1 1 5 type read only AdditionsFacilityType IAdditionsFacility type The facility s type ID 5 2 lAdditionsStateChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when a Guest Additions property changes Interested callees should query IGuest attributes to find out what has changed 52 5 Classes interfaces 5 2 1 Attributes 5 2 1 1 midlDoesNotLikeEmptylnterfaces read only boolean IAdditionsStateChangedEvent midlDoesNotLikeEmptyInterfaces 5 3 Appliance Represents a platform independent appliance in OVF format An instance of this is returned by TVirtualBox createAppliance which can then be used to import and export virtual machines within an appliance with VirtualBox The OVF standard suggests two different physical file formats 1 If the appliance is distributed as a set of files there must be at least one XML descriptor file
322. ice location information 128 bytes tion clien The client identifier assigned to the connecting client by the HGCM subsystem tld 32 bit The type field tells the HGCM how to look for the requested service Name hexadecimal Description value VMMDevHGCM The requested service is a shared library located on the host and Loc_LocalHost the location information contains the library name 0x1 VMMDevHGCM The requested service is a preloaded one and the location Loc_LocalHost Existing information contains the service name 0x2 373 7 Host Guest Communication Manager Note Currently preloaded HGCM services are hard coded in VirtualBox e VBoxSharedFolders e VBoxSharedClipboard e VBoxGuestPropSvc e VBoxSharedOpenGL There is no difference between both types of HGCM services only the location mechanism is different The client identifier is returned by the host and must be used in all subsequent requests by the client 7 2 3 Disconnect This request disconnects the client and makes the client identifier invalid VMMDevHGCMDis connect Name Description header The generic HGCM request header with type equal to VMMDevReq_HGCMDisconnect 61 clien The client identifier previously returned by the connect request 32 bit tld 7 2 4 Call32 and Call64 Calls the HGCM service entry point VMMDevHGCMCall using 32 bit or 64 bit addresses Name Desc
323. ice slot and have have the same meaning as with attachDevice If this method fails the following error codes may be reported e E_INVALIDARG SATA device SATA port IDE port or IDE slot out of range e VBOX_E_INVALID_OBJECT_STATE Attempt to modify an unregistered virtual machine e VBOX_E_INVALID_VM_STATE Invalid machine state 200 5 Classes interfaces 5 80 51 passthroughDevice void IMachine passthroughDevice in wstring name in long controllerPort in long device in boolean passthrough name Name of the storage controller controllerPort Storage controller port device Device slot in the given port passthrough New value for the passthrough setting Sets the passthrough mode of an existing DVD device Changing the setting while the VM is running is forbidden The setting is only used if at VM start the device is configured as a host DVD drive in all other cases it is ignored The device must already exist see attachDevice for how to attach a new device The controllerPort and device parameters specify the device slot and have have the same meaning as with attachDevice If this method fails the following error codes may be reported e E_INVALIDARG SATA device SATA port IDE port or IDE slot out of range e VBOX_E_INVALID_OBJECT_STATE Attempt to modify an unregistered virtual machine e VBOX_E_INVALID_VM_STATE Invalid machine state 5 80 52 queryLogFilename wstring IMachine queryLogFilename
324. icular this means that this medium can later be opened again using the IVirtualBox openMedium call Note that after this method successfully returns the given medium object becomes uninitial ized This means that any attempt to call any of its methods or attributes will fail with the Object not ready E_ACCESSDENIED error If this method fails the following error codes may be reported e VBOX_E_INVALID_OBJECT_STATE Invalid medium state other than not created created or inaccessible e VBOX_E_OBJECT_IN_USE Medium attached to virtual machine e VBOX_E_FILE_ERROR Settings file not accessible e VBOX_E_XML_ERROR Could not parse the settings file 5 87 7 compact IProgress IMedium compact Starts compacting of this medium This means that the medium is transformed into a possibly more compact storage representation This potentially creates temporary images which can require a substantial amount of additional disk space This medium will be placed to LockedWrite state and all its parent media if any will be placed to LockedRead state for the duration of this operation Please note that the results can be either returned straight away or later as the result of the background operation via the object returned via the progress parameter If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED Medium format does not support compacting but potentially needs it 5 87 8 createBaseStorage
325. ied 5 14 8 start void IDHCPServer start in wstring networkName in wstring trunkName in wstring trunkType networkName Name of internal network DHCP server should attach to trunkName Name of internal network trunk trunkType Type of internal network trunk Starts DHCP server process If this method fails the following error codes may be reported e E_FAIL Failed to start the process 73 5 Classes interfaces 5 14 9 stop void IDHCPServer stop Stops DHCP server process If this method fails the following error codes may be reported e E_FAIL Failed to stop the process 5 15 IDirectory Abstract parent interface for directories handled by VirtualBox 5 15 1 Attributes 5 15 1 1 directoryName read only wstring IDirectory directoryName The path specified when opening the directory 5 15 1 2 filter read only wstring IDirectory filter Directory listing filter to specified when opening the directory 5 15 2 close void IDirectory close Closes this directory After closing operations like reading the next directory entry will not be possible anymore 5 15 3 read IFsObjInfo IDirectory read Reads the next directory entry of this directory If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND No more directory entries to read 5 16 IDisplay The IDisplay interface represents the virtual machine s display The object implem
326. if ev null downcast to specific event interface in this case we have only registered for one type otherwise IEvent type would tell us IMachineStateChangedEvent mcse IMachineStateChangedEvent queryInterface ev inspect and do something es eventProcessed listener ev es unregisterListener listener A graphical user interface would probably best start its own thread to wait for events and then process these in a loop The events mechanism was introduced with VirtualBox 3 3 and replaces various callback in terfaces which were called for each event in the interface The callback mechanism was not compatible with scripting languages local Java bindings and remote web services as they do not support callbacks The new mechanism with events and event listeners works with all of these To simplify developement of application using events concept of event aggregator was intro duced Essentially its mechanism to aggregate multiple event sources into single one and then work with this single aggregated event source instead of original sources As an example one can evaluate demo recorder in VirtualBox Python shell shipped with SDK it records mouse and keyboard events represented as separate event sources Code is essentially like this listener console eventSource createListener agg console eventSource createAggregator console keyboard eventSource console mouse eventSource agg registerListener listener
327. ifies the number of milliseconds after which the operation will auto matically be canceled This can only be set on cancelable objects 276 5 Classes interfaces 5 115 2 cancel void IProgress cancel Cancels the task Note If cancelable is false then this method will fail If this method fails the following error codes may be reported e VBOX_E_INVALID_OBJECT_STATE Operation cannot be canceled 5 115 3 setCurrentOperationProgress void IProgress setCurrentOperationProgress in unsigned long percent percent Internal method not to be called externally 5 115 4 setNextOperation void IProgress setNextOperation in wstring nextOperationDescription in unsigned long nextOperationsWeight nextOperationDescription nextOperationsWeight Internal method not to be called externally 5 115 5 waitForAsyncProgressCompletion void IProgress waitForAsyncProgressCompletion in IProgress pProgressAsync pProgressAsync The progress object of the asynchrony process Waits until the other task is completed including all sub operations and forward all changes from the other progress to this progress This means sub operation number description percent and so on You have to take care on setting up at least the same count on sub operations in this progress object like there are in the other progress object If the other progress object supports cancel and this object gets any cancel
328. ilable read only boolean IHost acceleration3DAvailable Returns true when the host supports 3D hardware acceleration 5 69 1 19 videolnputDevices read only IHostVideoInputDevice IHost videoInputDevices List of currently available host video capture devices 5 69 2 createHostOnlyNetworkinterface IProgress IHost createHostOnlyNetworkInterface out IHostNetworkInterface hostInterface hostinterface Created host interface object Creates a new adapter for Host Only Networking If this method fails the following error codes may be reported e E_INVALIDARG Host network interface name already exists 143 5 Classes interfaces 5 69 3 createUSBDeviceFilter IHostUSBDeviceFilter IHost createUSBDeviceFilter in wstring name name Filter name See IUSBDeviceFilter name for more information Creates a new USB device filter All attributes except the filter name are set to empty any match active is false the filter is not active The created filter can be added to the list of filters using insertUSBDeviceFilter See also USBDeviceFilters 5 69 4 findHostDVDDrive IMedium IHost findHostDVDDrive in wstring name name Name of the host drive to search for Searches for a host DVD drive with the given name If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any host drive 5 69 5 findHostFloppyDrive IMedium IHost
329. ile should be created secure Whether to fail if the file can not be securely created Currently this means that another unprivileged user cannot manipulate the path specified or remove the temporary file after it has been created Also causes the mode specified to be ignored May not be supported on all guest types Creates a temporary file in the guest If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED The operation is not possible as requested on this particular guest OS e E_INVALIDARG Invalid argument This includes an incorrectly formatted template or a non absolute path e VBOX_E_IPRT_ERROR The temporary file could not be created Possible reasons include a non existing path or an insecure path when the secure option was requested 5 64 20 fileExists boolean IGuestSession fileExists in wstring path in boolean followSymlinks path Path to the alleged regular file Guest path style followSymlinks If true symbolic links in the final component will be followed and the exis tance of the symlink target made the question for this method If false a symbolic link in the final component will make the method return false because a symlink isn t a regular file Checks whether a regular file exists in the guest or not If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Error while checking existence of the file specified 132 5 Classes
330. ileQuerySize The parameters to the IGuestSession fileOpen and IGuestSession fileOpenEx meth ods were altered x The openMode string parameter was replaced by the enum FileAccessMode and renamed to accessMode The disposition string parameter was replaced by the enum FileOpenAction and renamed to openAction The unimplemented sharingMode string parameter was replaced by the enum FileSharingMode fileOpenEx only x Added a flags parameter taking a list of FileOpenExFlags values fileOpenEx only x Removed the offset parameter fileOpenEx only IGuestFile seek now returns the new offset Renamed the FileSeekType enum used by IGuestFile seek to FileSeekOrigin and added the missing End value and renaming the Set to Begin Extended the unimplemented IGuestFile setACL method with a UNIX style mode pa rameter as an alternative to the ACL Renamed the IFile openMode attribute to IFile accessMode and change the type from string to FileAccessMode to reflect the changes to the fileOpen methods Renamed the IGuestFile disposition attribute to IFile openAction and change the type from string to FileOpenAction to reflect the changes to the fileOpen methods Added IGuestSession pathStyle attribute Added IGuestSession fsObjExists attribute IConsole GetDeviceActivity returns information about multiple devices IMachine ReadSavedThumbnailToArray has a new parameter bitmapFormat As
331. iles are included in the SDK in the directories sdk bindings c include and sdk bindings c glue As part of the SDK a sample program tstCAPIGlue c is provided in the directory sdk bindings c samples which demonstrates using the C binding to initialize the API get handles for VirtualBox and Session objects make calls to list and start virtual machines monitor events and uninitialize resources when done The sample program is trying to illustrate all relevant concepts so it is a great source of detail information Among many other generally useful code sequences it contains a function which shows how to retrieve error details in C code if they are available from the API call The sample program tstCAPIGlue can be built using the provided Makefile and can be run without arguments It uses the VBoxCAPIGlue library source code is in directory sdk bindings c glue to be used in your API client code to open the C binding layer during runtime which is preferred to other means as it isolates the code which locates the necessary dynamic library using a known working way which works on all platforms If you encounter problems with this glue code in VBoxCAPIGlue c let the VirtualBox developers know rather than inventing incompatible solutions The following sections document the important concepts needed to correctly use the C binding as it is vital for developing API client code which manages memory correctly updates the refer ence counters correctl
332. illed and its status will be put to an appropriate value See ProcessStatus for more information 136 5 Classes interfaces Creates a new process running in the guest The new process will be started asynchronously meaning on return of this function it is not be guaranteed that the guest process is in a started state To wait for successful startup use the IProcess waitFor call Note Starting at VirtualBox 4 2 guest process execution by is default limited to serve up to 255 guest processes at a time If all 255 guest processes are active and running creating a new guest process will result in an error If ProcessCreateFlag WaitForStdOut and or ProcessCreateFlag WaitForStdErr are set the guest process will not enter the terminated state until all data from the specified streams have been read read If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Error creating guest process 5 64 31 processCreateEx IGuestProcess IGuestSession processCreateEx in wstring executable in wstring arguments in wstring environmentChanges in ProcessCreateFlag flags in unsigned long timeoutMS in ProcessPriority priority in long affinity executable Full path to the file to execute in the guest The file has to exists in the guest VM with executable right to the session user in order to succeed If empty null the first entry in the arguments array will be used instead i
333. included and RDPWeb flash content can be embedded to a Web page using dynamic HTML The HTML must include a placeholder which consists of 2 div elements 8 3 RDPWeb change log 8 3 1 Version 1 2 28 e keyboardLayout keyboardLayouts UUID properties e Support for German keyboard layout on the client e Rebranding to Oracle 8 3 2 Version 1 1 26 e webclient jsis a part of the distribution package e lastError property e keyboardSendScancodes and keyboardSendCAD methods 8 3 3 Version 1 0 24 e Initial release 380 9 Drag and Drop Since VirtualBox 4 2 it s possible to transfer files from host to the Linux guests by dragging files directories or text from the host into the guest s screen This is called drag and drop DnD In version 5 0 support for Windows guests has been added as well as the ability to transfer data the other way around that is from the guest to the host Note Currently only the VirtualBox Manager frontend supports drag and drop This chapter will show how to use the required interfaces provided by VirtualBox for adding drag and drop functionality to third party frontends 9 1 Basic concepts In order to use the interfaces provided by VirtualBox some basic concepts needs to be understood first To successfully initiate a drag and drop operation at least two sides needs to be involved a source and a target The source is the side which provides the data e g is the origin of
334. indirect attachment using this method will not implicitly delete them The IMedium deleteStorage operation should be explicitly performed by the caller af ter the medium is successfully detached and the settings are saved with saveSettings if it is the desired action If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Attempt to detach medium from a running virtual machine e VBOX_E_OBJECT_NOT_FOUND No medium attached to given slot bus e VBOX_E_NOT_SUPPORTED Medium format does not support storage deletion only for implicitly created differencing media should not happen 5 80 18 detachHostPCliDevice void IMachine detachHostPCIDevice in long hostAddress hostAddress Address of the host PCI device Detach host PCI device from the virtual machine Also HostPCIDevicePlugEvent on IVirtualBox event source will be delivered As currently we don t support hot device unplug IHostPCIDevi cePlugEvent event is delivered immediately See also IHostPCIDevicePlugEvent If this method fails the following error codes may be reported VBOX_E_INVALID_VM_STATE Virtual machine state is not stopped PCI hotplug not yet implemented VBOX_E_OBJECT_NOT_FOUND This host device is not attached to this machine VBOX_E_PDM_ERROR Virtual machine does not have a PCI controller allowing attachment of physical devices VBOX_E_NOT_SUPPORTED Hardware or host OS doesn t allow PCI
335. ing INetworkAdapter MACAddress Ethernet MAC address of the adapter 12 hexadecimal characters When setting it to null or an empty string VirtualBox will generate a unique MAC address 261 5 Classes interfaces 5 106 1 5 attachmentType read write NetworkAttachmentType INetworkAdapter attachmentType Sets Gets network attachment type of this network adapter 5 106 1 6 bridgedinterface read write wstring INetworkAdapter bridgedInterface Name of the network interface the VM should be bridged to 5 106 1 7 hostOnlylinterface read write wstring INetworkAdapter hostOnlyInterface Name of the host only network interface the VM is attached to 5 106 1 8 internalNetwork read write wstring INetworkAdapter internalNetwork Name of the internal network the VM is attached to 5 106 1 9 NATNetwork read write wstring INetworkAdapter NATNetwork Name of the NAT network the VM is attached to 5 106 1 10 genericDriver read write wstring INetworkAdapter genericDriver Name of the driver to use for the Generic network attachment type 5 106 1 11 cableConnected read write boolean INetworkAdapter cableConnected Flag whether the adapter reports the cable as connected or not It can be used to report offline situations to a VM 5 106 1 12 lineSpeed read write unsigned long INetworkAdapter LineSpeed Line speed reported by custom drivers in units of 1 kbps 5 106 1 13 promiscMod
336. ing lockMedia This method is intended to be used with teleportation so that it is possible to teleport between processes on the same machine 156 5 Classes interfaces 5 76 19 updateState void IInternalMachineControl updateState in MachineState state state Updates the VM state Note This operation will also update the settings file with the correct information about the saved state file and delete this file from disk when appropriate 5 77 linternalSessionControl Note This interface is not supported in the web service 5 77 1 Attributes 5 77 1 1 PID read only unsigned long IInternalSessionControl PID PID of the process that has created this Session object 5 77 1 2 remoteConsole read only IConsole IInternalSessionControl remoteConsole Returns the console object suitable for remote control 5 77 1 3 nominalState read only MachineState IInternalSessionControl nominalState Returns suitable machine state for the VM execution state Useful for choosing a sensible ma chine state after a complex operation which failed or otherwise resulted in an unclear situation 5 77 2 accessGuestProperty void IInternalSessionControl accessGuestProperty in wstring name in wstring value in wstring flags in unsigned long accessMode out wstring retValue out long long retTimestamp out wstring retFlags name value flags 157 5 Classes in
337. ings data 174 5 Classes interfaces 5 80 1 49 settingsModified read only boolean IMachine settingsModified Whether the settings of this machine have been modified but neither yet saved nor discarded Note Reading this property is only valid on instances returned by ISession machine and on new machines created by I VirtualBox createMachineQ or opened by IVirtualBox openMachine but not yet registered or on unregistered machines after calling unregister For all other cases the settings can never be modified Note For newly created unregistered machines the value of this property is al ways true until saveSettings is called no matter if any machine settings have been changed after the creation or not For opened machines the value is set to false and then follows to normal rules 5 80 1 50 sessionState read only SessionState IMachine sessionState Current session state for this machine 5 80 1 51 sessionName read only wstring IMachine sessionName Name of the session If sessionState is Spawning or Locked this attribute contains the same value as passed to the launchVMProcess method in the name parameter If the session was established with lockMachineQ it is the name of the session if set otherwise empty string If sessionState is SessionClosed the value of this attribute is an empty string 5 80 1 52 sessionPID read only unsigned long IMachine sessionPID
338. inked to the original VM KeepAlIMACs Don t generate new MAC addresses of the attached network adapters KeepNATMACs Dor t generate new MAC addresses of the attached network adapters when they are using NAT KeepDiskNames Don t change the disk names 337 6 Enumerations enums 6 21 DataFlags None Mandatory Expert Array FlagMask 6 22 DataType Int32 Int8 String 6 23 DeviceActivity Device activity for IConsole getDeviceActivity Null Idle Reading Writing 6 24 DeviceType Device type Null Null value may also mean no device not allowed for IConsole getDeviceActivityQ Floppy Floppy device DVD CD DVD ROM device HardDisk Hard disk device Network Network device USB USB device SharedFolder Shared folder device Graphics3D Graphics device 3D activity 338 6 Enumerations enums 6 25 DhcpOpt SubnetMask TimeOffset Router TimeServer NameServer DomainNameServer LogServer Cookie LPRServer ImpressServer ResourseLocationServer HostName BootFileSize MeritDumpFile DomainName SwapServer RootPath ExtensionPath IPForwardingEnableDisable NonLocalSourceRoutingEnableDisable PolicyFilter MaximumDatagramReassemblySize DefaultIPTime2Live PathMTUAgingTimeout IPLayerParametersPerlnterface InterfaceMTU AllSubnetsAreLocal BroadcastAddress PerformMaskDiscovery MaskSupplier PerformRouteDiscovery RouterSolicitationAddress 339 6 Enumerations enums StaticRoute T
339. ins a few JavaScript callable methods which are used both from webclient js and the user HTML page 8 2 1 1 JavaScript functions webclient js contains helper functions In the following table Elementld refers to an HTML element name or attribute and Element to the HTML element itself HTML code lt div id FlashRDP gt lt div gt would have Elementld equal to FlashRDP and Element equal to the div element e RDPWebClient embedSWF SWFFileName ElementId Uses SWFObject library to replace the HTML element with the Flash movie e RDPWebClient isRDPWebControlById ElementId Returns true if the given id refers to a RDPWeb Flash element 379 8 RDP Web Control e RDPWebClient isRDPwebControlByElement Element Returns true if the given element is a RDPWeb Flash element e RDPWebClient getFlashById ElementId Returns an element which is referenced by the given id This function will try to resolve any element event if it is not a Flash movie 8 2 1 2 Flash methods callable from JavaScript RDPWebClienUI swf methods can be called directly from JavaScript code on a HTML page e getProperty Name e setProperty Name e connect e disconnect e keyboardSendCADO 8 2 1 3 Flash JavaScript callbacks RDPWebClienUI swf calls JavaScript functions provided by the HTML page 8 2 2 Embedding RDPWeb in an HTML page It is necessary to include webclient js helper script If SWFObject library is used the swfobject js must be also
340. interface extends IEvent and therefore supports all its methods and at tributes as well Notification when a guest user changed its state 140 5 Classes interfaces 5 68 1 Attributes 5 68 1 1 name read only wstring IGuestUserStateChangedEvent name Name of the guest user whose state changed 5 68 1 2 domain read only wstring IGuestUserStateChangedEvent domain Name of the FQDN fully qualified domain name this user is bound to Optional 5 68 1 3 state read only GuestUserState IGuestUserStateChangedEvent state What was changed for this guest user See GuestUserState for more information 5 68 1 4 stateDetails read only wstring IGuestUserStateChangedEvent stateDetails Optional state details depending on the state attribute 5 69 lHost The IHost interface represents the physical machine that this VirtualBox installation runs on An object implementing this interface is returned by the IVirtualBox host attribute This inter face contains read only information about the host s physical hardware such as what processors and disks are available what the host operating system is and so on and also allows for ma nipulating some of the host s hardware such as global USB device filters and host interface networking 5 69 1 Attributes 5 69 1 1 DVDDrives read only IMedium IHost DVDDrives List of DVD drives available on the host 5 69 1 2 floppyDrives read only IMedium IHost floppy
341. interfaces 5 64 21 fileOpen IGuestFile IGuestSession fileOpen in wstring path in FileAccessMode accessMode in FileOpenAction openAction in unsigned long creationMode path Path to file to open Guest path style accessMode The file access mode read write and or append See FileAccessMode for details openAction What action to take depending on whether the file exists or not See FileOpenAction for details creationMode The UNIX style access mode mask to create the file with if openAction requested the file to be created otherwise ignored Whether how all three access groups and as sociated access rights are realized is guest OS dependent The API does the best it can on each OS Opens a file and creates a IGuestFile object that can be used for further operations If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND File to open was not found e VBOX_E_IPRT_ERROR Error while opening the file 5 64 22 fileOpenEx IGuestFile IGuestSession fileOpenEx in wstring path in FileAccessMode accessMode in FileOpenAction openAction in FileSharingMode sharingMode in unsigned long creationMode in FileOpenExFlags flags path Path to file to open Guest path style accessMode The file access mode read write and or append See FileAccessMode for details openAction What action to take depending on whether the file exists or not See FileOpenAction for d
342. internal VMM virtual machine manager failure which may happen as a result of either an unhandled low level virtual hardware exception or one of the recompiler exceptions such as the too many traps condition Note also that any online VM state may transit to the Aborted state This happens if the process that is executing the virtual machine terminates unexpectedly for example crashes Other than that the Aborted state is equivalent to PoweredOff There are also a few additional state diagrams that do not deal with virtual machine execution and therefore are shown separately The states shown on these diagrams are called offline VM states this includes PoweredOff Aborted and Saved too The first diagram shows what happens when a lengthy setup operation is being executed such as IMachine attachDevice gt PoweredOff l l gt Aborted gt lengthy VM configuration call gt SettingUp gt Saved The next two diagrams demonstrate the process of taking a snapshot of a powered off virtual machine restoring the state to that as of a snapshot or deleting a snapshot respectively gt PoweredOff Aborted gt restoreSnapshot gt RestoringSnapshot deleteSnapshot gt DeletingSnapshot gt Saved Saved if restored from an online snapshot PoweredOff otherwise Null Null value never used by the API PoweredOff Th
343. ion for each virtual machine found in the appliance Calling this method is the second step of importing an appliance into VirtualBox see TAppliance for an overview After calling this method one should call getWarnings to find out if problems were encoun tered during the processing which might later lead to errors 5 3 9 read IProgress IAppliance read in wstring file file Name of appliance file to open either with an ovf or ova extension depending on whether the appliance is distributed as a set of files or as a single file respectively Reads an OVF file into the appliance object This method succeeds if the OVF is syntactically valid and by itself without errors The mere fact that this method returns successfully does not mean that VirtualBox supports all features requested by the appliance this can only be examined after a call to interpret 5 3 10 write IProgress IAppliance write in wstring format in ExportOptions options in wstring path format Output format as a string Currently supported formats are ovf 0 9 ovf 1 0 and ovf 2 0 future versions of VirtualBox may support additional formats options Options for the exporting operation path Name of appliance file to open either with an ovf or ova extension depending on whether the appliance is distributed as a set of files or as a single file respectively 56 5 Classes interfaces Writes the contents of
344. irtualized guest interface provider 177 5 Classes interfaces 5 80 1 68 faultToleranceState read write FaultToleranceState IMachine faultToleranceState Fault tolerance state disabled source or target This property can be changed at any time If you change it for a running VM then the fault tolerance address and port must be set beforehand 5 80 1 69 faultTolerancePort read write unsigned long IMachine faultTolerancePort The TCP port the fault tolerance source or target will use for communication 5 80 1 70 faultToleranceAddress read write wstring IMachine faultToleranceAddress The address the fault tolerance source or target 5 80 1 71 faultTolerancePassword read write wstring IMachine faultTolerancePassword The password to check for on the standby VM This is just a very basic measure to prevent simple hacks and operators accidentally choosing the wrong standby VM 5 80 1 72 faultToleranceSynclinterval read write unsigned long IMachine faultToleranceSyncInterval The interval in ms used for syncing the state between source and target 5 80 1 73 RTCUseUTC read write boolean IMachine RTCUseUTC When set to true the RTC device of the virtual machine will run in UTC time otherwise in local time Especially Unix guests prefer the time in UTC 5 80 1 74 lOCacheEnabled read write boolean IMachine IOCacheEnabled When set to true the builtin I O cache of the virtual machine will
345. istered or on unregistered machines after calling unregister If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine is not mutable 5 80 21 enumerateGuestProperties void IMachine enumerateGuestProperties in wstring patterns out wstring names out wstring values out long long timestamps out wstring flags patterns The patterns to match the properties against separated by characters If this is empty or null all properties will match names The names of the properties returned values The values of the properties returned The array entries match the corresponding entries in the name array 190 5 Classes interfaces timestamps The time stamps of the properties returned The array entries match the corre sponding entries in the name array flags The flags of the properties returned The array entries match the corresponding entries in the name array Return a list of the guest properties matching a set of patterns along with their values time stamps and flags 5 80 22 exportTo IVirtualSystemDescription IMachine exportTo in IAppliance appliance in wstring location appliance Appliance to export this machine to location The target location Exports the machine to an OVF appliance See Appliance for the steps required to export VirtualBox machines to OVF 5 80 23 findSnapshot ISnapshot IMachine fi
346. ith write access ReadWrite Open the file with both read and write access AppendOnly Open the file for appending only no read or seek access Note Not yet implemented AppendRead Open the file for appending and read Writes always goes to the end of the file while reads are done at the current or specified file position Note Not yet implemented 6 36 FileCopyFlag File copying flags Note Not flags are implemented yet None No flag set NoReplace Do not replace the destination file if it exists Note This flag is not implemented yet FollowLinks Follow symbolic links Note This flag is not implemented yet Update Only copy when the source file is newer than the destination file or when the destination file is missing Note This flag is not implemented yet 343 6 Enumerations enums 6 37 FileOpenAction What action IGuestSession fileOpen O and IGuestSession fileOpenEx should take whether the file being opened exists or not OpenExisting Opens an existing file fails if no file exists Was oe OpenOrCreate Opens an existing file creates a new one if no file exists Was oc CreateNew Creates a new file is no file exists fails if there is a file there already Was ce CreateOrReplace Creates a new file replace any existing file Was ca Note Currently undefined whether we will inherit mode
347. itialize later on not from the handler itself That said if a client program forgets to call g_pVBoxFuncs gt pfnClientUninitialize be fore it terminates there is a mechanism in place which will eventually release references held by the client On Windows it can take quite a while in the order of 6 7 minutes 44 2 Environment specific notes 2 3 6 9 Compiling and linking A program using the C binding has to open the library during runtime using the help of glue code provided and as shown in the example tstCAPIGlue c Compilation and linking can be achieved with a makefile fragment similar to Where is the SDK directory PATH_SDK life CAPI_INC I PATH_SDK bindings c include ifeq BUILD_PLATFORM win PLATFORM_INC I PATH_SDK bindings mscom include PLATFORM_LIB PATH_SDK bindings mscom lib else PLATFORM_INC PLATFORM_LIB I PATH_SDK bindings xpcom include PATH_SDK bindings xpcom lib endif GLUE_DIR PATH_SDK bindings c glue GLUE_INC I GLUE_DIR Compile Glue Library VBoxCAPIGlue o GLUE_DIR VBoxCAPIGlue c CC CFLAGS CAPI_INC PLATFORM_INC GLUE_INC o 4 c lt Compile interface ID list VirtualBox_i o PLATFORM_LIB VirtualBox_i c CC CFLAGS CAPI_INC PLATFORM_INC GLUE_INC o c lt Compile program code program o program c CC CFLAGS CAPI_INC PLATFORM_INC GLUE_INC o c lt Link program program program o VBoxCA
348. ject machine LockMachine session LockType Write machine is now locked for writing IMachine mutable session getMachine obtain the mutable machine copy mutable setMemorySize 1024 mutable saveSettings write settings to XML session unlockMachine 3 3 Launching virtual machines To launch a virtual machine you call IMachine launchVMProcess In doing so the caller instructs the VirtualBox engine to start a new process with the virtual machine in it since to the host each virtual machine looks like single process even if it has hundreds of its own processes inside This new VM process in turn obtains a write lock on the machine as described above to prevent conflicting changes from other processes this is why opening another session will fail while the VM is running Starting a machine looks something like this IWebsessionManager mgr IVirtualBox vbox mgr logon user pass IMachine machine read only machine ISession session mgr getSessionObject IProgress prog machine launchVMProcess session gui session type Ny possibly environment setting prog waitForCompletion 10000 give the process 10 secs if prog getResultCode 0 check success System out println Cannot launch VM The caller s session object can then be used as a sort of remote control to the VM process that was launched It contains a console object see ISession console with which
349. ject which could generate events can be an event source or aggre gate one To simplify using one way protocols such as webservices running on top of HTTP S an event source can work with listeners in either active or passive mode In active mode it is up to the IEventSource implementation to call IEventListener handleEvent in passive mode the event source keeps track of pending events for each listener and returns available events on demand See IEvent for an introduction to VirtualBox event handling 5 25 1 createAggregator IEventSource IEventSource createAggregator in IEventSource subordinates subordinates Subordinate event source this one aggregates Creates an aggregator event source collecting events from multiple sources This way a single listener can listen for events coming from multiple sources using a single blocking getEventQ on the returned aggregator 5 25 2 createListener IEventListener IEventSource createListener Creates a new listener object useful for passive mode 87 5 Classes interfaces 5 25 3 eventProcessed void IEventSource eventProcessed in IEventListener listener in IEvent event listener Which listener processed event event Which event Must be called for waitable events after a particular listener finished its event processing When all listeners of a particular event have called this method the system will then call IEvent setProcessed 5 25 4 fireEvent
350. k is cXor width x 4 x height Note If shape is O only the pointer visibility is changed 5 97 INATEngine Interface for managing a NAT engine which is used with a virtual machine This allows for changing NAT behavior such as port forwarding rules This interface is used in the INetworkAdapter NATEngine attribute 5 97 1 Attributes 5 97 1 1 network read write wstring INATEngine network The network attribute of the NAT engine the same value is used with built in DHCP server to fill corresponding fields of DHCP leases 252 5 Classes interfaces 5 97 1 2 hostlP read write wstring INATEngine hostIP IP of host interface to bind all opened sockets to Note Changing this does not change binding of port forwarding 5 97 1 3 TFTPPrefix read write wstring INATEngine TFTPPrefix TFTP prefix attribute which is used with the built in DHCP server to fill the corresponding fields of DHCP leases 5 97 1 4 TFTPBootFile read write wstring INATEngine TFTPBootFile TFTP boot file attribute which is used with the built in DHCP server to fill the corresponding fields of DHCP leases 5 97 1 5 TFTPNextServer read write wstring INATEngine TFTPNextServer TFTP server attribute which is used with the built in DHCP server to fill the corresponding fields of DHCP leases Note The preferred form is IPv4 addresses 5 97 1 6 aliasMode read write unsigned long IN
351. l medium attached directly or indirectly preserved when taking snapshots Immutable Immutable medium attached indirectly changes are wiped out the next time the virtual machine is started Writethrough Write through medium attached directly ignored when taking snapshots Shareable Allow using this medium concurrently by several machines Note Present since VirtualBox 3 2 0 and accepted since 3 2 8 Readonly A readonly medium which can of course be used by several machines Note Present and accepted since VirtualBox 4 0 MultiAttach A medium which is indirectly attached so that one base medium can be used for several VMs which have their own differencing medium to store their modifications In some sense a variant of Immutable with unset AutoReset flag in each differencing medium Note Present and accepted since VirtualBox 4 0 6 67 MediumVariant Virtual medium image variant More than one flag may be set See also IMedium Standard No particular variant requested results in using the backend default VmdkSplit2G VMDK image split in chunks of less than 2GByte VmdkRawDisk VMDK image representing a raw disk VmdkStreamOptimized VMDK streamOptimized image Special import export format which is read only append only VmdkESX VMDK format variant used on ESX products VdiZeroExpand Fill new blocks with zeroes while expanding image file Fixed Fixed image Only allowed for base images
352. l va GH Sete ak ee es 99 Trane Ue cs gs Ow OS Ge Ba RE BADR BEER OS ORES 99 Booed a kk dee os BRR Rw wR ee mda wa ee A 99 5 36 7 5 38 3 39 5 40 5 41 5 42 5 43 5 44 5 45 5 46 5 47 5 48 5 49 5 50 Deal 5 92 5 93 5 54 Contents 5302 Serisible Resign ne se a A ae aw y 100 5 353 nonheDEvyent cs soccer eG ESSERE See eA ee eae 101 5 304 IONES 2 ones eh we Re a a eee en me 4 101 S 55 5 montypdate c42 442854444 44444 48204444484 101 S355 Moni pdatelnage lt ces ek se Ge we a ee ee eS 102 5 35 7 processVHWACommand 000 eee eee ee 102 35 10 80 BEtVISIDIGRBSION a ow we AA Ee E e G 102 5 00 9 wvideoModeSupported o e eesse BOS orar ee EE oneri 103 IFramebufferOverlay IFramebuffer o 0 eee eee eee ee 103 5S6 a ose ke e a ee Pa a 103 B o0 2 WOVE coco omar a Rae ko ee eee aE 104 PERSONS o Stee hw a RO ee ect ee eo a el do 104 ILL AIDES oscar dais aaa aaa 104 MESE ra a n id a A ele ee ec a eee amp 106 Bao AIDU ona ti Ban ad BOD hoe areas 106 DogA ll e doe eo aes sg ew wo BP Be 108 at beh 4S Se as DES Pewee EEE EO REDS 108 SpA petAdditionsStatis o oo oes be k a ee ee Oe 108 5 38 9 PelPacilitySranis ii eb oo SO ee i a D 109 5 38 6 internalGetStatistics oo eoa ee ee 109 5 397 setCredentials oo sod utre eee ea SE EEE EEE OS 110 5 38 8 updateGuestAddifions o e e atas 110 IGuestDirectory Directory gt xs sassa io wwe ee eee e
353. lI0Event processed Processed input or output in bytes 5 45 IGuestFileOffsetChangedEvent IGuestFilelOEvent Note This interface extends IGuestFilelOEvent and therefore supports all its methods and attributes as well Notification when a guest file changed its current offset 112 5 Classes interfaces 5 45 1 Attributes 5 45 1 1 midIDoesNotLikeEmptyInterfaces read only boolean IGuestFileOffsetChangedEvent midlDoesNotLikeEmptyInterfaces 5 46 IGuestFileReadEvent IGuestFilelOEvent Note This interface extends IGuestFilelOEvent and therefore supports all its methods and attributes as well Notification when data has been read from a guest file 5 46 1 Attributes 5 46 1 1 data read only octet IGuestFileReadEvent data Actual data read 5 47 IGuestFileRegisteredEvent IGuestFileEvent Note This interface extends IGuestFileEvent and therefore supports all its methods and attributes as well Notification when a guest file was registered or unregistered 5 47 1 Attributes 5 47 1 1 registered read only boolean IGuestFileRegisteredEvent registered If true the guest file was registered otherwise it was unregistered 5 48 IGuestFileStateChangedEvent IGuestFileEvent Note This interface extends IGuestFileEvent and therefore supports all its methods and attributes as well Notification when a guest file changed its state 5 48 1 Attributes
354. lid property 5 80 71 setExtraData void IMachine setExtraData in wstring key in wstring value key Name of the data key to set value Value to assign to the key Sets associated machine specific extra data If you pass null or an empty string as a key value the given key will be deleted 207 5 Classes interfaces Note Before performing the actual data change this method will ask all registered listeners using the IExtraDataCanChangeEvent notification for a permission If one of the listeners refuses the new value the change will not be performed Note On success the IExtraDataChangedEvent notification is called to inform all reg istered listeners about a successful data change Note This method can be called outside the machine session and therefore it s a caller s responsibility to handle possible race conditions when several clients change the same key at the same time If this method fails the following error codes may be reported e VBOX_E_FILE_ERROR Settings file not accessible e VBOX_E_XML_ERROR Could not parse the settings file 5 80 72 setGuestProperty void IMachine setGuestProperty in wstring property in wstring value in wstring flags property The name of the property to set change or delete value The new value of the property to set change or delete If the property does not yet exist and value is non empty it will be created If t
355. lockType session Session object for which the machine will be locked lockType If set to Write then attempt to acquire an exclusive write lock or fail If set to Shared then either acquire an exclusive write lock or establish a link to an existing session Locks the machine for the given session to enable the caller to make changes to the machine or start the VM or control VM execution There are two ways to lock a machine for such uses e If you want to make changes to the machine settings you must obtain an exclusive write lock on the machine by setting lockType to Write This will only succeed if no other process has locked the machine to prevent conflicting changes Only after an exclusive write lock has been obtained using this method one 198 5 Classes interfaces can change all VM settings or execute the VM in the process space of the session object Note that the latter is only of interest if you actually want to write a new front end for virtual machines but this API gets called internally by the existing front ends such as VBoxHeadless and the VirtualBox GUI to acquire a write lock on the machine that they are running On success write locking the machine for a session creates a second copy of the IMachine object It is this second object upon which changes can be made in VirtualBox terminology the second copy is mutable It is only this second mutable machine object upon which you can call methods that change
356. low you to use the VirtualBox web service in an intuitive object oriented way These libraries shield you from the client side complications of managed object references and other implementation details that come with the VirtualBox web service If you are interested in these complications have a look at chapter 2 2 Using the raw web service with any language page 30 We recommend that you start your experiments with the VirtualBox web service by using our object oriented client libraries for JAX WS a web service toolkit for Java which enables you to write code to interact with VirtualBox in the simplest manner possible As interfaces attributes and methods are COM concepts please read the documentation in chapter 5 Classes interfaces page 52 and chapter 6 Enumerations enums page 333 with the following notes in mind The OOWS bindings attempt to map the Main API as closely as possible to the Java Python and PHP languages In other words objects are objects interfaces become classes and you can call methods on objects as you would on local objects The main difference remains with attributes to read an attribute call a getXXX method with XXX being the attribute name with a capitalized first letter So when the Main API Ref erence says that IMachine has a name attribute see IMachine name call getName on an IMachine object to obtain a machine s name Unless the attribute is marked as read
357. lso fail while the machine is running The caller s session object remains separate from the session opened by the new VM process It receives its own Console object which can be used to control machine execution but it cannot be used to change all VM settings which would be available after a lockMachine call The caller must eventually release the session s shared lock by calling ISession unlockMachineO on the local session object once this call has returned However the session s state see ISession state will not return to Unlocked until the remote session has also unlocked the machine i e the machine has stopped running Launching a VM process can take some time a new VM is started in a new process for which memory and other resources need to be set up Because of this an IProgress object is returned to 197 5 Classes interfaces allow the caller to wait for this asynchronous operation to be completed Until then the caller s session object remains in the Unlocked state and its ISession machine and ISession console attributes cannot be accessed It is recommended to use IProgress waitForCompletion or simi lar calls to wait for completion Completion is signalled when the VM is powered on If launching the VM fails error messages can be queried via the progress object if available The progress object will have at least 2 sub operations The first operation covers the period up to the new VM process
358. ly because there are no free IP ports to bind to If this property is equal to 1 then the VRDE server has not yet been started 5 147 1 3 numberOfClients read only unsigned long IVRDEServerInfo numberOfClients How many times a client connected 5 147 1 4 beginTime read only long long IVRDEServerInfo beginTime When the last connection was established in milliseconds since 1970 01 01 UTC 5 147 1 5 endTime read only long long IVRDEServerInfo endTime When the last connection was terminated or the current time if connection is still active in milliseconds since 1970 01 01 UTC 5 147 1 6 bytesSent read only long long IVRDEServerInfo bytesSent How many bytes were sent in last or current if still active connection 310 5 Classes interfaces 5 147 1 7 bytesSentTotal read only long long IVRDEServerInfo bytesSentTotal How many bytes were sent in all connections 5 147 1 8 bytesReceived read only long long IVRDEServerInfo bytesReceived How many bytes were received in last or current if still active connection 5 147 1 9 bytesReceivedTotal read only long long IVRDEServerInfo bytesReceivedTotal How many bytes were received in all connections 5 147 1 10 user read only wstring IVRDEServerInfo user Login user name supplied by the client 5 147 1 11 domain read only wstring IVRDEServerInfo domain Login domain name supplied by the client 5 147 1 12 clientName read only wstri
359. mGuest e e eens 126 5045 directoryCopyloGuest o ee eS Be we 126 5 04 6 divectoryCredte 1 3 42 24 2204 o 44444445548 127 S647 directoryGreateTenmip o s koeie toa so Rh ae we ge A 127 5 64 8 directoryExists coi ec bas 128 S LO directo np nk ase ee a AE EE Se eS 128 5 64 10 directoryRemove oc cc orere epe bea be dw ee eee ee eS 129 64 11 directoryRemoveRectrsive 2 a ew E 129 5 64 12 environmentDoesBaseVariableExist 0 000 ee eae 129 5 64 13 environmentGetBaseVariable o 130 5 64 14 environmentScheduleBet 00 lt lt lt 130 5 64 15 environmentScheduleUnset o 130 B64 1G DISCOS oe A A 130 5 64 17 GileCopyFromGuEst occiso ra ao 131 35 64 18 Be Copy TOQUES eae ee a a e 131 9 64 19 fileCreateTemp oic tio 5 06 eee a te ee eS 132 6 64 20 TCU cs so kt ee ee a A me Se ee a a S 132 SOAL TOURER aaa SS Se ee ee ee oe 133 10422 TUCO PONE Ac fe oo sas Boks Bw we bea ee a es a WOR we a AG 133 50423 TIGQUAIYSIE coser AA Oe RES 134 5 64 24 fsObjExist ocio Daa ee ee eee ee 134 50425 BODMOVE oe eo hk ew we PG be teh A 134 5 04 26 tsObiQuervioto 244464485 See 4S See ee eae a eee ee 135 504 27 ISODIBEMOVE 6 a sw bee be ee A ee AS 135 5 64 28 fsObjRenamie 20 ooo EGER ERE ee Eee 135 6 64 29 ODISetACL kk hak Rbk a ad ee AAA ee es 136 5 64 30 processCreate o dodo eee ea aa Re ee a a 136 56431 ProcessCreatehe nw ook ke ew a Aw E
360. machineld machineld UUID of the machine to query Returns an array of UUIDs of all snapshots of the given machine where this medium is attached to If the medium is attached to the machine in the current state then the first element in the array will always be the ID of the queried machine i e the value equal to the machineId argument followed by snapshot IDs if any If the medium is not attached to the machine in the current state then the array will contain only snapshot IDs The returned array may be null if this medium is not attached to the given machine at all neither in the current state nor in one of the snapshots 5 87 15 lockRead IToken IMedium lockRead Locks this medium for reading A read lock is shared many clients can simultaneously lock the same medium for reading unless it is already locked for writing see lockWrite in which case an error is returned When the medium is locked for reading it cannot be modified from within VirtualBox This means that any method that changes the properties of this medium or contents of the storage unit will return an error unless explicitly stated otherwise That includes an attempt to start a virtual machine that wants to write to the the medium When the virtual machine is started up it locks for reading all media it uses in read only mode If some medium cannot be locked for reading the startup procedure will fail A medium is typically locked for reading while i
361. may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 5 77 14 onParallelPortChange void IInternalSessionControl onParallelPortChange in IParallelPort parallelPort parallelPort Triggered when settings of a parallel port of the associated virtual machine have changed If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 160 5 Classes interfaces 5 77 15 onSerialPortChange void IInternalSessionControl onSerialPortChange in ISerialPort serialPort serialPort Triggered when settings of a serial port of the associated virtual machine have changed If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 5 77 16 onSharedFolderChange void IInternalSessionControl onSharedFolderChange in boolean global global Triggered when a permanent global or machine shared folder has been created or removed Note We don t pass shared folder parameters in this notification because the order in which parallel notifications are delivered is not defined therefore it could happen that these parameters were outdated by the time of processing this notification
362. me 5 109 1 2 isPhysicalDevice read only boolean IPCIDeviceAttachment isPhysicalDevice If this is physical or virtual device 265 5 Classes interfaces 5 109 1 3 hostAddress read only long IPCIDeviceAttachment hostAddress Address of device on the host applicable only to host devices 5 109 1 4 guestAddress read only long IPCIDeviceAttachment guestAddress Address of device in the guest 5 110 IParallelPort The IParallelPort interface represents the virtual parallel port device The virtual parallel port device acts like an ordinary parallel port inside the virtual machine This device communicates to the real parallel port hardware using the name of the parallel device on the host computer specified in the path attribute Each virtual parallel port device is assigned a base I O address and an IRQ number that will be reported to the guest operating system and used to operate the given parallel port from within the virtual machine See also IMachine getParallelPortQ 5 110 1 Attributes 5 110 1 1 slot read only unsigned long IParallelPort slot Slot number this parallel port is plugged into Corresponds to the value you pass to IMachine getParallelPort to obtain this instance 5 110 1 2 enabled read write boolean IParallelPort enabled Flag whether the parallel port is enabled If disabled the parallel port will not be reported to the guest OS 5 110 1 3 lOBase read write unsign
363. me and createMachine for more details about the machine name groupName defines which additional subdirectory levels should be included It must be either a valid group name or null or empty string which designates that the machine will not be related to a machine group If baseFolder is a null or empty string which is recommended the default machine set tings folder see ISystemProperties defaultMachineFolder will be used as a base folder for the created machine resulting in a file name like home user VirtualBox VMs name name vbox Otherwise the given base folder will be used This method does not access the host disks In particular it does not check for whether a machine with this name already exists 5 151 4 createAppliance IAppliance IVirtualBox createAppliance Creates a new appliance object which represents an appliance in the Open Virtual Machine Format OVF This can then be used to import an OVF appliance into VirtualBox or to export machines as an OVF appliance see the documentation for Appliance for details 5 151 5 createDHCPServer IDHCPServer IVirtualBox createDHCPServer in wstring name name server name Creates a DHCP server settings to be used for the given internal network name If this method fails the following error codes may be reported e E_INVALIDARG Host network interface name already exists 317 5 Classes interfaces 5 151 6 createMachine IMachine IVirtualBox createMa
364. med in a deferred fashion This means that the given hard disk remains associated with the given machine after a successful IMachine detachDevice call until IMachine saveSettings is called to save all changes to machine settings to disk This deferring is necessary to guarantee that the hard disk configuration may be restored at any time by a call to IMachine discardSettings before the settings are saved committed Note that if IMachine discardSettings is called after indirectly attaching some hard disks to the machine but before a call to IMachine saveSettings is made it will implicitly delete all differencing hard disks implicitly created by IMachine attachDevice for these indirect at tachments Such implicitly created hard disks will also be immediately deleted when detached explicitly using the IMachine detachDevice call if it is made before IMachine saveSettings This implicit deletion is safe because newly created differencing hard disks do not contain any user data However keep in mind that detaching differencing hard disks that were implicitly created by IMachine attachDevice before the last IMachine saveSettings call will not implicitly delete them as they may already contain some data for example as a result of virtual machine exe cution If these hard disks are no more necessary the caller can always delete them explicitly using IMedium deleteStorage after they are actually de associated from this machi
365. medium format TcpNetworking The format backend uses the TCP networking interface for network access VFS The format backend supports virtual filesystem functionality CapabilityMask 6 65 MediumState Virtual medium state See also Medium NotCreated Associated medium storage does not exist either was not created yet or was deleted Created Associated storage exists and accessible this gets set if the accessibility check per formed by IMedium refreshState was successful LockedRead Medium is locked for reading see IMedium lockRead no data modification is possible LockedWrite Medium is locked for writing see IMedium lockWriteQ no concurrent data reading or modification is possible Inaccessible Medium accessibility check see IMedium refreshState has not yet been performed or else associated medium storage is not accessible In the first case IMedium lastAccessError is empty in the second case it describes the error that occurred Creating Associated medium storage is being created Deleting Associated medium storage is being deleted 355 6 Enumerations enums 6 66 MediumType Virtual medium type For each IMedium this defines how the medium is attached to a virtual machine see IMediumAttachment and what happens when a snapshot see ISnapshot is taken of a virtual machine which has the medium attached At the moment DVD and floppy media are always of type writethrough Normal Norma
366. ment and object array contains many the single metric name array element is applied to each object array element to form metric object pairs 5 113 IPerformanceMetric The IPerformanceMetric interface represents parameters of the given performance metric 5 113 1 Attributes 5 113 1 1 metricName read only wstring IPerformanceMetric metricName Name of the metric 5 113 1 2 object read only unknown IPerformanceMetric object Object this metric belongs to 5 113 1 3 description read only wstring IPerformanceMetric description Textual description of the metric 5 113 1 4 period read only unsigned long IPerformanceMetric period Time interval between samples measured in seconds 5 113 1 5 count read only unsigned long IPerformanceMetric count Number of recent samples retained by the performance collector for this metric When the collected sample count exceeds this number older samples are discarded 5 113 1 6 unit read only wstring IPerformanceMetric unit Unit of measurement 5 113 1 7 minimumValue read only long IPerformanceMetric minimumValue Minimum possible value of this metric 271 5 Classes interfaces 5 113 1 8 maximumValue read only long IPerformanceMetric maximumValue Maximum possible value of this metric 5 114 IProcess Abstract parent interface for processes handled by VirtualBox 5 114 1 Attributes 5 114 1 1 arguments read only wstrin
367. mes of the properties to get are specified using the names argument which is a list of comma separated property names or an empty string if all properties are to be returned Note Currently the value of this argument is ignored and the method always returns all existing properties The method returns two arrays the array of property names corresponding to the names argu ment and the current values of these properties Both arrays have the same number of elements with each element at the given index in the first array corresponds to an element at the same index in the second array 263 5 Classes interfaces 5 106 3 getProperty wstring INetworkAdapter getProperty in wstring key key Name of the property to get Returns the value of the network attachment property with the given name If the requested data key does not exist this function will succeed and return an empty string in the value argument If this method fails the following error codes may be reported e E_INVALIDARG name is null or empty 5 106 4 setProperty void INetworkAdapter setProperty in wstring key in wstring value key Name of the property to set value Property value to set Sets the value of the network attachment property with the given name Setting the property value to null or an empty string is equivalent to deleting the existing value If this method fails the following error codes may be reported e E_INVALI
368. mplifies restoring a machine to the state of a snapshot only the differencing images need to be deleted The current machine state is not changed by taking a snapshot except that IMachine currentSnapshot is set to the newly created snapshot which is also added to the machine s snapshots tree e IMachine restoreSnapshot resets a machine to the state of a previous snapshot by delet ing the differencing image of each of the machine s media and setting the machine s settings and state to the state that was saved in the snapshot if any This destroys the machine s current state After calling this IMachine currentSnapshot points to the snapshot that was restored e IMachine deleteSnapshot deletes a snapshot without affecting the current machine state This does not change the current machine state but instead frees the resources allocated when the snapshot was taken the settings and machine state file are deleted if any and the snapshot s differencing image for each of the machine s media gets merged with its parent image Neither the current machine state nor other snapshots are affected by this operation except that parent media will be modified to contain the disk data associated with the snapshot being deleted When deleting the current snapshot the IMachine currentSnapshot attribute is set to the current snapshot s parent or null if it has no parent Otherwise the attribute is unchanged Each snapshot contains a co
369. mptyInterfaces read only boolean ISnapshotRestoredEvent midlDoesNotLikeEmptyInterfaces 5 130 ISnapshotTakenEvent ISnapshotEvent Note This interface extends ISnapshotEvent and therefore supports all its methods and attributes as well A new snapshot of the machine has been taken See also ISnapshot 5 130 1 Attributes 5 130 1 1 midlDoesNotLikeEmptyInterfaces read only boolean ISnapshotTakenEvent midlDoesNotLikeEmptyInterfaces 5 131 IStateChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when the execution state of the machine has changed The new state is given 289 5 Classes interfaces 5 131 1 Attributes 5 131 1 1 state read only MachineState IStateChangedEvent state New machine state 5 132 IStorageController Represents a storage controller that is attached to a virtual machine IMachine Just as drives hard disks DVDs FDs are attached to storage controllers in a real computer virtual drives represented by IMediumAttachment are attached to virtual storage controllers represented by this interface As opposed to physical hardware VirtualBox has a very generic concept of a storage controller and for purposes of the Main API all virtual storage is attached to virtual machines via instances of this interface There are five types of such virtual storage controllers IDE SCSI SATA SA
370. n integer that items of the Harddisk type can use to specify which hard disk controller a virtual disk should be connected to Note that in OVF an IDE controller has two chan nels corresponding to master and slave in traditional terminology whereas the IDE storage controller that VirtualBox supports in its virtual machines supports four channels primary master primary slave secondary master secondary slave and thus maps to two IDE controllers in the OVF sense HardDiskControllerSATA an SATA hard disk controller There can be at most one such item This has no value in OVFValues or aVBoxValues The matching item in the aRefs array will be used as with IDE controllers see above HardDiskControllerSCSI a SCSI hard disk controller There can be at most one such item The items in OVFValues and aVBoxValues will either be LsiLogic Bus Logic or LsiLogicSas Note that in OVF the LsiLogicSas controller is treated as a SCSI controller whereas VirtualBox considers it a class of storage controllers of its own see StorageControllerType The matching item in the aRefs array will be used as with IDE controllers see above HardDiskImage a virtual hard disk most probably as a reference to an image file There can be an arbitrary number of these items one for each virtual disk image that accompanies the OVF The array item in O0VFValues will contain the file specification from
371. n is that this way it is always possible to undo all the changes you ve scheduled 5 64 1 Attributes 5 64 1 1 user read only wstring IGuestSession user Returns the user name used by this session to impersonate users in the guest 5 64 1 2 domain read only wstring IGuestSession domain Returns the domain name used by this session to impersonate users in the guest 5 64 1 3 name read only wstring IGuestSession name Returns the session s friendly name 5 64 1 4 id read only unsigned long IGuestSession id Returns the internal session ID 5 64 1 5 timeout read write unsigned long IGuestSession timeout Returns the session timeout in ms 5 64 1 6 protocolVersion read only unsigned long IGuestSession protocolVersion Returns the protocol version which is used by this session to communicate with the guest 5 64 1 7 status read only GuestSessionStatus IGuestSession status Returns the current session status 124 5 Classes interfaces 5 64 1 8 environmentChanges read write wstring IGuestSession environmentChanges The set of scheduled environment changes to the base environment of the session They are in putenv format i e VAR VALUE for setting and VAR for unsetting One entry per variable change The changes are applied when creating new guest processes This is writable so to undo all the scheduled changes assign it an empty array 5 64 1 9 envir
372. n long long offset in octet data in unsigned long timeoutMS offset Offset in bytes to start writing data Array of bytes to write The size of the array also specifies how much to write timeoutMS Timeout in ms to wait for the operation to complete Pass 0 for an infinite timeout Writes bytes at a certain offset to this file If this method fails the following error codes may be reported e E_NOTIMPL The method is not implemented yet 5 35 IFramebuffer 5 35 1 Attributes 5 35 1 1 width read only unsigned long IFramebuffer width Frame buffer width in pixels 5 35 1 2 height read only unsigned long IFramebuffer height Frame buffer height in pixels 5 35 1 3 bitsPerPixel read only unsigned long IFramebuffer bitsPerPixel Color depth in bits per pixel 5 35 1 4 bytesPerLine read only unsigned long IFramebuffer bytesPerLine Scan line size in bytes 5 35 1 5 pixelFormat read only BitmapFormat IFramebuffer pixelFormat Frame buffer pixel format It s one of the values defined by BitmapFormat Note This attribute must never and will never return Opaque the format of the frame buffer must be always known 99 5 Classes interfaces 5 35 1 6 heightReduction read only unsigned long IFramebuffer heightReduction Hint from the frame buffer about how much of the standard screen height it wants to use for itself This information is exposed to the guest thr
373. n virtual machine at startup 283 5 Classes interfaces e Transient IConsole sharedFolders VM specific shared folders created in the session context for example when the virtual machine is running and automatically discarded when the session is closed the VM is powered off Logical names of shared folders must be unique within the given scope global permanent or transient However they do not need to be unique across scopes In this case the definition of the shared folder in a more specific scope takes precedence over definitions in all other scopes The order of precedence is more specific to more general 1 Transient definitions 2 Permanent definitions 3 Global definitions For example if MyMachine has a shared folder named C_DRIVE that points to C then creating a transient shared folder named C_DRIVE that points to C WINDOWS will change the definition of C_DRIVE in the guest OS so that VBOXSVR C_DRIVE will give access to C WINDOWS instead of C on the host PC Removing the transient shared folder C_DRIVE will restore the previous permanent definition of C_DRIVE that points to C if it still exists Note that permanent and transient shared folders of different machines are in different name spaces so they don t overlap and don t need to have unique logical names Note Global shared folders are not implemented in the current version of the product 5 122 1 Attributes 5
374. n wstring newPath in FsObjRenameFlag flags oldPath The current path to the object Guest path style newPath The new path to the object Guest path style flags Zero or more FsObjRenameFlag values Renames a file system object file directory symlink etc in the guest If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND The file system object was not found e VBOX_E_IPRT_ERROR For most other errors We know this is unhelpful will fix shortly 135 5 Classes interfaces 5 64 29 fsObjSetACL void IGuestSession fsObjSetACL in wstring path in boolean followSymlinks in wstring acl in unsigned long mode path Full path of the file system object which ACL to set followSymlinks If true symbolic links in the final component will be followed otherwise if false the method will work directly on a symbolic link in the final component acl The ACL specification string To be defined mode UNIX style mode mask to use if acl is empty As mention in directoryCreate this is realized on a best effort basis and the exact behavior depends on the Guest OS Sets the access control list ACL of a file system object file directory etc in the guest If this method fails the following error codes may be reported e E_NOTIMPL The method is not implemented yet 5 64 30 processCreate IGuestProcess IGuestSession processCreate in wstring executable in wstri
375. n empty string indicates a failure and should normally describe a reason of the failure for example a file read error 5 87 1 21 machinelds read only uuid IMedium machinelds Array of UUIDs of all machines this medium is attached to A null array is returned if this medium is not attached to any machine or to any machine s snapshot Note The returned array will include a machine even if this medium is not attached to that machine in the current state but attached to it in one of the machine s snapshots See getSnapshotlds for details 229 5 Classes interfaces 5 87 2 changeEncryption IProgress IMedium changeEncryption in wstring currentPassword in wstring cipher in wstring newPassword in wstring newPasswordId currentPassword The current password the medium is protected with Use an empty string to indicate that the medium isn t encrypted cipher The cipher to use for encryption An empty string indicates no encryption for the result newPassword The new password the medium should be protected with An empty password and password ID will result in the medium being encrypted with the current password newPasswordld The ID of the new password when unlocking the medium Starts encryption of this medium This means that the stored data in the medium is encrypted This medium will be placed to LockedWrite state Please note that the results can be either returned straight away or lat
376. n library is required to implement exactly one entry point include VBoxAuth h kx Authentication library entry point Parameters szCaller The name of the component which calls the library UTF8 pUuid Pointer to the UUID of the accessed virtual machine Can be NULL guestJudgement Result of the guest authentication szUser User name passed in by the client UTF8 szPassword Password passed in by the client UTF8 szDomain Domain passed in by the client UTF8 fLogon Boolean flag Indicates whether the entry point is called for a client logon or the client disconnect clientId Server side unique identifier of the client Return code AuthResultAccessDenied Client access has been denied AuthResultAccessGranted Client has the right to use the virtual machine AuthResultDelegateToGuest Guest operating system must authenticate the client and the library must be called again with the result of the guest authentication Note When fLogon is 0 only pszCaller pUuid and clientId are valid and the return code is ignored we E A E GE Re E E OI E SES RO A E EE E gt E E E AuthResult AUTHCALL AuthEntry const char szCaller PAUTHUUID pUuid AuthGuestJudgement guestJudgement const char x szUser const char szPassword const char szDomain int fLogon 383 10 VirtualBox external authentication modules unsigned clientId Process request against your authentication source of choice if auth
377. n milliseconds 0 default 58 5 Classes interfaces 5 5 1 4 logolmagePath read write wstring IBIOSSettings logoImagePath Local file system path for external BIOS splash image Empty string means the default image is shown on boot 5 5 1 5 bootMenuMode read write BIOSBootMenuMode IBIOSSettings bootMenuMode Mode of the BIOS boot device menu 5 5 1 6 ACPlEnabled read write boolean IBIOSSettings ACPIEnabled ACPI support flag 5 5 1 7 lOAPICEnabled read write boolean IBIOSSettings IOAPICEnabled IO APIC support flag If set VirtualBox will provide an IO APIC and support IRQs above 15 5 5 1 8 timeOffset read write long long IBIOSSettings timeOffset Offset in milliseconds from the host system time This allows for guests running with a dif ferent system date time than the host It is equivalent to setting the system date time in the BIOS except it is not an absolute value but a relative one Guest Additions time synchronization honors this offset 5 5 1 9 PXEDebugEnabled read write boolean IBIOSSettings PXEDebugEnabled PXE debug logging flag If set VirtualBox will write extensive PXE trace information to the release log 5 5 1 10 nonVolatileStorageFile read only wstring IBIOSSettings nonVolatileStorageFile The location of the file storing the non volatile memory content when the VM is powered off The file does not always exist This feature will be realized after VirtualBox v4 3 0 5
378. nPasswords void IConsole addDiskEncryptionPasswords in wstring ids in wstring passwords in boolean clearOnSuspend ids List of identifiers for the passwords Must match the identifier used when the encrypted medium was created passwords List of passwords clearOnSuspend Flag whether to clear the given passwords on VM suspend due to a suspend ing host for example The passwords must be supplied again before the VM can resume Adds a password used for hard disk encryption decryption If this method fails the following error codes may be reported e VBOX_E_PASSWORD_INCORRECT The password provided wasn t correct for at least one disk using the provided ID 5 13 4 attachUSBDevice void IConsole attachUSBDevice in uuid id in wstring captureFilename id UUID of the host USB device to attach captureFilename Filename to capture the USB traffic to Attaches a host USB device with the given UUID to the USB controller of the virtual machine The device needs to be in one of the following states Busy Available or Held otherwise an error is immediately returned When the device state is Busy an error may also be returned if the host computer refuses to release it for some reason See also IUSBDeviceFilters deviceFilters USBDeviceState If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine state neither Running nor Paused e VBOX_E_PDM_ERROR
379. nalSessionControl onCPUExecutionCapChange in unsigned long executionCap executionCap The new CPU execution cap value 1 100 Notification when the CPU execution cap changes 159 5 Classes interfaces 5 77 10 onClipboardModeChange void IInternalSessionControl onClipboardModeChange in ClipboardMode clipboardMode clipboardMode The new shared clipboard mode Notification when the shared clipboard mode changes 5 77 11 onDnDModeChange void IInternalSessionControl onDnDModeChange in DnDMode dndMode dndMode The new mode for drag n drop Notification when the drag n drop mode changes 5 77 12 onMediumChange void IInternalSessionControl onMediumChange in IMediumAttachment mediumAttachment in boolean force mediumAttachment The medium attachment which changed force If the medium change was forced Triggered when attached media of the associated virtual machine have changed If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 5 77 13 onNetworkAdapterChange void IInternalSessionControl onNetworkAdapterChange in INetworkAdapter networkAdapter in boolean changeAdapter networkAdapter changeAdapter Triggered when settings of a network adapter of the associated virtual machine have changed If this method fails the following error codes
380. name The object s name 5 37 1 13 nodeld read only long long IFsObjInfo nodeId The unique identifier within the filesystem of this filesystem object st_ino 105 5 Classes interfaces 5 37 1 14 nodeldDevice read only unsigned long IFsObjInfo nodeIdDevice The device number of the device which this filesystem object resides on st_dev 5 37 1 15 objectSize read only long long IFsObjInfo objectSize The logical size st_size For normal files this is the size of the file For symbolic links this is the length of the path name contained in the symbolic link For other objects this fields needs to be specified 5 37 1 16 type read only FsObjType IFsObjInfo type The object type See FsObjType for more 5 37 1 17 UID read only unsigned long IFsObjInfo UID The user owning the filesystem object st_uid 5 37 1 18 userFlags read only unsigned long IFsObjInfo userFlags User flags st_flags 5 37 1 19 userName read only wstring IFsObjInfo userName The user name 5 38 IGuest The IGuest interface represents information about the operating system running inside the virtual machine Used in IConsole guest IGuest provides information about the guest operating system whether Guest Additions are installed and other OS specific virtual machine properties 5 38 1 Attributes 5 38 1 1 OSTypeld read only wstring IGuest 0STypeld Identifier of the Guest OS type as reported by the Guest A
381. name cannot safely be determined If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Could not find registered machine matching nameOrId 5 151 12 findNATNetworkByName INATNetwork IVirtualBox findNATNetworkByName in wstring networkName networkName 5 151 13 getExtraData wstring IVirtualBox getExtraData in wstring key key Name of the data key to get Returns associated global extra data If the requested data key does not exist this function will succeed and return an empty string in the value argument If this method fails the following error codes may be reported e VBOX_E_FILE_ERROR Settings file not accessible e VBOX_E_XML_ERROR Could not parse the settings file 5 151 14 getExtraDataKeys wstring IVirtualBox getExtraDataKeys Returns an array representing the global extra data keys which currently have values defined 5 151 15 getGuestOSType IGuestOSType IVirtualBox getGuestOSType in wstring id id Guest OS type ID string Returns an object describing the specified guest OS type The requested guest OS type is specified using a string which is a mnemonic identifier of the guest operating system such as win31 or ubuntu The guest OS type ID of a particular virtual machine can be read or set using the IMachine OSTypeld attribute The guestOSTypes collection contains all available guest OS type objects Each object has an
382. nce you call saveSettings to confirm the change The containing subdirectory will be also renamed but only if it has exactly the same name as the settings file itself prior to changing this property for backward compatibility with previous API releases The above implies the following limitations e The machine name cannot be empty e The machine name can contain only characters that are valid file name characters accord ing to the rules of the file system used to store VirtualBox configuration 168 5 Classes interfaces e You cannot have two or more machines with the same name if they use the same subdirec tory for storing the machine settings files e You cannot change the name of the machine if it is running or if any file in the directory containing the settings file is being used by another running machine or by any other process in the host operating system at a time when saveSettings is called If any of the above limitations are hit saveSettings will return an appropriate error message explaining the exact reason and the changes you made to this machine will not be saved Starting with VirtualBox 4 0 a vbox extension of the settings file is recommended but not enforced Previous versions always used a generic xml extension 5 80 1 6 description read write wstring IMachine description Description of the virtual machine The description attribute can contain any text and is typically used to
383. nd provide some meaningful defaults format vdi Call VirtualBox API using context s fields hdd ctx vb createMedium format loc ctx global constants AccessMode_ReadWrite ctx global constants DeviceType_HardDisk Access constants using ctx global constants progress hdd createBaseStorage size ctx global constants MediumVariant_Standard use standard progress bar mechanism ctx progressBar progress Report errors if not hdd id print cannot create disk file s exist loc return 0 Give user some feedback on success too print created HDD with id s hdd id 0 means continue execution other values mean exit from the interpreter return 0 commands 50 4 The VirtualBox shell myCreateHDD Create virtual HDD createHdd size location type createHdd Just store the above text in the file createHdd or any other meaningful name in config VirtualBox shexts Start the VirtualBox shell or just issue the reloadExts com mand if the shell is already running Your new command will now be available 51 5 Classes interfaces 5 1 lAdditionsFacility Note With the web service this interface is mapped to a structure Attributes that return this interface will not return an object but a complete structure containing the attributes listed below as structure members Structure representing a Guest Additions facility 5 1 1 Attr
384. nd the individual percentage of completion of the current operation in operationPercent and the percentage of completion of the task as a whole in percent Similarly you can wait for the completion of a particular operation via waitForOperationCompletion or for the completion of the whole task via waitForCompletion 274 5 Classes interfaces 5 115 1 Attributes 5 115 1 1 id read only uuid IProgress id ID of the task 5 115 1 2 description read only wstring IProgress description Description of the task 5 115 1 3 initiator read only unknown IProgress initiator Initiator of the task 5 115 1 4 cancelable read only boolean IProgress cancelable Whether the task can be interrupted 5 115 1 5 percent read only unsigned long IProgress percent Current progress value of the task as a whole in percent This value depends on how many operations are already complete Returns 100 if completed is true 5 115 1 6 timeRemaining read only long IProgress timeRemaining Estimated remaining time until the task completes in seconds Returns O once the task has completed returns 1 if the remaining time cannot be computed in particular if the current progress is 0 Even if a value is returned the estimate will be unreliable for low progress values It will become more reliable as the task progresses it is not recommended to display an ETA before at least 20 of a task have completed 5 115 1 7 compl
385. ndSnapshot in wstring nameOrId nameOrld What to search for Name or UUID of the snapshot to find Returns a snapshot of this machine with the given name or UUID Returns a snapshot of this machine with the given UUID A null argument can be used to obtain the first snapshot taken on this machine To traverse the whole tree of snapshots starting from the root inspect the root snapshot s ISnapshot children attribute and recurse over those children If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Virtual machine has no snapshots or snapshot not found 5 80 24 getBootOrder DeviceType IMachine getBootOrder in unsigned long position position Position in the boot order 1 to the total number of devices the machine can boot from as returned by ISystemProperties maxBootPosition Returns the device type that occupies the specified position in the boot order todo remove If the machine can have more than one device of the returned type such as hard disks then a separate method should be used to retrieve the individual device that occupies the given position If here are no devices at the given position then Null is returned todo getHardDiskBootOrder getNetworkBootOrder If this method fails the following error codes may be reported e E_INVALIDARG Boot position out of range 191 5 Classes interfaces 5 80 25 getCPUIDLeaf void IMachine getCPUIDLea
386. ne machine machines i IMachine_Release machine free machines Handling output parameters needs more special effort than input parameters thus only for the former there are special helpers and the latter is handled through the generic array support 2 3 6 7 Event handling The VirtualBox API offers two types of event handling active and passive and consequently there is support for both with the C API binding Active event handling based on asynchronous callback invocation for event delivery is more difficult as it requires the construction of valid C objects in C which is inherently platform and compiler dependent Passive event handling is much simpler it relies on an event loop fetching events and triggering the necessary handlers explicitly in the API client code Both approaches depend on an event loop to make sure that events get delivered in a timely manner with differences what exactly needs to be done The C API sample contains code for both event handling styles and one has to modify the appropriate define to select which style is actually used by the compiled program It allows a good comparison between the two variants and the code sequences are probably worth reusing without much change in other API clients with only minor adaptions Active event handling needs to ensure that the following helper function is called frequently enough in the primary thread g_pVBoxFuncs gt pfnProcessEventQueue cTimeoutMS
387. ne by the IMachine saveSettings call Smart Attachment When normal base or immutable hard disks are indirectly attached to a virtual machine then some additional steps are performed to make sure the virtual machine will have the most recent view of the hard disk being attached These steps include walking through the machine s snapshots starting from the current one and going through ancestors up to the first snapshot Hard disks attached to the virtual machine in all of the encountered snapshots are checked whether they are descendants of the given normal base or immutable hard disk The first found child which is the differencing hard disk will be used instead of the normal base or immutable hard disk as a parent for creating a new differencing hard disk that will be actually attached to the machine And only if no descendants are found or if the virtual machine does not have any snapshots then the normal base or immutable hard disk will be used itself as a parent for this differencing hard disk It is easier to explain what smart attachment does using the following example BEFORE attaching B vdi AFTER attaching B vdi Snapshot 1 B vdi Snapshot 1 B vdi Snapshot 2 D1 gt B vdi Snapshot 2 D1 gt B vdi Snapshot 3 D2 gt D1 vdi Snapshot 3 D2 gt D1 vdi Snapshot 4 none Snapshot 4 none CurState none CurState D3 gt D2 vdi NOT CurState D3 gt B vdi The first column is the virtual machine configuration before the ba
388. ner and newly arrived events are put in this queue When the listener calls IEventSource getEvent first element from its internal event queue is returned When the client completes processing of an event the IEventSource eventProcessed function must be called acknowledging that the event was processed It supports implementing waitable events On passive listener unregistration all events from its queue are auto acknowledged 85 5 Classes interfaces Waitable events are useful in situations where the event generator wants to track delivery or a party wants to wait until all listeners have completed the event A typical example would be a vetoable event see IVetoEvent where a listeners might veto a certain action and thus the event producer has to make sure that all listeners have processed the event and not vetoed before taking the action A given event may have both passive and active listeners at the same time Using events Any VirtualBox object capable of producing externally visible events provides an eventSource read only attribute which is of the type IEventSource This event source object is notified by VirtualBox once something has happened so consumers may register event listeners with this event source To register a listener an object implementing the IEventListener interface must be provided For active listeners such an object is typically created by the consumer while for passive listeners IEventSource createLis
389. nes attribute 5 151 1 Attributes 5 151 1 1 version read only wstring IVirtualBox version A string representing the version number of the product The format is 3 integer numbers divided by dots e g 1 0 1 The last number represents the build number and will frequently change This may be followed by a ALPHA O 9 BETA O 9 or RC 0 9 tag in prerelease builds Non Oracle builds may shall also have a publisher tag at the end The publisher tag starts with an underscore just like the prerelease build type tag 5 151 1 2 versionNormalized read only wstring IVirtualBox versionNormalized A string representing the version number of the product without the publisher information but still with other tags See version 313 5 Classes interfaces 5 151 1 3 revision read only unsigned long IVirtualBox revision The internal build revision number of the product 5 151 1 4 packageType read only wstring IVirtualBox packageType A string representing the package type of this product The format is OS ARCH DIST where OS is either WINDOWS LINUX SOLARIS DARWIN ARCH is either 32BITS or 64BITS DIST is either GENERIC UBUNTU_606 UBUNTU_710 or something like this 5 151 1 5 APIVersion read only wstring IVirtualBox APIVersion A string representing the VirtualBox API version number The format is 2 integer numbers divided by an underscore e g 1_0 After the first public release of packages with a partic
390. ng IVRDEServerInfo clientName The client name supplied by the client 5 147 1 13 clientlP read only wstring IVRDEServerInfo clientIP The IP address of the client 5 147 1 14 clientVersion read only unsigned long IVRDEServerInfo clientVersion The client software version number 5 147 1 15 encryptionStyle read only unsigned long IVRDEServerInfo encryptionStyle Public key exchange method used when connection was established Values 0 RDP4 public key exchange scheme 1 X509 certificates were sent to client 311 5 Classes interfaces 5 148 IVRDEServerlnfoChangedE vent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when the status of the VRDE server changes Interested callees should use IVRDEServerlInfo attributes to find out what is the current status 5 148 1 Attributes 5 148 1 1 midlDoesNotLikeEmptyInterfaces read only boolean IVRDEServerInfoChangedEvent midlDoesNotLikeEmptyInterfaces 5 149 IVetoEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Base abstract interface for veto events 5 149 1 addApproval void IVetoEvent addApproval in wstring reason reason Reason for approval could be null or empty string Adds an approval on this event 5 149 2 addVeto void IVetoEvent addVeto in wstring reason reas
391. ng a lock Shared Request only a shared lock for remote controlling the machine Such a lock allows changing certain VM settings which can be safely modified for a running VM Write Lock the machine for writing This requests an exclusive lock i e there cannot be any other API client holding any type of lock for this VM concurrently Remember that a VM process counts as an API client which implicitly holds the equivalent of a shared lock during the entire VM runtime VM Lock the machine for writing and create objects necessary for running a VM in this process 6 63 MachineState Virtual machine execution state This enumeration represents possible values of the IMachine state attribute Below is the basic virtual machine state diagram It shows how the state changes during virtual machine execution The text in square braces shows a method of the IConsole or Machine interface that performs the given state transition powerDown lt Stuck lt failure Vv l gt PoweredOff gt powerUp gt Starting resume l l Iv l Aborted gt Running pause gt Paused l l Saved powerUp gt Restoring l l OnlineSnapshotting lt takeSnapshot lt l l t Saving lt saveState lt
392. ng and will be checked by the web service For details see below As hinted above IWebsessionManager logon is the only operation provided by the web service which does not take a managed object reference as the first argument 3 The VirtualBox Main API documentation says that the IVirtualBox interface has a version attribute which is a string For each attribute there is a get and a set method in COM which maps to according operations in the web service So to retrieve the version attribute of this IVirtualBox object the web service client does this string version version webservice IVirtualBox_getVersion oVirtualBox print version And it will print 5 0 10 4 The web service client calls IWebsessionManager logoff with the VirtualBox managed object reference This will clean up all allocated resources 33 2 Environment specific notes 2 2 3 3 Managed object references To a web service client a managed object reference looks like a string two 64 bit hex numbers separated by a dash This string however represents a COM object that lives in the web service process The two 64 bit numbers encoded in the managed object reference represent a session ID which is the same for all objects in the same web service session i e for all objects after one logon and a unique object ID within that session Managed object references are created in two situations 1 When a client logs on by
393. ng arguments in wstring environmentChanges in ProcessCreateFlag flags in unsigned long timeoutMS executable Full path to the file to execute in the guest The file has to exists in the guest VM with executable right to the session user in order to succeed If empty null the first entry in the arguments array will be used instead i e argv 0 arguments Array of arguments passed to the new process Note Starting with VirtualBox 5 0 this array starts with argument 0 instead of argu ment 1 as in previous versions Whether the zeroth argument can be passed to the guest depends on the VBoxService version running there If you depend on this check that the protocolVersion is 3 or higher environmentChanges Set of environment changes to complement environmentChangesl Takes precedence over the session ones The changes are in putenv format i e VAR VALUE for setting and VAR for unsetting The changes are applied to the base environment of the impersonated guest user environmentBase when creating the process This is done on the guest side of things in order to be compatible with older guest additions That is one of the motivations for not passing in the whole environment here flags Process creation flags see ProcessCreateFlag for more information timeoutMS Timeout in ms for limiting the guest process running time Pass O for an infi nite timeout On timeout the guest process will be k
394. ng explains some basic VirtualBox concepts such as the VirtualBox object sessions and how virtual machines are manipulated and launched using the Main API The coding examples use a pseudo code style closely related to the object oriented web service OOWS for JAX WS Depending on which environment you are using you will need to adjust the examples 3 1 Obtaining basic machine information Reading attributes Any program using the Main API will first need access to the global VirtualBox object see IVirtualBox from which all other functionality of the API is derived With the OOWS for JAX WS this is returned from the IWebsessionManager logon call To enumerate virtual machines one would look at the machines array attribute in the VirtualBox object see IVirtualBox machines This array contains all virtual machines currently registered with the host each of them being an instance of IMachine From each such instance one can query additional information such as the UUID the name memory operating system and more by looking at the attributes see the attributes list in Machine documentation As mentioned in the preceding chapters depending on your programming environment at tributes are mapped to corresponding get and if the attribute is not read only set methods So when the documentation says that IMachine has a name attribute this means you need to code something like the following to get the machine s name
395. nge o e e 159 577 BR PUC e o a wee eae we ee Be eS 159 5 77 9 onCPUExecutionCapChange 159 5 77 10 onClipboardModeChange o cc ec o agoes aaa ee ee es 160 5 77 11 onDnDModeChante occ cosas a a i ae 160 5 37 12 gniMediumChange wa e os teie e a eA ee we ge 160 5 77 13 onNetworkAdapterChange o e e tiw 160 5 77 14 onParallalPartCnange jcc ee ee a A EE A 160 5 77 15 onSeralPortChange cocos eb ew ee EEE Ee ee eS 161 5 77 16 onSharedPolderGhange o s sti ete s ak a ew a E 161 5 77 17 OnShow Window oca e ceee a e ee ee i 161 5 77 18 onStorageControllerChange lt roana 488 0a ee ee a e a S 161 S 77 19 onStorageDevice Change o ccce a a p OS Ra ee e i e 162 5 77 20 onUSBControllerChange 2 2c se a eee 1 162 5 7721 ONUSBDSICEATIONN oo a ea ee ee a ee 162 5 77 22 O0USBDevceUetach on eee ee Ra eee ta a ead 163 5 77 20 BAVRDESSTVETCHANSE ios iini ek a a a e E 163 5 77 24 onVideoCaptureChange o o eee eee ee 163 5 77 25 oline Mere led os se eee ae ww a ed a e e 163 5 77 26 PatiseWIlReasOM o concu ee eea oe SPS ee ee ew eee Sa 164 5 77 27 reconfigureMediumAttachments o o 164 5 77 20 resume WithReaso oe 26 coe ceceo re Pe REE EEE oe HES 164 5 77 29 saveStateWithReason o e e ee 164 SIRO MEA o A Seb Se Pa ae A 165 5 7731 updateMachineState 2 04 25 see 4a Sees eae ee aes 165 Tea nak ee Rw EO Ge ec BR ee ee ee 165 578 1 AWDIS oaks ee
396. no medium represents a CD DVD or floppy drive with no medium inserted By contrast hard disk attachments will always have an IMedium object attached 223 5 Classes interfaces e Each Medium in turn points to a storage unit such as a file on the host computer or a network resource that holds actual data This location is represented by the location attribute Existing media are opened using IVirtualBox openMedium new hard disk media can be created with the VirtualBox API using the IVirtualBox createMedium Q method Differencing hard disks see below are usually implicitly created by VirtualBox as needed but may also be created explicitly using createDiffStorage VirtualBox cannot create CD DVD or floppy images ISO and RAW files these should be created with external tools and then opened from within VirtualBox Only for CD DVDs and floppies an IMedium instance can also represent a host drive In that case the id attribute contains the UUID of one of the drives in IHost DVDDrives or THost floppyDrivesT Media registries When a medium has been opened or created using one of the aforementioned APIs it be comes known to VirtualBox Known media can be attached to virtual machines and re found through IVirtualBox openMedium They also appear in the global IVirtualBox hardDisks IVirtualBox DVDImages and IVirtualBox floppyImages arrays Prior to VirtualBox 4 0 opening a medium added it to a global media r
397. nsigned long y in DnDAction defaultAction in DnDAction allowedActions in wstring formats screenld The screen ID where the drag and drop event occurred x X position of the event y Y position of the event defaultAction The default action to use allowedActions The actions which are allowed formats The supported MIME types Informs the target about a drag and drop move event If this method fails the following error codes may be reported e VBOX_E_VM_ERROR VMM device is not available 5 21 6 sendData IProgress IDnDTarget sendData in unsigned long screenld in wstring format in octet data screenld The screen ID where the drag and drop event occurred format The MIME type the data is in data The actual data Initiates sending data to the target If this method fails the following error codes may be reported e VBOX_E_VM_ERROR VMM device is not available 5 22 lEmulatedUSB Manages emulated USB devices 84 5 Classes interfaces 5 22 1 Attributes 5 22 1 1 webcams read only wstring IEmulatedUSB webcams Lists attached virtual webcams 5 22 2 webcamAttach void IEmulatedUSB webcamAttach in wstring path in wstring settings path The host path of the capture device to use settings Optional settings Attaches the emulated USB webcam to the VM which will use a host video capture device 5 22 3 webcamDetach void IEmulatedUSB webcamDetach in wstring
398. nt specific notes return EXIT_FAILURE g_pVBoxFuncs gt pfnClientInitialize NULL amp vboxclient if vboxclient fprintf stderr s FATAL could not get VirtualBoxClient reference n argv 01 return EXIT_FAILURE If vboxclient is still NULL this means the initializationi failed and the VirtualBox C API cannot be used It is possible to write C applications using multiple threads which all use the VirtualBox API as long as you re initializing the C API in each thread which your application creates This is done with g_pVBoxFuncs gt pfnClientThreadInitialize and likewise before the thread is termi nated the API must be uninitialized with g_pVBoxFuncs gt pfnClientThreadUninitialize You don t have to use these functions in worker threads created by COM XPCOM which you might observe if your code uses active event handling everything is initialized correctly already On Windows the C bindings create a marshaller which supports a wide range of COM threading models from STA to MTA so you don t have to worry about these details unless you plan to use active event handlers See the sample code how to get this to work reliably in other words think twice if passive event handling isn t the better solution after you looked at the sample code 2 3 6 4 C API attribute and method invocation Method invocation is straightforward It looks pretty much like the C way by using a macro which internally accesses the vtabl
399. nto the virtualization engine for our own front ends This ensures the entire Main API is both well documented and well tested The same applies to VBoxHeadless which is not shown in the image 1 2 Two guises of the same Main API the web service or COM XPCOM There are several ways in which the Main API can be called by other code 1 VirtualBox comes with a web service that maps nearly the entire Main API The web ser vice ships in a stand alone executable vboxwebsrv that when running acts as an HTTP server accepts SOAP connections and processes them Since the entire web service API is publicly described in a web service description file in WSDL format you can write client programs that call the web service in any language with a toolkit that understands WSDL These days that includes most programming languages that are available Java C NET PHP Python Perl and probably many more All of this is explained in detail in subsequent chapters of this book There are two ways in which you can write client code that uses the web service a For Java as well as Python the SDK contains easy to use classes that allow you to use the web service in an object oriented straightforward manner We shall refer to this as the object oriented web service OOWS The OO bindings for Java are described in chapter 11 Using Java API page 385 those for Python in chapter 2 1 2 The object oriented web service for Python page
400. ntroller IMachine getStorageControllerByName in wstring name name Returns a storage controller with the given name If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND A storage controller with given name doesn t exist 5 80 43 getUSBControllerByName IUSBController IMachine getUSBControllerByName in wstring name name Returns a USB controller with the given type If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND A USB controller with given name doesn t exist 5 80 44 getUSBControllerCountByType unsigned long IMachine getUSBControllerCountByType in USBControllerType type type Returns the number of USB controllers of the given type attached to the VM 5 80 45 hotPlugCPU void IMachine hotPlugCPU in unsigned long cpu cpu The CPU id to insert Plugs a CPU into the machine 196 5 Classes interfaces 5 80 46 hotUnplugCPU void IMachine hotUnplugCPU in unsigned long cpu cpu The CPU id to remove Removes a CPU from the machine 5 80 47 launchVMProcess IProgress IMachine LaunchVMProcess in ISession session in wstring name in wstring environment session Client session object to which the VM process will be connected this must be in Un locked state name Front end to use for the new VM process The following are currently supported e gui VirtualBox Qt GU
401. nymore will be closed Guest processes which fall into this category and still are running in the guest will be terminated automatically 5 64 3 directoryCopy IProgress IGuestSession directoryCopy in wstring source in wstring destination in DirectoryCopyFlags flags source The path to the directory to copy in the guest Guest path style destination The path to the target directory in the guest Unless the DirectoryCopyFlags CopyIntoExisting flag is given the directory shall not already exist Guest path style flags Zero or more DirectoryCopyFlags values Recursively copies a directory from one guest location to another If this method fails the following error codes may be reported e E_NOTIMPL Not yet implemented 5 64 4 directoryCopyFromGuest IProgress IGuestSession directoryCopyFromGuest in wstring source in wstring destination in DirectoryCopyFlags flags source Path to the directory on the guest side that should be copied to the host Guest path style destination Where to put the directory on the host Unless the DirectoryCopyFlags CopyIntoExisting flag is given the directory shall not already exist Host path style flags Zero or more DirectoryCopyFlags values Recursively copies a directory from the guest to the host If this method fails the following error codes may be reported e E_NOTIMPL Not yet implemented 5 64 5 directoryCopyToGuest IProgress IGuestSession di
402. o an attempt to insert a filter already in the list is an error Note If USB functionality is not available in the given edition of VirtualBox this method will set the result code to E_NOTIMPL See also USBDeviceFilters If this method fails the following error codes may be reported e VBOX_E_INVALID_OBJECT_STATE USB device filter is not created within this VirtualBox instance e E_INVALIDARG USB device filter already in list 5 69 17 removeHostOnlyNetworkinterface IProgress IHost removeHostOnlyNetworkInterface in uuid id id Adapter GUID Removes the given Host Only Networking interface If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND No host network interface matching id found 5 69 18 removeUSBDeviceFilter void IHost removeUSBDeviceFilter in unsigned long position position Position to remove the filter from Removes a USB device filter from the specified position in the list of filters Positions are numbered starting from 0 Specifying a position equal to or greater than the number of elements in the list will produce an error Note If USB functionality is not available in the given edition of VirtualBox this method will set the result code to E_NOTIMPL See also USBDeviceFilters If this method fails the following error codes may be reported e E_INVALIDARG USB device filter list empty or invalid position
403. o on To query metric values without aggregates can be used The valid names for base metrics are e CPU Load e CPU MHz 267 5 Classes interfaces e RAM Usage e RAM VMM The general sequence for collecting and retrieving the metrics is e Obtain an instance of IPerformanceCollector with IVirtualBox performanceCollector Allocate and populate an array with references to objects the metrics will be collected for Use references to Host and IMachine objects Allocate and populate an array with base metric names the data will be collected for Call setupMetrics From now on the metric data will be collected and stored Wait for the data to get collected Allocate and populate an array with references to objects the metric values will be queried for You can re use the object array used for setting base metrics Allocate and populate an array with metric names the data will be collected for Note that metric names differ from base metric names Call queryMetricsData The data that have been collected so far are returned Note that the values are still retained internally and data collection continues For an example of usage refer to the following files in VirtualBox SDK e Java bindings webservice java jax ws samples metrictest java e Python bindings xpcom python sample shellcommon py 5 112 1 Attributes 5 112 1 1 metricNames read only wstring IPerformanceCollector metricNames Array of unique names of me
404. o the image The only exception is opening a source image temporarily for copying and cloning see IMedium cloneTo when the image will be closed again soon The format of the location string is storage format specific See IMedium location and IMedium for more details If this method fails the following error codes may be reported e VBOX_E_FILE_ERROR Invalid medium storage file location or could not find the medium at the specified location e VBOX_E_IPRT_ERROR Could not get medium storage format e E_INVALIDARG Invalid medium storage format e VBOX_E_INVALID_OBJECT_STATE Medium has already been added to a media registry 5 151 20 registerMachine void IVirtualBox registerMachine in IMachine machine machine 323 5 Classes interfaces Registers the machine previously created using createMachine or opened using openMachine within this VirtualBox installation After successful method invocation the IMachineRegisteredEvent event is fired Note This method implicitly calls IMachine saveSettings to save all current machine settings before registering it If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND No matching virtual machine found e VBOX_E_INVALID_OBJECT_STATE Virtual machine was not created within this VirtualBox instance 5 151 21 removeDHCPServer void IVirtualBox removeDHCPServer in IDHCPServer server server DHCP server set
405. od fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine state neither Running nor Paused e VBOX_E_FILE_ERROR Failed to create directory for saved state file 5 80 66 setAutoDiscardForDevice void IMachine setAutoDiscardForDevice in wstring name in long controllerPort in long device in boolean discard name Name of the storage controller controllerPort Storage controller port device Device slot in the given port discard New value for the discard device flag 205 5 Classes interfaces Sets a flag in the device information which indicates that the medium supports discarding unused blocks called trimming for SATA or unmap for SCSI devices This may or may not be supported by a particular drive and is silently ignored in the latter case At the moment only hard disks which is a misnomer in this context accept this setting Changing the setting while the VM is running is forbidden The device must already exist see attachDevice for how to attach a new device The controllerPort and device parameters specify the device slot and have have the same meaning as with attachDevice If this method fails the following error codes may be reported e E_INVALIDARG SATA device SATA port SCSI port out of range e VBOX_E_INVALID_OBJECT_STATE Attempt to modify an unregistered virtual machine e VBOX_E_INVALID_VM_STATE Invalid machine state 5 80 67 setBandwidthGroupForDevi
406. od must set winId to zero if it has performed all actions necessary to complete the request and the console window is now active and in foreground to indicate that no further action is required on the caller s side 285 5 Classes interfaces 5 124 1 Attributes 5 124 1 1 winid read write long long IShowWindowEvent winId Platform dependent identifier of the top level VM console window or zero if this method has performed all actions necessary to implement the show window semantics for the given platform and or this VirtualBox front end 5 125 ISnapshot The Snapshot interface represents a snapshot of the virtual machine Together with the differencing media that are created when a snapshot is taken a machine can be brought back to the exact state it was in when the snapshot was taken The ISnapshot interface has no methods only attributes snapshots are controlled through methods of the Machine interface which also manage the media associated with the snapshot The following operations exist e IMachine takeSnapshot creates a new snapshot by creating new empty differencing im ages for the machine s media and saving the VM settings and if the VM is running the current VM state in the snapshot The differencing images will then receive all data written to the machine s media while their parent base images remain unmodified after the snapshot has been taken see IMedium for details about differencing images This si
407. of 3 3 0r12345 397 13 Main API change log e To address shared folders auto mounting support the following APIs were extended to require an additional automount parameter IVirtualBox createSharedFolderQ IMachine createSharedFolder IConsole createSharedFolder Also a new property named autoMount was added to the ISharedFolder interface e The appliance OVF APIs were enhanced as follows IMachine export received an extra parameter location which is used to decide for the disk naming IAppliance writeQ received an extra parameter manifest which can suppress creat ing the manifest file on export IVFSExplorer entryList received two extra parameters sizes and modes which contains the sizes in bytes and the file access modes in octal form of the returned files e Support for remote desktop access to virtual machines has been cleaned up to allow third party implementations of the remote desktop server This is called the VirtualBox Remote Desktop Extension VRDE and can be added to VirtualBox by installing the corresponding extension package see the VirtualBox User Manual for details The following API changes were made to support the VRDE interface IVRDPServer has been renamed to IVRDEServer IRemoteDisplayInfo has been renamed to IVRDEServerInfo IMachine VRDEServer replaces VRDPServer IConsole VRDEServerInfo replaces RemoteDisplayInfo ISystemProperties VRDEAuthLibr
408. oleCallback onMousePointerShapeChange was changed from a implementation specific pointer to a safearray enabling scripting languages to pro cess pointer shapes 13 7 Incompatible API changes with version 3 1 e Due to the new flexibility in medium attachments that was introduced with version 3 1 in particular full flexibility with attaching CD DVD drives to arbitrary controllers we seized the opportunity to rework all interfaces dealing with storage media to make the API more flexible as well as logical The IStorageController IMedium IMediumAttachment and IMachine interfaces were affected the most Existing code using them to configure storage and media needs to be carefully checked All media hard disks floppies and CDs DVDs are now uniformly handled through the IMedium interface The device specific interfaces IHardDisk IDVDImage IHostDVDDrive IFloppyImage and IHostFloppyDrive have been merged into IMedium CD DVD and floppy media no longer need special treatment The device type of a medium determines in which context it can be used Some functionality was moved to the other storage related interfaces IMachine attachHardDisk and similar methods have been renamed and generalized to deal with any type of drive and medium IMachine attachDevice is the API method for adding any drive to a storage controller The floppy and DVD CD drives are no longer 399 13 Main API change log handled specially and that means you can h
409. ompletion of the progress object 5 76 4 beginPoweringDown void IInternalMachineControl beginPoweringDown out IProgress progress progress Progress object created by VBoxSVC to wait until the VM is powered down Called by the VM process to inform the server it wants to stop the VM execution and power down 152 5 Classes interfaces 5 76 5 captureUSBDevice void IInternalMachineControl captureUSBDevice in uuid id in wstring captureFilename id captureFilename Requests a capture of the given host USB device When the request is completed the VM process will get a IInternalSessionControl onUSBDeviceAttach notification 5 76 6 detachAllUSBDevices void IInternalMachineControl detachAllUSBDevices in boolean done done Notification that a VM that is being powered down The done parameter indicates whether which stage of the power down we re at When done false the VM is announcing its inten tions while when done true the VM is reporting what it has done Note In the done true case the server must run its own filters and filters of all VMs but this one on all detach devices as if they were just attached to the host computer 5 76 7 detachUSBDevice void IInternalMachineControl detachUSBDevice in uuid id in boolean done id done Notification that a VM is going to detach done false or has already detached done true the given USB device When the done t
410. on Ethernet encapsulation includes both wired and wireless Ethernet con nections See also IHostNetworkInterface Unknown The type of interface cannot be determined Ethernet Ethernet frame encapsulation PPP Point to point protocol encapsulation SLIP Serial line IP encapsulation 350 6 Enumerations enums 6 57 HostNetworkinterfaceStatus Current status of the interface See also IHostNetworkInterface Unknown The state of interface cannot be determined Up The interface is fully operational Down The interface is not functioning 6 58 HostNetworkinterfaceType Network interface type Bridged HostOnly 6 59 ImportOptions Import options used with IAppliance importMachines KeepAlIMACs Don t generate new MAC addresses of the attached network adapters KeepNATMACs Don t generate new MAC addresses of the attached network adapters when they are using NAT ImportToVDI Import all disks to VDI format 6 60 KeyboardHIDType Type of keyboard device used in a virtual machine None No keyboard PS2Keyboard PS 2 keyboard USBKeyboard USB keyboard ComboKeyboard Combined device working as PS 2 or USB keyboard depending on guest behavior Using of such device can have negative performance implications 6 61 KeyboardLED Keyboard LED indicators NumLock CapsLock ScrollLock 351 6 Enumerations enums 6 62 LockType Used with IMachine lockMachine Null Placeholder value do not use when obtaini
411. on Reason for veto could be null or empty string Adds a veto on this event 5 149 3 getApprovals wstring IVetoEvent getApprovals Current approval reason list if size is O no approvals 5 149 4 getVetos wstring IVetoEvent getVetos Current veto reason list if size is O no veto 312 5 Classes interfaces 5 149 5 isApproved boolean IVetoEvent isApproved If this event was approved 5 149 6 isVetoed boolean IVetoEvent isVetoed If this event was vetoed 5 150 IVideoCaptureChangedEvent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well Notification when video capture settings have changed 5 150 1 Attributes 5 150 1 1 midlDoesNotLikeEmptyInterfaces read only boolean IVideoCaptureChangedEvent midlDoesNotLikeEmptyInterfaces 5 151 IVirtualBox The IVirtualBox interface represents the main interface exposed by the product that provides virtual machine management An instance of IVirtualBox is required for the product to do anything useful Even though the interface does not expose this internally IVirtualBox is implemented as a singleton and actually lives in the process of the VirtualBox server VBoxSVC exe This makes sure that IVirtualBox can track the state of all virtual machines on a particular host regardless of which frontend started them To enumerate all the virtual machines on the host use the machi
412. on Win32 extensions earlier than 2 16 are known to have bugs leading to issues with VirtualBox Python bindings and also some early builds of Python 2 5 for Windows have issues with reporting platform name on some Windows versions so please make sure to use latest available Python and Win32 extensions The VirtualBox OOWS for Python relies on the Python ZSI SOAP implementation see http pywebsvcs sourceforge net zsi html which you will need to install locally before trying the examples Most Linux distributions come with package for ZSI such as python zsi in Ubuntu To get started open a terminal and change to the bindings glue python sample direc tory which contains an example of a simple interactive shell able to control a VirtualBox in stance The shell is written using the API layer thereby hiding different implementation de tails so it is actually an example of code share among XPCOM MSCOM and web services If you are interested in how to interact with the web services layer directly have a look at install vboxapi __init__ py which contains the glue layer for all target platforms i e XP COM MSCOM and web services To start the shell perform the following commands opt VirtualBox vboxwebsrv t 0 start web service with object autocollection disabled export VBOX_PROGRAM_PATH opt VirtualBox your VirtualBox installation directory export VBOX_SDK_PATH home youruser vbox sdk where you ve extracted the SDK vboxshell
413. only in the documentation there will also be a corresponding set method 2 1 1 The object oriented web service for JAX WS JAX WS is a powerful toolkit by Sun Microsystems to build both server and client code with Java It is part of Java 6 JDK 1 6 but can also be obtained separately for Java 5 JDK 1 5 The VirtualBox SDK comes with precompiled OOWS bindings working with both Java 5 and 6 The following sections explain how to get the JAX WS sample code running and explain a few common practices when using the JAX WS object oriented web service 2 1 1 1 Preparations Since JAX WS is already integrated into Java 6 no additional preparations are needed for Java 6 If you are using Java 5 JDK 1 5 x you will first need to download and install an external JAX WS implementation as Java 5 does not support JAX WS out of the box for example you can 27 2 Environment specific notes download one from here https jax ws dev java net 2 1 4 JAXWS2 1 4 20080502 jar Then perform the installation java jar JAXWS2 1 4 20080502 jar 2 1 1 2 Getting started running the sample code To run the OOWS for JAX WS samples that we ship with the SDK perform the following steps 1 Open a terminal and change to the directory where the JAX WS samples reside Examine the header of Makefile to see if the supplied variables Java compiler Java executable and a few other details match your system settings 2 To start the VirtualBox web se
414. onmentBase read only wstring IGuestSession environmentBase The base environment of the session They are on the VAR VALUE form one array entry per variable Access fails with VBOX_E_NOT_SUPPORTED if the guest additions does not support the ses sion base environment feature Support for this was introduced with protocol version XXXX Access fails with VBOX_E_ INVALID _OBJECT_STATE if the guest additions has yet to report the session base environment 5 64 1 10 processes read only IGuestProcess IGuestSession processes Returns all current guest processes 5 64 1 11 pathStyle read only PathStyle IGuestSession pathStyle The style of paths used by the guest Handy for giving the right kind of path specifications to fileOpen and similar methods 5 64 1 12 currentDirectory read write wstring IGuestSession currentDirectory The current directory of the session Guest path style 5 64 1 13 directories read only IGuestDirectory IGuestSession directories Returns all currently opened guest directories 5 64 1 14 files read only IGuestFile IGuestSession files Returns all currently opened guest files 5 64 1 15 eventSource read only IEventSource IGuestSession eventSource Event source for guest session events 125 5 Classes interfaces 5 64 2 close void IGuestSession close Closes this session All opened guest directories files and processes which are not referenced by clients a
415. onsistency IMachine getCpuPropertyO is now IMachine getCPUPropertyO IMachine setCpuProperty is now IMachine setCPUProperty IMachine getCpuldLeaf is now IMachine getCPUIDLeaf IMachine setCpuldLeaf is now IMachine setCPUIDLeafO IMachine removeCpuldLeaf is now IMachine removeCPUIDLeafO IMachine removeAllCpuldLeafs is now Machine removeAllCPUIDLeaves the CpuPropertyType enum is now CPUPropertyType TVirtualBoxCallback onSnapshotDiscarded is now IVirtualBoxCallback onSnapshotDeleted When creating a VM configuration with IVirtualBox createMachine it is now possible to ignore existing configuration files which would previously have caused a failure For this the override parameter was added Deleting snapshots via IConsole deleteSnapshot is now possible while the associ ated VM is running in almost all cases The API is unchanged but client code that verifies machine states to determine whether snapshots can be deleted may need to be adjusted The IoBackendType enumeration was replaced with a boolean flag see IStorageController useHostIOCache To address multi monitor support the following APIs were extended to require an addi tional screenId parameter IMachine querySavedThumbnailSize IMachine readSavedThumbnailToArray IMachine querySavedScreenshotPNGSize IMachine readSavedScreenshotPNGToArray e The shape parameter of ICons
416. ormation This can be information about a file or a directory for example 5 37 1 Attributes 5 37 1 1 accessTime read only long long IFsObjInfo accessTime Time of last access st_atime 5 37 1 2 allocatedSize read only long long IFsObjInfo allocatedSize Disk allocation size st_blocks DEV_BSIZE 5 37 1 3 birthTime read only long long IFsObjInfo birthTime Time of file birth st_birthtime 104 5 Classes interfaces 5 37 1 4 changeTime read only long long IFsObjInfo changeTime Time of last status change st_ctime 5 37 1 5 deviceNumber read only unsigned long IFsObjInfo deviceNumber The device number of a character or block device type object st_rdev 5 37 1 6 fileAttributes read only wstring IFsObjInfo fileAttributes File attributes Not implemented yet 5 37 1 7 generationld read only unsigned long IFsObjInfo generationId The current generation number st_gen 5 37 1 8 GID read only unsigned long IFsObjInfo GID The group the filesystem object is assigned st_gid 5 37 1 9 groupName read only wstring IFsObjInfo groupName The group name 5 37 1 10 hardLinks read only unsigned long IFsObjInfo hardLinks Number of hard links to this filesystem object st_nlink 5 37 1 11 modificationTime read only long long IFsObjInfo modificationTime Time of last data modification st_mtime 5 37 1 12 name read only wstring IFsObjInfo
417. ormation object 5 151 1 11 machines read only IMachine IVirtualBox machines Array of machine objects registered within this VirtualBox instance 5 151 1 12 machineGroups read only wstring IVirtualBox machineGroups Array of all machine group names which are used by the machines which are accessible Each group is only listed once however they are listed in no particular order and there is no guarantee that there are no gaps in the group hierarchy i e group subgroup is a valid result 5 151 1 13 hardDisks read only IMedium IVirtualBox hardDisks Array of medium objects known to this VirtualBox installation This array contains only base media All differencing media of the given base medium can be enumerated using Medium children 5 151 1 14 DVDImages read only IMedium IVirtualBox DVDImages Array of CD DVD image objects currently in use by this VirtualBox instance 5 151 1 15 floppylmages read only IMedium IVirtualBox floppyImages Array of floppy image objects currently in use by this VirtualBox instance 5 151 1 16 progressOperations read only IProgress IVirtualBox progressOperations 5 151 1 17 guestOSTypes read only IGuestOSType IVirtualBox guestOSTypes 5 151 1 18 sharedFolders read only ISharedFolder IVirtualBox sharedFolders Collection of global shared folders Global shared folders are available to all virtual machines New shared folders are added to t
418. ormats 5 18 3 isFormatSupported boolean IDnDBase isFormatSupported in wstring format format Format to check for Checks if a specific drag n drop MIME Content type format is supported 5 18 4 removeFormats void IDnDBase removeFormats in wstring formats formats Collection of formats to remove Removes MIME Content type formats from the supported formats 5 19 IDnDModeChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when the drag n drop mode changes 5 19 1 Attributes 5 19 1 1 dndMode read only DnDMode IDnDModeChangedEvent dndMode The new drag n drop mode 5 20 IDnDSource IDnDBase Note This interface extends IDnDBase and therefore supports all its methods and attributes as well Abstract interface for handling drag n drop sources 81 5 Classes interfaces 5 20 1 draglsPending DnDAction IDnDSource dragIsPending in unsigned long screenld out wstring formats out DnDAction allowedActions screenld The screen ID where the drag and drop event occurred formats On return the supported mime types allowedActions On return the actions which are allowed Ask the source if there is any drag and drop operation pending If no drag and drop operation is pending currently DnDAction Ignore is returned If this method fails the following error codes may
419. orted e E_INVALIDARG Boot position out of range e E_NOTIMPL Booting from USB device currently not supported 206 5 Classes interfaces 5 80 69 setCPUIDLeaf void IMachine setCPUIDLeaf in unsigned long id in unsigned long valEax in unsigned long valEbx in unsigned long valEcx in unsigned long valEdx id CPUID leaf index valEax CPUID leaf value for register eax valEbx CPUID leaf value for register ebx valEcx CPUID leaf value for register ecx valEdx CPUID leaf value for register edx Sets the virtual CPU cpuid information for the specified leaf Note that these values are not passed unmodified VirtualBox clears features that it doesn t support Currently supported index values for cpuid Standard CPUID leafs 0 OxA Extended CPUID leafs Ox80000000 0x8000000A See the Intel and AMD programmer s manuals for detailed information about the cpuid in struction and its leafs Do not use this method unless you know exactly what you re doing Misuse can lead to random crashes inside VMs If this method fails the following error codes may be reported e E_INVALIDARG Invalid id 5 80 70 setCPUProperty void IMachine setCPUProperty in CPUPropertyType property in boolean value property Property type to query value Property value Sets the virtual CPU boolean value of the specified property If this method fails the following error codes may be reported e E_INVALIDARG Inva
420. orts all its methods and attributes as well 5 101 1 Attributes 5 101 1 1 creationEvent read only boolean INATNetworkCreationDeletionEvent creationEvent 5 102 INATNetworkPortForwardEvent INATNetworkAlterEvent Note This interface extends INATNetworkAlterEvent and therefore supports all its methods and attributes as well 5 102 1 Attributes 5 102 1 1 create read only boolean INATNetworkPortForwardEvent create 258 5 Classes interfaces 5 102 1 2 ipv6 read only boolean INATNetworkPortForwardEvent ipv6 5 102 1 3 name read only wstring INATNetworkPortForwardEvent name 5 102 1 4 proto read only NATProtocol INATNetworkPortForwardEvent proto 5 102 1 5 hostlp read only wstring INATNetworkPortForwardEvent hostIp 5 102 1 6 hostPort read only long INATNetworkPortForwardEvent hostPort 5 102 1 7 guestlp read only wstring INATNetworkPortForwardEvent guestIp 5 102 1 8 guestPort read only long INATNetworkPortForwardEvent guestPort 5 103 INATNetworkSettingEvent INATNetworkAlterEvent Note This interface extends INATNetworkAlterEvent and therefore supports all its methods and attributes as well 5 103 1 Attributes 5 103 1 1 enabled read only boolean INATNetworkSettingEvent enabled 5 103 1 2 network read only wstring INATNetworkSettingEvent network 5 103 1 3 gateway read only wstring INATNetworkSettingEvent gateway
421. ot exist not supported by the format e E_INVALIDARG name is null or empty 239 5 Classes interfaces 5 88 IMediumAttachment Note With the web service this interface is mapped to a structure Attributes that return this interface will not return an object but a complete structure containing the attributes listed below as structure members The IMediumAttachment interface links storage media to virtual machines For each medium IMedium which has been attached to a storage controller IStorageController of a machine IMachine via the IMachine attachDevice method one instance of IMediumAttachment is added to the machine s IMachine mediumAttachments array attribute Each medium attachment specifies the storage controller as well as a port and device number and the IMedium instance representing a virtual hard disk or floppy or DVD image For removable media DVDs or floppies there are two additional options For one the IMedium instance can be null to represent an empty drive with no media inserted see IMachine mountMedium secondly the medium can be one of the pseudo media for host drives listed in IHost DVDDrives or IHost floppyDrives Attaching Hard Disks Hard disks are attached to virtual machines using the IMachine attachDevice method and detached using the IMachine detachDeviceQ method Depending on a medium s type see IMedium type hard disks are attached either directly or indire
422. otUnplugCPU lt ca ca iio corra ars a 197 5 80 47 launchVMProcess o 197 5 8048 lockMachine ocurra ee ee a 198 5 80 49 mountMedium cies e a ee a es eS we 199 5 80 50 nonRotationalDevice o ee ee 200 SSOS5L passthronsiDeres o e os eee Sw a de a wa E 201 10 5 81 5 82 Contents 5 30 52 qlerlogrilename 0030259 Pa oe ww EEG Pe a ee 201 5 80 53 querySavedGuestScreenInfo lt lt o csao o oo 201 5 80 54 querySavedScreenshotinfo o ooo 202 5 80 55 teadlos 2202 rirr ira 20444 4445 202 5 80 56 readSavedScreenshotloAiray lt o e 1 vos 202 5 80 57 readSavedThumbnailToArray o oo 202 5 80 58 remove AlCPUIDLeaves oe creara ee e 203 5 90 59 removeCPlllDLesd ue cee eee ros a ER OE ORES 203 5 80 60 removeSharedPolder ook el ek aa ee 203 5 80 61 removeStorageController oces ce eee ee ea eee oe 203 5 80 62 removeUSBController o e m ereo eee ee ea a 204 5 80 63 restoresnapshot ss oe ee ecra we ee ee A 204 5 80 64 SAVEBCIIDES ac 4 424494042 a54444 44004 4448 4 204 o ta koe e iis ds Sw Gd owe elie eee GS a eee 205 5 80 66 setAutoDiscardForDevice s resa 2 2 0 205 5 80 67 setBandwidthGroupForDevice o o a eee 206 5 00 08 e so ctw ce eee eb bed Bae e ee eee ee mae 206 530 69 SECPUIDESE oo ke Gels ee we mR aR a ea aw a E 207 DAL FU SELCPUIPFOPOIY os oe os Neg oe eS A eee aie Brae
423. ote Remote state filter Note This filter makes sense only for machine USB filters i e it is ignored by IHos tUSBDeviceFilter objects 5 140 1 11 maskedinterfaces read write unsigned long IUSBDeviceFilter maskedInterfaces This is an advanced option for hiding one or more USB interfaces from the guest The value is a bit mask where the bits that are set means the corresponding USB interface should be hidden masked off if you like This feature only works on Linux hosts 5 141 lUSBDeviceFilters 5 141 1 Attributes 5 141 1 1 deviceFilters read only IUSBDeviceFilter IUSBDeviceFilters deviceFilters List of USB device filters associated with the machine If the machine is currently running these filters are activated every time a new sup ported USB device is attached to the host computer that was not ignored by global filters IHost USBDeviceFilters These filters are also activated when the machine is powered up They are run against a list of all currently available USB devices in states Available Busy Held that were not previously ignored by global filters If at least one filter matches the USB device in question this device is automatically captured attached to the virtual USB controller of this machine See also IUSBDeviceFilter IUSBController 304 5 Classes interfaces 5 141 2 createDeviceFilter IUSBDeviceFilter IUSBDeviceFilters createDeviceFilter in wstring name nam
424. otplugCapable boolean ISystemProperties getStorageControllerHotplugCapable in StorageControllerType controllerType controllerType The storage controller to check the setting for Returns whether the given storage controller supports hot plugging devices 5 136 IToken The IToken interface represents a token passed to an API client which triggers cleanup actions when it is explicitly released by calling the abandon method preferred as it is accurately defined when the release happens or when the object reference count drops to 0 The latter way is implicitly used when an API client crashes however the discovery that there was a crash can take rather long depending on the platform COM needs 6 minutes So better don t rely on the crash behavior too much 5 136 1 abandon void IToken abandon Releases this token Cannot be undone in any way and makes the token object unusable even the dummy method will return an error ready for releasing It is a more defined way than just letting the reference count drop to 0 because the latter depending on the platform can trigger asynchronous cleanup activity 5 136 2 dummy void IToken dummy Purely a NOOP Useful when using proxy type API bindings e g the webservice which man age objects on behalf of the actual client using an object reference expiration time based garbage collector 299 5 Classes interfaces 5 137 lUSBController 5 137 1 Attributes
425. ough the VESA BIOS and VMMDev interface so that it can use it for determining its video mode table It is not guaranteed that the guest respects the value 5 35 1 7 overlay read only IFramebufferOverlay IFramebuffer overlay An alpha blended overlay which is superposed over the frame buffer The initial purpose is to allow the display of icons providing information about the VM state including disk activity in front ends which do not have other means of doing that The overlay is designed to controlled exclusively by IDisplay It has no locking of its own and any changes made to it are not guar anteed to be visible until the affected portion of Framebuffer is updated The overlay can be created lazily the first time it is requested This attribute can also return null to signal that the overlay is not implemented 5 35 1 8 winld read only long long IFramebuffer winId Platform dependent identifier of the window where context of this frame buffer is drawn or zero if there s no such window 5 35 1 9 capabilities read only FramebufferCapabilities IFramebuffer capabilities Capabilities of the framebuffer instance For the meaning of individual capability flags see FramebufferCapabilities 5 35 2 getVisibleRegion Note This method is not supported in the web service unsigned long IFramebuffer getVisibleRegion in ptr octet rectangles in unsigned long count rectangles Pointer to the RTRECT
426. ouldn t notice that it was cloned or teleported 5 80 1 12 CPUCount read write unsigned long IMachine CPUCount Number of virtual CPUs in the VM 5 80 1 13 CPUHotPlugEnabled read write boolean IMachine CPUHotPlugEnabled This setting determines whether VirtualBox allows CPU hotplugging for this machine 5 80 1 14 CPUExecutionCap read write unsigned long IMachine CPUExecutionCap Means to limit the number of CPU cycles a guest can use The unit is percentage of host CPU cycles per second The valid range is 1 100 100 the default implies no limit 5 80 1 15 CPUIDPortabilityLevel read write unsigned long IMachine CPUIDPortabilityLevel Virtual CPUID portability level the higher number the fewer newer or vendor specific CPU feature is reported to the guest via the CPUID instruction The default level of zero 0 means that all virtualized feautres supported by the host is pass thru to the guest While the three 3 is currently the level supressing the most features Exactly which of the CPUID features are left out by the VMM at which level is subject to change with each major version 5 80 1 16 memorySize read write unsigned long IMachine memorySize System memory size in megabytes 5 80 1 17 memoryBalloonSize read write unsigned long IMachine memoryBalloonSize Memory balloon size in megabytes 5 80 1 18 pageFusionEnabled read write boolean IMachine pageFusionEnabled This setting determin
427. our XPCOM implementation as described above Since COM and XPCOM are conceptually very similar but vary in the implementation details we have created a glue layer that shields COM client code from these differences All VirtualBox uses is this glue layer so the same code written once works on both Windows hosts with native COM as well as on other hosts with our XPCOM implementation It is recommended to always use this glue code instead of using the COM and XPCOM APIs directly as it is very easy to make your code completely independent from the platform it is running on In order to encapsulate platform differences between Microsoft COM and XPCOM the follow ing items should be kept in mind when using the glue layer 1 Attribute getters and setters COM has the notion of attributes in interfaces which roughly compare to C member variables in classes The difference is that for each attribute declared in an interface COM automatically provides a get method to return the attribute s value Unless the attribute has been marked as readonly a set attribute is also provided To illustrate the VirtualBox interface has a version attribute which is read only and of the wstring type the standard string type in COM As a result you can call the get method for this attribute to retrieve the version number of VirtualBox Unfortunately the implementation differs between COM and XPCOM Microsoft C
428. own An ACPI shutdown event is generated 335 6 Enumerations enums 6 12 BIOSBootMenuMode BIOS boot menu mode Disabled MenuOnly MessageAndMenu 6 13 BandwidthGroupType Type of a bandwidth control group Null Null type must be first Disk The bandwidth group controls disk I O Network The bandwidth group controls network I O 6 14 BitmapFormat Format of a bitmap Generic values for formats used by the source bitmap the screen shot or image update APIs Opaque Unknown buffer format the user may not assume any particular format of the buffer BGR Generic BGR format without alpha channel Pixel layout depends on the number of bits per pixel e 32 bits 31 24 undefined bits 23 16 R bits 15 8 G bits 7 0 B e 16 bits 15 11 R bits 10 5 G bits 4 0 B BGRO 4 bytes per pixel B G R 0 BGRA 4 bytes per pixel B G R A RGBA 4 bytes per pixel R G B A PNG PNG image JPEG JPEG image 6 15 CPUPropertyType Virtual CPU property type This enumeration represents possible values of the IMachine get and setCPUProperty methods Null Null value never used by the API PAE This setting determines whether VirtualBox will expose the Physical Address Extension PAE feature of the host CPU to the guest Note that in case PAE is not available it will not be reported LongMode This setting determines whether VirtualBox will advertise long mode i e 64 bit guest support and let the guest enter it Triple
429. port which it is attached to including hubs and cables in the path Note Due to differences in USB stack implementations on various hosts the reported speed may not exactly match the actual speed See also IHostUSBDevice Null null value Never returned by the API Low Low speed 1 5 Mbps Full Full speed 12 Mbps High High speed 480 Mbps Super SuperSpeed 5 Gbps SuperPlus SuperSpeedPlus 10 Gbps 6 98 USBControllerType The USB controller type IUSBController type Null null value Never used by the API OHCI EHCI XHCI Last Last element invalid Used for parameter checks 6 99 USBDeviceFilterAction Actions for host USB device filters See also IHostUSBDeviceFilter USBDeviceState Null Null value never used by the API Ignore Ignore the matched USB device Hold Hold the matched USB device 366 6 Enumerations enums 6 100 USBDeviceState USB device state This enumeration represents all possible states of the USB device physically attached to the host computer regarding its state on the host computer and availability to guest computers all currently running virtual machines Once a supported USB device is attached to the host global USB filters IHost USBDeviceFilters are activated They can either ignore the device or put it to USBDeviceState_Held state or do nothing Unless the device is ignored by global filters filters of all currently running guests USBDeviceFilters deviceFil
430. properties are to be returned Note Currently the value of this argument is ignored and the method always returns all existing properties The list of all properties supported by the given medium format can be obtained with IMediumFormat describeProperties The method returns two arrays the array of property names corresponding to the names argu ment and the current values of these properties Both arrays have the same number of elements with each element at the given index in the first array corresponds to an element at the same index in the second array For properties that do not have assigned values an empty string is returned at the appropriate index in the returnValues array 5 87 13 getProperty wstring IMedium getProperty in wstring name name Name of the property to get Returns the value of the custom medium property with the given name The list of all properties supported by the given medium format can be obtained with IMediumFormat describeProperties Note If this method returns an empty string in value the requested property is sup ported but currently not assigned any value If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Requested property does not exist not supported by the format e E_INVALIDARG name is null or empty 234 5 Classes interfaces 5 87 14 getSnapshotlds uuid IMedium getSnapshotIds in uuid
431. property a full path is always returned Note The specified path may not exist it will be created when necessary 173 5 Classes interfaces 5 80 1 41 VRDEServer read only IVRDEServer IMachine VRDEServer VirtualBox Remote Desktop Extension VRDE server object 5 80 1 42 emulatedUSBCardReaderEnabled read write boolean IMachine emulatedUSBCardReaderEnabled 5 80 1 43 mediumAttachments read only IMediumAttachment IMachine mediumAttachments Array of media attached to this machine 5 80 1 44 USBControllers read only IUSBController IMachine USBControllers Array of USB controllers attached to this machine Note If USB functionality is not available in the given edition of VirtualBox this method will set the result code to E_NOTIMPL 5 80 1 45 USBDeviceFilters read only IUSBDeviceFilters IMachine USBDeviceFilters Associated USB device filters object Note If USB functionality is not available in the given edition of VirtualBox this method will set the result code to E_NOTIMPL 5 80 1 46 audioAdapter read only TAudioAdapter IMachine audioAdapter Associated audio adapter always present 5 80 1 47 storageControllers read only IStorageController IMachine storageControllers Array of storage controllers attached to this machine 5 80 1 48 settingsFilePath read only wstring IMachine settingsFilePath Full name of the file containing machine sett
432. py of virtual machine s settings hardware configuration etc This copy is contained in an immutable read only instance of IMachine which is available from the snapshot s machine attribute When restoring the snapshot these settings are copied back to the original machine In addition if the machine was running when the snapshot was taken IMachine state is Running the current VM state is saved in the snapshot similarly to what happens when a VM s 286 5 Classes interfaces state is saved The snapshot is then said to be online because when restoring it the VM will be running If the machine was in Saved saved the snapshot receives a copy of the execution state file IMachine stateFilePath Otherwise if the machine was not running PoweredOff or Aborted the snapshot is offline it then contains a so called zero execution state representing a machine that is powered off 5 125 1 Attributes 5 125 1 1 id read only uuid ISnapshot id UUID of the snapshot 5 125 1 2 name read write wstring ISnapshot name Short name of the snapshot Note Setting this attribute causes IMachine saveSettings to be called implicitly 5 125 1 3 description read write wstring ISnapshot description Optional description of the snapshot Note Setting this attribute causes IMachine saveSettings to be called implicitly 5 125 1 4 timeStamp read only long long ISnapshot timeStamp Tim
433. r if media from this machine s media registry are also attached to another machine shared attachments each such medium will be moved to another machine s registry This is because without this machine s media registry the other machine cannot find its media any more and would become inaccessible This API implicitly calls saveSettings to save all current machine settings before unregister ing it It may also silently call saveSettings on other machines if media are moved to other machines media registries After successful method invocation the IMachineRegisteredEvent event is fired The call will fail if the machine is currently locked see ISession Note If the given machine is inaccessible see accessible it will be unregistered and fully uninitialized right afterwards As a result the returned machine object will be unusable and an attempt to call any method will return the Object not ready error If this method fails the following error codes may be reported e VBOX_E_INVALID_OBJECT_STATE Machine is currently locked for a session 5 81 IMachineDataChangedEvent IMachineEvent Note This interface extends IMachineEvent and therefore supports all its methods and attributes as well Any of the settings of the given machine has changed 5 81 1 Attributes 5 81 1 1 temporary read only boolean IMachineDataChangedEvent temporary true if the settings change is temporary All pe
434. r codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine currently changing state 211 5 Classes interfaces 5 80 81 temporaryEjectDevice void IMachine temporaryEjectDevice in wstring name in long controllerPort in long device in boolean temporaryEject name Name of the storage controller controllerPort Storage controller port device Device slot in the given port temporaryEject New value for the eject behavior Sets the behavior for guest triggered medium eject In some situations it is desirable that such ejects update the VM configuration and in others the eject should keep the VM configuration The device must already exist see attachDevice for how to attach a new device The controllerPort and device parameters specify the device slot and have have the same meaning as with attachDevice If this method fails the following error codes may be reported e E_INVALIDARG SATA device SATA port IDE port or IDE slot out of range e VBOX_E_INVALID_OBJECT_STATE Attempt to modify an unregistered virtual machine e VBOX_E_INVALID_VM_STATE Invalid machine state 5 80 82 unmountMedium void IMachine unmountMedium in wstring name in long controllerPort in long device in boolean force name Name of the storage controller to unmount the medium from controllerPort Port to unmount the medium from device Device slot in the given port to unmount the medium from force Allows to
435. r details on the file format 5 82 4 dumpGuestStack wstring IMachineDebugger dumpGuestStack in unsigned long cpuld cpuld The identifier of the Virtual CPU Produce a simple stack dump using the current guest state This feature is not implemented in the 4 0 0 release but may show up in a dot release 5 82 5 dumpHostProcessCore void IMachineDebugger dumpHostProcessCore in wstring filename in wstring compression filename The name of the output file The file must not exist compression Reserved for future compression method indicator Takes a core dump of the VM process on the host This feature is not implemented in the 4 0 0 release but it may show up in a dot release 217 5 Classes interfaces 5 82 6 dumpStats void IMachineDebugger dumpStats in wstring pattern pattern The selection pattern A bit similar to filename globbing Dumps VM statistics 5 82 7 getRegister wstring IMachineDebugger getRegister in unsigned long cpuld in wstring name cpuld The identifier of the Virtual CPU name The register name case is ignored Gets one register 5 82 8 getRegisters void IMachineDebugger getRegisters in unsigned long cpuld out wstring names out wstring values cpuld The identifier of the Virtual CPU names Array containing the lowercase register names values Array parallel to the names holding the register values as if the register was returned by getRe
436. r incoming teleportations and 3 per form teleportation These operations will be reflected as the last three operations of the progress objected returned by IMachine launchVMProcess as well See also IMachine saveState If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine already running e VBOX_E_HOST_ERROR Host interface does not exist or name not set e VBOX_E_FILE_ERROR Invalid saved state file 5 13 17 powerUpPaused IProgress IConsole powerUpPaused Identical to powerUp except that the VM will enter the Paused state instead of Running See also powerUpQ If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine already running e VBOX_E_HOST_ERROR Host interface does not exist or name not set e VBOX_E_FILE_ERROR Invalid saved state file 69 5 Classes interfaces 5 13 18 removeDiskEncryptionPassword void IConsole removeDiskEncryptionPassword in wstring id id The identifier used for the password Must match the identifier used when the encrypted medium was created Removes a password used for hard disk encryption decryption from the running VM As soon as the medium requiring this password is accessed the VM is paused with an error and the password must be provided again 5 13 19 removeSharedFolder void IConsole removeSharedFolder in wstring name name Logical name of the shar
437. r performing the actual update on the guest 392 13 Main API change log e A new event IGuestUserStateChangedEvent was introduced to provide guest user status updates to the host via event listeners To use this event there needs to be at least the 4 3 Guest Additions installed on the guest At the moment only the states Idle and InUse of the GuestUserState enumeration arei supported on Windows guests starting at Windows 2000 SP2 The attribute IGuestSession protocolVersion was added to provide a convenient way to lookup the guest session s protocol version it uses to communicate with the installed Guest Additions on the guest Older Guest Additions will set the protocol version to 1 whereas Guest Additions 4 3 will set the protocol version to 2 This might change in the future as new features arise IDisplay getScreenResolution has been extended to return the display position in the guest The IUSBController class is not a singleton of IMachine anymore but Machine contains a list of USB controllers present in the VM The USB device filter handling was moved to IUSBDeviceFilters 13 3 Incompatible API changes with version 4 2 e Guest control APIs for executing guest processes working with guest files or directories have been moved to the newly introduced IGuestSession interface which can be created by calling IGuest createSession A guest session will act as a guest user s impersonation so that the guest creden
438. r than deleting snapshots one by one and often also needs less extra disk space before freeing up disk space by deleting the removed disk images corresponding to the snapshot Note This API method is right now not implemented If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE The running virtual machine prevents deleting this snap shot This happens only in very specific situations usually snapshots can be deleted with out trouble while a VM is running The error message text explains the reason for the failure e E_NOTIMPL The method is not implemented yet 5 80 17 detachDevice void IMachine detachDevice in wstring name in long controllerPort in long device name Name of the storage controller to detach the medium from controllerPort Port number to detach the medium from 188 5 Classes interfaces device Device slot number to detach the medium from Detaches the device attached to a device slot of the specified bus Detaching the device from the virtual machine is deferred This means that the medium re mains associated with the machine when this method returns and gets actually de associated only after a successful saveSettings call See IMedium for more detailed information about attaching media Note You cannot detach a device from a running machine Note Detaching differencing media implicitly created by attachDevice for the
439. railerEncapsulation ARPCacheTimeout EthernetEncapsulation TCPDefaultTTL TCPKeepAlivelnterval TCPKeepAliveGarbage NetworkInformationServiceDomain NetworkInformationServiceServers NetworkTimeProtocolServers VendorSpecificInformation Option_44 Option_45 Option_46 Option_47 Option_48 Option_49 IPAddressLeaseTime Option_64 Option_65 TFTPServerName BootfileName Option_68 Option_69 Option_70 Option_71 Option_72 Option_73 Option_74 Option_75 Option_119 340 6 Enumerations enums 6 26 DhcpOptEncoding Legacy Hex 6 27 DirectoryCopyFlags Directory copying flags Note Not flags are implemented yet None No flag set CopylntoExisting Allow copying into an existing destination directory 6 28 DirectoryCreateFlag Directory creation flags None No flag set Parents No error if existing make parent directories as needed 6 29 DirectoryOpenFlag Directory open flags None No flag set NoSymlinks Don t allow symbolic links as part of the path 6 30 DirectoryRemoveRecFlag Directory recursive removement flags Note WARNING THE FLAGS ARE CURRENTLY IGNORED THE METHOD APPLIES ContentAndDir REGARDLESS OF THE INPUT None No flag set ContentAndDir Delete the content of the directory and the directory itself ContentOnly Only delete the content of the directory omit the directory it self 341 6 Enumerations enums 6 31 DnDAction Possible actions of
440. rc VbglHGCMConnect amp handle amp data if RT_SUCCESS rc rc data result if RT_SUCCESS rc Get the assigned client identifier ulClientID data u32ClientID DECLVBGL int VbglHGCMDisconnect VBGLHGCMHANDLE handle VBoxGuestHGCMDisconnectInfo xpData Disconnects from the service VBoxGuestHGCMDisconnectInfo data RtlZeroMemory amp data sizeof VBoxGuestHGCMDisconnectInfo data result data u32ClientID VINF_SUCCESS ulClientID rc VbglHGCMDisconnect handle data DECLVBGL int VbglHGCMCall VBGLHGCMHANDLE handle VBoxGuestHGCMCallInfo pData uint32_t cbData Calls a function in the service typedef struct _VBoxSFRead VBoxGuestHGCMCallInfo callInfo pointer in SHFLROOT Root handle of the mapping which name is queried HGCMFunctionParameter root value64 in SHFLHANDLE of object to read from HGCMFunctionParameter handle x value64 in Offset to read from HGCMFunctionParameter offset x value64 in out Bytes to read How many were read HGCMFunctionParameter cb 376 7 Host Guest Communication Manager pointer out Buffer to place data to HGCMFunctionParameter buffer VBoxSFRead Number of parameters define SHFL_CPARMS_READ 5 VBoxSFRead data The call information data calliInfo result VINF_SUCCESS Will be returned by HGCM data callInfo u32ClientID ul
441. rcentage of processor time spent in kernel mode as seen by the guest cpuldle Percentage of processor time spent idling as seen by the guest memTotal Total amount of physical guest RAM memFree Free amount of physical guest RAM memBalloon Amount of ballooned physical guest RAM memShared Amount of shared physical guest RAM memCache Total amount of guest disk cache memory pagedTotal Total amount of space in the page file memAllocTotal Total amount of memory allocated by the hypervisor memFreeTotal Total amount of free memory available in the hypervisor memBalloonTotal Total amount of memory ballooned by the hypervisor memSharedTotal Total amount of shared memory in the hypervisor vmNetRx Network receive rate for VM vmNetTx Network transmit rate for VM Passes statistics collected by VM including guest statistics to VBoxSVC 5 76 17 runUSBDeviceFilters void IInternalMachineControl runUSBDeviceFilters in IUSBDevice device out boolean matched out unsigned long maskedInterfaces device matched maskedinterfaces Asks the server to run USB devices filters of the associated machine against the given USB device and tell if there is a match Note Intended to be used only for remote USB devices Local ones don t require to call this method this is done implicitly by the Host and USBProxyService 5 76 18 unlockMedia void IInternalMachineControl unlockMedia Unlocks all media previously locked us
442. re implementation o e e 72 Protocol specificatiod cosido 44440808 24444445504 Tal Request lcd rr eb wo Boles eae deere GODNE ce bee wate a 2 bbe ow Bee eee der ale ee ae S Fido O a ha oka ceded ow A BO we ae Re Bee ee e 7 24 Calld2 and Call64 o occa eee ee bbe ee ee ee eS Tas CANEL ote yk e Bk ee es ES eR a we wa A A 7a Guest sottware interface 2 2400 62560 2a OSS Owed a 72 The guest driver interface oce soo 39 SOS ee ee a Toa Guest applicndon imterfa e lt u o oe e ee Ree ee ea ed 7 4 HGCM Service Implementation o e e RDP Web Control 8 1 RDPWeb features ee ee 8 2 RBRDPWebreference s bee hae Oe A Ed ROHS 8 2 1 RDPWebfunctions 0 0 0 0c eee ee eee eee 8 2 2 Embedding RDPWeb in an HTML page o 2 3 TDP WER Change l t oo ae ee a a a a Dol VERBAL al cr aa 4 he ee a dde 532 YesionLl LZb ocio 20444444844 aa Do rOn LL ee an aoe a E Drag and Drop Ol BASE TONES cian de de a e ie g2 S pp red formats aaa a Ba A se A 10 VirtualBox external authentication modules 11 Using Java API LLL Imiro ii a ee ao a a E aa 11 2 Requirements bs Ge EE EO Sob ee ee eS LA ESE a ek ek a A e A 12 License information 13 Main API change log 13 1 Incompatible API changes with version 5 0 o o 13 2 Incompatible API changes with version 4 3 o o 13 3 Incompatible API changes with version 4 2
443. rectoryCopyToGuest in wstring source in wstring destination in DirectoryCopyFlags flags source Path to the directory on the host side that should be copied to the guest Host path style destination Where to put the file in the guest Unless the DirectoryCopyFlags CopyIntoExisting flag is given the directory shall not already exist Guest style path 126 5 Classes interfaces flags Zero or more DirectoryCopyFlags values Recursively copies a directory from the host to the guest If this method fails the following error codes may be reported e E_NOTIMPL Not yet implemented 5 64 6 directoryCreate void IGuestSession directoryCreate in wstring path in unsigned long mode in DirectoryCreateFlag flags path Path to the directory directory to be created Guest path style mode The UNIX style access mode mask to create the directory with Whether how all three access groups and associated access rights are realized is guest OS dependent The API does the best it can on each OS flags Zero or more DirectoryCreateFlag flags Creates a directory in the guest If this method fails the following error codes may be reported e VBOX_E_IPRT_ERROR Error while creating the directory 5 64 7 directoryCreateTemp wstring IGuestSession directoryCreateTemp in wstring templateName in unsigned long mode in wstring path in boolean secure templateName Template for the name of the director
444. red folder already exists e VBOX_E_FILE_ERROR Shared folder hostPath not accessible 5 80 12 deleteConfig IProgress IMachine deleteConfig in IMedium media media List of media to be closed and whose storage files will be deleted 185 5 Classes interfaces Deletes the files associated with this machine from disk If medium objects are passed in with the aMedia argument they are closed and if closing was successful their storage files are deleted as well For convenience this array of media files can be the same as the one returned from a previous unregister call This method must only be called on machines which are either write locked i e on instances returned by ISession machine or on unregistered machines i e not yet registered machines created by IVirtualBox createMachine or opened by IVirtualBox openMachineO or after hav ing called unregister The following files will be deleted by this method e If unregister had been previously called with a cleanupMode argument other than Un registerOnly this will delete all saved state files that the machine had in use possibly one if the machine was in Saved state and one for each online snapshot that the machine had e On each medium object passed in the aMedia array this will call IMedium close If that succeeds this will attempt to delete the medium s storage on disk Since the IMedium closeQ call will fail if the medium is still in u
445. resents one impersonated user account in the guest so every operation will use the same credentials specified when creating the session object via createSession Anonymous sessions that is sessions without specifying a valid user account in the guest are not allowed reasons of security There can be a maximum of 32 sessions at once per VM An error will be returned if this has been reached For more information please consult IGuestSession 5 38 3 findSession IGuestSession IGuest findSession in wstring sessionName sessionName The session s friendly name to find Wildcards like and are allowed Finds guest sessions by their friendly name and returns an interface array with all found guest sessions 5 38 4 getAdditionsStatus boolean IGuest getAdditionsStatus in AdditionsRunLevelType level level Status level to check Retrieve the current status of a certain Guest Additions run level If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED Wrong status level specified 108 5 Classes interfaces 5 38 5 getFacilityStatus AdditionsFacilityStatus IGuest getFacilityStatus in AdditionsFacilityType facility out long long timestamp facility Facility to check status for timestamp Timestamp in ms of last status update seen by the host Get the current status of a Guest Additions facility 5 38 6 internalGetStatistics void IGuest internalGetStatistics
446. ress in wstring name name Address of the USB device as assigned by the host to search for Searches for a USB device with the given host address See also IUSBDevice address If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any USB device 5 69 10 findUSBDeviceByld IHostUSBDevice IHost findUSBDeviceById in uuid id id UUID of the USB device to search for Searches for a USB device with the given UUID See also IUSBDevice id If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND Given id does not correspond to any USB device 5 69 11 generateMACAddress wstring IHost generateMACAddress Generates a valid Ethernet MAC address 12 hexadecimal characters 5 69 12 getProcessorCPUIDLeaf void IHost getProcessorCPUIDLeaf in unsigned long cpuld in unsigned long leaf in unsigned long subLeaf out unsigned long valEax out unsigned long valEbx out unsigned long valEcx out unsigned long valEdx cpuld Identifier of the CPU The CPU most be online Note The current implementation might not necessarily return the description for this exact CPU 145 5 Classes interfaces leaf CPUID leaf index eax subLeaf CPUID leaf sub index ecx This currently only applies to cache information on Intel CPUs Use 0 if retrieving values for IMachine setCPUIDLeaf
447. rget Note This interface extends IDnDTarget and therefore supports all its methods and attributes as well Implementation of the IDnDTarget object for target drag n drop operations on the guest 5 41 1 Attributes 5 41 1 1 midIDoesNotLikeEmptyInterfaces read only boolean IGuestDnDTarget midl DoesNotLikeEmptyInterfaces 5 42 IGuestFile IFile Note This interface extends IFile and therefore supports all its methods and attributes as well Implementation of the IFile object for files in the guest 111 5 Classes interfaces 5 42 1 Attributes 5 42 1 1 midIDoesNotLikeEmptyInterfaces read only boolean IGuestFile midlDoesNotLikeEmptyInterfaces 5 43 IGuestFileEvent IGuestSessionEvent Note This interface extends IGuestSessionEvent and therefore supports all its methods and attributes as well Base abstract interface for all guest file events 5 43 1 Attributes 5 43 1 1 file read only IGuestFile IGuestFileEvent file Guest file object which is related to this event 5 44 IGuestFilelOEvent IGuestFileEvent Note This interface extends IGuestFileEvent and therefore supports all its methods and attributes as well Base abstract interface for all guest file input output IO events 5 44 1 Attributes 5 44 1 1 offset read only long long IGuestFilel0Event offset Current offset in bytes 5 44 1 2 processed read only unsigned long IGuestFile
448. rial ports changes Interested callees should use ISerialPort methods and attributes to find out what has changed 5 119 1 Attributes 5 119 1 1 serialPort read only ISerialPort ISerialPortChangedEvent serialPort Serial port that is subject to change 5 120 ISession The ISession interface represents a client process and allows for locking virtual machines repre sented by IMachine objects to prevent conflicting changes to the machine Any caller wishing to manipulate a virtual machine needs to create a session object first which lives in its own process space Such session objects are then associated with IMachine objects living in the VirtualBox server process to coordinate such changes There are two typical scenarios in which sessions are used e To alter machine settings or control a running virtual machine one needs to lock a machine for a given session client process by calling IMachine lockMachine Whereas multiple sessions may control a running virtual machine only one process can obtain a write lock on the machine to prevent conflicting changes A write lock is also needed if a process wants to actually run a virtual machine in its own context such as the VirtualBox GUI or VBoxHeadless front ends They must also lock a machine for their own sessions before they are allowed to power up the virtual machine As a result no machine settings can be altered while another process is already using it either because that p
449. ring patterns out wstring keys out wstring values out long long timestamps out wstring flags patterns The patterns to match the properties against as a comma separated string If this is empty all properties currently set will be returned keys The key names of the properties returned values The values of the properties returned The array entries match the corresponding entries in the key array timestamps The time stamps of the properties returned The array entries match the corre sponding entries in the key array flags The flags of the properties returned The array entries match the corresponding entries in the key array Return a list of the guest properties matching a set of patterns along with their values time stamps and flags If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open e VBOX_E_INVALID_OBJECT_STATE Session type is not direct 5 77 7 onBandwidthGroupChange void IInternalSessionControl onBandwidthGroupChange in IBandwidthGroup bandwidthGroup bandwidthGroup The bandwidth group which changed Notification when one of the bandwidth groups change 5 77 8 onCPUChange void IInternalSessionControl onCPUChange in unsigned long cpu in boolean add cpu The CPU which changed add Flag whether the CPU was added or removed Notification when a CPU changes 5 77 9 onCPUExecutionCapChange void IInter
450. ription header The generic HGCM request header with type equal to either VMMDevReq_HGCMCall32 62 or VUMDevReq_HGCMCall64 63 clien The client identifier previously returned by the connect request 32 bit tld func The function code to be processed by the service 32 bit tion cParms The number of following parameters 32 bit This value is O if the function requires no parameters parms An array of parameter description structures HGCMFunctionParameter32 or HGCMFunctionParameter64 The 32 bit parameter description HGCMFunctionParameter32 consists of 32 bit type field and 8 bytes of an opaque value so 12 bytes in total The 64 bit variant HGCMFunctionParame ter64 consists of the type and 12 bytes of a value so 16 bytes in total 374 7 Host Guest Communication Manager Type Format of the value VMMDevHGCMParm A 32 bit value Type_32bit 1 VMMDevHGCMParm A 64 bit value Type_64bit 2 VMMDevHGCMParm A 32 bit size followed by a 32 bit or 64 bit guest physical Type_PhysAddr address 3 VMMDevHGCMParm A 32 bit size followed by a 32 bit or 64 bit guest linear address Type_LinAddr The buffer is used both for guest to host and for host to guest 4 data VMMDevHGCMParm Same as VMMDevHGCMParmType_LinAddr but the buffer is Type _LinAddr_ In used only for host to guest data 5 VMMDevHGCMParm Same as VMMDevHGCMParmType_LinAd
451. rkMask Returns the network mask of the interface 5 71 1 8 IPV6Supported read only boolean IHostNetworkInterface IPV6Supported Specifies whether the IP V6 is supported enabled for the interface 5 71 1 9 IPV6Address read only wstring IHostNetworkInterface IPV6Address Returns the IP V6 address of the interface 5 71 1 10 IPV6NetworkMaskPrefixLength read only unsigned long IHostNetworkInterface IPV6NetworkMaskPrefixLength Returns the length IP V6 network mask prefix of the interface 5 71 1 11 hardwareAddress read only wstring IHostNetworkInterface hardwareAddress Returns the hardware address For Ethernet it is MAC address 5 71 1 12 mediumType read only HostNetworkInterfaceMediumType IHostNetworkInterface mediumType Type of protocol encapsulation used 5 71 1 13 status read only HostNetworkInterfaceStatus IHostNetworkInterface status Status of the interface 5 71 1 14 interfaceType read only HostNetworkInterfaceType IHostNetworkInterface interfaceType specifies the host interface type 5 71 2 DHCPRediscover void IHostNetworkInterface DHCPRediscover refreshes the IP configuration for DHCP enabled interface 5 71 3 enableDynamiclPConfig void IHostNetworkInterface enableDynamicIPConfig enables the dynamic IP configuration 149 5 Classes interfaces 5 71 4 enableStaticlIPConfig void IHostNetworkInterface enableStaticIPConfig in wstring IPAddr
452. rmanent settings changes will trigger an event and only temporary settings changes for running VMs will trigger an event Note sending events for temporary changes is NOT IMPLEMENTED 5 82 IMachineDebugger 5 82 1 Attributes 5 82 1 1 singleStep read write boolean IMachineDebugger singleStep Switch for enabling single stepping 5 82 1 2 recompileUser read write boolean IMachineDebugger recompileUser Switch for forcing code recompilation for user mode code 214 5 Classes interfaces 5 82 1 3 recompileSupervisor read write boolean IMachineDebugger recompileSupervisor Switch for forcing code recompilation for supervisor mode code 5 82 1 4 executeAllInIEM read write boolean IMachineDebugger executeALLInIEM Whether to execute all the code in the instruction interpreter This is mainly for testing the interpreter and not an execution mode intended for general consumption 5 82 1 5 PATMEnabled read write boolean IMachineDebugger PATMEnabled Switch for enabling and disabling the PATM component 5 82 1 6 CSAMEnabled read write boolean IMachineDebugger CSAMEnabled Switch for enabling and disabling the CSAM component 5 82 1 7 logEnabled read write boolean IMachineDebugger LogEnabled Switch for enabling and disabling the debug logger 5 82 1 8 logDbgFlags read only wstring IMachineDebugger LogDbgFlags The debug logger flags 5 82 1 9 logDbgGroups read only wstring IMachineDebugger
453. rocess is modifying machine settings or because the machine is running 281 5 Classes interfaces e To start a VM using one of the existing VirtualBox front ends e g the VirtualBox GUI or VBoxHeadless one would use I Machine launchVMProcess which also takes a session object as its first parameter This session then identifies the caller and lets the caller control the started machine for example pause machine execution or power it down as well as be notified about machine execution state changes How sessions objects are created in a client process depends on whether you use the Main API via COM or via the webservice e When using the COM API directly an object of the Session class from the VirtualBox type library needs to be created In regular COM C client code this can be done by calling createLocal0bject a standard COM API This object will then act as a local session object in further calls to open a session e In the webservice the session manager IWebsessionManager instead creates a session ob ject automatically whenever IWebsessionManager logon is called A managed object ref erence to that session object can be retrieved by calling IWebsessionManager getSessionObject 5 120 1 Attributes 5 120 1 1 state read only SessionState ISession state Current state of this session 5 120 1 2 type read only SessionType ISession type Type of this session The value of this attribute is valid only if t
454. ror id error Triggered when a request to release the USB device as a result of machine termination or direct call to IConsole detachUSBDevice has completed A nullerror object means success otherwise it describes a failure If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 5 77 23 onVRDEServerChange void IInternalSessionControl onVRDEServerChange in boolean restart restart Flag whether the server must be restarted Triggered when settings of the VRDE server object of the associated virtual machine have changed If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation e VBOX_E_INVALID_OBJECT_STATE Session type prevents operation 5 77 24 onVideoCaptureChange void IInternalSessionControl onVideoCaptureChange Triggered when video capture settings have changed 5 77 25 onlineMergeMedium void IInternalSessionControl onlineMergeMedium in IMediumAttachment mediumAttachment in unsigned long sourceldx in unsigned long targetldx in IProgress progress mediumAttachment The medium attachment to identify the medium chain sourceldx The index of the source image in the chain Redundant but drastically reduces IPC targetldx The index of the target image in the chain Redundant but drastically reduc
455. roto Protocol handled with the rule hostIP IP of the host interface to which the rule should apply An empty ip address is acceptable in which case the NAT engine binds the handling socket to any interface hostPort The port number to listen on guestIP The IP address of the guest which the NAT engine will forward matching packets to An empty IP address is not acceptable guestPort The port number to forward 5 98 4 removePortForwardRule void INATNetwork removePortForwardRule in boolean iSipv6 in wstring ruleName iSipv6 ruleName 5 98 5 start void INATNetwork start in wstring trunkType trunkType Type of internal network trunk 5 98 6 stop void INATNetwork stop 257 5 Classes interfaces 5 99 INATNetworkAlterEvent INATNetworkChangedE vent Note This interface extends INATNetworkChangedEvent and therefore supports all its methods and attributes as well 5 99 1 Attributes 5 99 1 1 midlDoesNotLikeEmptyInterfaces read only boolean INATNetworkAlterEvent midlDoesNotLikeEmptyInterfaces 5 100 INATNetworkChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well 5 100 1 Attributes 5 100 1 1 networkName read only wstring INATNetworkChangedEvent networkName 5 101 INATNetworkCreationDeletionEvent INATNetworkAlterEvent Note This interface extends INATNetworkAlterEvent and therefore supp
456. rted attribute as a result the FramebufferAcceleration0peration enum was no longer needed and removed as well the solidFill method the copyScreenBits method In the Display interface the following were removed the setupInternalFramebuffer method the lockFramebuffer method the unlockFramebuffer method the registerExternalFramebuffer method 13 9 Incompatible API changes with version 2 2 Added explicit version number into JAX WS Java package names such as org virtualbox_2_2 allowing connect to multiple VirtualBox clients from single Java application The interfaces having a 2 suffix attached to them with version 2 1 were renamed again to have that suffix removed This time around this change involves only the name there are no functional differences As a result IDVDImage2 is now IDVDImage IHardDisk2 is now IHardDisk IHard Disk2Attachment is now IHardDiskAttachment Consequentially all related methods and attributes that had a 2 suffix have been re named for example IMachine attachHardDisk2 now becomes IMachine attachHardDisk IVirtualBox openHardDisk has an extra parameter for opening a disk read write or read only The remaining collections were replaced by more performant safe arrays This affects the following collections IGuestOSTypeCollection IHostDVDDriveCollection 401 13 Main API change log IHostFloppyDriveCollection I
457. rue request is completed the VM process will get a IInternalSessionControl onUSBDeviceDetach notification Note In the done true case the server must run its own filters and filters of all VMs but this one on the detached device as if it were just attached to the host computer 5 76 8 ejectMedium IMediumAttachment IInternalMachineControl ejectMedium in IMediumAttachment attachment attachment The medium attachment where the eject happened Tells VBoxSVC that the guest has ejected the medium associated with the medium attachment 153 5 Classes interfaces 5 76 9 endPowerUp void IInternalMachineControl endPowerUp in long result result Tells VBoxSVC that IConsole powerUp has completed This method may query status infor mation from the progress object it received in beginPowerUp and copy it over to any in progress IMachine launchVMProcess call in order to complete that progress object 5 76 10 endPoweringDown void IInternalMachineControl endPoweringDown in long result in wstring errMsg result S_OK to indicate success errMsg human readable error message in case of failure Called by the VM process to inform the server that powering down previously requested by beginPoweringDown is either successfully finished or there was a failure If this method fails the following error codes may be reported e VBOX_E_FILE_ERROR Settings file not accessible e VBOX_E_XML_ERROR
458. rvice open a second terminal and change to the directory where the VirtualBox executables are located Then type vboxwebsrv v The web service now waits for connections and will run until you press Ctrl C in this second terminal The v argument causes it to log all connections to the terminal See chapter 1 4 Running the web service page 24 for details on how to run the web service 3 Back in the first terminal and still in the samples directory to start a simple client example just type make runl6 if you re on a Java 6 system on a Java 5 system run make run15 instead This should work on all Unix like systems such as Linux and Solaris For Windows systems use commands similar to what is used in the Makefile This will compile the clienttest java code on the first call and then execute the resulting clienttest class to show the locally installed VMs see below The clienttest sample imitates a few typical command line tasks that VBoxManage VirtualBox s regular command line front end would provide see the VirtualBox User Manual for details In particular you can run e java clienttest show vms show the virtual machines that are registered locally e java clienttest list hostinfo show various information about the host this VirtualBox installation runs on e java clienttest startvm lt vmname uuid gt start the given virtual machine The clienttest java sample code illustrates common basic practices how to us
459. s snapshots disks etc switched from GUIDs to strings now still having string representation of GUIDs inside As a result no particular internal struc ture can be assumed for object identifiers instead they should be treated as opaque unique handles This change mostly affects Java and C programs for other languages GUIDs are transparently converted to strings 400 13 Main API change log The uses of NULL strings have been changed greatly All out parameters now use empty strings to signal a null value For in parameters both the old NULL and empty string is allowed This change was necessary to support more client bindings especially using the web service API Many of them either have no special NULL value or have trouble dealing with it correctly in the respective library code Accidentally the TSBool interface still appeared in 3 0 0 and was removed in 3 0 2 This is an SDK bug do not use the SDK for VirtualBox 3 0 0 for developing clients The type of IVirtualBoxErrorInfo resultCode changed from result to long The parameter list of IVirtualBox openHardDisk was changed The method IConsole discardSavedState was renamed to IConsole forgetSavedState and a parameter was added The method IConsole powerDownAsync was renamed to IConsole powerDown and the previous method with that name was deleted So effectively a parameter was added In the Framebuffer interface the following were removed the operationSuppo
460. s a subset of the functionality of VirtualBox openMedium The use of acronyms in API enumeration interface attribute and method names has been made much more consistent previously they sometimes were lowercase and sometimes mixed case They are now consistently all caps 394 13 Main API change log Old name New name PointingHidType PointingHIDType KeyboardHidType KeyboardHIDType IPciAddress IPCIAddress IPciDeviceAttachment IPCIDeviceAttachment IMachine pointingHidType IMachine pointingHIDType IMachine keyboardHidType IMachine keyboardHIDType IMachine hpetEnabled IMachine HPETEnabled IMachine sessionPid IMachine sessionPID IMachine i0CacheEnabled IMachine IOCacheEnabled IMachine ioCacheSize IMachine IOCacheSize IMachine pciDeviceAssignments IMachine PCIDeviceAssignments IMachine attachHostPciDevice IMachine attachHostPCIDevice IMachine detachHostPciDevice IMachine detachHostPCIDevice IConsole attachedPciDevices IConsole attachedPCIDevices IHostNetworkInterface dhcpEnabled IHostNetworkInterface DHCPEnabled THostNetworkInterface enableStaticIpConfigO THostNetworkInterface enableStaticIPConfig IHostNetworkInterface enableStaticIpConfigV60 THostNetworkInterface enableStaticIPConfigV6 IHostNetworkInterface enableDynamicIpConfig IHostNetworkInterface enableDynamic
461. s all existing objects If metric name array contains a single element and object array contains many the single metric name array element is applied to each object array element to form metric object pairs 5 112 4 getMetrics IPerformanceMetric IPerformanceCollector getMetrics in wstring metricNames in unknown objects metricNames Metric name filter Currently only a comma separated list of metrics is supported objects Set of objects to return metric parameters for Returns parameters of specified metrics for a set of objects Note Null metrics array means all metrics Null object array means all existing objects 5 112 5 queryMetricsData long IPerformanceCollector queryMetricsData in wstring metricNames in unknown objects out wstring returnMetricNames out unknown returnObjects out wstring returnUnits out unsigned long returnScales out unsigned long returnSequenceNumbers out unsigned long returnDatalndices out unsigned long returnDataLengths metricNames Metric name filter Comma separated list of metrics with wildcard support objects Set of objects to query metrics for returnMetricNames Names of metrics returned in returnData returnObjects Objects associated with metrics returned in returnData returnUnits Units of measurement for each returned metric 269 5 Classes interfaces returnScales Divisor that should be applied to
462. s applied to each object array element to form metric object pairs Note Data collection continues behind the scenes after call to queryMetricsData The return data can be seen as the snapshot of the current state at the time of queryMetricsData call The internally kept metric values are not cleared by the call This allows querying different subsets of metrics or aggregates with subsequent calls If periodic querying is needed it is highly suggested to query the values with interval count period to avoid confusion This way a completely new set of data values will be provided by each query 5 112 6 setupMetrics IPerformanceMetric IPerformanceCollector setupMetrics in wstring metricNames in unknown objects in unsigned long period in unsigned long count metricNames Metric name filter Comma separated list of metrics with wildcard support objects Set of objects to setup metric parameters for period Time interval in seconds between two consecutive samples of performance data count Number of samples to retain in performance data history Older samples get discarded 270 5 Classes interfaces Sets parameters of specified base metrics for a set of objects Returns an array of IPerformanceMetric describing the metrics have been affected Note Null or empty metric name array means all metrics Null or empty object array means all existing objects If metric name array contains a single ele
463. s medium through the VirtualBox API not a physical file system lock of the underlying storage unit If this method fails the following error codes may be reported e VBOX_E_INVALID_OBJECT_STATE Invalid medium state e g not created locked inac cessible creating deleting 5 87 17 mergeTo IProgress IMedium mergeTo in IMedium target target Target medium Starts merging the contents of this medium and all intermediate differencing media in the chain to the given target medium The target medium must be either a descendant of this medium or its ancestor otherwise this method will immediately return a failure It follows that there are two logical directions of the merge operation from ancestor to descendant forward merge and from descendant to ancestor backward merge Let us consider the following medium chain Base lt Diff_1 lt Diff_2 Here calling this method on the Base medium object with Diff_2 as an argument will be a forward merge calling it on Diff_2 with Base as an argument will be a backward merge Note that in both cases the contents of the resulting medium will be the same the only difference is the medium object that takes the result of the merge operation In case of the forward merge in the above example the result will be written to Diff_2 in case of the backward merge the result will be written to Base In other words the result of the operation is always stored in the target medium Upon su
464. s not support the session base envi ronment feature Support for this was introduced with protocol version XXXX e VBOX_E_INVALID_OBJECT_STATE If the guest additions has yet to report the session base environment 129 5 Classes interfaces 5 64 13 environmentGetBaseVariable wstring IGuestSession environmentGetBaseVariable in wstring name name Name of the environment variable to get This cannot be empty nor can it contain any equal signs Gets an environment variable from the session s base environment environmentBase If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED If the guest additions does not support the session base envi ronment feature Support for this was introduced with protocol version XXXX e VBOX_E_INVALID_OBJECT_STATE If the guest additions has yet to report the session base environment 5 64 14 environmentScheduleSet void IGuestSession environmentScheduleSet in wstring name in wstring value name Name of the environment variable to set This cannot be empty nor can it contain any equal signs value Value to set the session environment variable to Schedules setting an environment variable when creating the next guest process This affects the environmentChanges attribute 5 64 15 environmentScheduleUnset void IGuestSession environmentScheduleUnset in wstring name name Name of the environment variable to unset This cannot be
465. s receiving TCP window in bytes when establishing a new TCP connection Sets network configuration of the NAT engine 5 98 INATNetwork 5 98 1 Attributes 5 98 1 1 networkName read write wstring INATNetwork networkName TBD the idea technically we can start any number of the NAT networks but we should expect that at some point we will get collisions because of port forwanding rules so perhaps we should support only single instance of NAT network 5 98 1 2 enabled read write boolean INATNetwork enabled 5 98 1 3 network read write wstring INATNetwork network This is CIDR IPv4 string Specifying it user defines IPv4 addresses of gateway low address 1 and DHCP server low address 2 Note If there are defined IPv4 port forward rules update of network will be ignored because new assignment could break existing rules 255 5 Classes interfaces 5 98 1 4 gateway read only wstring INATNetwork gateway This attribute is read only It s recalculated on changing network attribute low address of network 1 5 98 1 5 IPv6Enabled read write boolean INATNetwork IPv6Enabled This attribute define whether gateway will support IPv6 or not 5 98 1 6 IPv6Prefix read write wstring INATNetwork IPv6Prefix This a CIDR IPv6 defining prefix for link local addresses autoconfiguration within network Note ignored if attribute IPv6Enabled is false 5 98 1 7 advertiseDefaultIPv6RouteEnabled r
466. s snapshot will be merged with the contents of their dependent child media to keep the medium chain valid in other words all changes represented by media being deleted will be propagated to their child medium After that this snapshot s differencing medium will be deleted The parent of this snapshot will become a new parent for all its child snapshots If the deleted snapshot is the current one its parent snapshot will become a new current snapshot The current machine state is not directly affected in this case except that currently attached differencing media based on media of the deleted snapshot will be also merged as described above If the deleted snapshot is the first or current snapshot then the respective Machine attributes will be adjusted Deleting the current snapshot will also implicitly call saveSettings to make all current machine settings permanent Deleting a snapshot has the following preconditions e Child media of all normal media of the deleted snapshot must be accessible see IMedium state for this operation to succeed If only one running VM refers to all images which participates in merging the operation can be performed while the VM is running Otherwise all virtual machines whose media are directly or indirectly based on the media of deleted snapshot must be powered off In any case online snapshot deleting usually is slower than the same operation without any running VM e You cannot delete the snapshot if a
467. s we eee es ected te A 300 Ble UBB oea a a A eae tanh ean aa 300 BAS A ANDES cae Skok a aw e we Ae ok a eee a 300 5 140 IUSBDeviceFilter occa oee kk ee ed as dae wee oe e Baas 302 5 140 1 PRUSIA e eo 303 5 141 IUSBDeviceFilters so occi dtto e recep ee bee ee Eee RRS 304 VALU ARIAS sc la els A ede eel we es 304 5 1412 oreateDeviceiligt ocv su ee a PS Ee ee ea ae ae 305 5 141 3 insertDeviceFiltet sw e ae ae WOR we a 305 5 141 4 removeDeviceFilter 2 ee 305 5 142 IUSBDeviceStateChangedEvent IEvent o 000 ce eee eae 306 By ae a e tS soe o A Awa Bao ow eee oe Be a A 306 5 143 IVBoxSVCAvailabilityChangedEvent IEvent o aa 306 SEL AMBITE ooe s a a A eae eS 306 5 144 IVESExplorer 2 ee ee eee aaa a a a ae 307 A o gh eras GS OO Ge 307 M OE dis BR a a 307 SITES A o cece ie es ol ek a es we ww east a es a HR ew RS 307 SILA ONNVLSE o oa RE RR OE eS DERN BEER oe oS RRS 307 SIES ORN ois ce cece eh bee a ge Bee we ae ee Remo ard ee ale eee 308 15 Contents SHAO V IS cia ack Ae a we ew I we we ws SRR ee ee 308 S1447 update ica aras A et eS 308 3 1459 INRDESCIVET o o os a A e dea 308 5 145 1 Attributes o sc 4 644 6288S oa A 308 5 145 23 get VRDEPrOpEry eo rosaa apaa we Se ee a ee e 309 los SANRDEPTOPET o i i i bce go EE ie eerie ews eee ea 309 5 146 IVRDEServerChangedEvent Event lt 309 S1461 AMIDES 22 he Khe wea DDE OOS Code EE EE Eo moe 310 5 147 IVRDEServerinio ccc ese nk AA AAA
468. scee a ee ee Oe waea 341 G28 DiteciorGresterlag coca BSG 4 ad ee BO 341 6 29 DireetoryOpenblag o ce nea idd esera do ee eee ee ae Saas 341 6 30 DirectoryRemoyeRecFlag 2 4454 24 S44 SG Bae Dedede daa aS 341 GSL DEIDSCUIOR 4 6 4 4 6 2 amp aoe ses aha eee ea ds RS 342 632 DiDiMode 224 4604555444 22 be S49S 4454444424000 44544 342 Gas EPOPS ae eee a ee we EE a we a eee Ge ee ee 342 634 FaultToleranceState ina 544044 a8 SS eee weer ee Baas 342 A iii on hos See we ew we ood ew TE ay Ge a ee 343 6 36 EleCopvElSg sco oponerse Sod deed ee ee Oe ee eed 343 A oeae ea aes SSG A 344 6 38 PileOpenExPlacs on a ae eR a Ew EY See SH aes 344 6 39 PileSeekQMeit ogc e aoe e a a de da 344 6 40 FileSharingMode c20ooocccessros sana aa es 344 GAL FileSfatus ccoo a ads 345 OAA in A Qo GG Mea ee ee ae ee 345 17 6 43 6 44 6 45 6 46 6 47 6 48 6 49 6 50 6 51 6 52 6 53 6 54 635 6 56 6 57 6 58 6 59 6 60 6 61 6 62 6 63 6 64 6 65 6 66 6 67 6 68 6 69 6 70 6 71 6 72 6 73 6 74 6 75 6 76 6 77 6 78 6 79 6 80 6 81 6 82 6 83 6 84 6 85 6 86 6 87 6 88 6 89 6 90 6 91 6 92 6 93 6 94 6 95 Contents PramebulerCapabllles lt lt 02 2 Pe ww ERE OPE a 345 EsSObDiMovePla8s o e a 4 a SS ae retira RR 345 FPsObjRemamePlag o i e e e p a eh ae ee oa ee de 346 ESOBIO PE es eocena osa naaa SASSER ESE iaa 346 GraphmiesContraller Type nidos se He wee la 346 GuestMonitorChangedEventType o o e 346 GOmESTNOUIOFS
469. se e g because it is still attached to a second machine in that case the storage will not be deleted e Finally the machine s own XML file will be deleted Since deleting large disk image files can be a time consuming I O operation this method oper ates asynchronously and returns an IProgress object to allow the caller to monitor the progress There will be one sub operation for each file that is being deleted saved state or medium storage file Note settingsModified will return true after this method successfully returns If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine is registered but not write locked e VBOX_E_IPRT_ERROR Could not delete the settings file 5 80 13 deleteGuestProperty void IMachine deleteGuestProperty in wstring name name The name of the property to delete Deletes an entry from the machine s guest property store If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open 5 80 14 deleteSnapshot IProgress IMachine deleteSnapshot in uuid id id UUID of the snapshot to delete 186 5 Classes interfaces Starts deleting the specified snapshot asynchronously See ISnapshot for an introduction to snapshots The execution state and settings of the associated machine stored in the snapshot will be deleted The contents of all differencing media of thi
470. se hard disk B vdi is at tached the second column shows the machine after this hard disk is attached Constructs like D1 gt B vdi and similar mean that the hard disk that is actually attached to the machine is a differencing hard disk D1 vdi which is linked to based on another hard disk B vdi As we can see from the example the hard disk B vdi was detached from the machine before taking Snapshot 4 Later after Snapshot 4 was taken the user decides to attach B vdi again B vdi has dependent child hard disks D1 vdi D2 vdi therefore it cannot be attached directly 241 5 Classes interfaces and needs an indirect attachment i e implicit creation of a new differencing hard disk Due to the smart attachment procedure the new differencing hard disk D3 vdi will be based on D2 vdi not on B vdi itself since D2 vdi is the most recent view of B vdi existing for this snapshot branch of the given virtual machine Note that if there is more than one descendant hard disk of the given base hard disk found in a snapshot and there is an exact device channel and bus match then this exact match will be used Otherwise the youngest descendant will be picked up There is one more important aspect of the smart attachment procedure which is not related to snapshots at all Before walking through the snapshots as described above the backup copy of the current list of hard disk attachment is searched for descendants This backup copy is created wh
471. se hard disks they are attached directly if they do not have children and are not attached to virtual machines in snapshots and indirectly otherwise Note that the smart attachment procedure is never performed for differencing hard disks Immutable hard disks are always attached indirectly because they are designed to be non writable If an immutable hard disk is attached to a virtual machine with snapshots then a special procedure called smart attachment is performed see below Writethrough hard disks are always attached directly also as designed This also means that writethrough hard disks cannot have other hard disks linked to them at all Shareable hard disks are always attached directly also as designed This also means that shareable hard disks cannot have other hard disks linked to them at all They behave almost like writethrough hard disks except that shareable hard disks can be attached to several virtual machines which are running allowing concurrent accesses You need special cluster software running in the virtual machines to make use of such disks 240 5 Classes interfaces Note that the same hard disk regardless of its type may be attached to more than one virtual machine at a time In this case the machine that is started first gains exclusive access to the hard disk and attempts to start other machines having this hard disk attached will fail until the first machine is powered down Detaching hard disks is perfor
472. seconds for events processing them immediately as they arrive It achieves better runtime behavior than separate sleeping processing 386 12 License information The sample code files shipped with the SDK are generally licensed liberally to make it easy for anyone to use this code for their own application code The Java files under bindings webservice java jax ws library files for the object oriented web service are by contrast licensed under the GNU Lesser General Public License LGPL V2 1 See sdk bindings webservice java jax ws src COPYING LIB for the full text of the LGPL 2 1 When in doubt please refer to the individual source code files shipped with this SDK 387 13 Main API change log Generally VirtualBox will maintain API compatibility within a major release a major release occurs when the first or the second of the three version components of VirtualBox change that is in the x y z scheme a major release is one where x or y change but not when only z changes In other words updates like those from 2 0 0 to 2 0 2 will not come with API breakages Migration between major releases most likely will lead to API breakage so please make sure you updated code accordingly The OOWS Java wrappers enforce that mechanism by putting VirtualBox classes into version specific packages such as org virtualbox_2_2 This approach allows for connecting to multiple VirtualBox versions simultaneously from the same Java appli cation
473. served field 1 reserved2 A reserved field 2 flags HGCM flags set by the VMM device result The HGCM result code set by the VMM device 372 7 Host Guest Communication Manager Note e All fields are 32 bit e Fields from size to reserved2 are a standard VMM device request header which is used for other interfaces as well The type field indicates the type of the HGCM request Name decimal value Description VMMDevReq_HGCMConnect Connect to a HGCM service 60 VMMDe Disconnect from the service vReq_HGCMDisconnect 61 VMMDevReg_HGCMCall32 Call a HGCM function using the 32 bit interface 62 VMMDevReg_HGCMCall64 Call a HGCM function using the 64 bit interface 63 VMMDevReg_HGCMCancel Cancel a HGCM request currently being processed by a host 64 HGCM service The flags field may contain Name hexadecimal value Description VBOX_HGCM_REQ_DONE 0x00000001 The request has been processed by the host service VBOX_HGCM_REQ_CANCELLED This request was cancelled 0x00000002 7 2 2 Connect The connection request must be issued by the guest HGCM client before it can call the HGCM service VMMDevHGCMConnect Name Description header The generic HGCM request header with type equal to VMMDevReq_HGCMConnect 60 type The type of the service location information 32 bit loca The serv
474. ses are gone and will have replace ments that use IHardDisk2 IDVDImage2 and IFloppyImage2 see for example IMa chine attachHardDisk2 In particular the IVirtualBox hardDisks2 array replaces the earlier IVirtual Box hardDisks collection IGuestOSType was extended to group operating systems into families and for 64 bit sup port The IHostNetworkInterface interface was completely rewritten to account for the changes in how Host Interface Networking is now implemented in VirtualBox 2 1 The IVirtualBox machines2 array replaces the former IVirtualBox machines collection Added IHost getProcessorFeature and ProcessorFeature enumeration The parameter list for IVirtualBox createMachine was modified Added IMachine pushGuestProperty New attributes in Machine accelerate3DEnabled HWVirtExVPIDEnabled IMachine guestPropertyNotifi CPUCount Added IConsole powerUpPaused and IConsole getGuestEnteredACPIMode Removed ResourceUsage enumeration 403
475. sh the minimum possible integer is assumed if n is omitted after a dash the maximum possible integer is assumed Boolean filters Used to specify acceptable values for boolean device attributes The format of the string is true false yes no 0 1 e Exact match Used to specify a single value for the given device attribute Any string that doesn t start with int represents the exact match String device attributes are compared to this string including case of symbols Integer attributes are first converted to a string see individual filter attributes and then compared ignoring case e Any match Any value of the corresponding device attribute will match the given filter An empty or null string is used to construct this type of filtering expressions 302 5 Classes interfaces Note On the Windows host platform interval filters are not currently available Also all string filter attributes manufacturer product serialNumber are ignored so they behave as any match no matter what string expression is specified See also IUSBDeviceFilters deviceFilters IHostUSBDeviceFilter 5 140 1 Attributes 5 140 1 1 name read write wstring IUSBDeviceFilter name Visible name for this filter This name is used to visually distinguish one filter from another so it can neither be null nor an empty string 5 140 1 2 active read write boolean IUSBDeviceFilter active Whether this filter active or has been t
476. side one variable The attribute IMedium logicalSize now returns the logical size of exactly this medium object whether it is a base or diff image The old behavior was no longer acceptable as each image can have a different capacity Guest control APIs such as IGuest IGuestSession IGuestProcess and so on now emit own events to provide clients much finer control and the ability to write own frontends for guest operations The event IGuestSessionEvent acts as an abstract base class for all guest control events Certain guest events contain a IVirtualBoxErrorInfo member to provide more information in case of an error happened on the guest side Guest control sessions on the guest started by IGuest createSession now are dedicated guest processes to provide more safety and performance for certain operations Also the IGuest createSession call does not wait for the guest session being created anymore due to the dedicated guest session processes just mentioned This also will enable webservice clients to handle guest session creation more gracefully To wait for a guest session being started use the newly added attribute IGuestSession status to query the current guest session status The IGuestFile APIs are now implemented to provide native guest file access from the host The parameter list for IMedium updateGuestAdditions was modified It now supports specifying optional command line arguments for the Guest Additions installe
477. sion for this machine must be opened using one of the lockMachine or launchVMProcess methods After the machine has been successfully locked for a session a mutable machine object needs to be queried from the session object and then the desired settings changes can be applied to the returned object using Machine attributes and methods See the Session interface description for more information about sessions Note that IMachine does not provide methods to control virtual machine execution such as start the machine or power it down these methods are grouped in a separate interface called IConsole See also ISession IConsole 5 80 1 Attributes 5 80 1 1 parent read only IVirtualBox IMachine parent Associated parent object 5 80 1 2 icon read write octet IMachine icon Overridden VM Icon details 167 5 Classes interfaces 5 80 1 3 accessible read only boolean IMachine accessible Whether this virtual machine is currently accessible or not A machine is always deemed accessible unless it is registered and its settings file cannot be read or parsed either because the file itself is unavailable or has invalid XML contents Every time this property is read the accessibility state of this machine is re evaluated If the returned value is false the accessError property may be used to get the detailed error information describing the reason of inaccessibility including XML error messages When the machin
478. sition position Position to remove the filter from Removes a USB device filter from the specified position in the list of filters Positions are numbered starting from 0 Specifying a position equal to or greater than the number of elements in the list will produce an error See also deviceFilters If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Virtual machine is not mutable e E_INVALIDARG USB device filter list empty or invalid position 305 5 Classes interfaces 5 142 lUSBDeviceStateChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when a USB device is attached to or detached from the virtual USB controller This notification is sent as a result of the indirect request to attach the device because it matches one of the machine USB filters or as a result of the direct request issued by IConsole attachUSBDevice or IConsole detachUSBDevice This notification is sent in case of both a succeeded and a failed request completion When the request succeeds the error parameter is null and the given device has been already added to when attached is true or removed from when attached is false the collection represented by IConsole USBDevices On failure the collection doesn t change and the error parameter represents the error message describing the failure 5 142 1 Attri
479. sively as DTrace probes So the effect of the same config may differ between Solaris and Windows for example 5 80 1 80 allowTracingToAccessVM read write boolean IMachine allowTracingToAccessVM Enables tracepoints in PDM devices and drivers to use the VMCPU or VM structures when firing off trace points This is especially useful with DTrace tracepoints as it allows you to use the VMCPU or VM pointer to obtain useful information such as guest register state This is disabled by default because devices and drivers normally has no business accessing the VMCPU or VM structures and are therefore unable to get any pointers to these 5 80 1 81 autostartEnabled read write boolean IMachine autostartEnabled Enables autostart of the VM during system boot 5 80 1 82 autostartDelay read write unsigned long IMachine autostartDelay Number of seconds to wait until the VM should be started during system boot 5 80 1 83 autostopType read write AutostopType IMachine autostopType Action type to do when the system is shutting down 179 5 Classes interfaces 5 80 1 84 defaultFrontend read write wstring IMachine defaultFrontend Selects which VM frontend should be used by default when launching this VM through the launchVMProcess method Empty or null strings do not define a particular default it is up to launchVMProcess to select one See the description of launchVMProcess for the valid frontend types This p
480. sor affinity to set for the new process This is a list of guest CPU numbers the process is allowed to run on Note This is silently ignored if the guest does not support setting the affinity of pro cesses or if the guest additions does not implemet this feature Creates a new process running in the guest with the extended options for setting the process priority and affinity See processCreate for more information 5 64 32 processGet IGuestProcess IGuestSession processGet in unsigned long pid pid Process ID PID to get guest process for Gets a certain guest process by its process ID PID 5 64 33 symlinkCreate void IGuestSession symlinkCreate in wstring symlink in wstring target in SymlinkType type symlink Path to the symbolic link that should be created Guest path style target The path to the symbolic link target If not an absolute this will be relative to the symlink location at access time Guest path style type The symbolic link type mainly for Windows See SymlinkType for more information Creates a symbolic link in the guest If this method fails the following error codes may be reported e E_NOTIMPL The method is not implemented yet 5 64 34 symlinkExists boolean IGuestSession symlinkExists in wstring symlink symlink Path to the alleged symbolic link Guest path style Checks whether a symbolic link exists in the guest If this method fails the following error
481. specify GuestSessionWaitResult_Terminate None No result was returned Not being used Start The guest session has been started Terminate The guest session has been terminated Status The guest session has changed its status The status then can be retrieved via IGuestSession status Error Error while executing the process Timeout The waiting operation timed out This also will happen when no event has been oc curred matching the current waiting flags in a IGuestSession waitFor call WaitFlagNotSupported A waiting flag specified in the IGuestSession waitFor call is not sup ported by the guest 6 54 GuestUserState State a guest user has been changed to Unknown Unknown state Not being used Loggedin A guest user has been successfully logged into the guest OS Note This property is not implemented yet LoggedOut A guest user has been successfully logged out of the guest OS Note This property is not implemented yet Locked A guest user has locked its account This might include running a password protected screensaver in the guest Note This property is not implemented yet Unlocked A guest user has unlocked its account Note This property is not implemented yet Disabled A guest user has been disabled by the guest OS 348 6 Enumerations enums Note This property is not implemented yet Idle A guest user currently is not using the gu
482. stProcesslOEvent Note This interface extends IGuestProcessIOEvent and therefore supports all its meth ods and attributes as well Notification when a guest process stdin became available Note This event is right now not implemented 121 5 Classes interfaces 5 59 1 Attributes 5 59 1 1 status read only ProcessInputStatus IGuestProcessInputNotifyEvent status Current process input status 5 60 IGuestProcessOutputEvent IGuestProcesslOEvent Note This interface extends IGuestProcessIOEvent and therefore supports all its meth ods and attributes as well Notification when there is guest process output available for reading 5 60 1 Attributes 5 60 1 1 data read only octet IGuestProcessOutputEvent data Actual output data 5 61 IGuestProcessRegisteredEvent IGuestProcessEvent Note This interface extends IGuestProcessEvent and therefore supports all its methods and attributes as well Notification when a guest process was registered or unregistered 5 61 1 Attributes 5 61 1 1 registered read only boolean IGuestProcessRegisteredEvent registered If true the guest process was registered otherwise it was unregistered 5 62 IGuestProcessStateChangedEvent IGuestProcessEvent Note This interface extends IGuestProcessEvent and therefore supports all its methods and attributes as well Notification when a guest process changed its state
483. storyCount This value specifies how many old release log files are kept 296 5 Classes interfaces 5 135 1 26 defaultAudioDriver read only AudioDriverType ISystemProperties defaultAudioDriver This value hold the default audio driver for the current system 5 135 1 27 autostartDatabasePath read write wstring ISystemProperties autostartDatabasePath The path to the autostart database Depending on the host this might be a filesystem path or something else 5 135 1 28 defaultAdditionsISO read write wstring ISystemProperties defaultAdditionsISO The path to the default Guest Additions ISO image Can be empty if the location is not known in this installation 5 135 1 29 defaultFrontend read write wstring ISystemProperties defaultFrontend Selects which VM frontend should be used by default when launching a VM through the IMachine launchVMProcess method Empty or null strings do not define a particu lar default it is up to IMachine launchVMProcess to select one See the description of IMachine launchVMProcess for the valid frontend types This global setting is overridden by the per VM attribute IMachine defaultFrontend or a fron tend type passed to IMachine launchVMProcess 5 135 1 30 screenShotFormats read only BitmapFormat ISystemProperties screenShotFormats Supported bitmap formats which can be used with takeScreenShot and takeScreenShotToArray methods 5 135 2 getDefaultloCache
484. szString The ownership of a string determines who is responsible for releasing resources associated with the string Whenever the API creates a string essentially for output parameters ownership is transferred to the caller To avoid resource leaks the caller should release resources once the string is no longer needed There are plenty of examples in the sample code 2 3 6 6 Array handling Arrays are handled somewhat similarly to strings with the additional information of the number of elements in the array The exact details of string passing depends on the platform middle ware COM XPCOM and therefore the C binding offers helper functions to gloss over these differences Passing arrays as input parameters to API methods is usually done by the following sequence calling a hypothetical IArrayDemo_PassArray API method static const ULONG aElements 1 2 3 4 ULONG cElements sizeof aElements sizeof aElements 0 SAFEARRAY x psa NULL psa g_pVBoxFuncs gt pfnSafeArrayCreateVector VT_I4 0 cElements g_pVBoxFuncs gt pfnSafeArrayCopyInParamHelper psa aElements sizeof aElements IArrayDemo_PassArray pThis ComSafeArrayAsInParam psa g_pVBoxFuncs gt pfnSafeArrayDestroy psa 42 2 Environment specific notes Likewise getting arrays results from output parameters is done using helper functions which manage memory allocations as part of their other functionality SAFEARRAY psa g_pVBoxFuncs gt
485. t 349 6 Enumerations enums GroupAdded To guest OS has added a user to a specific user group Note This property is not implemented yet GroupRemoved To guest OS has removed a user from a specific user group Note This property is not implemented yet Elevated To guest OS temporarily has elevated a user to perform a certain task Note This property is not implemented yet 6 55 HWVirtExPropertyType Hardware virtualization property type This enumeration represents possible values for the IMachine getHWVirtExProperty and IMachine setHWVirtExProperty methods Null Null value never used by the API Enabled Whether hardware virtualization VI x AMD V is enabled at all If such extensions are not available they will not be used VPID Whether VI x VPID is enabled If this extension is not available it will not be used NestedPaging Whether Nested Paging is enabled If this extension is not available it will not be used UnrestrictedExecution Whether VT x unrestricted execution is enabled If this feature is not available it will not be used LargePages Whether large page allocation is enabled requires nested paging and a 64 bit host Force Whether the VM should fail to start if hardware virtualization VI x AMD V cannot be used If not set there will be an automatic fallback to software virtualization 6 56 HostNetworkinterfaceMediumType Type of encapsulati
486. t or writeQ for export This attribute is empty until one of these methods has been called 5 3 1 2 disks read only wstring IAppliance disks Array of virtual disk definitions One such description exists for each disk definition in the OVF each string array item represents one such piece of disk information with the information fields separated by tab t characters The caller should be prepared for additional fields being appended to this string in future versions of VirtualBox and therefore check for the number of tabs in the strings returned In the current version the following eight fields are returned per string in the array 1 Disk ID unique string identifier given to disk 2 Capacity unsigned integer indicating the maximum capacity of the disk 3 Populated size optional unsigned integer indicating the current size of the disk can be approximate 1 if unspecified 4 Format string identifying the disk format typically http www vmware com specifications vmdk html spars 5 Reference where to find the disk image typically a file name if empty then the disk should be created on import 6 Image size optional unsigned integer indicating the size of the image which need not necessarily be the same as the values specified above since the image may be compressed or sparse 1 if not specified 7 Chunk size optional unsigned integer if the image is split into chunks presently unsup ported and alwa
487. t is relative absolute or multi touch 5 53 1 2 x read only long IGuestMouseEvent x New X position or X delta 5 53 1 3 y read only long IGuestMouseEvent y New Y position or Y delta 5 53 1 4 z read only long IGuestMouseEvent z Z delta 5 53 1 5 w read only long IGuestMouseEvent w W delta 5 53 1 6 buttons read only long IGuestMouseEvent buttons Button state bitmask 5 54 IGuestMultiTouchEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when guest touch screen event happens 5 54 1 Attributes 5 54 1 1 contactCount read only long IGuestMultiTouchEvent contactCount Number of contacts in the event 116 5 Classes interfaces 5 54 1 2 xPositions read only short IGuestMultiTouchEvent xPositions X positions 5 54 1 3 yPositions read only short IGuestMultiTouchEvent yPositions Y positions 5 54 1 4 contactlds read only unsigned short IGuestMultiTouchEvent contactIds Contact identifiers 5 54 1 5 contactFlags read only unsigned short IGuestMultiTouchEvent contactFlags Contact state Bit 0 in contact Bit 1 in range 5 54 1 6 scanTime read only unsigned long IGuestMultiTouchEvent scanTime Timestamp of the event in milliseconds Only relative time between events is important 5 55 IGuestOSType Note With the web service this interfa
488. t is said that a programming language supports web services this typically means that a programming language has support for parsing WSDL files and somehow integrating the remote procedure calls into the native language syntax for example like in the Java sample shown in chapter 2 2 1 Raw web service example for Java with Axis page 30 For details about how programming languages support web services please refer to the docu mentation that comes with the individual languages Here are a few pointers 1 For C among many others the gSOAP toolkit is a good option Parts of gSOAP are also used in VirtualBox to implement the VirtualBox web service 2 For Java there are several implementations already described in this document see chap ter 2 1 1 The object oriented web service for JAX WS page 27 and chapter 2 2 1 Raw web service example for Java with Axis page 30 35 2 Environment specific notes 3 Perl supports WSDL via the SOAP Lite package This in turn comes with a tool called stubmaker pl that allows you to turn any WSDL file into a Perl package that you can import You can also import any WSDL file live by having it parsed every time the script runs but that can take a while You can then code again assuming the above example my result servicename gt sayHello Peter A sample that uses SOAP Lite was described in chapter 2 2 2 Raw web service example for Perl page 31 2 3 Using COM XPCOM
489. t is used by a running virtual machine but has a depending differencing image that receives the actual write operations This way one base medium can have multiple child differencing images which can be written to simultaneously Read only media such as DVD and floppy images are also locked for reading only so they can be in use by multiple machines simultaneously A medium is also locked for reading when it is the source of a write operation such as cloneTo or mergeTo The medium locked for reading must be unlocked by abandoning the returned token object see IToken Calls to lockRead can be nested and the lock is actually released when all callers have abandoned the token This method sets the medium state see state to LockedRead on success The medium s previous state must be one of Created Inaccessible or LockedRead Locking an inaccessible medium is not an error this method performs a logical lock that prevents modifications of this medium through the VirtualBox API not a physical file system lock of the underlying storage unit This method returns the current state of the medium before the operation If this method fails the following error codes may be reported e VBOX_E_INVALID_OBJECT_STATE Invalid medium state e g not created locked inac cessible creating deleting 5 87 16 lockWrite IToken IMedium LockWrite 235 5 Classes interfaces Locks this medium for writing A write
490. t more details about the failure If the state of the medium is LockedRead then it remains the same and a non empty value of lastAccessError will indicate a failed accessibility check in this case Note that not all medium states are applicable to all medium types 5 87 19 reset IProgress IMedium reset Starts erasing the contents of this differencing medium This operation will reset the differencing medium to its initial state when it does not contain any sector data and any read operation is redirected to its parent medium This automatically gets called during VM power up for every medium whose autoReset attribute is true The medium will be write locked for the duration of this operation see lockWrite If this method fails the following error codes may be reported e VBOX_E_NOT_SUPPORTED This is not a differencing medium e VBOX_E_INVALID_OBJECT_STATE Medium is not in Created or Inaccessible state 237 5 Classes interfaces 5 87 20 resize IProgress IMedium resize in long long logicalSize logicalSize New nominal capacity of the medium in bytes Starts resizing this medium This means that the nominal size of the medium is set to the new value Both increasing and decreasing the size is possible and there are no safety checks since VirtualBox does not make any assumptions about the medium contents Resizing usually needs additional disk space and possibly also some temporary disk space Note th
491. t subtree does not include the current state It is still significantly faster than deleting the snapshots one by one if the current state is in the subtree and 187 5 Classes interfaces there are more than one snapshots from current state to the snapshot which marks the subtree since it eliminates the incremental image merging Note This API method is right now not implemented If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE The running virtual machine prevents deleting this snap shot This happens only in very specific situations usually snapshots can be deleted with out trouble while a VM is running The error message text explains the reason for the failure e E_NOTIMPL The method is not implemented yet 5 80 16 deleteSnapshotRange IProgress IMachine deleteSnapshotRange in uuid startId in uuid endId startld UUID of the first snapshot to delete endid UUID of the last snapshot to delete Starts deleting the specified snapshot range This is limited to linear snapshot lists which means there may not be any other child snapshots other than the direct sequence between the start and end snapshot If the start and end snapshot point to the same snapshot this method is completely equivalent to deleteSnapshot See ISnapshot for an introduction to snapshots The conditions and many details are the same as with deleteSnapshot This operation is generally faste
492. t to check Perform error checking before using an IMachine object Generally useful before starting a VM and all other uses If anything is not as it should be then this method will return an appropriate error 5 153 IVirtualBoxErrorinfo The IVirtualBoxErrorInfo interface represents extended error information Extended error information can be set by VirtualBox components after unsuccessful or par tially successful method invocation This information can be retrieved by the calling party as an IVirtualBoxErrorInfo object and then shown to the client in addition to the plain 32 bit result code In MS COM this interface extends the IErrorInfo interface in XPCOM it extends the nsIExcep tion interface In both cases it provides a set of common attributes to retrieve error information Sometimes invocation of some component s method may involve methods of other components that may also fail independently of this method s failure or a series of non fatal errors may precede a fatal error that causes method failure In cases like that it may be desirable to preserve information about all errors happened during method invocation and deliver it to the caller The next attribute is intended specifically for this purpose and allows to represent a chain of errors through a single IVirtualBoxErrorInfo object set after method invocation Note errors are stored to a chain in the reverse order i e the initial error object you query right after me
493. tEvent guestlp INATRedirectEvent guestIP THostPciDevicePlugEvent THostPCIDevicePlugEvent 13 4 Incompatible API changes with version 4 1 e The method lAppliance importMachines has one more parameter now which allows to configure the import process in more detail e The method IVirtualBox openMedium has one more parameter now which allows re solving duplicate medium UUIDs without the need for external tools e The INetworkAdapter interface has been cleaned up The various methods to activate an attachment type have been replaced by the INetworkAdapter attachmentType setter 395 13 Main API change log Additionally each attachment mode now has its own attribute which means that host only networks no longer share the settings with bridged interfaces To allow introducing new network attachment implementations without making API changes the concept of a generic network attachment driver has been introduced which is configurable through key value properties This version introduces the guest facilities concept A guest facility either represents a mod ule or feature the guest is running or offering which is defined by AdditionsFacilityType Each facility is member of a AdditionsFacilityClass and has a current status indicated by AdditionsFacilityStatus together with a timestamp in ms of the last status update To address the above concept the following changes were made In the IGuest interface
494. tRestored See ISnapshotRestoredEvent OnMediumConfigChanged See IMediumConfigChangedEvent Last Must be last event used for iterations and structures relying on numerical event values 369 6 Enumerations enums 6 102 VFSType Virtual file systems supported by VFSExplorer File Cloud 3 WebDav 6 103 VirtualSystemDescriptionType Used with IVirtualSystemDescription to describe the type of a configuration value Ignore OS Name Product Vendor Version ProductUrl VendorUrl Description License Miscellaneous CPU Memory HardDiskControllerIDE HardDiskControllerSATA HardDiskControllerSCSI HardDiskControllerSAS HardDisklmage Floppy CDROM NetworkAdapter USBController SoundCard SettingsFile Not used implemented right now will be added later in 4 1 x 370 6 Enumerations enums 6 104 VirtualSystemDescriptionValueType Used with IVirtualSystemDescription getValuesByType to describe the value type to fetch Reference Original Auto ExtraConfig 371 7 Host Guest Communication Manager The VirtualBox Host Guest Communication Manager HGCM allows a guest application or a guest driver to call a host shared library The following features of VirtualBox are implemented using HGCM e Shared Folders e Shared Clipboard e Guest configuration interface The shared library contains a so called HGCM service The guest HGCM clients establish connections to the service to call it When calling a HGC
495. table is not contained with the VirtualBox SDK but instead ships with the standard VirtualBox binary package for your specific platform Since the SDK contains only platform independent text files and documentation the binaries are instead shipped with the platform specific packages For this reason the information how to run it as a service is included in the VirtualBox documentation The vboxwebsrv program which implements the web service is a text mode console pro gram which after being started simply runs until it is interrupted with Ctrl C or a kill command Once the web service is started it acts as a front end to the VirtualBox installation of the user account that it is running under In other words if the web service is run under the user account of userl it will see and manipulate the virtual machines and other data represented by the VirtualBox data of that user for example on a Linux machine under home user1 config VirtualBox see the VirtualBox User Manual for details on where this data is stored 1 4 1 Command line options of vboxwebsrv The web service supports the following command line options e help or h print a brief summary of command line options e background or b run the web service as a background daemon This option is not supported on Windows hosts host or H This specifies the host to bind to and defaults to localhost port or p This specifies which port to bind
496. tachDeviceO and IMachine mountMedium now take an IMedium ob ject instead of a UUID as an argument It is these two calls which add media to a registry now either a machine registry for machines created with VirtualBox 4 0 or later or the global registry otherwise As a consequence if a medium is opened but never attached to a machine it is no longer added to any registry any more To reduce code duplication the APIs IVirtualBox findHardDiskQ getHard DiskQ findDVDImageO getDVDImage findFloppyImageQ and getFloppy ImageO have all been merged into IVirtualBox findMediumQ and IVirtual Box openHardDisk openDVDImage and openFloppyImage have all been merged into IVirtualBox openMedium The rare use case of changing the UUID and parent UUID of a medium previously handled by openHardDisk is now in a separate IMedium setIDs method ISystemProperties get setDefaultHardDiskFolder have been removed since disk images are now by default placed in each machine s folder The ISystemProperties infoVDSize attribute replaces the getMaxVDISize API call this now uses bytes instead of megabytes e Machine management APIs were enhanced as follows IVirtualBox createMachine is no longer restricted to creating machines in the de fault Machines folder but can now create machines at arbitrary locations For this to work the parameter list had to be changed The long deprecated IVirtualBox
497. taching media The specified device slot must not have a device attached to it or this method will fail Note You cannot attach a device to a newly created machine until this machine s settings are saved to disk using saveSettings 183 5 Classes interfaces Note If the medium is being attached indirectly a new differencing medium will implicitly be created for it and attached instead If the changes made to the machine settings including this indirect attachment are later cancelled using discardSettings this implicitly created differencing medium will implicitly be deleted If this method fails the following error codes may be reported e E_INVALIDARG SATA device SATA port IDE port or IDE slot out of range or file or UUID not found e VBOX_E_INVALID_OBJECT_STATE Machine must be registered before media can be at tached e VBOX_E_INVALID_VM_STATE Invalid machine state e VBOX_E_OBJECT_IN_USE A medium is already attached to this or another virtual ma chine 5 80 8 attachHostPCIDevice void IMachine attachHostPCIDevice in long hostAddress in long desiredGuestAddress in boolean tryToUnbind hostAddress Address of the host PCI device desiredGuestAddress Desired position of this device on guest PCI bus tryToUnbind If VMM shall try to unbind existing drivers from the device before attaching it to the guest Attaches host PCI device with the given host PCI address to t
498. tatus Guest Additions facility states Inactive Facility is not active Paused Facility has been paused Prelnit Facility is preparing to initialize Init Facility is initializing Active Facility is up and running Terminating Facility is shutting down Terminated Facility successfully shut down Failed Facility failed to start Unknown Facility status is unknown 333 6 Enumerations enums 6 4 AdditionsFacilityType Guest Additions facility IDs None No invalid facility VBoxGuestDriver VirtualBox base driver VBoxGuest AutoLogon Auto logon modules VBoxGINA VBoxCredProv pam_vbox VBoxService VirtualBox system service VBoxService VBoxTrayClient VirtualBox desktop integration VBoxTray on Windows VBoxClient on non Windows Seamless Seamless guest desktop integration Graphics Guest graphics mode If not enabled seamless rendering will not work resize hints are not immediately acted on and guest display resizes are probably not initiated by the guest additions All All facilities selected 6 5 AdditionsRunLevelType Guest Additions run level type None Guest Additions are not loaded System Guest drivers are loaded Userland Common components such as application services are loaded Desktop Per user desktop components are loaded 6 6 AdditionsUpdateFlag Guest Additions update flags None No flag set WaitForUpdateStartOnly Starts the regular updating process and waits until the actual
499. ted 134 5 Classes interfaces 5 64 26 fsObjQuerylnfo IGuestFsObjInfo IGuestSession fsObjQueryInfo in wstring path in boolean followSymlinks path Path to the file system object to gather information about Guest path style followSymlinks Information about symbolic links is returned if false Otherwise symbolic links are followed and the returned information concerns itself with the symlink target if true Queries information about a file system object file directory etc in the guest If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND The file system object was not found e VBOX_E_IPRT_ERROR Error while querying information 5 64 27 fsObjRemove void IGuestSession fsObjRemove in wstring path path Path to the file system object to remove Guest style path Removes a file system object file symlink etc in the guest Will not work on directories use directoryRemove to remove directories Note This method will remove symbolic links in the final path component not follow them If this method fails the following error codes may be reported e E_NOTIMPL The method has not been implemented yet e VBOX_E_OBJECT_NOT_FOUND The file system object was not found e VBOX_E_IPRT_ERROR For most other errors We know this is unhelpful will fix shortly 5 64 28 fsObjRename void IGuestSession fsObjRename in wstring oldPath i
500. tener should be used Please note that a listener created with IEventSource createListener must not be used as an active listener Once created the listener must be registered to listen for the desired events see IEventSource registerListener providing an array of VBoxEventType enums Those elements can either be the individual event IDs or wildcards matching multiple event IDs After registration the callback s IEventListener handleEvent method is called automatically when the event is triggered while passive listeners have to call IEventSource getEvent and IEventSource eventProcessed in an event processing loop The IEvent interface is an abstract parent interface for all such VirtualBox events coming in As a result the standard use pattern inside IEventListener handleEvent or the event processing loop is to check the type attribute of the event and then cast to the appropriate specific interface using QueryInterface 5 23 1 Attributes 5 23 1 1 type read only VBoxEventType IEvent type Event type 5 23 1 2 source read only IEventSource IEvent source Source of this event 5 23 1 3 waitable read only boolean IEvent waitable If we can wait for this event being processed If false waitProcessed returns immediately and setProcessed doesn t make sense Non waitable events are generally better performing as no additional overhead associated with waitability imposed Waitable events are neede
501. ter 2 3 Using COM XPCOM directly page 36 below The VirtualBox front ends the graphical user interfaces as well as the command line which are all written in C use COM XPCOM to call the Main API Technically the web service is another front end to this COM API mapping almost all of it to SOAP clients If you wonder which way to choose here are a few comparisons 22 1 Introduction Web service COM XPCOM Pro Easy to use with Java and Python with the Con Usable from languages where object oriented web service extensive support COM bridge available most languages even with other languages C NET PHP on Windows platform Python and C Perl and others on other hosts Pro Client can be on remote machine Con Client must be on the same host where virtual machine is executed Con Significant overhead due to XML Pro Relatively low invocation overhead marshalling over the wire for each method call In the following chapters we will describe the different ways in which to program VirtualBox starting with the method that is easiest to use and then increase complexity as we go along 1 3 About web services in general Web services are a particular type of programming interface Whereas with normal program ming a program calls an application programming interface APD defined by another program or the operating system and both sides of the interface have to agree on the calling convention an
502. ter the machine has been unregistered Unregisters a machine previously registered with VirtualBox registerMachine and option ally do additional cleanup before the machine is unregistered This method does not delete any files It only changes the machine configuration and the list of registered machines in the VirtualBox object To delete the files which belonged to the machine including the XML file of the machine itself call deleteConfig optionally with the array of IMedium objects which was returned from this method How thoroughly this method cleans up the machine configuration before unregistering the machine depends on the cleanupMode argument e With UnregisterOnly the machine will only be unregistered but no additional cleanup will be performed The call will fail if the machine is in Saved state or has any snapshots or any media attached see IMediumAttachment It is the responsibility of the caller to delete all such configuration in this mode In this mode the API behaves like the former IVirtualBox unregisterMachine API which it replaces With DetachAllReturnNone the call will succeed even if the machine is in Saved state or if it has snapshots or media attached All media attached to the current machine state or in snapshots will be detached No medium objects will be returned all of the machine s media will remain open With DetachAllReturnHardDisksOnly the call will behave like with
503. terfaces accessMode 0 get 1 set 2 delete retValue retTimestamp retFlags Called by IMachine getGuestPropertyQ and by IMachine setGuestProperty in order to read and modify guest properties If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open e VBOX_E_INVALID_OBJECT_STATE Session type is not direct 5 77 3 assignRemoteMachine void IInternalSessionControl assignRemoteMachine in IMachine machine in IConsole console machine console Assigns the machine and the remote console object associated with this remote type session If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Session state prevents operation 5 77 4 cancelSaveStateWithReason void IInternalSessionControl cancelSaveStateWithReason Internal method for cancelling a VM save state See also saveStateWithReason 5 77 5 enableVMMStatistics void IInternalSessionControl enableVMMStatistics in boolean enable enable True enables statistics collection Enables or disables collection of VMM RAM statistics If this method fails the following error codes may be reported e VBOX_E_INVALID_VM_STATE Machine session is not open e VBOX_E_INVALID_OBJECT_STATE Session type is not direct 158 5 Classes interfaces 5 77 6 enumerateGuestProperties void IInternalSessionControl enumerateGuestProperties in wst
504. ters are activated that can put it to USBDeviceState_Captured state If the device was ignored by global filters or didn t match any filters at all including guest ones it is handled by the host in a normal way In this case the device state is determined by the host and can be one of USBDeviceState_Unavailable USBDeviceState_Busy or USBDeviceS tate Available depending on the current device usage Besides auto capturing based on filters the device can be manually captured by guests IConsole attachUSBDevice if its state is USBDeviceState_Busy USBDeviceState_Available or USBDeviceState_Held Note Due to differences in USB stack implementations in Linux and Win32 states US BDeviceState_Busy and USBDeviceState Unavailable are applicable only to the Linux version of the product This also means that IConsole attachUSBDevice can only succeed on Win32 if the device state is USBDeviceState_Held See also IHostUSBDevice IHostUSBDeviceFilter NotSupported Not supported by the VirtualBox server not available to guests Unavailable Being used by the host computer exclusively not available to guests Busy Being used by the host computer potentially available to guests Available Not used by the host computer available to guests the host computer can also start using the device at any time Held Held by the VirtualBox server ignored by the host computer available to guests Captured Captured by one of the g
505. that conforms to the OVF standard and carries an ovf file extension If this descriptor file references other files such as disk images as OVF appliances typically do those additional files must be in the same directory as the descriptor file If the appliance is distributed as a single file it must be in TAR format and have the ova file extension This TAR file must then contain at least the OVF descriptor files and optionally other files At this time VirtualBox does not not yet support the packed TAR variant support will be added with a later version Importing an OVF appliance into VirtualBox as instances of IMachine involves the following sequence of API calls 1 2 Call IVirtualBox createAppliance This will create an empty IAppliance object On the new object call read O with the full path of the OVF file you would like to import So long as this file is syntactically valid this will succeed and fill the appliance object with the parsed data from the OVF file Next call interpret which analyzes the OVF data and sets up the contents of the TAppliance attributes accordingly These can be inspected by a VirtualBox front end such as the GUI and the suggestions can be displayed to the user In particular the virtualSystemDescriptions array contains instances of IVirtualSystemDescription which represent the virtual systems machines in the OVF which in turn describe the virtual hardware prescribed by the O
506. that no machine is currently locked for this session Locked In IMachine sessionState this means that the machine is currently locked for a session whose process identifier can then be found in the IMachine sessionPID attribute In ISession state this means that a machine is currently locked for this session and the mutable machine object can be found in the ISession machine attribute see IMachine lockMachine for details Spawning A new process is being spawned for the machine as a result of IMachine launchVMProcess call This state also occurs as a short transient state during an IMachine lockMachine call Unlocking The session is being unlocked 6 90 SessionType Session type This enumeration represents possible values of the ISession type attribute Null Null value never used by the API WriteLock Session has acquired an exclusive write lock on a machine using IMachine lockMachine Remote Session has launched a VM process using IMachine launchVMProcess Shared Session has obtained a link to another session using IMachine lockMachine 6 91 SettingsVersion Settings version of VirtualBox settings files This is written to the version attribute of the root VirtualBox element in the settings file XML and indicates which VirtualBox version wrote the file Null Null value indicates invalid version v1_0 Legacy settings version not currently supported 363 6 Enumerations enums v1_1 Le
507. the VM can be paused stopped snapshotted or other things 3 4 VirtualBox events In VirtualBox events provide a uniform mechanism to register for and consume specific events A VirtualBox client can register an event listener represented by the IEventListener interface 48 3 Basic VirtualBox concepts some examples which will then get notified by the server when an event represented by the IEvent interface happens The IEvent interface is an abstract parent interface for all events that can occur in VirtualBox The actual events that the server sends out are then of one of the specific subclasses for example IMachineStateChangedEvent or IMediumChangedEvent As an example the VirtualBox GUI waits for machine events and can thus update its display when the machine state changes or machine settings are modified even if this happens in another client This is how the GUI can automatically refresh its display even if you manipulate a machine from another client for example from VBoxManage To register an event listener to listen to events use code like this EventSource es console getEventSource IEventListener listener es createListener VBoxEventType aTypes VBoxEventType OnMachineStateChanged list of event types to listen for es registerListener listener aTypes false active register passive listener IEvent ev es getEvent listener 1000 wait up to one second for event to happen
508. the appliance exports into a new OVF file Calling this method is the final step of exporting an appliance from VirtualBox see Appliance for an overview Since exporting the appliance will most probably involve copying and converting disk images which can take a long time this method operates asynchronously and returns an Progress object to allow the caller to monitor the progress 5 4 lAudioAdapter The IAudioAdapter interface represents the virtual audio adapter of the virtual machine Used in IMachine audioAdapter 5 4 1 Attributes 5 4 1 1 enabled read write boolean IAudioAdapter enabled Flag whether the audio adapter is present in the guest system If disabled the virtual guest hardware will not contain any audio adapter Can only be changed when the VM is not running 5 4 1 2 enabledin read write boolean IAudioAdapter enabledIn Flag whether the audio adapter is enabled for audio input Only relevant if the adapter is enabled 5 4 1 3 enabledOut read write boolean IAudioAdapter enabledOut Flag whether the audio adapter is enabled for audio output Only relevant if the adapter is enabled 5 4 1 4 audioController read write AudioControllerType IAudioAdapter audioController The emulated audio controller 5 4 1 5 audioCodec read write AudioCodecType IAudioAdapter audioCodec The exact variant of audio codec hardware presented to the guest For HDA and SB16 only one variant is available
509. thod invocation is the last error set by the callee the object it points to in the next attribute is the previous error and so on up to the first error which is the last in the chain 5 153 1 Attributes 5 153 1 1 resultCode read only long IVirtualBoxErrorInfo resultCode Result code of the error Usually it will be the same as the result code returned by the method that provided this error information but not always For example on Win32 CoCreateInstance will most likely return E NOINTERFACE upon unsuccessful component instantiation attempt but not the value the component factory returned Value is typed ong not result to make interface usable from scripting languages Note In MS COM there is no equivalent In XPCOM it is the same as nsIExcep tion result 326 5 Classes interfaces 5 153 1 2 resultDetail read only long IVirtualBoxErrorInfo resultDetail Optional result data of this error This will vary depending on the actual error usage By default this attribute is not being used 5 153 1 3 interfacelD read only uuid IVirtualBoxErroriInfo interfaceID UUID of the interface that defined the error Note In MS COM it is the same as IErrorInfo GetGUID except for the data type In XPCOM there is no equivalent 5 153 1 4 component read only wstring IVirtualBoxErrorInfo component Name of the component that generated the error Note In MS COM it
510. tials only have to be provided when creating a new guest session There can be up to 32 guest sessions at once per VM each session serving up to 2048 guest processes running or files opened Instead of working with process or directory handles before version 4 2 there now are the dedicated interfaces IGuestProcess IGuestDirectory and IGuestFile To retrieve more information of a file system object the new interface IGuestFsObjInfo has been introduced Even though the guest control API was changed it is backwards compatible so that it can be used with older installed Guest Additions However to use upcoming features like process termination or waiting for input output new Guest Additions must be installed when these features got implemented The following limitations apply The IGuestFile interface is not fully implemented yet The symbolic link APIs IGuestSession symlinkCreate IGuestSession symlinkExists IGuestSession symlinkRead O IGuestSession symlinkRemoveDirectory and IGuest Session symlinkRemoveFile are not implemented yet The directory APIs IGuestSession directoryRemove IGuestSession directoryRemoveRecursive IGuestSession directoryRename and IGuestSession directorySetACL are not im plemented yet The temporary file creation API IGuestSession fileCreateTempO is not implemented yet Guest process termination via IProcess terminate is not implemented yet Waiting for g
511. ting from 1 dz Amount of mouse wheel moves Positive values describe clockwise wheel rotations negative values describe counterclockwise rotations dw Amount of horizontal mouse wheel moves Positive values describe a movement to the left negative values describe a movement to the right buttonState The current state of mouse buttons Every bit represents a mouse button as follows Bit O 0x01 left mouse buttonBit 1 0x02 right mouse buttonBit 2 0x04 middle mouse button A value of 1 means the corresponding button is pressed otherwise it is released Positions the mouse pointer using absolute x and y coordinates These coordinates are ex pressed in pixels and start from 1 1 which corresponds to the top left corner of the virtual display Note This method will have effect only if absolute mouse positioning is supported by the guest OS See also absoluteSupported If this method fails the following error codes may be reported e E_ACCESSDENIED Console not powered up e VBOX_E_IPRT_ERROR Could not send mouse event to virtual mouse 5 94 IMouseCapabilityChangedEvent IEvent Note This interface extends Event and therefore supports all its methods and at tributes as well Notification when the mouse capabilities reported by the guest have changed The new capa bilities are passed 5 94 1 Attributes 5 94 1 1 supportsAbsolute read only boolean IMouseCapabilityChangedEvent supportsAbsolute
512. tings to be removed Removes the DHCP server settings If this method fails the following error codes may be reported e E_INVALIDARG Host network interface name already exists 5 151 22 removeNATNetwork void IVirtualBox removeNATNetwork in INATNetwork network network 5 151 23 removeSharedFolder void IVirtualBox removeSharedFolder in wstring name name Logical name of the shared folder to remove Removes the global shared folder with the given name previously created by createSharedFolder from the collection of shared folders and stops sharing it Note In the current implementation this operation is not implemented 5 151 24 setExtraData void IVirtualBox setExtraData in wstring key in wstring value key Name of the data key to set value Value to assign to the key 324 5 Classes interfaces Sets associated global extra data If you pass null or empty string as a key value the given key will be deleted Note Before performing the actual data change this method will ask all registered event listener using the IExtraDataCanChangeEvent notification for a permission If one of the listeners refuses the new value the change will not be performed Note On success the IExtraDataChangedEvent notification is called to inform all reg istered listeners about a successful data change If this method fails the following error codes may be reported e
513. tingsFile argument composeMachineFilename is called automatically to have such a recommended name com posed based on the machine name given in the name argument and the primary group If the resulting settings file already exists this method will fail unless the forceOverwrite flag is set The new machine is created unregistered with the initial configuration set according to the specified guest OS type A typical sequence of actions to create a new virtual machine is as follows 1 Call this method to have a new machine created The returned machine object will be mutable allowing to change any machine property 2 Configure the machine using the appropriate attributes and methods 3 Call IMachine saveSettings to write the settings to the machine s XML settings file The configuration of the newly created machine will not be saved to disk until this method is called 4 Call registerMachine to add the machine to the list of machines known to VirtualBox The specified guest OS type identifier must match an ID of one of known guest OS types listed in the guestOSTypes array Note IMachine settingsModified will return false for the created machine until any of machine settings are changed 318 5 Classes interfaces Note There is no way to change the name of the settings file or subfolder of the created machine directly If this method fails the following error codes may be reported
514. tion method 5 145 1 3 authTimeout read write unsigned long IVRDEServer authTimeout Timeout for guest authentication Milliseconds 5 145 1 4 allowMultiConnection read write boolean IVRDEServer allowMultiConnection Flag whether multiple simultaneous connections to the VM are permitted Note that this will be replaced by a more powerful mechanism in the future 308 5 Classes interfaces 5 145 1 5 reuseSingleConnection read write boolean IVRDEServer reuseSingleConnection Flag whether the existing connection must be dropped and a new connection must be estab lished by the VRDE server when a new client connects in single connection mode 5 145 1 6 VRDEExtPack read write wstring IVRDEServer VRDEExtPack The name of Extension Pack providing VRDE for this VM Overrides ISystemProperties defaultVRDEExtPack 5 145 1 7 authLibrary read write wstring IVRDEServer authLibrary Library used for authentication of RDP clients by this VM Overrides ISystemProperties VRDEAuthLibrary 5 145 1 8 VRDEProperties read only wstring IVRDEServer VRDEProperties Array of names of properties which are supported by this VRDE server 5 145 2 getVRDEProperty wstring IVRDEServer getVRDEProperty in wstring key key Name of the key to get Returns a VRDE specific property string If the requested data key does not exist this function will succeed and return an empty string in the value argument
515. tke EEG SR RES ESE eS Se 91 IExtPackFile IExtPackBase 92 BOO 4 ADUS 2 4 5 0 4 S455 li ad BOD a S 92 A Il ote coe sae ee Ae he ee es ey ey ey he A rada el ae 92 IExtPackManager 2 2 aa Gee AAR Re Eee a 92 5 30 1 Attributes saco ee ee 92 520 2 CARNE oa oe ee ee eb oe SO e ee re aie eS 93 530 3 fnd op eo SS Ree eR RO aw A Re ee A eS 93 5304A isExtPacklisable coo a EER EE ROR DS 93 520 5 ApenExiPackFlle oe e e os eels a ae a do awa WG E 93 5 30 6 queryAllPluginsForFrontend o o e 93 SOT unmellen a a a a a RS 94 IExtPackPlogin x ap ca a se 6 ee E BR aa da 94 SLI ADUS ici 24428 40440408 a eee eae eae 94 IExtraDataCanChangeEvent IVetoEvent 000 eee eee 94 B22 ARTIE usais cierta a See ee eae Rees 95 IExtraDataChangedEvent IEvent ee ee ee 95 SSS ADW eo Baw de eS HOS RP a EEE EE ROS 95 MES ona a o Be SSMS Eee st Behe eh ae eee oe ee Bere 95 SSAI IOUS we ey hk Sow a Se aw OP Re ee ee Ww a 96 POLA AGRE ge eee cs ony teh fo eg eee Bw wees wat a el we Be BSE Akad ww Re ease 97 SOLS Quelle cc oboe ees bebe eo ee bd CHOSE EE EO Oe RES 97 B344 QUCIVSIZe oscar eee edd AAA 97 PORT WEA ir a a a EE we ee eke ee 97 3 6 PEGA 6624 4 5 5 4 aah eR eee RE Boe oa eee SS 97 EOR A a ke apy Gb Ww a as a da 98 5 348 SEAL 6 2 45 468 aaa e EE EA HS 98 AD SEE ees as et A ere he Se OE em a ek an ee eee t 98 e Se ae Be ee Ww ea 98 de E MEL ii A Be wt Ge wat ads STs et El as va
516. to html 5 28 2 queryLicense wstring IExtPackBase queryLicense in wstring preferredLocale in wstring preferredLanguage in wstring format preferredLocale The preferred license locale Pass an empty string to get the default license preferredLanguage The preferred license language Pass an empty string to get the default language for the locale format The license format html rtf or txt If a license is present there will always be an HTML of it the rich text format RTF and plain text txt versions are optional If Full feature version of the license attribute 91 5 Classes interfaces 5 29 lExtPackFile IExtPackBase Note This interface is not supported in the web service Note This interface extends IExtPackBase and therefore supports all its methods and attributes as well Extension pack file aka tarball vbox extpack representation returned by IExtPackManager openExtPackFile This provides the base extension pack information with the addition of the file name 5 29 1 Attributes 5 29 1 1 filePath read only wstring IExtPackFile filePath The path to the extension pack file 5 29 2 install IProgress IExtPackFile install in boolean replace in wstring displayInfo replace Set this to automatically uninstall any existing extension pack with the same name as the one being installed displaylnfo Platform specific display information Reserved for future
517. to on the host and defaults to 18083 ssl or s This enables SSL support keyfile or K This specifies the file name containing the server private key and the certificate This is a mandatory parameter if SSL is enabled passwordfile or a This specifies the file name containing the password for the server private key If unspecified or an empty string is specified this is interpreted as an empty password i e the private key is not protected by a password If the file name is specified then then the password is read from the standard input stream otherwise from the specified file The user is responsible for appropriate access rights to protect the confidential password cacert or c This specifies the file name containing the CA certificate appropriate for the server certificate capath or C This specifies the directory containing several CA certificates appropriate for the server certificate dhfile or D This specifies the file name containing the DH key Alternatively it can contain the number of bits of the DH key to generate If left empty RSA is used e randfile or r This specifies the file name containing the seed for the random num ber generator If left empty an operating system specific source of the seed 24 1 Introduction timeout or t This specifies the session timeout in seconds and defaults to 300 five minutes A web service client that has logged on but makes no c
518. to redesign the interfaces in a more logical way Previously the old IHardDisk interface had several derivatives called IVirtualDiskIm age IVMDKImage IVHDImage IISCSIHardDisk and ICustomHardDisk for the various disk formats supported by VirtualBox The new IHardDisk2 interface that comes with version 2 1 now supports all hard disk image formats itself IHardDiskFormat is a new interface to describe the available back ends for hard disk images e g VDI VMDK VHD or iSCSI The IHardDisk2 format attribute can be used to find out the back end that is in use for a particular hard disk image ISys temProperties hardDiskFormats contains a list of all back ends supported by the system ISystemProperties defaultHardDiskFormat contains the default system for mat In addition the new IMedium interface is a generic interface for hard disk DVD and floppy images that contains the attributes and methods shared between them It can be considered a parent class of the more specific interfaces for those images which are now IHardDisk2 IDVDImage2 and IFloppyImage2 In each case the 2 versions of these interfaces replace the earlier versions that did not have the 2 suffix Previously the IDVDImage and IFloppyImage interfaces were entirely unrelated to IHardDisk 402 13 Main API change log As a result all parts of the API that previously referenced IHardDisk IDVDIm age or IFloppyImage or any of the old subclas
519. to save the recorded content This setting cannot be changed while video capturing is enabled Note When setting this attribute the specified path has to be absolute full path When reading this attribute a full path is always returned 171 5 Classes interfaces 5 80 1 27 videoCaptureWidth read write unsigned long IMachine videoCaptureWidth This setting determines the horizontal resolution of the recorded video This setting cannot be changed while video capturing is enabled 5 80 1 28 videoCaptureHeight read write unsigned long IMachine videoCaptureHeight This setting determines the vertical resolution of the recorded video This setting cannot be changed while video capturing is enabled 5 80 1 29 videoCaptureRate read write unsigned long IMachine videoCaptureRate This setting determines the bitrate in kilobits per second Increasing this value makes the video look better for the cost of an increased file size This setting cannot be changed while video capturing is enabled 5 80 1 30 videoCaptureFPS read write unsigned long IMachine videoCaptureFPS This setting determines the maximum number of frames per second Frames with a higher frequency will be skipped Reducing this value increases the number of skipped frames and reduces the file size This setting cannot be changed while video capturing is enabled 5 80 1 31 videoCaptureMaxTime read write unsigned long IMachine videoCaptureMaxTime
520. trics This array represents all metrics supported by the performance collector Individual objects do not necessarily support all of them getMetrics can be used to get the list of supported metrics for a particular object 5 112 2 disableMetrics IPerformanceMetric IPerformanceCollector disableMetrics in wstring metricNames in unknown objects metricNames Metric name filter Comma separated list of metrics with wildcard support objects Set of objects to disable metrics for Turns off collecting specified base metrics Returns an array of IPerformanceMetric describing the metrics have been affected Note Null or empty metric name array means all metrics Null or empty object array means all existing objects If metric name array contains a single element and object array contains many the single metric name array element is applied to each object array element to form metric object pairs 268 5 Classes interfaces 5 112 3 enableMetrics IPerformanceMetric IPerformanceCollector enableMetrics in wstring metricNames in unknown objects metricNames Metric name filter Comma separated list of metrics with wildcard support objects Set of objects to enable metrics for Turns on collecting specified base metrics Returns an array of IPerformanceMetric describing the metrics have been affected Note Null or empty metric name array means all metrics Null or empty object array mean
521. tring IMediumFormat name Human readable description of this format Mainly for use in file open dialogs 244 5 Classes interfaces 5 91 1 3 capabilities read only MediumFormatCapabilities IMediumFormat capabilities Capabilities of the format as an array of the flags For the meaning of individual capability flags see MediumFormatCapabilities 5 91 2 describeFileExtensions void IMediumFormat describeFileExtensions out wstring extensions out DeviceType types extensions The array of supported extensions types The array which indicates the device type for every given extension Returns two arrays describing the supported file extensions The first array contains the supported extensions and the seconds one the type each extension supports Both have the same size Note that some backends do not work on files so this array may be empty See also capabilities 5 91 3 describeProperties void IMediumFormat describeProperties out wstring names out wstring descriptions out DataType types out unsigned long flags out wstring defaults names Array of property names descriptions Array of property descriptions types Array of property types flags Array of property flags defaults Array of default property values Returns several arrays describing the properties supported by this format An element with the given index in each array describes one property Thus the num
522. ttachment passthrough Pass I O requests through to a device on the host 242 5 Classes interfaces 5 88 1 7 temporaryEject read only boolean IMediumAttachment temporaryEject Whether guest triggered eject results in unmounting the medium 5 88 1 8 isEjected read only boolean IMediumAttachment isEjected Signals that the removable medium has been ejected This is not necessarily equivalent to having a null medium association 5 88 1 9 nonRotational read only boolean IMediumAttachment nonRotational Whether the associated medium is non rotational 5 88 1 10 discard read only boolean IMediumAttachment discard Whether the associated medium supports discarding unused blocks 5 88 1 11 hotPluggable read only boolean IMediumAttachment hotPluggable Whether this attachment is hot pluggable or not 5 88 1 12 bandwidthGroup read only IBandwidthGroup IMediumAttachment bandwidthGroup The bandwidth group this medium attachment is assigned to 5 89 IMediumChangedEvent IEvent Note This interface extends IEvent and therefore supports all its methods and at tributes as well Notification when a medium attachment changes Note This event is not yet implemented 5 89 1 Attributes 5 89 1 1 mediumAttachment read only IMediumAttachment IMediumChangedEvent mediumAttachment Medium attachment that is subject to change 243 5 Classes interfaces 5 90 IMediumConfigChange
523. tualBox 95 5 Classes interfaces 5 34 1 Attributes 5 34 1 1 eventSource read only IEventSource IFile eventSource Event source for file events 5 34 1 2 id read only unsigned long IFile id The ID VirtualBox internally assigned to the open file 5 34 1 3 initialSize read only long long IFile initialSize The initial size in bytes when opened 5 34 1 4 offset read only long long IFile offset The current file position The file current position always applies to the readQ method which updates it upon return Same goes for the write method except when accessMode is FileAccessMode AppendOnly or FileAccessMode AppendRead where it will always write to the end of the file and will leave this attribute unchanged The seek is used to change this attribute without transfering any file data like read and write does 5 34 1 5 status read only FileStatus IFile status Current file status 5 34 1 6 fileName read only wstring IFile fileName Full path of the actual file name of this file 5 34 1 7 creationMode read only unsigned long IFile creationMode The UNIX style creation mode specified when opening the file 5 34 1 8 openAction read only FileOpenAction IFile openAction The opening action specified when opening the file 96 5 Classes interfaces 5 34 1 9 accessMode read only FileAccessMode IFile accessMode The file access mode 5 34 2 close void
524. tualBox e With a HardDisk device type the file must be a hard disk image in one of the formats supported by VirtualBox see ISystemProperties mediumFormats After the storage unit is successfully created and this method succeeds if the medium is a base medium it will be added to the hardDisks array attribute e With a DVD device type the file must be an ISO 9960 CD DVD image After this method succeeds the medium will be added to the DVDImages array attribute e With a Floppy device type the file must be an RAW floppy image After this method succeeds the medium will be added to the floppyImages array attribute 319 5 Classes interfaces The list of all storage formats supported by this VirtualBox installation can be obtained using ISystemProperties mediumFormats If the format attribute is empty or null then the default storage format specified by ISystemProperties defaultHardDiskFormat will be used for disks r creating a storage unit of the medium Note that the format of the location string is storage format specific See IMedium location and IMedium for more details If this method fails the following error codes may be reported e VBOX_E_OBJECT_NOT_FOUND format identifier is invalid See ISystemProperties mediumFormats e VBOX_E_FILE_ERROR location is a not valid file name for file based formats only 5 151 8 createNATNetwork INATNetwork IVirtualBox createNATNetwork in
525. turned The array entries match the corresponding entries in the name array Get the list of the guest properties matching a set of patterns along with their values time stamps and flags and give responsibility for managing properties to the console 5 76 15 pushGuestProperty void IInternalMachineControl pushGuestProperty in wstring name in wstring value in long long timestamp in wstring flags name The name of the property to be updated value The value of the property timestamp The timestamp of the property flags The flags of the property Update a single guest property in IMachine 5 76 16 reportVmStatistics void IInternalMachineControl reportVmStatistics in unsigned long validStats in unsigned long cpuUser in unsigned long cpuKernel in unsigned long cpuldle in unsigned long memTotal in unsigned long memFree in unsigned long memBalloon in unsigned long memShared in unsigned long memCache in unsigned long pagedTotal in unsigned long memAllocTotal in unsigned long memFreeTotal in unsigned long memBalloonTotal in unsigned long memSharedTotal in unsigned long vmNetRx in unsigned long vmNetTx 155 5 Classes interfaces validStats Mask defining which parameters are valid For example 0x11 means that cpuldle and XXX are valid Other parameters should be ignored cpuUser Percentage of processor time spent in user mode as seen by the guest cpuKernel Pe
526. u can request the creation of such an object by calling IWebsessionManager getSessionObject More complex management tasks might need mul tiple instances of ISession and each call returns a new one 47 3 Basic VirtualBox concepts some examples This session object must then be used like a mutex semaphore in common programming envi ronments Before you can change machine settings you must write lock the machine by calling IMachine lockMachine with your process s session object After the machine has been locked the ISession machine attribute contains a copy of the original Machine object upon which the session was opened but this copy is mutable you can invoke set methods on it When done making the changes to the machine you must call IMachine saveSettings which will copy the changes you have made from your mutable machine back to the real machine and write them out to the machine settings XML file This will make your changes permanent Finally it is important to always unlock the machine again by calling ISession unlockMachine Otherwise when the calling process end the machine will receive the aborted state which can lead to loss of data So as an example the sequence to change a machine s memory to 1024 MB is something like this IWebsessionManager mgr IVirtualBox vbox mgr logon user pass IMachine machine read only machine ISession session mgr getSessionOb
527. uch device Also enables the USB tablet and mouse devices 6 77 PortMode The PortMode enumeration represents possible communication modes for the virtual serial port device Disconnected Virtual device is not attached to any real host device HostPipe Virtual device is attached to a host pipe HostDevice Virtual device is attached to a host device RawFile Virtual device is attached to a raw file TCP Virtual device is attached to a TCP socket 6 78 ProcessCreateFlag Guest process execution flags Note The values are passed to the guest additions so its not possible to change move or reuse values here See EXECUTEPROCESSFLAG_XXX in GuestControlSvc h None No flag set WaitForProcessStartOnly Only use the specified timeout value to wait for starting the guest process the guest process itself then uses an infinite timeout 359 6 Enumerations enums IgnoreOrphanedProcesses Do not report an error when executed processes are still alive when VBoxService or the guest OS is shutting down Hidden Do not show the started process according to the guest OS guidelines NoProfile Do not use the user s profile data when exeuting a process Only available for Win dows guests WaitForStdOut The guest process waits until all data from stdout is read out WaitForStdErr The guest process waits until all data from stderr is read out ExpandArguments Expands environment variables in process arguments Note This is
528. ues will contain a numerical value that described the operating system in the OVF 328 5 Classes interfaces Name the name to give to the new virtual machine There can be at most one such array item if none is present on import then an automatic name will be created from the operating system type The corresponding item im OVFValues will contain the suggested virtual machine name from the OVF file and aVBoxValues will contain a suggestion for a unique VirtualBox IMachine name that does not exist yet Description an arbitrary description License the EULA section from the OVF if present It is the responsibility of the calling code to display such a license for agreement the Main API does not enforce any such policy Miscellaneous reserved for future use CPU the number of CPUs There can be at most one such item which will presently be ignored Memory the amount of guest RAM in bytes There can be at most one such array item if none is present on import then VirtualBox will set a meaningful default based on the operating system type HardDiskControllerIDE an IDE hard disk controller There can be at most two such items An optional value in OVFValues and aVBoxValues can be PIIX3 or PIIX4 to specify the type of IDE controller this corresponds to the ResourceSubType element which VirtualBox writes into the OVF The matching item in the aRefs array will contain a
529. uest computers not available to anybody else 6 101 VBoxEventType Type of an event See IEvent for an introduction to VirtualBox event handling Invalid Invalid event must be first Any Wildcard for all events Events of this type are never delivered and only used in IEventSource registerListener call to simplify registration Vetoable Wildcard for all vetoable events Events of this type are never delivered and only used in IEventSource registerListener call to simplify registration MachineEvent Wildcard for all machine events Events of this type are never delivered and only used in IEventSource registerListener call to simplify registration SnapshotEvent Wildcard for all snapshot events Events of this type are never delivered and only used in IEventSource registerListener call to simplify registration 367 6 Enumerations enums InputEvent Wildcard for all input device keyboard mouse events Events of this type are never delivered and only used in IEventSource registerListener call to simplify registra tion LastWildcard Last wildcard OnMachineStateChanged See IMachineStateChangedEvent OnMachineDataChanged See IMachineDataChangedEvent OnExtraDataChanged See IExtraDataChangedEvent OnExtraDataCanChange See IExtraDataCanChangeEvent OnMediumRegistered See IMediumRegisteredEvent OnMachineRegistered See IMachineRegisteredEvent OnSessionStateChanged See ISessionStateChangedEvent OnSnapshotTaken S
530. uest process output via ProcessWaitForFlag StdOut and ProcessWaitForFlag StdErr is not implemented yet To wait for process output IProcess read with appropriate flags still can be used to periodically check for new output data to arrive Note that 393 13 Main API change log ProcessCreateFlag WaitForStdOut and or ProcessCreateFlag WaitForStdErr need to be specified when creating a guest process via IGuestSession processCreate or IGuestSession processCreateEx ACL Access Control List handling in general is not implemented yet The LockType enumeration now has an additional value VM which tells IMachine lockMachine Q to create a full blown object structure for running a VM This was the previous behavior with Write which now only creates the minimal object structure to save time and re sources at the moment the Console object is still created but all sub objects such as Display Keyboard Mouse Guest are not Machines can be put in groups actually an array of groups The primary group af fects the default placement of files belonging to a VM IVirtualBox createMachine and IVirtualBox composeMachineFilename have been adjusted accordingly the former tak ing an array of groups as an additional parameter and the latter taking a group as an ad ditional parameter The create option handling has been changed for those two methods too The method IVirtualBox findMedium has been removed since it provide
531. ui progress waitForCompletion 1 mgr closeMachineSession session Following code will print all registered machines and their log folders from vboxapi import VirtualBoxManager mgr VirtualBoxManager None None vbox mgr vbox for m in mgr getArray vbox machines print Machine s logs in s m name m logFolder Code above demonstrates cross platform access to array properties certain limitations prevent one from using vbox machines to access a list of available virtual machines in case of XPCOM and a mechanism of uniform session creation and closing mgr getSession0bject In case you want to use the glue layer with a different Python installation use these steps in a shell to add the necessary files cd VBOX_INSTALL_PATH sdk installer PYTHON vboxapisetup py install 2 3 3 C COM API C is the language that VirtualBox itself is written in so C is the most direct way to use the Main API but it is not necessarily the easiest as using COM and XPCOM has its own set of complications 37 2 Environment specific notes VirtualBox ships with sample programs that demonstrate how to use the Main API to im plement a number of tasks on your host platform These samples can be found in the bindings xpcom samples directory for Linux Mac OS X and Solaris and bindings mscom samples for Windows The two samples are actually different because the one for Windows uses native COM whereas the other uses
532. ular API version the API will not be changed in an incompatible way Note that this guarantee does not apply to development builds and also there is no guarantee that this version is identical to the first two integer numbers of the package version 5 151 1 6 APIRevision read only long long IVirtualBox APIRevision To be defined exactly but we need something that the Validation Kit can use to figure which methods and attributes can safely be used on a continuously changing trunk and occasional branch 5 151 1 7 homeFolder read only wstring IVirtualBox homeFolder Full path to the directory where the global settings file VirtualBox xml is stored In this version of VirtualBox the value of this property is always lt user_dir gt VirtualBox where lt user_dir gt is the path to the user directory as determined by the host OS and cannot be changed This path is also used as the base to resolve relative paths in places where relative paths are allowed unless otherwise expressly indicated 5 151 1 8 settingsFilePath read only wstring IVirtualBox settingsFilePath Full name of the global settings file The value of this property corresponds to the value of homeFolder plus VirtualBox xml 5 151 1 9 host read only IHost IVirtualBox host Associated host object 314 5 Classes interfaces 5 151 1 10 systemProperties read only ISystemProperties IVirtualBox systemProperties Associated system inf
533. ume the execution until the snapshot operation has completed Starting Machine is being started after powering it on from a zero execution state Stopping Machine is being normally stopped powering it off or after the guest OS has initiated a shutdown sequence Saving Machine is saving its execution state to a file Restoring Execution state of the machine is being restored from a file after powering it on from the saved execution state TeleportingPausedVM The machine is being teleported to another host or process but it is not running This is the paused variant of the Teleporting state TeleportingIn Teleporting the machine state in from another host or process FaultTolerantSyncing The machine is being synced with a fault tolerant VM running else where DeletingSnapshotOnline Like DeletingSnapshot but the merging of media is ongoing in the background while the machine is running DeletingSnapshotPaused Like DeletingSnapshotOnline but the machine was paused when the merging of differencing media was started OnlineSnapshotting Like LiveSnapshotting but the machine was paused when the merging of differencing media was started RestoringSnapshot A machine snapshot is being restored this typically does not take long DeletingSnapshot A machine snapshot is being deleted this can take a long time since this may require merging differencing media This value indicates that the machine is not running while the snapshot is bein
534. urned 5 114 4 waitFor ProcessWaitResult IProcess waitFor in unsigned long waitFor in unsigned long timeoutMS waitFor Specifies what to wait for see ProcessWaitForFlag for more information timeoutMS Timeout in ms to wait for the operation to complete Pass O for an infinite timeout Waits for one or more events to happen 5 114 5 waitForArray ProcessWaitResult IProcess waitForArray in ProcessWaitForFlag waitFor in unsigned long timeoutMS waitFor Specifies what to wait for see ProcessWaitForFlag for more information timeoutMS Timeout in ms to wait for the operation to complete Pass 0 for an infinite timeout Waits for one or more events to happen Scriptable version of waitFor 273 5 Classes interfaces 5 114 6 write unsigned long IProcess write in unsigned long handle in unsigned long flags in octet data in unsigned long timeoutMS handle Handle to write to Usually 0 is stdin 1 is stdout and 2 is stderr flags A combination of ProcessInputFlag flags data Array of bytes to write The size of the array also specifies how much to write timeoutMS Timeout in ms to wait for the operation to complete Pass 0 for an infinite timeout Writes data to a running process 5 114 7 writeArray unsigned long IProcess writeArray in unsigned long handle in ProcessInputFlag flags in octet data in unsigned long timeoutMS handle Handle to write to
535. usableEvent 0 0 0000 ee eee eee 115 SSSI ARIUS 5 hack Se Doo SS AAA 116 IGuestMultiTouchEvent IEvent 116 5 55 5 56 Dot 5 58 3 99 5 60 5 61 5 62 5 63 5 64 Contents SAL ADE a a a A we we as A a y 116 IGUESTOSTAPE secc eA SSS aR A AA 117 Bye PORE ba a ee SS eee ee ae a we ee ee we ee ee en s wwe A 117 IGuestProcess Process 120 BG ALES a cece aos a aoe wee dr ae ee Gee ee es 120 IGuestProcessEvent IGuestSessionEvent 0 0 eee ee ee ee 121 GBP a socorre Gia pew oe Bow a a a a les ly ee a a ea 121 IGuestProcessIOEvent IGuestProcessEvent 121 SOS MIDIS cr E aa daa 121 IGuestProcessInputNotifyEvent IGuestProcessIOEvent 121 5 59 1 Atmibutes 2 44 24 8 88 e445 858544 bee ead a 122 IGuestProcessOutputEvent IGuestProcessIOEvent 122 5 60 1 Attributes 2404 2424444488540 4 2 e205 424484 122 IGuestProcessRegisteredEvent IGuestProcessEvent 122 S611 Aributes ooo ooo aaa 122 IGuestProcessStateChangedEvent IGuestProcessEvent 122 SOZI ANDIS cars rr da 122 IGuestPropertyChangedEvent IMachineEvent 2 123 S631 e eb a OO Re ee eae 123 E o ke a ae RS BS EO OR a a ee e A a 123 SO41 ADUS sreci errre rr Edi wee ES EE Eee 124 5 64 2 dlos 2 2 44 sa 880458 24 aaa eE 126 SOLA dment Copy rodri we ee Gee ee 126 5 64 4 directoryCopyFro
536. ution of the virtual machines and making sure they do not conflict with each other or whatever the host computer is doing otherwise On top of the hypervisor additional internal modules provide extra functionality For example the RDP server which can deliver the graphical output of a VM remotely to an RDP client is a separate module that is only loosely tacked into the virtual graphics device Live Migration and Resource Monitor are additional modules currently in the process of being added to VirtualBox What is primarily of interest for purposes of the SDK is the API layer block that sits on top of all the previously mentioned blocks This API which we call the Main APT exposes the entire feature set of the virtualization engine below It is completely documented in this SDK Reference see chapter 5 Classes interfaces page 52 and chapter 6 Enumerations enums page 333 and available to anyone who wishes to control VirtualBox programmatically We chose the name Main API to differentiate it from other programming interfaces of VirtualBox that may be publicly accessible With the Main API you can create configure start stop and delete virtual machines retrieve performance statistics about running VMs configure the VirtualBox installation in general and 21 1 Introduction more In fact internally the front end programs VirtualBox and VBoxManage use nothing but this API as well there are no hidden backdoors i
537. vice offers as described by the WSDL file This is the bit that makes using web services so attractive to client developers if a lan guage s toolkit understands WSDL it can generate large amounts of support code auto matically Clients can then easily use this support code and can be done with just a few lines of code 3 Next compile the clienttest java source javac clienttest java This should yield a clienttest class file 4 To start the VirtualBox web service open a second terminal and change to the directory where the VirtualBox executables are located Then type vboxwebsrv v The web service now waits for connections and will run until you press Ctrl C in this second terminal The v argument causes it to log all connections to the terminal See chapter 1 4 Running the web service page 24 for details on how to run the web service 5 Back in the original terminal where you compiled the Java source run the resulting binary which will then connect to the web service java clienttest The client sample will connect to the web service on localhost but the code could be changed to connect remotely if the web service was running on a different machine and make a number of method calls It will output the version number of your VirtualBox installation and a list of all virtual machines that are currently registered with a bit of seemingly random data which will be explained later 2 2 2 Raw web service
538. vice only not in COM XPCOM Websession manager This provides essential services to webservice clients 5 155 1 getSessionObject ISession IWebsessionManager getSessionObject in IVirtualBox refIVirtualBox reflVirtualBox Returns a managed object reference to a new Session object for every call to this method See also Session 5 155 2 logoff void IWebsessionManager logoff in IVirtualBox refIVirtualBox reflVirtualBox Logs off the client who has previously logged on with logon and destroys all resources as sociated with the websession most importantly all managed objects created in the server while the websession was active 331 5 Classes interfaces 5 155 3 logon IVirtualBox IWebsessionManager Logon in wstring username in wstring password username password Logs a new client onto the webservice and returns a managed object reference to the IVirtu alBox instance which the client can then use as a basis to further queries since all calls to the VirtualBox API are based on the IVirtualBox interface in one way or the other 332 6 Enumerations enums 6 1 AccessMode Access mode for opening files ReadOnly ReadWrite 6 2 AdditionsFacilityClass Guest Additions facility classes None No invalid class Driver Driver Service System service Program Program Feature Feature ThirdParty Third party All All facility classes selected 6 3 AdditionsFacilityS
539. vice type of the attached device For media opened by IVirtualBox 0penMediumo this must match the device type specified there medium Medium to mount or null for an empty drive Attaches a device and optionally mounts a medium to the given storage controller IStorageController identified by name at the indicated port and device This method is intended for managing storage devices in general while a machine is powered off It can be used to attach and detach fixed and removable media The following kind of media can be attached to a machine e For fixed and removable media you can pass in a medium that was previously opened using IVirtualBox openMedium e Only for storage devices supporting removable media such as DVDs and floppies you can also specify a null pointer to indicate an empty drive or one of the medium objects listed in the IHost DVDDrives and IHost floppyDrives arrays to indicate a host drive For removable devices you can also use mountMedium to change the media while the machine is running In a VM s default configuration of virtual machines the secondary master of the IDE controller is used for a CD DVD drive After calling this returns successfully a new instance of IMediumAttachment will appear in the machine s list of medium attachments see mediumAttachments See IMedium and IMediumAttachment for more information about attaching media The specified device slot must not have a device attache
540. xplicitly One example is IVirtualBox createMedium with the empty format argument A more complex example is implicit creation of differencing media when taking a snapshot of a virtual machine this operation will try to use a format of the parent medium first and if this format does not support differencing media the default format specified by this argument will be used The list of supported medium formats may be obtained by the mediumFormats call Note that the default medium format must have a capability to create differencing media otherwise operations that create media implicitly may fail unexpectedly The initial value of this property is VDI in the current version of the VirtualBox product but may change in the future Note Setting this property to null or empty string will restore the initial value See also mediumFormats IMediumFormat id VirtualBox createMedium 5 135 1 18 freeDiskSpaceWarning read write long long ISystemProperties freeDiskSpaceWarning Issue a warning if the free disk space is below or in some disk intensive operation is expected to go below the given size in bytes 5 135 1 19 freeDiskSpacePercentWarning read write unsigned long ISystemProperties freeDiskSpacePercentWarning Issue a warning if the free disk space is below or in some disk intensive operation is expected to go below the given percentage 5 135 1 20 freeDiskSpaceError read write long long ISystemProp
541. y avoiding crashes and memory leaks Often API clients need to handle events so the C API specifics are also described below 2 3 6 3 VirtualBox C API initialization Just like in C the API and the underlying middleware needs to be initialized before it can be used The VBoxCAPI_v4_3 h header provides the interface to the C binding but you can alternatively and more conveniently also include VBoxCAPIGlue h as this avoids the VirtualBox version dependent header file name and makes sure the global variable g_pVBoxFuncs contains a pointer to the structure which contains the helper function pointers Here s how to initialize the C API include VBoxCAPIGlue h IVirtualBoxClient vboxclient NULL IVirtualBox vbox NULL ISession session NULL HRESULT rc ULONG revision N VBoxCGlueInit loads the necessary dynamic library handles errors producing an error message hinting what went wrong and gives you the pointer to the function table g_pVBoxFuncs Once you get the function table then how and which functions to use is explained below o pVBoxFuncs gt pfnClientInitialize does all the necessary startup action and provides us with pointers to an IVirtualBoxClient instance It should be matched by a call to g_pVBoxFuncs gt pfnClientUninitialize when done ee E E ES EE FE N if VBoxCGlueInit fprintf stderr s FATAL VBoxCGlueInit failed s n argv 0 g_szVBoxErrMsg 40 2 Environme
542. y to create This must contain at least one X character The first group of consecutive X characters in the template will be replaced by a random alphanumeric string to produce a unique name mode The UNIX style access mode mask to create the directory with Whether how all three access groups and associated access rights are realized is guest OS dependent The API does the best it can on each OS This parameter is ignore if the secure parameter is set to true Note It is strongly recommended to use 0700 path The path to the directory in which the temporary directory should be created Guest path style secure Whether to fail if the directory can not be securely created Currently this means that another unprivileged user cannot manipulate the path specified or remove the temporary directory after it has been created Also causes the mode specified to be ignored May not be supported on all guest types Creates a temporary directory in the guest If this method fails the following error codes may be reported 127 5 Classes interfaces e VBOX_E_NOT_SUPPORTED The operation is not possible as requested on this particular guest type e E_INVALIDARG Invalid argument This includes an incorrectly formatted template or a non absolute path e VBOX_E_IPRT_ERROR The temporary directory could not be created Possible reasons include a non existing path or an insecure path when the secure option was requested 5
543. your application like this java cp vboxjmscom jar c jacob jacob jar Djava library path c jacob MyProgram SOAP all platforms Java 6 is required as it comes with builtin support for SOAP via the JAX WS library Also the VirtualBox provided vbojws jar must be in the class path In the SOAP case it s possible to create several VirtualBoxManager instances to communicate with multiple VirtualBox hosts Start your application like this java cp vboxjws jar MyProgram Exception handling is also generalized by the generic glue layer so that all methods could throw VBoxException containing human readable text message see getMessage method along with wrapped original exception see getWrapped method 385 11 Using Java API 11 3 Example This example shows a simple use case of the Java API Differences for SOAP vs local version are minimal and limited to the connection setup phase see ws variable In the SOAP case it s possible to create several VirtualBoxManager instances to communicate with multiple VirtualBox hosts import org virtualbox_4_3 x VirtualBoxManager mgr VirtualBoxManager createInstance null boolean ws false or true if we need the SOAP version if ws String url http myhost 18034 String user test String passwd test mgr connect url user passwd IVirtualBox vbox mgr getVBox System out println VirtualBox version get first VM name String m v
544. ys 1 8 Compression optional string equaling gzip if the image is gzip compressed 5 3 1 3 virtualSystemDescriptions read only IVirtualSystemDescription IAppliance virtualSystemDescriptions Array of virtual system descriptions One such description is created for each virtual sys tem machine found in the OVF This array is empty until either interpret for import or IMachine exportTo for export has been called 54 5 Classes interfaces 5 3 1 4 machines read only wstring IAppliance machines Contains the UUIDs of the machines created from the information in this appliances This is only relevant for the import case and will only contain data after a call to importMachines succeeded 5 3 2 addPasswords void IAppliance addPasswords in wstring identifiers in wstring passwords identifiers List of identifiers passwords List of matching passwords Adds a list of passwords required to import or export encrypted virtual machines 5 3 3 createVFSExplorer IVFSExplorer IAppliance createVFSExplorer in wstring URT URI The URI describing the file system to use Returns a IVFSExplorer object for the given URI 5 3 4 getMediumldsForPasswordld uuid IAppliance getMediumIdsForPasswordId in wstring passwordId passwordld The password identifier to get the medium identifiers for Returns a list of medium identifiers which use the given password identifier 5 3 5 getP

SDK documentation - Oracle Software Downloads

Contents

Download Pdf Manuals

Related Search

Related Contents