VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IInternalSessionControl Interface Reference
Inheritance diagram for IInternalSessionControl:

## 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 RecordingState state, out IProgress progress)
| Triggered when a recording state got changed.
void | onRecordingScreenStateChange (in RecordingState state, 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.

## Member Function Documentation

## ◆ assignRemoteMachine()

void IInternalSessionControl::assignRemoteMachine | ( | in IMachine | machine,
|  | in IConsole | console
| ) |  |

Assigns the machine and the (remote) console object associated with this remote-type session.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.

## ◆ updateMachineState()

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).

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ uninitialize()

void IInternalSessionControl::uninitialize | ( |  | ) |

Uninitializes (closes) this session.

Used by VirtualBox to close the corresponding remote session when the direct session dies or gets closed.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.

## ◆ onNetworkAdapterChange()

void IInternalSessionControl::onNetworkAdapterChange | ( | in INetworkAdapter | networkAdapter,
|  | in boolean | changeAdapter
| ) |  |

Triggered when settings of a network adapter of the associated virtual machine have changed.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onAudioAdapterChange()

void IInternalSessionControl::onAudioAdapterChange | ( | in IAudioAdapter | audioAdapter | ) |

Triggerd when settings of the audio adapter of the associated virtual machine have changed.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onHostAudioDeviceChange()

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.

Parameters

  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.

## ◆ onSerialPortChange()

void IInternalSessionControl::onSerialPortChange | ( | in ISerialPort | serialPort | ) |

Triggered when settings of a serial port of the associated virtual machine have changed.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onParallelPortChange()

void IInternalSessionControl::onParallelPortChange | ( | in IParallelPort | parallelPort | ) |

Triggered when settings of a parallel port of the associated virtual machine have changed.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onStorageControllerChange()

void IInternalSessionControl::onStorageControllerChange | ( | in wstringUUID | machineId,
|  | in wstring | controllerName
| ) |  |

Triggered when settings of a storage controller of the associated virtual machine have changed.

Parameters

  machineId | The id of the machine containing the storage controller.
  controllerName | The name of the storage controller.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onMediumChange()

void IInternalSessionControl::onMediumChange | ( | in IMediumAttachment | mediumAttachment,
|  | in boolean | force
| ) |  |

Triggered when attached media of the associated virtual machine have changed.

Parameters

  mediumAttachment | The medium attachment which changed.
  force | If the medium change was forced.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onStorageDeviceChange()

void IInternalSessionControl::onStorageDeviceChange | ( | in IMediumAttachment | mediumAttachment,
|  | in boolean | remove,
|  | in boolean | silent
| ) |  |

Triggered when attached storage devices of the associated virtual machine have changed.

Parameters

  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.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onVMProcessPriorityChange()

void IInternalSessionControl::onVMProcessPriorityChange | ( | in VMProcPriority | priority | ) |

Triggered when process priority of the associated virtual machine have changed.

Parameters

  priority | The priority which set.

Expected result codes:

  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.

## ◆ onClipboardModeChange()

void IInternalSessionControl::onClipboardModeChange | ( | in ClipboardMode | clipboardMode | ) |

Notification when the shared clipboard mode changes.

Parameters

  clipboardMode | The new shared clipboard mode.

## ◆ onClipboardFileTransferModeChange()

void IInternalSessionControl::onClipboardFileTransferModeChange | ( | in boolean | enabled | ) |

Notification when the shared clipboard file transfers mode changes.

Parameters

  enabled | Flag whether clipboard file transfers are allowed or not.

## ◆ onDnDModeChange()

void IInternalSessionControl::onDnDModeChange | ( | in DnDMode | dndMode | ) |

Notification when the drag'n drop mode changes.

Parameters

  dndMode | The new mode for drag'n drop.

## ◆ onCPUChange()

void IInternalSessionControl::onCPUChange | ( | in unsigned long | cpu,
|  | in boolean | add
| ) |  |

Notification when a CPU changes.

Parameters

  cpu | The CPU which changed
  add | Flag whether the CPU was added or removed

## ◆ onCPUExecutionCapChange()

void IInternalSessionControl::onCPUExecutionCapChange | ( | in unsigned long | executionCap | ) |

Notification when the CPU execution cap changes.

Parameters

  executionCap | The new CPU execution cap value. (1-100)

## ◆ onVRDEServerChange()

void IInternalSessionControl::onVRDEServerChange | ( | in boolean | restart | ) |

