Public Member Functions

IInternalMachineControl Interface Reference

List of all members.

Public Member Functions

void setRemoveSavedStateFile (in boolean remove)
 Updates the flag whether the saved state file is removed on a machine state change from Saved to PoweredOff.
void updateState (in MachineState state)
 Updates the VM state.
void beginPowerUp (in IProgress progress)
 Tells VBoxSVC that IConsole::powerUp is under ways and gives it the progress object that should be part of any pending IMachine::launchVMProcess operations.
void endPowerUp (in long result)
 Tells VBoxSVC that IConsole::powerUp has completed.
void beginPoweringDown (out IProgress progress)
 Called by the VM process to inform the server it wants to stop the VM execution and power down.
void endPoweringDown (in long result, in wstring errMsg)
 Called by the VM process to inform the server that powering down previously requested by beginPoweringDown is either successfully finished or there was a failure.
void runUSBDeviceFilters (in IUSBDevice device, out boolean matched, out unsigned long maskedInterfaces)
 Asks the server to run USB devices filters of the associated machine against the given USB device and tell if there is a match.
void captureUSBDevice (in wstringUUID id)
 Requests a capture of the given host USB device.
void detachUSBDevice (in wstringUUID id, in boolean done)
 Notification that a VM is going to detach (done = false) or has already detached (done = true) the given USB device.
void autoCaptureUSBDevices ()
 Requests a capture all matching USB devices attached to the host.
void detachAllUSBDevices (in boolean done)
 Notification that a VM that is being powered down.
void onSessionEnd (in ISession session,[retval] out IProgress progress)
 Triggered by the given session object when the session is about to close normally.
void beginSavingState (out IProgress progress, out wstring stateFilePath)
 Called by the VM process to inform the server it wants to save the current state and stop the VM execution.
void endSavingState (in long result, in wstring errMsg)
 Called by the VM process to inform the server that saving the state previously requested by beginSavingState is either successfully finished or there was a failure.
void adoptSavedState (in wstring savedStateFile)
 Gets called by IConsole::adoptSavedState.
void beginTakingSnapshot (in IConsole initiator, in wstring name, in wstring description, in IProgress consoleProgress, in boolean fTakingSnapshotOnline, out wstring stateFilePath)
 Called from the VM process to request from the server to perform the server-side actions of creating a snapshot (creating differencing images and the snapshot object).
void endTakingSnapshot (in boolean success)
 Called by the VM process to inform the server that the snapshot previously requested by beginTakingSnapshot is either successfully taken or there was a failure.
void deleteSnapshot (in IConsole initiator, in wstringUUID startId, in wstringUUID endId, in boolean deleteAllChildren, out MachineState machineState,[retval] out IProgress progress)
 Gets called by IConsole::deleteSnapshot, IConsole::deleteSnapshotAndAllChildren and IConsole::deleteSnapshotRange.
void finishOnlineMergeMedium ()
 Gets called by IInternalSessionControl::onlineMergeMedium.
void restoreSnapshot (in IConsole initiator, in ISnapshot snapshot, out MachineState machineState,[retval] out IProgress progress)
 Gets called by IConsole::restoreSnapshot.
void pullGuestProperties (out wstring[] names, out wstring[] values, out long long[] timestamps, out wstring[] flags)
 Get the list of the guest properties matching a set of patterns along with their values, time stamps and flags and give responsibility for managing properties to the console.
void pushGuestProperty (in wstring name, in wstring value, in long long timestamp, in wstring flags)
 Update a single guest property in IMachine.
void lockMedia ()
 Locks all media attached to the machine for writing and parents of attached differencing media (if any) for reading.
void unlockMedia ()
 Unlocks all media previously locked using IInternalMachineControl::lockMedia.
void ejectMedium (in IMediumAttachment attachment,[retval] out IMediumAttachment newAttachment)
 Tells VBoxSVC that the guest has ejected the medium associated with the medium attachment.
void reportVmStatistics (in unsigned long validStats, in unsigned long cpuUser, in unsigned long cpuKernel, in unsigned long cpuIdle, in unsigned long memTotal, in unsigned long memFree, in unsigned long memBalloon, in unsigned long memShared, in unsigned long memCache, in unsigned long pagedTotal, in unsigned long memAllocTotal, in unsigned long memFreeTotal, in unsigned long memBalloonTotal, in unsigned long memSharedTotal, in unsigned long vmNetRx, in unsigned long vmNetTx)
 Passes statistics collected by VM (including guest statistics) to VBoxSVC.

Member Function Documentation

void IInternalMachineControl::setRemoveSavedStateFile ( in boolean  remove  ) 

Updates the flag whether the saved state file is removed on a machine state change from Saved to PoweredOff.

void IInternalMachineControl::updateState ( in MachineState  state  ) 

Updates the VM state.

Note:
This operation will also update the settings file with the correct information about the saved state file and delete this file from disk when appropriate.
void IInternalMachineControl::beginPowerUp ( in IProgress  progress  ) 

Tells VBoxSVC that IConsole::powerUp is under ways and gives it the progress object that should be part of any pending IMachine::launchVMProcess operations.

