# IVirtualBoxCallback Interface Reference

List of all members.

## Public Member Functions
void | onMachineStateChange (in wstringUUID machineId, in MachineState state)
| The execution state of the given machine has changed.
void | onMachineDataChange (in wstringUUID machineId)
| Any of the settings of the given machine has changed.
void | onExtraDataCanChange (in wstringUUID 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 wstringUUID machineId, in wstring key, in wstring value)
| Notification when machine specific or global extra data has changed.
void | onMediumRegistered (in wstringUUID mediumId, in DeviceType mediumType, in boolean registered)
| The given medium was registered or unregistered within this VirtualBox installation.
void | onMachineRegistered (in wstringUUID machineId, in boolean registered)
| The given machine was registered or unregistered within this VirtualBox installation.
void | onSessionStateChange (in wstringUUID machineId, in SessionState state)
| The state of the session for the given machine was changed.
void | onSnapshotTaken (in wstringUUID machineId, in wstringUUID snapshotId)
| A new snapshot of the machine has been taken.
void | onSnapshotDeleted (in wstringUUID machineId, in wstringUUID snapshotId)
| Snapshot of the given machine has been deleted.
void | onSnapshotChange (in wstringUUID machineId, in wstringUUID snapshotId)
| Snapshot properties (name and/or description) have been changed.
void | onGuestPropertyChange (in wstringUUID machineId, in wstring name, in wstring value, in wstring flags)
| Notification when a guest property has changed.

## Member Function Documentation

void IVirtualBoxCallback::onMachineStateChange | ( | in wstringUUID | 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.

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP.

See also:
  IMachine::state

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

Any of the settings of the given machine has changed.

Parameters:

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

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP.

void IVirtualBoxCallback::onExtraDataCanChange | ( | in wstringUUID | 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`).

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP. Change is allowed.

void IVirtualBoxCallback::onExtraDataChange | ( | in wstringUUID | 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.

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP.

void IVirtualBoxCallback::onMediumRegistered | ( | in wstringUUID | mediumId,
|  | in DeviceType | mediumType,
|  | in boolean | registered |
| ) |  |  |

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

The mediumType parameter describes what type of medium the specified mediumId refers to. Possible values are:

- DeviceType_HardDisk: the medium is a hard disk that, if registered, can be obtained using the IVirtualBox::getHardDisk call.
- DeviceType_DVD: the medium is a CD/DVD image that, if registered, can be obtained using the IVirtualBox::getDVDImage call.
- DeviceType_Floppy: the medium 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 medium. It is supposed that the application will do required cleanup based on the mediumId value.

Parameters:

  | mediumId | ID of the medium this event relates to.
  | mediumType | Type of the medium this event relates to.
  | registered | If `true`, the medium was registered, otherwise it was unregistered.

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP.

void IVirtualBoxCallback::onMachineRegistered | ( | in wstringUUID | 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.

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP.

void IVirtualBoxCallback::onSessionStateChange | ( | in wstringUUID | 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.

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP.

See also:
  IMachine::sessionState

void IVirtualBoxCallback::onSnapshotTaken | ( | in wstringUUID | machineId,
|  | in wstringUUID | 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.

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP.

See also:
  ISnapshot

void IVirtualBoxCallback::onSnapshotDeleted | ( | in wstringUUID | machineId,
|  | in wstringUUID | snapshotId |
| ) |  |  |

Snapshot of the given machine has been deleted.

Parameters:

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

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP.

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 wstringUUID | machineId,
|  | in wstringUUID | 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.

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP.

See also:
  ISnapshot

void IVirtualBoxCallback::onGuestPropertyChange | ( | in wstringUUID | 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.

Expected result codes:

  VBOX_E_DONT_CALL_AGAIN | Do not call again, this method is a NOP.