Triggered when settings of the VRDE server object of the associated virtual machine have changed.

Parameters

  restart | Flag whether the server must be restarted

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onRecordingStateChange()

void IInternalSessionControl::onRecordingStateChange | ( | in RecordingState | state,
|  | out IProgress | progress
| ) |  |

Triggered when a recording state got changed.

Parameters

  state | Whether recording was enabled or disabled.
  progress | Progress object.

## ◆ onRecordingScreenStateChange()

void IInternalSessionControl::onRecordingScreenStateChange | ( | in RecordingState | state,
|  | in unsigned long | screen
| ) |  |

Triggered when a recording screen state got changed.

Parameters

  state | Whether recording for that screen was enabled or disabled.
  screen | Number of screen for which the event has happened.

## ◆ onUSBControllerChange()

void IInternalSessionControl::onUSBControllerChange | ( |  | ) |

Triggered when settings of the USB controller object of the associated virtual machine have changed.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onSharedFolderChange()

void IInternalSessionControl::onSharedFolderChange | ( | in boolean | global | ) |

Triggered when a permanent (global or machine) shared folder has been created or removed.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

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.

## ◆ onGuestDebugControlChange()

void IInternalSessionControl::onGuestDebugControlChange | ( | in IGuestDebugControl | guestDebugControl | ) |

Triggered when settings of the guest debug settings of the associated virtual machine have changed.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onUSBDeviceAttach()

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.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onUSBDeviceDetach()

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.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onShowWindow()

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.

Expected result codes:

  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ onBandwidthGroupChange()

void IInternalSessionControl::onBandwidthGroupChange | ( | in IBandwidthGroup | bandwidthGroup | ) |

Notification when one of the bandwidth groups change.

Parameters

  bandwidthGroup | The bandwidth group which changed.

## ◆ 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
| ) |  |

Called by IMachine::getGuestProperty and by IMachine::setGuestProperty in order to read and modify guest properties.

Parameters

  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.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.
  VBOX_E_INVALID_OBJECT_STATE | Session type is not direct.

## ◆ enumerateGuestProperties()

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.

Parameters

  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.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.
  VBOX_E_INVALID_OBJECT_STATE | Session type is not direct.

## ◆ onlineMergeMedium()

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.

Parameters

  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.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.
  VBOX_E_INVALID_OBJECT_STATE | Session type is not direct.

## ◆ reconfigureMediumAttachments()

void IInternalSessionControl::reconfigureMediumAttachments | ( | in IMediumAttachment[] | attachments | ) |

Reconfigure all specified medium attachments in one go, making sure the current state corresponds to the specified medium.

Parameters

  attachments | Array containing the medium attachments which need to be reconfigured.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.
  VBOX_E_INVALID_OBJECT_STATE | Session type is not direct.

## ◆ enableVMMStatistics()

void IInternalSessionControl::enableVMMStatistics | ( | in boolean | enable | ) |

Enables or disables collection of VMM RAM statistics.

Parameters

  enable | True enables statistics collection.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.
  VBOX_E_INVALID_OBJECT_STATE | Session type is not direct.

## ◆ pauseWithReason()

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.

Parameters

  reason | Specify the best matching reason code please.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine not in Running state.
  VBOX_E_VM_ERROR | Virtual machine error in suspend operation.

See also
  IConsole::pause

## ◆ resumeWithReason()

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.

Parameters

  reason | Specify the best matching reason code please.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine not in Paused state.
  VBOX_E_VM_ERROR | Virtual machine error in resume operation.

See also
  IConsole::resume

## ◆ saveStateWithReason()

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).

Parameters

  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).

Expected result codes:

  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.

See also
  IMachine::saveState

## ◆ cancelSaveStateWithReason()

void IInternalSessionControl::cancelSaveStateWithReason | ( |  | ) |

Internal method for cancelling a VM save state.

See also
  IInternalSessionControl::saveStateWithReason

## ◆ assignMachine() [1/2]

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`).

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ assignMachine() [2/2]

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`).

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## Member Data Documentation

## ◆ PID

readonly attribute unsigned long IInternalSessionControl::PID

PID of the process that has created this Session object.

## ◆ remoteConsole

readonly attribute IConsole IInternalSessionControl::remoteConsole

Returns the console object suitable for remote control.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Session state prevents operation.
  VBOX_E_INVALID_OBJECT_STATE | Session type prevents operation.

## ◆ nominalState

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.