VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
ICloudMachine Interface Reference

Virtual virtual machine (sic) in the cloud. More...

Inheritance diagram for ICloudMachine:

## Public Member Functions
void | refresh ([retval] out IProgress progress)
| Refresh information by reading it from the cloud.
void | getDetailsForm ([retval] out IForm form)
| Obtain a form with the current settings for this cloud machine.
void | getSettingsForm (out IForm form, [retval] out IProgress progress)
| Obtain a form with settings for this cloud machine.
void | powerUp ([retval] out IProgress progress)
| Start cloud virtual machine execution.
void | reboot ([retval] out IProgress progress)
| Reboot cloud virtual machine.
void | reset ([retval] out IProgress progress)
| Forcing reset or hard reset of a cloud virtual machine.
void | shutdown ([retval] out IProgress progress)
| Shutdown cloud virtual machine.
void | powerDown ([retval] out IProgress progress)
| Initiates the power down procedure to stop the virtual machine execution.
void | terminate ([retval] out IProgress progress)
| Terminate cloud virtual machine.
void | unregister ([retval] out IProgress progress)
| Unregister this cloud machine, but leave the cloud artifacts intact.
void | remove ([retval] out IProgress progress)
| Unregister this cloud machine and delete all its cloud artifacts.
void | getConsoleHistory (out IDataStream stream, [retval] out IProgress progress)
| Get the backlog of the machine's console.
void | createConsoleConnection (in wstring sshPublicKey, [retval] out IProgress progress)
void | deleteConsoleConnection ([retval] out IProgress progress)
void | listMetricNames (out IStringArray metricNames, [retval] out IProgress progress)
| Returns the metrics available for the instances in the Cloud.
void | enumerateMetricData (in MetricType metricType, in unsigned long pointsNumber, out IStringArray values, out IStringArray timestamps, out IStringArray unit, [retval] out IProgress progress)
| Returns the interested metric history points.

## Public Attributes
readonly attribute wstringUUID | id
| UUID of the cloud machine within VirtualBox.
readonly attribute wstring | cloudId
| UUID of the cloud machine within Cloud.
readonly attribute boolean | accessible
| Whether this virtual machine is currently accessible or not.
readonly attribute IVirtualBoxErrorInfo | accessError
| Error information describing the reason of machine inaccessibility.
readonly attribute wstring | name
| Convenience shortcut to retrieve the name of the cloud machine.
readonly attribute wstring | OSTypeId
| Convenience shortcut to retrieve the OS Type id of the cloud machine.
readonly attribute CloudMachineState | state
| Machine state.
readonly attribute wstring | consoleConnectionFingerprint
| The fingerprint of the ssh key that is authorized to access the machine's console connection.
readonly attribute wstring | serialConsoleCommand
| The shell command to establish ssh connection to the cloud machine serial console.
readonly attribute wstring | serialConsoleCommandWindows
| The PowerShell command to establish ssh connection to the cloud machine serial console using PuTTY's plink.
readonly attribute wstring | VNCConsoleCommand
| The shell command to establish ssh port forwarding for the VNC connection to the cloud machine console.
readonly attribute wstring | VNCConsoleCommandWindows
| The PowerShell command to establish ssh port forwarding for the VNC connection to the cloud machine console using PuTTY's plink.

## Detailed Description

Virtual virtual machine (sic) in the cloud.

Reading object attributes returns cached values, use refresh to refresh them.

Interface ID:
  `{147816C8-17E0-11EB-81FA-87CEA6263E1A}`

## Member Function Documentation

## ◆ refresh()

void ICloudMachine::refresh | ( | [retval] out IProgress | progress | ) |

Refresh information by reading it from the cloud.

Parameters

  progress | Progress object to track the operation completion.

## ◆ getDetailsForm()

void ICloudMachine::getDetailsForm | ( | [retval] out IForm | form | ) |

Obtain a form with the current settings for this cloud machine.

The form is not editable.

Parameters

  form | A form with the cloud machine settings.

## ◆ getSettingsForm()

void ICloudMachine::getSettingsForm | ( | out IForm | form,
|  | [retval] out IProgress | progress
| ) |  |

Obtain a form with settings for this cloud machine.

The form is editable.

Parameters

  form | A form with the cloud machine settings.
  progress | Progress object to track the operation completion.

## ◆ powerUp()

void ICloudMachine::powerUp | ( | [retval] out IProgress | progress | ) |

Start cloud virtual machine execution.

Parameters

  progress | Progress object to track the operation completion.

## ◆ reboot()

void ICloudMachine::reboot | ( | [retval] out IProgress | progress | ) |

Reboot cloud virtual machine.

Parameters

  progress | Progress object to track the operation completion.

## ◆ reset()

void ICloudMachine::reset | ( | [retval] out IProgress | progress | ) |

Forcing reset or hard reset of a cloud virtual machine.

Parameters

  progress | Progress object to track the operation completion.

## ◆ shutdown()

void ICloudMachine::shutdown | ( | [retval] out IProgress | progress | ) |

Shutdown cloud virtual machine.

Parameters

  progress | Progress object to track the operation completion.

## ◆ powerDown()

void ICloudMachine::powerDown | ( | [retval] out IProgress | progress | ) |

Initiates the power down procedure to stop the virtual machine execution.

The completion of the power down procedure is tracked using the returned IProgress object. After the operation is complete, the machine will go to the PoweredOff state.

Parameters

  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine must be Running, to be powered down.

