# IInternalMachineControl Interface Reference

List of all members.

## Public Member Functions
void | updateState (in MachineState state)
| Updates the VM state.
void | getIPCId ([retval] out wstring id)
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 uuid id)
| Requests a capture of the given host USB device.
void | detachUSBDevice (in uuid 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 (in 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 boolean success)
| 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 progress, out wstring stateFilePath, out IProgress serverProgress)
| Called by the VM process to inform the server it wants to take a snapshot.
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 | discardSnapshot (in IConsole initiator, in uuid id, out MachineState machineState,[retval] out IProgress progress)
| Gets called by IConsole::discardSnapshot.
void | discardCurrentState (in IConsole initiator, out MachineState machineState,[retval] out IProgress progress)
| Gets called by IConsole::discardCurrentState.
void | discardCurrentSnapshotAndState (in IConsole initiator, out MachineState machineState,[retval] out IProgress progress)
| Gets called by IConsole::discardCurrentSnapshotAndState.
void | pullGuestProperties (out wstring[] name, out wstring[] value, out unsigned long long[] timestamp, 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 | pushGuestProperties (in wstring[] name, in wstring[] value, in unsigned long long[] timestamp, in wstring[] flags)
| Set the list of the guest properties matching a set of patterns along with their values, time stamps and flags and return responsibility for managing properties to IMachine.
void | pushGuestProperty (in wstring name, in wstring value, in unsigned 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 attahced different hard disks (if any) for reading.

## Member Function Documentation

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::getIPCId | ( | [retval] out wstring | id | ) |

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 uuid | 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 uuid | 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 | ( | in 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 the VM process to wait until the state is saved.
  | stateFilePath | File path the VM process must save the execution state to.

void IInternalMachineControl::endSavingState | ( | in boolean | success | ) |

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:

  | success | `true` to indicate success and `false` otherwise.

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 | progress,
|  | out wstring | stateFilePath,
|  | out IProgress | serverProgress |
| ) |  |  |

Called by the VM process to inform the server it wants to take a snapshot.

Parameters:

  | initiator | The console object that initiated this call.
  | name | Snapshot name.
  | description | Snapshot description.
  | progress | Progress object created by the VM process to wait until the state is saved (only for online snapshots).
  | stateFilePath | File path the VM process must save the execution state to.
  | serverProgress | Progress object created by the server process to wait until the snapshot is taken (VDI diff creation, etc.).

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::discardSnapshot | ( | in IConsole | initiator,
|  | in uuid | id,
|  | out MachineState | machineState,
|  | [retval] out IProgress | progress |
| ) |  |  |

Gets called by IConsole::discardSnapshot.

Parameters:

  | initiator | The console object that initiated this call.
  | id | UUID of the snapshot to discard.
  | 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.

void IInternalMachineControl::discardCurrentState | ( | in IConsole | initiator,
|  | out MachineState | machineState,
|  | [retval] out IProgress | progress |
| ) |  |  |

Gets called by IConsole::discardCurrentState.

Parameters:

  | initiator | The console object that initiated this call.
  | 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 | Virtual machine does not have any snapshot.

void IInternalMachineControl::discardCurrentSnapshotAndState | ( | in IConsole | initiator,
|  | out MachineState | machineState,
|  | [retval] out IProgress | progress |
| ) |  |  |

Gets called by IConsole::discardCurrentSnapshotAndState.

Parameters:

  | initiator | The console object that initiated this call.
  | 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 | Virtual machine does not have any snapshot.

void IInternalMachineControl::pullGuestProperties | ( | out wstring[] | name,
|  | out wstring[] | value,
|  | out unsigned long long[] | timestamp,
|  | 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:

  | name | The names of the properties returned.
  | value | The values of the properties returned. The array entries match the corresponding entries in the name array.
  | timestamp | 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::pushGuestProperties | ( | in wstring[] | name,
|  | in wstring[] | value,
|  | in unsigned long long[] | timestamp,
|  | in wstring[] | flags |
| ) |  |  |

Set the list of the guest properties matching a set of patterns along with their values, time stamps and flags and return responsibility for managing properties to IMachine.

Parameters:

  | name | The names of the properties.
  | value | The values of the properties. The array entries match the corresponding entries in the name array.
  | timestamp | The time stamps of the properties. The array entries match the corresponding entries in the name array.
  | flags | The flags of the properties. The array entries match the corresponding entries in the name array.

void IInternalMachineControl::pushGuestProperty | ( | in wstring | name,
|  | in wstring | value,
|  | in unsigned 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 attahced different hard disks (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.