The progress object may be called back to reflect an early cancelation, so some care have to be taken with respect to any cancelation callbacks. The console object will call IInternalMachineControl::endPowerUp to signal the completion of the progress object.

void IInternalMachineControl::endPowerUp ( in long  result  ) 

Tells VBoxSVC that IConsole::powerUp has completed.

This method may query status information from the progress object it received in IInternalMachineControl::beginPowerUp and copy it over to any in-progress IMachine::launchVMProcess call in order to complete that progress object.

void IInternalMachineControl::beginPoweringDown ( out IProgress  progress  ) 

Called by the VM process to inform the server it wants to stop the VM execution and power down.

Parameters:
progress Progress object created by VBoxSVC to wait until the VM is powered down.
void IInternalMachineControl::endPoweringDown ( in long  result,
in wstring  errMsg 
)

Called by the VM process to inform the server that powering down previously requested by beginPoweringDown is either successfully finished or there was a failure.

Parameters:
result S_OK to indicate success.
errMsg human readable error message in case of failure.
Expected result codes:
VBOX_E_FILE_ERROR Settings file not accessible.
VBOX_E_XML_ERROR Could not parse the settings file.
void IInternalMachineControl::runUSBDeviceFilters ( in IUSBDevice  device,
out boolean  matched,
out unsigned long  maskedInterfaces 
)

Asks the server to run USB devices filters of the associated machine against the given USB device and tell if there is a match.

Note:
Intended to be used only for remote USB devices. Local ones don't require to call this method (this is done implicitly by the Host and USBProxyService).
void IInternalMachineControl::captureUSBDevice ( in wstringUUID  id  ) 

Requests a capture of the given host USB device.

When the request is completed, the VM process will get a IInternalSessionControl::onUSBDeviceAttach notification.

void IInternalMachineControl::detachUSBDevice ( in wstringUUID  id,
in boolean  done 
)

Notification that a VM is going to detach (done = false) or has already detached (done = true) the given USB device.

When the done = true request is completed, the VM process will get a IInternalSessionControl::onUSBDeviceDetach notification.

Note:
In the done = true case, the server must run its own filters and filters of all VMs but this one on the detached device as if it were just attached to the host computer.
void IInternalMachineControl::autoCaptureUSBDevices (  ) 

Requests a capture all matching USB devices attached to the host.

When the request is completed, the VM process will get a IInternalSessionControl::onUSBDeviceAttach notification per every captured device.

void IInternalMachineControl::detachAllUSBDevices ( in boolean  done  ) 

Notification that a VM that is being powered down.

The done parameter indicates whether which stage of the power down we're at. When done = false the VM is announcing its intentions, while when done = true the VM is reporting what it has done.

Note:
In the done = true case, the server must run its own filters and filters of all VMs but this one on all detach devices as if they were just attached to the host computer.
void IInternalMachineControl::onSessionEnd ( in ISession  session,
[retval] out IProgress  progress 
)

Triggered by the given session object when the session is about to close normally.

Parameters:
session Session that is being closed
progress Used to wait until the corresponding machine is actually dissociated from the given session on the server. Returned only when this session is a direct one.
void IInternalMachineControl::beginSavingState ( out IProgress  progress,
out wstring  stateFilePath 
)

Called by the VM process to inform the server it wants to save the current state and stop the VM execution.

Parameters:
progress Progress object created by VBoxSVC to wait until the state is saved.
stateFilePath File path the VM process must save the execution state to.
void IInternalMachineControl::endSavingState ( in long  result,
in wstring  errMsg 
)

Called by the VM process to inform the server that saving the state previously requested by beginSavingState is either successfully finished or there was a failure.

Parameters:
result S_OK to indicate success.
errMsg human readable error message in case of failure.
Expected result codes:
VBOX_E_FILE_ERROR Settings file not accessible.
VBOX_E_XML_ERROR Could not parse the settings file.
void IInternalMachineControl::adoptSavedState ( in wstring  savedStateFile  ) 

Gets called by IConsole::adoptSavedState.

Parameters:
savedStateFile Path to the saved state file to adopt.
Expected result codes:
VBOX_E_FILE_ERROR Invalid saved state file path.
void IInternalMachineControl::beginTakingSnapshot ( in IConsole  initiator,
in wstring  name,
in wstring  description,
in IProgress  consoleProgress,
in boolean  fTakingSnapshotOnline,
out wstring  stateFilePath 
)

Called from the VM process to request from the server to perform the server-side actions of creating a snapshot (creating differencing images and the snapshot object).

Parameters:
initiator The console object that initiated this call.
name Snapshot name.
description Snapshot description.
consoleProgress Progress object created by the VM process tracking the snapshot's progress. This has the following sub-operations:

  • setting up (weight 1);
  • one for each medium attachment that needs a differencing image (weight 1 each);
  • another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);
  • another one to save the VM state (if online, weight is VM memory size in MB);
  • finishing up (weight 1)
fTakingSnapshotOnline Whether this is an online snapshot (i.e. the machine is running).
stateFilePath File path the VM process must save the execution state to.
Expected result codes:
VBOX_E_FILE_ERROR Settings file not accessible.
VBOX_E_XML_ERROR Could not parse the settings file.
void IInternalMachineControl::endTakingSnapshot ( in boolean  success  ) 

