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. More...
 
void updateMachineState (in MachineState machineState)
 Updates the machine state in the VM process. More...
 
void uninitialize ()
 Uninitializes (closes) this session. More...
 
void onNetworkAdapterChange (in INetworkAdapter networkAdapter, in boolean changeAdapter)
 Triggered when settings of a network adapter of the associated virtual machine have changed. More...
 
void onSerialPortChange (in ISerialPort serialPort)
 Triggered when settings of a serial port of the associated virtual machine have changed. More...
 
void onParallelPortChange (in IParallelPort parallelPort)
 Triggered when settings of a parallel port of the associated virtual machine have changed. More...
 
void onStorageControllerChange ()
 Triggered when settings of a storage controller of the associated virtual machine have changed. More...
 
void onMediumChange (in IMediumAttachment mediumAttachment, in boolean force)
 Triggered when attached media of the associated virtual machine have changed. More...
 
void onStorageDeviceChange (in IMediumAttachment mediumAttachment, in boolean remove, in boolean silent)
 Triggered when attached storage devices of the associated virtual machine have changed. More...
 
void onClipboardModeChange (in ClipboardMode clipboardMode)
 Notification when the shared clipboard mode changes. More...
 
void onDnDModeChange (in DnDMode dndMode)
 Notification when the drag'n drop mode changes. More...
 
void onCPUChange (in unsigned long cpu, in boolean add)
 Notification when a CPU changes. More...
 
void onCPUExecutionCapChange (in unsigned long executionCap)
 Notification when the CPU execution cap changes. More...
 
void onVRDEServerChange (in boolean restart)
 Triggered when settings of the VRDE server object of the associated virtual machine have changed. More...
 
void onVideoCaptureChange ()
 Triggered when video capture settings have changed. More...
 
void onUSBControllerChange ()
 Triggered when settings of the USB controller object of the associated virtual machine have changed. More...
 
void onSharedFolderChange (in boolean global)
 Triggered when a permanent (global or machine) shared folder has been created or removed. More...
 
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. More...
 
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. More...
 
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. More...
 
void onBandwidthGroupChange (in IBandwidthGroup bandwidthGroup)
 Notification when one of the bandwidth groups change. More...
 
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. More...
 
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, time stamps and flags. More...
 
void onlineMergeMedium (in IMediumAttachment mediumAttachment, in unsigned long sourceIdx, in unsigned long targetIdx, in IProgress progress)
 Triggers online merging of a hard disk. More...
 
void reconfigureMediumAttachments (in IMediumAttachment[] attachments)
 Reconfigure all specified medium attachments in one go, making sure the current state corresponds to the specified medium. More...
 
void enableVMMStatistics (in boolean enable)
 Enables or disables collection of VMM RAM statistics. More...
 
void pauseWithReason (in Reason reason)
 Internal method for triggering a VM pause with a specified reason code. More...
 
void resumeWithReason (in Reason reason)
 Internal method for triggering a VM resume with a specified reason code. More...
 
void saveStateWithReason (in Reason reason, in IProgress progress, in wstring stateFilePath, in boolean pauseVM, [retval] out boolean leftPaused)
 Internal method for triggering a VM save state with a specified reason code. More...
 
void cancelSaveStateWithReason ()
 Internal method for cancelling a VM save state. More...
 
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). More...
 
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). More...
 

Public Attributes

readonly attribute unsigned long PID
 PID of the process that has created this Session object. More...
 
readonly attribute IConsole remoteConsole
 Returns the console object suitable for remote control. More...
 
readonly attribute MachineState nominalState
 Returns suitable machine state for the VM execution state. More...
 

Member Function Documentation

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  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.
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
mediumAttachmentThe medium attachment which changed.
forceIf 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
mediumAttachmentThe medium attachment which changed.
removeTRUE if the device is removed, FALSE if it was added.
silentTRUE 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
clipboardModeThe new shared clipboard mode.
void IInternalSessionControl::onDnDModeChange ( in DnDMode  dndMode)

Notification when the drag'n drop mode changes.

Parameters
dndModeThe new mode for drag'n drop.
void IInternalSessionControl::onCPUChange ( in unsigned long  cpu,
in boolean  add 
)

Notification when a CPU changes.

Parameters
cpuThe CPU which changed
addFlag whether the CPU was added or removed
void IInternalSessionControl::onCPUExecutionCapChange ( in unsigned long  executionCap)

Notification when the CPU execution cap changes.

Parameters
executionCapThe 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
restartFlag 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::onVideoCaptureChange ( )

Triggered when video capture settings have changed.

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

Parameters
accessMode0 = get, 1 = set, 2 = delete.
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[]  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, time stamps and flags.

Parameters
patternsThe patterns to match the properties against as a comma-separated string. If this is empty, all properties currently set will be returned.
keysThe key names of the properties returned.
valuesThe values of the properties returned. The array entries match the corresponding entries in the key array.
timestampsThe time stamps of the properties returned. The array entries match the corresponding entries in the key array.
flagsThe 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 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
mediumAttachmentThe medium attachment to identify the medium chain.
sourceIdxThe index of the source image in the chain. Redundant, but drastically reduces IPC.
targetIdxThe index of the target image in the chain. Redundant, but drastically reduces IPC.
progressProgress 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::reconfigureMediumAttachments ( in IMediumAttachment[]  attachments)

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

Parameters
attachmentsArray 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.
void IInternalSessionControl::enableVMMStatistics ( in boolean  enable)

Enables or disables collection of VMM RAM statistics.

Parameters
enableTrue 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
reasonSpecify 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
reasonSpecify 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,
in IProgress  progress,
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
reasonSpecify the best matching reason code please.
progressProgress object to track the operation completion.
stateFilePathFile path the VM process must save the execution state to.
pauseVMThe VM should be paused before saving state. It is automatically unpaused on error in the "vanilla save state" case.
leftPausedReturns 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
void IInternalSessionControl::cancelSaveStateWithReason ( )

Internal method for cancelling a VM save state.

See also
IInternalSessionControl::saveStateWithReason
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.
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

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.

Expected result codes:
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.