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	onRecordingChange (in boolean enable)
	Triggered when recording settings 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	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.

◆ onRecordingChange()

void IInternalSessionControl::onRecordingChange ( in boolean enable )

Triggered when recording settings have changed.

Parameters

enable TODO

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

Public Member Functions

Public Attributes

Member Function Documentation

◆ assignRemoteMachine()

◆ updateMachineState()

◆ uninitialize()

◆ onNetworkAdapterChange()

◆ onAudioAdapterChange()

◆ onHostAudioDeviceChange()

◆ onSerialPortChange()

◆ onParallelPortChange()

◆ onStorageControllerChange()

◆ onMediumChange()

◆ onStorageDeviceChange()

◆ onVMProcessPriorityChange()

◆ onClipboardModeChange()

◆ onClipboardFileTransferModeChange()

◆ onDnDModeChange()

◆ onCPUChange()

◆ onCPUExecutionCapChange()

◆ onVRDEServerChange()

◆ onRecordingChange()

◆ onUSBControllerChange()

◆ onSharedFolderChange()

◆ onGuestDebugControlChange()

◆ onUSBDeviceAttach()

◆ onUSBDeviceDetach()

◆ onShowWindow()

◆ onBandwidthGroupChange()

◆ accessGuestProperty()

◆ enumerateGuestProperties()

◆ onlineMergeMedium()

◆ reconfigureMediumAttachments()

◆ enableVMMStatistics()

◆ pauseWithReason()

◆ resumeWithReason()

◆ saveStateWithReason()

◆ cancelSaveStateWithReason()

◆ assignMachine() [1/2]

◆ assignMachine() [2/2]

Member Data Documentation

◆ PID

◆ remoteConsole

◆ nominalState