| VirtualBox Main API
    | 
 
 | Public Member Functions | |
| void | assignRemoteMachine (in IMachine machine, in IConsole console) | 
| Assigns the machine and the (remote) console object associated with this remote-type session. | |
| void | updateMachineState (in MachineState machineState) | 
| Updates the machine state in the VM process. | |
| void | uninitialize () | 
| Uninitializes (closes) this session. | |
| void | onNetworkAdapterChange (in INetworkAdapter networkAdapter, in boolean changeAdapter) | 
| Triggered when settings of a network adapter of the associated virtual machine have changed. | |
| void | onAudioAdapterChange (in IAudioAdapter audioAdapter) | 
| Triggerd when settings of the audio adapter of the associated virtual machine have changed. | |
| void | onHostAudioDeviceChange (in IHostAudioDevice device, in boolean isNew, in AudioDeviceState state, in IVirtualBoxErrorInfo errorInfo) | 
| Triggerd when the state of a host audio device has changed. | |
| void | onSerialPortChange (in ISerialPort serialPort) | 
| Triggered when settings of a serial port of the associated virtual machine have changed. | |
| void | onParallelPortChange (in IParallelPort parallelPort) | 
| Triggered when settings of a parallel port of the associated virtual machine have changed. | |
| void | onStorageControllerChange (in wstringUUID machineId, in wstring controllerName) | 
| Triggered when settings of a storage controller of the associated virtual machine have changed. | |
| void | onMediumChange (in IMediumAttachment mediumAttachment, in boolean force) | 
| Triggered when attached media of the associated virtual machine have changed. | |
| void | onStorageDeviceChange (in IMediumAttachment mediumAttachment, in boolean remove, in boolean silent) | 
| Triggered when attached storage devices of the associated virtual machine have changed. | |
| void | onVMProcessPriorityChange (in VMProcPriority priority) | 
| Triggered when process priority of the associated virtual machine have changed. | |
| void | onClipboardModeChange (in ClipboardMode clipboardMode) | 
| Notification when the shared clipboard mode changes. | |
| void | onClipboardFileTransferModeChange (in boolean enabled) | 
| Notification when the shared clipboard file transfers mode changes. | |
| void | onDnDModeChange (in DnDMode dndMode) | 
| Notification when the drag'n drop mode changes. | |
| void | onCPUChange (in unsigned long cpu, in boolean add) | 
| Notification when a CPU changes. | |
| void | onCPUExecutionCapChange (in unsigned long executionCap) | 
| Notification when the CPU execution cap changes. | |
| void | onVRDEServerChange (in boolean restart) | 
| Triggered when settings of the VRDE server object of the associated virtual machine have changed. | |
| void | onRecordingStateChange (in boolean enabled, out IProgress progress) | 
| Triggered when a recording state got changed. | |
| void | onRecordingScreenStateChange (in boolean enabled, in unsigned long screen) | 
| Triggered when a recording screen state got changed. | |
| void | onUSBControllerChange () | 
| Triggered when settings of the USB controller object of the associated virtual machine have changed. | |
| void | onSharedFolderChange (in boolean global) | 
| Triggered when a permanent (global or machine) shared folder has been created or removed. | |
| void | onGuestDebugControlChange (in IGuestDebugControl guestDebugControl) | 
| Triggered when settings of the guest debug settings of the associated virtual machine have changed. | |
| void | onUSBDeviceAttach (in IUSBDevice device, in IVirtualBoxErrorInfo error, in unsigned long maskedInterfaces, in wstring captureFilename) | 
| Triggered when a request to capture a USB device (as a result of matched USB filters or direct call to IConsole::attachUSBDevice) has completed. | |
| void | onUSBDeviceDetach (in wstringUUID id, in IVirtualBoxErrorInfo error) | 
| Triggered when a request to release the USB device (as a result of machine termination or direct call to IConsole::detachUSBDevice) has completed. | |
| void | onShowWindow (in boolean check, out boolean canShow, out long long winId) | 
| Called by IMachine::canShowConsoleWindow and by IMachine::showConsoleWindow in order to notify console listeners ICanShowWindowEvent and IShowWindowEvent. | |
| void | onBandwidthGroupChange (in IBandwidthGroup bandwidthGroup) | 
| Notification when one of the bandwidth groups change. | |
| void | accessGuestProperty (in wstring name, in wstring value, in wstring flags, in unsigned long accessMode, out wstring retValue, out long long retTimestamp, out wstring retFlags) | 
| Called by IMachine::getGuestProperty and by IMachine::setGuestProperty in order to read and modify guest properties. | |
| void | enumerateGuestProperties (in wstring patterns, out wstring[] keys, out wstring[] values, out long long[] timestamps, out wstring[] flags) | 
| Return a list of the guest properties matching a set of patterns along with their values, timestamps and flags. | |
| void | onlineMergeMedium (in IMediumAttachment mediumAttachment, in unsigned long sourceIdx, in unsigned long targetIdx, in IProgress progress) | 
| Triggers online merging of a hard disk. | |
| void | reconfigureMediumAttachments (in IMediumAttachment[] attachments) | 
| Reconfigure all specified medium attachments in one go, making sure the current state corresponds to the specified medium. | |
| void | enableVMMStatistics (in boolean enable) | 
| Enables or disables collection of VMM RAM statistics. | |
| void | pauseWithReason (in Reason reason) | 
| Internal method for triggering a VM pause with a specified reason code. | |
| void | resumeWithReason (in Reason reason) | 
| Internal method for triggering a VM resume with a specified reason code. | |
| void | saveStateWithReason (in Reason reason, in IProgress progress, in ISnapshot snapshot, in wstring stateFilePath, in boolean pauseVM, [retval] out boolean leftPaused) | 
| Internal method for triggering a VM save state with a specified reason code. | |
| void | cancelSaveStateWithReason () | 
| Internal method for cancelling a VM save state. | |
| void | assignMachine (in IMachine machine, in LockType lockType, in wstring tokenId) | 
| Assigns the machine object associated with this direct-type session or informs the session that it will be a remote one (if machine == null). | |
| void | assignMachine (in IMachine machine, in LockType lockType, in IToken token) | 
| Assigns the machine object associated with this direct-type session or informs the session that it will be a remote one (if machine == null). | |
| Public Attributes | |
| readonly attribute unsigned long | PID | 
| PID of the process that has created this Session object. | |
| readonly attribute IConsole | remoteConsole | 
| Returns the console object suitable for remote control. | |
| readonly attribute MachineState | nominalState | 
| Returns suitable machine state for the VM execution state. | |
Assigns the machine and the (remote) console object associated with this remote-type session.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| void IInternalSessionControl::updateMachineState | ( | in MachineState | machineState | ) | 
Updates the machine state in the VM process.
Must be called only in certain cases (see the method implementation).
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::uninitialize | ( | ) | 
Uninitializes (closes) this session.
Used by VirtualBox to close the corresponding remote session when the direct session dies or gets closed.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| void IInternalSessionControl::onNetworkAdapterChange | ( | in INetworkAdapter | networkAdapter, | 
| in boolean | changeAdapter | ||
| ) | 
Triggered when settings of a network adapter of the associated virtual machine have changed.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onAudioAdapterChange | ( | in IAudioAdapter | audioAdapter | ) | 
Triggerd when settings of the audio adapter of the associated virtual machine have changed.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onHostAudioDeviceChange | ( | in IHostAudioDevice | device, | 
| in boolean | isNew, | ||
| in AudioDeviceState | state, | ||
| in IVirtualBoxErrorInfo | errorInfo | ||
| ) | 
Triggerd when the state of a host audio device has changed.
| device | Device the state has been changed for. | 
| isNew | Whether this is a newly detected device or not. | 
| state | The new device state. | 
| errorInfo | Error information. | 
| void IInternalSessionControl::onSerialPortChange | ( | in ISerialPort | serialPort | ) | 
Triggered when settings of a serial port of the associated virtual machine have changed.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onParallelPortChange | ( | in IParallelPort | parallelPort | ) | 
Triggered when settings of a parallel port of the associated virtual machine have changed.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onStorageControllerChange | ( | in wstringUUID | machineId, | 
| in wstring | controllerName | ||
| ) | 
Triggered when settings of a storage controller of the associated virtual machine have changed.
| machineId | The id of the machine containing the storage controller. | 
| controllerName | The name of the storage controller. | 
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onMediumChange | ( | in IMediumAttachment | mediumAttachment, | 
| in boolean | force | ||
| ) | 
Triggered when attached media of the associated virtual machine have changed.
| mediumAttachment | The medium attachment which changed. | 
| force | If the medium change was forced. | 
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onStorageDeviceChange | ( | in IMediumAttachment | mediumAttachment, | 
| in boolean | remove, | ||
| in boolean | silent | ||
| ) | 
Triggered when attached storage devices of the associated virtual machine have changed.
| 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. | 
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onVMProcessPriorityChange | ( | in VMProcPriority | priority | ) | 
Triggered when process priority of the associated virtual machine have changed.
| priority | The priority which set. | 
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| VBOX_E_VM_ERROR | Error from underlying level. See additional error info. | 
| void IInternalSessionControl::onClipboardModeChange | ( | in ClipboardMode | clipboardMode | ) | 
Notification when the shared clipboard mode changes.
| clipboardMode | The new shared clipboard mode. | 
| void IInternalSessionControl::onClipboardFileTransferModeChange | ( | in boolean | enabled | ) | 
Notification when the shared clipboard file transfers mode changes.
| enabled | Flag whether clipboard file transfers are allowed or not. | 
| void IInternalSessionControl::onDnDModeChange | ( | in DnDMode | dndMode | ) | 
Notification when the drag'n drop mode changes.
| dndMode | The new mode for drag'n drop. | 
| void IInternalSessionControl::onCPUChange | ( | in unsigned long | cpu, | 
| in boolean | add | ||
| ) | 
Notification when a CPU changes.
| cpu | The CPU which changed | 
| add | Flag whether the CPU was added or removed | 
| void IInternalSessionControl::onCPUExecutionCapChange | ( | in unsigned long | executionCap | ) | 
Notification when the CPU execution cap changes.
| executionCap | The new CPU execution cap value. (1-100) | 
| void IInternalSessionControl::onVRDEServerChange | ( | in boolean | restart | ) | 
Triggered when settings of the VRDE server object of the associated virtual machine have changed.
| restart | Flag whether the server must be restarted | 
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onRecordingStateChange | ( | in boolean | enabled, | 
| out IProgress | progress | ||
| ) | 
Triggered when a recording state got changed.
| enabled | Whether recording was enabled or disabled. | 
| progress | Progress object. | 
| void IInternalSessionControl::onRecordingScreenStateChange | ( | in boolean | enabled, | 
| in unsigned long | screen | ||
| ) | 
Triggered when a recording screen state got changed.
| enabled | Whether recording for that screen was enabled or disabled. | 
| screen | Number of screen for which the event has happened. | 
| void IInternalSessionControl::onUSBControllerChange | ( | ) | 
Triggered when settings of the USB controller object of the associated virtual machine have changed.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onSharedFolderChange | ( | in boolean | global | ) | 
Triggered when a permanent (global or machine) shared folder has been created or removed.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onGuestDebugControlChange | ( | in IGuestDebugControl | guestDebugControl | ) | 
Triggered when settings of the guest debug settings of the associated virtual machine have changed.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onUSBDeviceAttach | ( | in IUSBDevice | device, | 
| in IVirtualBoxErrorInfo | error, | ||
| in unsigned long | maskedInterfaces, | ||
| in wstring | captureFilename | ||
| ) | 
Triggered when a request to capture a USB device (as a result of matched USB filters or direct call to IConsole::attachUSBDevice) has completed.
A null error object means success, otherwise it describes a failure.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onUSBDeviceDetach | ( | in wstringUUID | id, | 
| in IVirtualBoxErrorInfo | 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 null error object means success, otherwise it describes a failure.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onShowWindow | ( | in boolean | check, | 
| out boolean | canShow, | ||
| out long long | winId | ||
| ) | 
Called by IMachine::canShowConsoleWindow and by IMachine::showConsoleWindow in order to notify console listeners ICanShowWindowEvent and IShowWindowEvent.
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::onBandwidthGroupChange | ( | in IBandwidthGroup | bandwidthGroup | ) | 
Notification when one of the bandwidth groups change.
| bandwidthGroup | The bandwidth group which changed. | 
| 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 | ||
| ) | 
Called by IMachine::getGuestProperty and by IMachine::setGuestProperty in order to read and modify guest properties.
| name | Name of guest property. | 
| value | Value of guest property. | 
| flags | Flags of guest property. | 
| accessMode | 0 = get, 1 = set, 2 = delete. | 
| retValue | When getting: Value of guest property. | 
| retTimestamp | When getting: Timestamp of guest property. | 
| retFlags | When getting: Flags of guest property. | 
| VBOX_E_INVALID_VM_STATE | Machine session is not open. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type is not direct. | 
| void IInternalSessionControl::enumerateGuestProperties | ( | in wstring | patterns, | 
| out wstring[] | keys, | ||
| out wstring[] | values, | ||
| out long long[] | timestamps, | ||
| out wstring[] | flags | ||
| ) | 
Return a list of the guest properties matching a set of patterns along with their values, timestamps and 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 timestamps of the properties returned. The array entries match the corresponding entries in the key array. | 
| flags | The flags of the properties returned. The array entries match the corresponding entries in the key array. | 
| VBOX_E_INVALID_VM_STATE | Machine session is not open. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type is not direct. | 
| void IInternalSessionControl::onlineMergeMedium | ( | in IMediumAttachment | mediumAttachment, | 
| in unsigned long | sourceIdx, | ||
| in unsigned long | targetIdx, | ||
| in IProgress | progress | ||
| ) | 
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.
| mediumAttachment | The medium attachment to identify the medium chain. | 
| sourceIdx | The index of the source image in the chain. Redundant, but drastically reduces IPC. | 
| targetIdx | The index of the target image in the chain. Redundant, but drastically reduces IPC. | 
| progress | Progress object for this operation. | 
| VBOX_E_INVALID_VM_STATE | Machine session is not open. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type is not direct. | 
| void IInternalSessionControl::reconfigureMediumAttachments | ( | in IMediumAttachment[] | attachments | ) | 
Reconfigure all specified medium attachments in one go, making sure the current state corresponds to the specified medium.
| attachments | Array containing the medium attachments which need to be reconfigured. | 
| VBOX_E_INVALID_VM_STATE | Machine session is not open. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type is not direct. | 
| void IInternalSessionControl::enableVMMStatistics | ( | in boolean | enable | ) | 
Enables or disables collection of VMM RAM statistics.
| enable | True enables statistics collection. | 
| VBOX_E_INVALID_VM_STATE | Machine session is not open. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type is not direct. | 
| void IInternalSessionControl::pauseWithReason | ( | in Reason | reason | ) | 
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.
| reason | Specify the best matching reason code please. | 
| VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state. | 
| VBOX_E_VM_ERROR | Virtual machine error in suspend operation. | 
| void IInternalSessionControl::resumeWithReason | ( | in Reason | reason | ) | 
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.
| reason | Specify the best matching reason code please. | 
| VBOX_E_INVALID_VM_STATE | Virtual machine not in Paused state. | 
| VBOX_E_VM_ERROR | Virtual machine error in resume operation. | 
| void IInternalSessionControl::saveStateWithReason | ( | in Reason | reason, | 
| in IProgress | progress, | ||
| in ISnapshot | snapshot, | ||
| in wstring | stateFilePath, | ||
| in boolean | pauseVM, | ||
| [retval] out boolean | leftPaused | ||
| ) | 
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 appropriately (and has to set the follow-up machine state if this call failed).
| reason | Specify the best matching reason code please. | 
| progress | Progress object to track the operation completion. | 
| snapshot | Snapshot object for which this save state operation is executed. | 
| 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. | 
| leftPaused | Returns if the VM was left in paused state, which is necessary in many situations (snapshots, teleportation). | 
| VBOX_E_INVALID_VM_STATE | Virtual machine state is not one of the expected values. | 
| VBOX_E_FILE_ERROR | Failed to create directory for saved state file. | 
| void IInternalSessionControl::cancelSaveStateWithReason | ( | ) | 
Internal method for cancelling a VM save state.
| void IInternalSessionControl::assignMachine | ( | in IMachine | machine, | 
| in LockType | lockType, | ||
| in wstring | tokenId | ||
| ) | 
Assigns the machine object associated with this direct-type session or informs the session that it will be a remote one (if machine == null). 
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| void IInternalSessionControl::assignMachine | ( | in IMachine | machine, | 
| in LockType | lockType, | ||
| in IToken | token | ||
| ) | 
Assigns the machine object associated with this direct-type session or informs the session that it will be a remote one (if machine == null). 
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| readonly attribute unsigned long IInternalSessionControl::PID | 
PID of the process that has created this Session object.
| readonly attribute IConsole IInternalSessionControl::remoteConsole | 
Returns the console object suitable for remote control.
| VBOX_E_INVALID_VM_STATE | Session state prevents operation. | 
| VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation. | 
| readonly attribute MachineState IInternalSessionControl::nominalState | 
Returns suitable machine state for the VM execution state.
Useful for choosing a sensible machine state after a complex operation which failed or otherwise resulted in an unclear situation.