## ◆ terminate()

void ICloudMachine::terminate | ( | [retval] out IProgress | progress | ) |

Terminate cloud virtual machine.

Parameters

  progress | Progress object to track the operation completion.

## ◆ unregister()

void ICloudMachine::unregister | ( | [retval] out IProgress | progress | ) |

Unregister this cloud machine, but leave the cloud artifacts intact.

Parameters

  progress | Progress object to track the operation completion.

## ◆ remove()

void ICloudMachine::remove | ( | [retval] out IProgress | progress | ) |

Unregister this cloud machine and delete all its cloud artifacts.

Parameters

  progress | Progress object to track the operation completion.

## ◆ getConsoleHistory()

void ICloudMachine::getConsoleHistory | ( | out IDataStream | stream,
|  | [retval] out IProgress | progress
| ) |  |

Get the backlog of the machine's console.

If you have ever seen console teletypes, this is like looking at the last few meters of the paper it spewed.

Parameters

  stream | Data stream object for reading the console history. For now we are abusing/repurposing this interface from the media convertion API to avoid marshalling a huge string through xpcom.
  progress | Progress object to track the operation completion.

## ◆ createConsoleConnection()

void ICloudMachine::createConsoleConnection | ( | in wstring | sshPublicKey,
|  | [retval] out IProgress | progress
| ) |  |

## ◆ deleteConsoleConnection()

void ICloudMachine::deleteConsoleConnection | ( | [retval] out IProgress | progress | ) |

## ◆ listMetricNames()

void ICloudMachine::listMetricNames | ( | out IStringArray | metricNames,
|  | [retval] out IProgress | progress
| ) |  |

Returns the metrics available for the instances in the Cloud.

In instance, CPU utilization, memory utilization, disk read I/O. Not all instances can have such metrics because a special service must be running on the instance. Converting a string representation to a MetricType is done using ICloudClient::getMetricTypeByName.

Parameters

  metricNames | List of metrics names. May be empty if there are no metrics available on the instance or if the corresponding service is not running on the instance.
  progress | Progress object to track the operation completion.

## ◆ enumerateMetricData()

void ICloudMachine::enumerateMetricData | ( | in MetricType | metricType,
|  | in unsigned long | pointsNumber,
|  | out IStringArray | values,
|  | out IStringArray | timestamps,
|  | out IStringArray | unit,
|  | [retval] out IProgress | progress
| ) |  |

Returns the interested metric history points.

Parameters

  metricType | The type of the requested metric. Standard usage to get an appropriate MetricType: call listMetricNames function; returns the types in string representation. call ICloudClient::getMetricTypeByName function; converts the string representation into MetricType.
  pointsNumber | History metric point numbers start at 1 and can go backwards as long as history exists. Points are counted from the current time to the past. If user only wants the last actual value he passes the value "1". If 2 values need to be returned (last and second to last), the user passes "2", etc. and etc.
  values | The values of the metric returned.
  timestamps | The timestamps of the metric returned. The array entries match the corresponding entries in the array. Time format is represented in Rfc2822.
  unit | The measurement unit as "byte", "percentage" and etc... The array entries match the corresponding entries in the array.
  progress | Progress object to track the operation completion.

## Member Data Documentation

## ◆ id

readonly attribute wstringUUID ICloudMachine::id

UUID of the cloud machine within VirtualBox.

## ◆ cloudId

readonly attribute wstring ICloudMachine::cloudId

UUID of the cloud machine within Cloud.

## ◆ accessible

readonly attribute boolean ICloudMachine::accessible

Whether this virtual machine is currently accessible or not.

TBD...

## ◆ accessError

readonly attribute IVirtualBoxErrorInfo ICloudMachine::accessError

Error information describing the reason of machine inaccessibility.

Reading this property is only valid after the last call to accessible returned `false` (i.e. the machine is currently inaccessible). Otherwise, a `null` IVirtualBoxErrorInfo object will be returned.

## ◆ name

readonly attribute wstring ICloudMachine::name

Convenience shortcut to retrieve the name of the cloud machine.

The name is part of the machine settings that are hidden behind the settings form (see getSettingsForm).

## ◆ OSTypeId

readonly attribute wstring ICloudMachine::OSTypeId

Convenience shortcut to retrieve the OS Type id of the cloud machine.

It is part of the machine settings that are hidden behind the settings form (see getSettingsForm).

## ◆ state

readonly attribute CloudMachineState ICloudMachine::state

Machine state.

## ◆ consoleConnectionFingerprint

readonly attribute wstring ICloudMachine::consoleConnectionFingerprint

The fingerprint of the ssh key that is authorized to access the machine's console connection.

## ◆ serialConsoleCommand

readonly attribute wstring ICloudMachine::serialConsoleCommand

The shell command to establish ssh connection to the cloud machine serial console.

## ◆ serialConsoleCommandWindows

readonly attribute wstring ICloudMachine::serialConsoleCommandWindows

The PowerShell command to establish ssh connection to the cloud machine serial console using PuTTY's plink.

## ◆ VNCConsoleCommand

readonly attribute wstring ICloudMachine::VNCConsoleCommand

The shell command to establish ssh port forwarding for the VNC connection to the cloud machine console.

## ◆ VNCConsoleCommandWindows

readonly attribute wstring ICloudMachine::VNCConsoleCommandWindows

The PowerShell command to establish ssh port forwarding for the VNC connection to the cloud machine console using PuTTY's plink.