Called by the VM process to inform the server that the snapshot previously requested by beginTakingSnapshot is either successfully taken or there was a failure.

Parameters:
success true to indicate success and false otherwise
void IInternalMachineControl::deleteSnapshot ( in IConsole  initiator,
in wstringUUID  startId,
in wstringUUID  endId,
in boolean  deleteAllChildren,
out MachineState  machineState,
[retval] out IProgress  progress 
)

Gets called by IConsole::deleteSnapshot, IConsole::deleteSnapshotAndAllChildren and IConsole::deleteSnapshotRange.

Parameters:
initiator The console object that initiated this call.
startId UUID of the first snapshot to delete.
endId UUID of the last snapshot to delete.
deleteAllChildren Whether all children should be deleted.
machineState New machine state after this operation is started.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_INVALID_OBJECT_STATE Snapshot has more than one child snapshot. Only possible if the delete operation does not delete all children or the range does not meet the linearity condition.
void IInternalMachineControl::finishOnlineMergeMedium (  ) 

Gets called by IInternalSessionControl::onlineMergeMedium.

All necessary state information is available at the called object.

void IInternalMachineControl::restoreSnapshot ( in IConsole  initiator,
in ISnapshot  snapshot,
out MachineState  machineState,
[retval] out IProgress  progress 
)

Gets called by IConsole::restoreSnapshot.

Parameters:
initiator The console object that initiated this call.
snapshot The snapshot to restore the VM state from.
machineState New machine state after this operation is started.
progress Progress object to track the operation completion.
void IInternalMachineControl::pullGuestProperties ( out wstring[]  names,
out wstring[]  values,
out long long[]  timestamps,
out wstring[]  flags 
)

Get the list of the guest properties matching a set of patterns along with their values, time stamps and flags and give responsibility for managing properties to the console.

Parameters:
names The names of the properties returned.
values The values of the properties returned. The array entries match the corresponding entries in the name array.
timestamps The time stamps of the properties returned. The array entries match the corresponding entries in the name array.
flags The flags of the properties returned. The array entries match the corresponding entries in the name array.
void IInternalMachineControl::pushGuestProperty ( in wstring  name,
in wstring  value,
in long long  timestamp,
in wstring  flags 
)

Update a single guest property in IMachine.

Parameters:
name The name of the property to be updated.
value The value of the property.
timestamp The timestamp of the property.
flags The flags of the property.
void IInternalMachineControl::lockMedia (  ) 

Locks all media attached to the machine for writing and parents of attached differencing media (if any) for reading.

This operation is atomic so that if it fails no media is actually locked.

This method is intended to be called when the machine is in Starting or Restoring state. The locked media will be automatically unlocked when the machine is powered off or crashed.

void IInternalMachineControl::unlockMedia (  ) 

Unlocks all media previously locked using IInternalMachineControl::lockMedia.

This method is intended to be used with teleportation so that it is possible to teleport between processes on the same machine.

void IInternalMachineControl::ejectMedium ( in IMediumAttachment  attachment,
[retval] out IMediumAttachment  newAttachment 
)

Tells VBoxSVC that the guest has ejected the medium associated with the medium attachment.

Parameters:
attachment The medium attachment where the eject happened.
newAttachment A new reference to the medium attachment, as the config change can result in the creation of a new instance.
void IInternalMachineControl::reportVmStatistics ( in unsigned long  validStats,
in unsigned long  cpuUser,
in unsigned long  cpuKernel,
in unsigned long  cpuIdle,
in unsigned long  memTotal,
in unsigned long  memFree,
in unsigned long  memBalloon,
in unsigned long  memShared,
in unsigned long  memCache,
in unsigned long  pagedTotal,
in unsigned long  memAllocTotal,
in unsigned long  memFreeTotal,
in unsigned long  memBalloonTotal,
in unsigned long  memSharedTotal,
in unsigned long  vmNetRx,
in unsigned long  vmNetTx 
)

Passes statistics collected by VM (including guest statistics) to VBoxSVC.

Parameters:
validStats Mask defining which parameters are valid. For example: 0x11 means that cpuIdle and XXX are valid. Other parameters should be ignored.
cpuUser Percentage of processor time spent in user mode as seen by the guest.
cpuKernel Percentage of processor time spent in kernel mode as seen by the guest.
cpuIdle Percentage of processor time spent idling as seen by the guest.
memTotal Total amount of physical guest RAM.
memFree Free amount of physical guest RAM.
memBalloon Amount of ballooned physical guest RAM.
memShared Amount of shared physical guest RAM.
memCache Total amount of guest (disk) cache memory.
pagedTotal Total amount of space in the page file.
memAllocTotal Total amount of memory allocated by the hypervisor.
memFreeTotal Total amount of free memory available in the hypervisor.
memBalloonTotal Total amount of memory ballooned by the hypervisor.
memSharedTotal Total amount of shared memory in the hypervisor.
vmNetRx Network receive rate for VM.
vmNetTx Network transmit rate for VM.