Public Member Functions

# IInternalSessionControl Interface Reference

List of all members.

## Public Member Functions
void | getPID ([retval] out unsigned long pid)
| PID of the process that has created this Session object.
void | getRemoteConsole ([retval] out IConsole console)
| Returns the console object suitable for remote control.
void | assignMachine (in IMachine machine, in LockType lockType)
| 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 | 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 aMachineState)
| 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 | 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 ()
| 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 | onClipboardModeChange (in ClipboardMode clipboardMode)
| Notification when the shared clipboard mode changes.
void | onDragAndDropModeChange (in DragAndDropMode dragAndDropMode)
| 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 | 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 | onUSBDeviceAttach (in IUSBDevice device, in IVirtualBoxErrorInfo error, in unsigned long maskedInterfaces)
| 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 boolean isSetter, 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[] key, out wstring[] value, out long long[] timestamp, out wstring[] flags)
| Return a list of the guest properties matching a set of patterns along with their values, time stamps and flags.
void | onlineMergeMedium (in IMediumAttachment mediumAttachment, in unsigned long sourceIdx, in unsigned long targetIdx, in IMedium source, in IMedium target, in boolean mergeForward, in IMedium parentForTarget, in IMedium[] childrenToReparent, in IProgress progress)
| Triggers online merging of a hard disk.
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,[retval] out IProgress progress)
| Internal method for triggering a VM save state with a specified reason code.

## Member Function Documentation

void IInternalSessionControl::getPID | ( | [retval] out unsigned long | pid | ) |

PID of the process that has created this Session object.

void IInternalSessionControl::getRemoteConsole | ( | [retval] out IConsole | console | ) |

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.

void IInternalSessionControl::assignMachine | ( | in IMachine | machine,
|  | in LockType | lockType |
| ) |  |  |

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.

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.

void IInternalSessionControl::updateMachineState | ( | in MachineState | aMachineState | ) |

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.

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.

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.

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.

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.

void IInternalSessionControl::onStorageControllerChange | ( |  | ) |

Triggered when settings of a storage controller 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.

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.

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.

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

Notification when the shared clipboard mode changes.

Parameters:

  | clipboardMode | The new shared clipboard mode.

void IInternalSessionControl::onDragAndDropModeChange | ( | in DragAndDropMode | dragAndDropMode | ) |

Notification when the drag'n'drop mode changes.

Parameters:

  | dragAndDropMode | The new mode for drag'n'drop.

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

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

Notification when the CPU execution cap changes.

Parameters:

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

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.

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.

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.

void IInternalSessionControl::onUSBDeviceAttach | ( | in IUSBDevice | device,
|  | in IVirtualBoxErrorInfo | error,
|  | in unsigned long | maskedInterfaces |
| ) |  |  |

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.

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.

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.

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

Notification when one of the bandwidth groups change.

Parameters:

  | bandwidthGroup | The bandwidth group which changed.

void IInternalSessionControl::accessGuestProperty | ( | in wstring | name,
|  | in wstring | value,
|  | in wstring | flags,
|  | in boolean | isSetter,
|  | 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.

Expected result codes:

  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[] | key,
|  | out wstring[] | value,
|  | out long long[] | timestamp,
|  | out wstring[] | flags |
| ) |  |  |

Return a list of the guest properties matching a set of patterns along with their values, time stamps 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.
  | key | The key names of the properties returned.
  | value | The values of the properties returned. The array entries match the corresponding entries in the key array.
  | timestamp | The time stamps 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.

void IInternalSessionControl::onlineMergeMedium | ( | in IMediumAttachment | mediumAttachment,
|  | in unsigned long | sourceIdx,
|  | in unsigned long | targetIdx,
|  | in IMedium | source,
|  | in IMedium | target,
|  | in boolean | mergeForward,
|  | in IMedium | parentForTarget,
|  | in IMedium[] | childrenToReparent,
|  | 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.
  | source | Merge source medium.
  | target | Merge target medium.
  | mergeForward | Merge direction.
  | parentForTarget | For forward merges: new parent for target medium.
  | childrenToReparent | For backward merges: list of media which need their parent UUID updated.
  | 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.

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.

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

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

void IInternalSessionControl::saveStateWithReason | ( | in Reason | reason,
|  | [retval] out IProgress | progress |
| ) |  |  |

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.

Parameters:

  | reason | Specify the best matching reason code please.
  | progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine state neither Running nor Paused.
  VBOX_E_FILE_ERROR | Failed to create directory for saved state file.

See also:
  IConsole::saveState