# IVirtualBoxCallback Interface Reference

List of all members.

## Public Member Functions
void | onMachineStateChange (in uuid machineId, in MachineState state)
| The execution state of the given machine has changed.
void | onMachineDataChange (in uuid machineId)
| Any of the settings of the given machine has changed.
void | onExtraDataCanChange (in uuid machineId, in wstring key, in wstring value, out wstring error,[retval] out boolean allowChange)
| Notification when someone tries to change extra data for either the given machine or (if null) global extra data.
void | onExtraDataChange (in uuid machineId, in wstring key, in wstring value)
| Notification when machine specific or global extra data has changed.
void | onMediaRegistered (in uuid mediaId, in DeviceType mediaType, in boolean registered)
| The given media was registered or unregistered within this VirtualBox installation.
void | onMachineRegistered (in uuid machineId, in boolean registered)
| The given machine was registered or unregistered within this VirtualBox installation.
void | onSessionStateChange (in uuid machineId, in SessionState state)
| The state of the session for the given machine was changed.
void | onSnapshotTaken (in uuid machineId, in uuid snapshotId)
| A new snapshot of the machine has been taken.
void | onSnapshotDiscarded (in uuid machineId, in uuid snapshotId)
| Snapshot of the given machine has been discarded.
void | onSnapshotChange (in uuid machineId, in uuid snapshotId)
| Snapshot properties (name and/or description) have been changed.
void | onGuestPropertyChange (in uuid machineId, in wstring name, in wstring value, in wstring flags)
| Notification when a guest property has changed.

## Member Function Documentation

void IVirtualBoxCallback::onMachineStateChange | ( | in uuid | machineId,
|  | in MachineState | state |
| ) |  |  |

The execution state of the given machine has changed.

Parameters:

  | machineId | ID of the machine this event relates to.
  | state | New execution state.

See also:
  IMachine::state

void IVirtualBoxCallback::onMachineDataChange | ( | in uuid | machineId | ) |

Any of the settings of the given machine has changed.

Parameters:

  | machineId | ID of the machine this event relates to.

void IVirtualBoxCallback::onExtraDataCanChange | ( | in uuid | machineId,
|  | in wstring | key,
|  | in wstring | value,
|  | out wstring | error,
|  | [retval] out boolean | allowChange |
| ) |  |  |

Notification when someone tries to change extra data for either the given machine or (if null) global extra data.

This gives the chance to veto against changes.

Parameters:

  | machineId | ID of the machine this event relates to (null ID for global extra data change requests).
  | key | Extra data key for the attempted write.
  | value | Extra data value for the given key.
  | error | Optional error message describing the reason of the veto (ignored if this notification returns `true`).
  | allowChange | Flag to indicate whether the callee agrees (@ true) or vetoes against the change (@ false).

void IVirtualBoxCallback::onExtraDataChange | ( | in uuid | machineId,
|  | in wstring | key,
|  | in wstring | value |
| ) |  |  |

Notification when machine specific or global extra data has changed.

Parameters:

  | machineId | ID of the machine this event relates to. Null for global extra data changes.
  | key | Extra data key that has changed.
  | value | Extra data value for the given key.

void IVirtualBoxCallback::onMediaRegistered | ( | in uuid | mediaId,
|  | in DeviceType | mediaType,
|  | in boolean | registered |
| ) |  |  |

The given media was registered or unregistered within this VirtualBox installation.

The mediaType parameter describes what type of media the specified mediaId refers to. Possible values are:

- DeviceType::HardDisk: the media is a hard disk that, if registered, can be obtained using the IVirtualBox::getHardDisk call.
- DeviceType::DVD: the media is a CD/DVD image that, if registered, can be obtained using the IVirtualBox::getDVDImage call.
- DeviceType::Floppy: the media is a Floppy image that, if registered, can be obtained using the IVirtualBox::getFloppyImage call.

Note that if this is a deregistration notification, there is no way to access the object representing the unregistered media. It is supposed that the application will do required cleanup based on the mediaId value.

Parameters:

  | mediaId | ID of the media this event relates to.
  | mediaType | Type of the media this event relates to.
  | registered | If true, the media was registered, otherwise it was unregistered.

void IVirtualBoxCallback::onMachineRegistered | ( | in uuid | machineId,
|  | in boolean | registered |
| ) |  |  |

The given machine was registered or unregistered within this VirtualBox installation.

Parameters:

  | machineId | ID of the machine this event relates to.
  | registered | If true, the machine was registered, otherwise it was unregistered.

void IVirtualBoxCallback::onSessionStateChange | ( | in uuid | machineId,
|  | in SessionState | state |
| ) |  |  |

The state of the session for the given machine was changed.

Parameters:

  | machineId | ID of the machine this event relates to.
  | state | New session state.

See also:
  IMachine::sessionState

void IVirtualBoxCallback::onSnapshotTaken | ( | in uuid | machineId,
|  | in uuid | snapshotId |
| ) |  |  |

A new snapshot of the machine has been taken.

Parameters:

  | machineId | ID of the machine this event relates to.
  | snapshotId | ID of the new snapshot.

See also:
  ISnapshot

void IVirtualBoxCallback::onSnapshotDiscarded | ( | in uuid | machineId,
|  | in uuid | snapshotId |
| ) |  |  |

Snapshot of the given machine has been discarded.

Parameters:

  | machineId | ID of the machine this event relates to.
  | snapshotId | ID of the discarded snapshot. `null` means the current machine state has been discarded (restored from the current snapshot).

Note:
  This notification is delivered after the snapshot object has been uninitialized on the server (so that any attempt to call its methods will return an error).

See also:
  ISnapshot

void IVirtualBoxCallback::onSnapshotChange | ( | in uuid | machineId,
|  | in uuid | snapshotId |
| ) |  |  |

Snapshot properties (name and/or description) have been changed.

Parameters:

  | machineId | ID of the machine this event relates to.
  | snapshotId | ID of the changed snapshot.

See also:
  ISnapshot

void IVirtualBoxCallback::onGuestPropertyChange | ( | in uuid | machineId,
|  | in wstring | name,
|  | in wstring | value,
|  | in wstring | flags |
| ) |  |  |

Notification when a guest property has changed.

Parameters:

  | machineId | ID of the machine this event relates to.
  | name | The name of the property that has changed.
  | value | The new property value.
  | flags | The new property flags.