VirtualBox Main API

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

## Public Member Functions
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, in wstring captureFilename)
| 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 | finishOnlineMergeMedium ()
| Gets called by IInternalSessionControl::onlineMergeMedium.
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, timestamps 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, in boolean fWasDeleted)
| 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.
void | authenticateExternal (in wstring[] authParams, out wstring result)
| Verify credentials using the external auth library.

## Member Function Documentation

## ◆ updateState()

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.

## ◆ beginPowerUp()

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.

## ◆ endPowerUp()

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.

## ◆ beginPoweringDown()

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.

## ◆ endPoweringDown()

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.

## ◆ runUSBDeviceFilters()

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

## ◆ captureUSBDevice()

void IInternalMachineControl::captureUSBDevice | ( | in wstringUUID | id,
|  | in wstring | captureFilename
| ) |  |

Requests a capture of the given host USB device.

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

## ◆ detachUSBDevice()

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.

## ◆ autoCaptureUSBDevices()

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.

## ◆ detachAllUSBDevices()

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.

## ◆ onSessionEnd()

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.

## ◆ finishOnlineMergeMedium()

void IInternalMachineControl::finishOnlineMergeMedium | ( |  | ) |

Gets called by IInternalSessionControl::onlineMergeMedium.

All necessary state information is available at the called object.

## ◆ pullGuestProperties()

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

## ◆ pushGuestProperty()

void IInternalMachineControl::pushGuestProperty | ( | in wstring | name,
|  | in wstring | value,
|  | in long long | timestamp,
|  | in wstring | flags,
|  | in boolean | fWasDeleted
| ) |  |

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.
  fWasDeleted | The flag which indicates if property was deleted.

## ◆ lockMedia()

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.

## ◆ unlockMedia()

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.

## ◆ ejectMedium()

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.

## ◆ reportVmStatistics()

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.

## ◆ authenticateExternal()

void IInternalMachineControl::authenticateExternal | ( | in wstring[] | authParams,
|  | out wstring | result
| ) |  |

Verify credentials using the external auth library.

Parameters

  authParams | The auth parameters, credentials, etc.
  result | The authentification result.