VirtualBox Main API

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

The IMachine interface represents a virtual machine, or guest, created in VirtualBox. More...

Inheritance diagram for IMachine:

## Public Member Functions
void | lockMachine (in ISession session, in LockType lockType)
| Locks the machine for the given session to enable the caller to make changes to the machine or start the VM or control VM execution.
void | launchVMProcess (in ISession session, in wstring name, in wstring[] environmentChanges, [retval] out IProgress progress)
| Spawns a new process that will execute the virtual machine and obtains a shared lock on the machine for the calling session.
void | setBootOrder (in unsigned long position, in DeviceType device)
| Puts the given device to the specified position in the boot order.
void | getBootOrder (in unsigned long position, [retval] out DeviceType device)
| Returns the device type that occupies the specified position in the boot order.
void | attachDevice (in wstring name, in long controllerPort, in long device, in DeviceType type, in IMedium medium)
| Attaches a device and optionally mounts a medium to the given storage controller (IStorageController, identified by name), at the indicated port and device.
void | attachDeviceWithoutMedium (in wstring name, in long controllerPort, in long device, in DeviceType type)
| Attaches a device and optionally mounts a medium to the given storage controller (IStorageController, identified by name), at the indicated port and device.
void | detachDevice (in wstring name, in long controllerPort, in long device)
| Detaches the device attached to a device slot of the specified bus.
void | passthroughDevice (in wstring name, in long controllerPort, in long device, in boolean passthrough)
| Sets the passthrough mode of an existing DVD device.
void | temporaryEjectDevice (in wstring name, in long controllerPort, in long device, in boolean temporaryEject)
| Sets the behavior for guest-triggered medium eject.
void | nonRotationalDevice (in wstring name, in long controllerPort, in long device, in boolean nonRotational)
| Sets a flag in the device information which indicates that the medium is not based on rotational technology, i.e.
void | setAutoDiscardForDevice (in wstring name, in long controllerPort, in long device, in boolean discard)
| Sets a flag in the device information which indicates that the medium supports discarding unused blocks (called trimming for SATA or unmap for SCSI devices) .This may or may not be supported by a particular drive, and is silently ignored in the latter case.
void | setHotPluggableForDevice (in wstring name, in long controllerPort, in long device, in boolean hotPluggable)
| Sets a flag in the device information which indicates that the attached device is hot pluggable or not.
void | setBandwidthGroupForDevice (in wstring name, in long controllerPort, in long device, in IBandwidthGroup bandwidthGroup)
| Sets the bandwidth group of an existing storage device.
void | setNoBandwidthGroupForDevice (in wstring name, in long controllerPort, in long device)
| Sets no bandwidth group for an existing storage device.
void | unmountMedium (in wstring name, in long controllerPort, in long device, in boolean force)
| Unmounts any currently mounted medium (IMedium, identified by the given UUID id) to the given storage controller (IStorageController, identified by name), at the indicated port and device.
void | mountMedium (in wstring name, in long controllerPort, in long device, in IMedium medium, in boolean force)
| Mounts a medium (IMedium, identified by the given UUID id) to the given storage controller (IStorageController, identified by name), at the indicated port and device.
void | getMedium (in wstring name, in long controllerPort, in long device, [retval] out IMedium medium)
| Returns the virtual medium attached to a device slot of the specified bus.
void | getMediumAttachmentsOfController (in wstring name, [retval] out IMediumAttachment[] mediumAttachments)
| Returns an array of medium attachments which are attached to the the controller with the given name.
void | getMediumAttachment (in wstring name, in long controllerPort, in long device, [retval] out IMediumAttachment attachment)
| Returns a medium attachment which corresponds to the controller with the given name, on the given port and device slot.
void | attachHostPCIDevice (in long hostAddress, in long desiredGuestAddress, in boolean tryToUnbind)
| Attaches host PCI device with the given (host) PCI address to the PCI bus of the virtual machine.
void | detachHostPCIDevice (in long hostAddress)
| Detach host PCI device from the virtual machine.
void | getNetworkAdapter (in unsigned long slot, [retval] out INetworkAdapter adapter)
| Returns the network adapter associated with the given slot.
void | addStorageController (in wstring name, in StorageBus connectionType, [retval] out IStorageController controller)
| Adds a new storage controller (SCSI, SAS or SATA controller) to the machine and returns it as an instance of IStorageController.
void | getStorageControllerByName (in wstring name, [retval] out IStorageController storageController)
| Returns a storage controller with the given name.
void | getStorageControllerByInstance (in StorageBus connectionType, in unsigned long instance, [retval] out IStorageController storageController)
| Returns a storage controller of a specific storage bus with the given instance number.
void | removeStorageController (in wstring name)
| Removes a storage controller from the machine with all devices attached to it.
void | setStorageControllerBootable (in wstring name, in boolean bootable)
| Sets the bootable flag of the storage controller with the given name.
void | addUSBController (in wstring name, in USBControllerType type, [retval] out IUSBController controller)
| Adds a new USB controller to the machine and returns it as an instance of IUSBController.
void | removeUSBController (in wstring name)
| Removes a USB controller from the machine.
void | getUSBControllerByName (in wstring name, [retval] out IUSBController controller)
| Returns a USB controller with the given type.
void | getUSBControllerCountByType (in USBControllerType type, [retval] out unsigned long controllers)
| Returns the number of USB controllers of the given type attached to the VM.
void | getSerialPort (in unsigned long slot, [retval] out ISerialPort port)
| Returns the serial port associated with the given slot.
void | getParallelPort (in unsigned long slot, [retval] out IParallelPort port)
| Returns the parallel port associated with the given slot.
void | getExtraDataKeys ([retval] out wstring[] keys)
| Returns an array representing the machine-specific extra data keys which currently have values defined.
void | getExtraData (in wstring key, [retval] out wstring value)
| Returns associated machine-specific extra data.
void | setExtraData (in wstring key, in wstring value)
| Sets associated machine-specific extra data.
void | setSettingsFilePath (in wstring settingsFilePath, [retval] out IProgress progress)
| Currently, it is an error to change this property on any machine.
void | saveSettings ()
| Saves any changes to machine settings made since the session has been opened or a new machine has been created, or since the last call to saveSettings or discardSettings.
void | discardSettings ()
| Discards any changes to the machine settings made since the session has been opened or since the last call to saveSettings or discardSettings.
void | unregister (in CleanupMode cleanupMode, [retval] out IMedium[] media)
| Unregisters a machine previously registered with IVirtualBox::registerMachine and optionally do additional cleanup before the machine is unregistered.
void | deleteConfig (in IMedium[] media, [retval] out IProgress progress)
| Deletes the files associated with this machine from disk.
void | exportTo (in IAppliance appliance, in wstring location, [retval] out IVirtualSystemDescription description)
| Exports the machine to an OVF appliance.
void | findSnapshot (in wstring nameOrId, [retval] out ISnapshot snapshot)
| Returns a snapshot of this machine with the given name or UUID.
void | createSharedFolder (in wstring name, in wstring hostPath, in boolean writable, in boolean automount, in wstring autoMountPoint)
| Creates a new permanent shared folder by associating the given logical name with the given host path, adds it to the collection of shared folders and starts sharing it.
void | removeSharedFolder (in wstring name)
| Removes the permanent shared folder with the given name previously created by createSharedFolder from the collection of shared folders and stops sharing it.
void | canShowConsoleWindow ([retval] out boolean canShow)
| Returns `true` if the VM console process can activate the console window and bring it to foreground on the desktop of the host PC.
void | showConsoleWindow ([retval] out long long winId)
| Activates the console window and brings it to foreground on the desktop of the host PC.
void | getGuestProperty (in wstring name, out wstring value, out long long timestamp, out wstring flags)
| Reads an entry from the machine's guest property store.
void | getGuestPropertyValue (in wstring property, [retval] out wstring value)
| Reads a value from the machine's guest property store.
void | getGuestPropertyTimestamp (in wstring property, [retval] out long long value)
| Reads a property timestamp from the machine's guest property store.
void | setGuestProperty (in wstring property, in wstring value, in wstring flags)
| Sets, changes or deletes an entry in the machine's guest property store.
void | setGuestPropertyValue (in wstring property, in wstring value)
| Sets or changes a value in the machine's guest property store.
void | deleteGuestProperty (in wstring name)
| Deletes an entry from the machine's guest property store.
void | enumerateGuestProperties (in wstring patterns, out wstring[] names, out wstring[] values, out long long[] timestamps, out wstring[] flags)
| Return a list of the guest properties matching a set of patterns along with their values, timestamps and flags.
void | querySavedGuestScreenInfo (in unsigned long screenId, out unsigned long originX, out unsigned long originY, out unsigned long width, out unsigned long height, out boolean enabled)
| Returns the guest dimensions from the saved state.
void | readSavedThumbnailToArray (in unsigned long screenId, in BitmapFormat bitmapFormat, out unsigned long width, out unsigned long height, [retval] out octet[] data)
| Thumbnail is retrieved to an array of bytes in the requested format.
void | querySavedScreenshotInfo (in unsigned long screenId, out unsigned long width, out unsigned long height, [retval] out BitmapFormat[] bitmapFormats)
| Returns available formats and size of the screenshot from saved state.
void | readSavedScreenshotToArray (in unsigned long screenId, in BitmapFormat bitmapFormat, out unsigned long width, out unsigned long height, [retval] out octet[] data)
| Screenshot in requested format is retrieved to an array of bytes.
void | hotPlugCPU (in unsigned long cpu)
| Plugs a CPU into the machine.
void | hotUnplugCPU (in unsigned long cpu)
| Removes a CPU from the machine.
void | getCPUStatus (in unsigned long cpu, [retval] out boolean attached)
| Returns the current status of the given CPU.
void | getEffectiveParavirtProvider ([retval] out ParavirtProvider paravirtProvider)
| Returns the effective paravirtualization provider for this VM.
void | queryLogFilename (in unsigned long idx, [retval] out wstring filename)
| Queries for the VM log file name of an given index.
void | readLog (in unsigned long idx, in long long offset, in long long size, [retval] out octet[] data)
| Reads the VM log file.
void | cloneTo (in IMachine target, in CloneMode mode, in CloneOptions[] options, [retval] out IProgress progress)
| Creates a clone of this machine, either as a full clone (which means creating independent copies of the hard disk media, save states and so on), or as a linked clone (which uses its own differencing media, sharing the parent media with the source machine).
void | moveTo (in wstring folder, in wstring type, [retval] out IProgress progress)
| Move machine on to new place/folder.
void | saveState ([retval] out IProgress progress)
| Saves the current execution state of a running virtual machine and stops its execution.
void | adoptSavedState (in wstring savedStateFile)
| Associates the given saved state file to the virtual machine.
void | discardSavedState (in boolean fRemoveFile)
| Forcibly resets the machine to "Powered Off" state if it is currently in the "Saved" state previously created by saveState) or in the "AbortedSaved" state.
void | takeSnapshot (in wstring name, in wstring description, in boolean pause, out wstringUUID id, [retval] out IProgress progress)
| Saves the current execution state and all settings of the machine and creates differencing images for all normal (non-independent) media.
void | deleteSnapshot (in wstringUUID id, [retval] out IProgress progress)
| Starts deleting the specified snapshot asynchronously.
void | deleteSnapshotAndAllChildren (in wstringUUID id, [retval] out IProgress progress)
| Starts deleting the specified snapshot and all its children asynchronously.
void | deleteSnapshotRange (in wstringUUID startId, in wstringUUID endId, [retval] out IProgress progress)
| Starts deleting the specified snapshot range.
void | restoreSnapshot (in ISnapshot snapshot, [retval] out IProgress progress)
| Starts resetting the machine's current state to the state contained in the given snapshot, asynchronously.
void | applyDefaults (in wstring flags)
| Applies the defaults for the configured guest OS type.
void | changeEncryption (in wstring currentPassword, in wstring cipher, in wstring newPassword, in wstring newPasswordId, in boolean force, [retval] out IProgress progress)
| Starts encryption of this VM.
void | getEncryptionSettings (out wstring cipher, out wstring passwordId)
| Returns the encryption settings for this VM.
void | checkEncryptionPassword (in wstring password)
| Checks whether the supplied password is correct for the VM.
void | addEncryptionPassword (in wstring id, in wstring password)
| Adds a password used for encryption.
void | addEncryptionPasswords (in wstring[] ids, in wstring[] passwords)
| Adds passwords used for encryption.
void | removeEncryptionPassword (in wstring id)
| Removes a password used for the VM encryption/decryption.
void | clearAllEncryptionPasswords ()
| Clears all provided VM passwords.

## Public Attributes
readonly attribute IVirtualBox | parent
| Associated parent object.
attribute octet[] | icon
| Overridden VM Icon details.
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.
attribute wstring | name
| Name of the virtual machine.
attribute wstring | description
| Description of the virtual machine.
readonly attribute wstringUUID | id
| UUID of the virtual machine.
attribute wstring[] | groups
| Array of machine group names of which this machine is a member.
attribute wstring | OSTypeId
| User-defined identifier of the Guest OS type.
attribute wstring | hardwareVersion
| Hardware version identifier.
attribute wstringUUID | hardwareUUID
| The UUID presented to the guest via memory tables, hardware and guest properties.
attribute unsigned long | CPUCount
| Number of virtual CPUs in the VM.
attribute boolean | CPUHotPlugEnabled
| This setting determines whether VirtualBox allows CPU hotplugging for this machine.
attribute unsigned long | CPUExecutionCap
| Means to limit the number of CPU cycles a guest can use.
attribute unsigned long | CPUIDPortabilityLevel
| Virtual CPUID portability level.
attribute unsigned long | memorySize
| System memory size in megabytes.
attribute unsigned long | memoryBalloonSize
| Memory balloon size in megabytes.
attribute boolean | pageFusionEnabled
| This setting determines whether VirtualBox allows page fusion for this machine (64-bit hosts only).
readonly attribute IGraphicsAdapter | graphicsAdapter
| Graphics adapter object.
readonly attribute IPlatform | platform
| Associated platform object.
readonly attribute IFirmwareSettings | firmwareSettings
| Object containing all firmware settings.
readonly attribute ITrustedPlatformModule | trustedPlatformModule
| Object containing all TPM settings.
readonly attribute INvramStore | nonVolatileStore
| Object to manipulate data in the non volatile storage file.
readonly attribute IRecordingSettings | recordingSettings
| Object containing all recording settings.
attribute PointingHIDType | pointingHIDType
| Type of pointing HID (such as mouse or tablet) used in this VM.
attribute KeyboardHIDType | keyboardHIDType
| Type of keyboard HID used in this VM.
attribute wstring | snapshotFolder
| Full path to the directory used to store snapshot data (differencing media and saved state files) of this machine.
readonly attribute IVRDEServer | VRDEServer
| VirtualBox Remote Desktop Extension (VRDE) server object.
attribute boolean | emulatedUSBCardReaderEnabled
readonly attribute IMediumAttachment[] | mediumAttachments
| Array of media attached to this machine.
readonly attribute IUSBController[] | USBControllers
| Array of USB controllers attached to this machine.
readonly attribute IUSBDeviceFilters | USBDeviceFilters
| Associated USB device filters object.
readonly attribute IAudioSettings | audioSettings
| The machine's audio settings.
readonly attribute IStorageController[] | storageControllers
| Array of storage controllers attached to this machine.
readonly attribute wstring | settingsFilePath
| Full name of the file containing machine settings data.
readonly attribute wstring | settingsAuxFilePath
| Full name of the file containing auxiliary machine settings data.
readonly attribute boolean | settingsModified
| Whether the settings of this machine have been modified (but neither yet saved nor discarded).
readonly attribute SessionState | sessionState
| Current session state for this machine.
readonly attribute wstring | sessionName
| Name of the session.
readonly attribute unsigned long | sessionPID
| Identifier of the session process.
readonly attribute MachineState | state
| Current execution state of this machine.
readonly attribute long long | lastStateChange
| Timestamp of the last execution state change, in milliseconds since 1970-01-01 UTC.
readonly attribute wstring | stateFilePath
| Full path to the file that stores the execution state of the machine when it is in either the MachineState_Saved or MachineState_AbortedSaved state.
readonly attribute wstring | logFolder
| Full path to the folder that stores a set of rotated log files recorded during machine execution.
readonly attribute ISnapshot | currentSnapshot
| Current snapshot of this machine.
readonly attribute unsigned long | snapshotCount
| Number of snapshots taken on this machine.
readonly attribute boolean | currentStateModified
| Returns `true` if the current state of the machine is not identical to the state stored in the current snapshot.
readonly attribute ISharedFolder[] | sharedFolders
| Collection of shared folders for this machine (permanent shared folders).
attribute ClipboardMode | clipboardMode
| Synchronization mode between the host OS clipboard and the guest OS clipboard.
attribute boolean | clipboardFileTransfersEnabled
| Sets or retrieves whether clipboard file transfers are allowed or not.
attribute DnDMode | dnDMode
| Sets or retrieves the current drag'n drop mode.
attribute boolean | teleporterEnabled
| When set to true, the virtual machine becomes a target teleporter the next time it is powered on.
attribute unsigned long | teleporterPort
| The TCP port the target teleporter will listen for incoming teleportations on.
attribute wstring | teleporterAddress
| The address the target teleporter will listen on.
attribute wstring | teleporterPassword
| The password to check for on the target teleporter.
attribute ParavirtProvider | paravirtProvider
| The paravirtualized guest interface provider.
attribute boolean | IOCacheEnabled
| When set to true, the builtin I/O cache of the virtual machine will be enabled.
attribute unsigned long | IOCacheSize
| Maximum size of the I/O cache in MB.
readonly attribute IPCIDeviceAttachment[] | PCIDeviceAssignments
| Array of PCI devices assigned to this machine, to get list of all PCI devices attached to the machine use IConsole::attachedPCIDevices attribute, as this attribute is intended to list only devices additional to what described in virtual hardware config.
readonly attribute IBandwidthControl | bandwidthControl
| Bandwidth control manager.
attribute boolean | tracingEnabled
| Enables the tracing facility in the VMM (including PDM devices + drivers).
attribute wstring | tracingConfig
| Tracepoint configuration to apply at startup when IMachine::tracingEnabled is true.
attribute boolean | allowTracingToAccessVM
| Enables tracepoints in PDM devices and drivers to use the VMCPU or VM structures when firing off trace points.
attribute boolean | autostartEnabled
| Enables autostart of the VM during system boot.
attribute unsigned long | autostartDelay
| Number of seconds to wait until the VM should be started during system boot.
attribute AutostopType | autostopType
| Action type to do when the system is shutting down.
attribute wstring | defaultFrontend
| Selects which VM frontend should be used by default when launching this VM through the IMachine::launchVMProcess method.
readonly attribute boolean | USBProxyAvailable
| Returns whether there is a USB proxy available.
attribute VMProcPriority | VMProcessPriority
| Sets the priority of the VM process.
attribute VMExecutionEngine | VMExecutionEngine
| The configured VM execution engine.
attribute wstring | paravirtDebug
| Debug parameters for the paravirtualized guest interface provider.
attribute wstring | CPUProfile
| Experimental feature to select the guest CPU profile.
readonly attribute wstring | stateKeyId
| Key Id of the password used for encrypting the state file.
readonly attribute wstring | stateKeyStore
| Key store used for encrypting the state file.
readonly attribute wstring | logKeyId
| Key Id of the password used for encrypting the log files.
readonly attribute wstring | logKeyStore
| Key store used for encrypting the log files.
readonly attribute IGuestDebugControl | guestDebugControl
| Guest debugging configuration.

## Detailed Description

The IMachine interface represents a virtual machine, or guest, created in VirtualBox.

This interface is used in two contexts. First of all, a collection of objects implementing this interface is stored in the IVirtualBox::machines attribute which lists all the virtual machines that are currently registered with this VirtualBox installation. Also, once a session has been opened for the given virtual machine (e.g. the virtual machine is running), the machine object associated with the open session can be queried from the session object; see ISession for details.

The main role of this interface is to expose the settings of the virtual machine and provide methods to change various aspects of the virtual machine's configuration. For machine objects stored in the IVirtualBox::machines collection, all attributes are read-only unless explicitly stated otherwise in individual attribute and method descriptions.

In order to change a machine setting, a session for this machine must be opened using one of the IMachine::lockMachine or IMachine::launchVMProcess methods. After the machine has been successfully locked for a session, a mutable machine object needs to be queried from the session object and then the desired settings changes can be applied to the returned object using IMachine attributes and methods. See the ISession interface description for more information about sessions.

Note that IMachine does not provide methods to control virtual machine execution (such as start the machine, or power it down) – these methods are grouped in a separate interface called IConsole.

See also
  ISession, IConsole

Interface ID:
  `{E36A5081-A82A-40BD-9E4E-42A44D6CE50F}`

## Member Function Documentation

## ◆ lockMachine()

void IMachine::lockMachine | ( | in ISession | session,
|  | in LockType | lockType
| ) |  |

Locks the machine for the given session to enable the caller to make changes to the machine or start the VM or control VM execution.

There are two ways to lock a machine for such uses:

- If you want to make changes to the machine settings, you must obtain an exclusive write lock on the machine by setting lockType to `Write`.

  This will only succeed if no other process has locked the machine to prevent conflicting changes. Only after an exclusive write lock has been obtained using this method, one can change all VM settings or execute the VM in the process space of the session object. (Note that the latter is only of interest if you actually want to write a new front-end for virtual machines; but this API gets called internally by the existing front-ends such as VBoxHeadless and the VirtualBox GUI to acquire a write lock on the machine that they are running.)

  On success, write-locking the machine for a session creates a second copy of the IMachine object. It is this second object upon which changes can be made; in VirtualBox terminology, the second copy is "mutable". It is only this second, mutable machine object upon which you can call methods that change the machine state. After having called this method, you can obtain this second, mutable machine object using the ISession::machine attribute.

- If you only want to check the machine state or control machine execution without actually changing machine settings (e.g. to get access to VM statistics or take a snapshot or save the machine state), then set the lockType argument to `Shared`.

  If no other session has obtained a lock, you will obtain an exclusive write lock as described above. However, if another session has already obtained such a lock, then a link to that existing session will be established which allows you to control that existing session.

  To find out which type of lock was obtained, you can inspect ISession::type, which will have been set to either `WriteLock` or `Shared`.

In either case, you can get access to the IConsole object which controls VM execution.

Also in all of the above cases, one must always call ISession::unlockMachine to release the lock on the machine, or the machine's state will eventually be set to "Aborted".

To change settings on a machine, the following sequence is typically performed:

1. Call this method to obtain an exclusive write lock for the current session.
2. Obtain a mutable IMachine object from ISession::machine.
3. Change the settings of the machine by invoking IMachine methods.
4. Call IMachine::saveSettings.
5. Release the write lock by calling ISession::unlockMachine.

Parameters

  session | Session object for which the machine will be locked.
  lockType | If set to `Write`, then attempt to acquire an exclusive write lock or fail. If set to `Shared`, then either acquire an exclusive write lock or establish a link to an existing session.

Expected result codes:

  E_UNEXPECTED | Virtual machine not registered.
  E_ACCESSDENIED | Process not started by IMachine::launchVMProcess.
  VBOX_E_INVALID_OBJECT_STATE | Session already open or being opened.
  VBOX_E_VM_ERROR | Failed to assign machine to session.

## ◆ launchVMProcess()

void IMachine::launchVMProcess | ( | in ISession | session,
|  | in wstring | name,
|  | in wstring[] | environmentChanges,
|  | [retval] out IProgress | progress
| ) |  |

Spawns a new process that will execute the virtual machine and obtains a shared lock on the machine for the calling session.

If launching the VM succeeds, the new VM process will create its own session and write-lock the machine for it, preventing conflicting changes from other processes. If the machine is already locked (because it is already running or because another session has a write lock), launching the VM process will therefore fail. Reversely, future attempts to obtain a write lock will also fail while the machine is running.

The caller's session object remains separate from the session opened by the new VM process. It receives its own IConsole object which can be used to control machine execution, but it cannot be used to change all VM settings which would be available after a lockMachine call.

The caller must eventually release the session's shared lock by calling ISession::unlockMachine on the local session object once this call has returned. However, the session's state (see ISession::state) will not return to "Unlocked" until the remote session has also unlocked the machine (i.e. the machine has stopped running).

Launching a VM process can take some time (a new VM is started in a new process, for which memory and other resources need to be set up). Because of this, an IProgress object is returned to allow the caller to wait for this asynchronous operation to be completed. Until then, the caller's session object remains in the "Unlocked" state, and its ISession::machine and ISession::console attributes cannot be accessed. It is recommended to use IProgress::waitForCompletion or similar calls to wait for completion. Completion is signalled when the VM is powered on. If launching the VM fails, error messages can be queried via the progress object, if available.

The progress object will have at least 2 sub-operations. The first operation covers the period up to the new VM process calls powerUp. The subsequent operations mirror the IConsole::powerUp progress object. Because IConsole::powerUp may require some extra sub-operations, the IProgress::operationCount may change at the completion of operation.

For details on the teleportation progress operation, see IConsole::powerUp.

The environmentChanges argument is a list of strings where every string contains environment variable in the putenv style, i.e. "VAR=VALUE" for setting/replacing and "VAR" for unsetting. These environment variables will be applied to the environment of the VirtualBox server process. If an environment variable exists both in the server process and in this list, the value from this list takes precedence over the server's variable. If the value of the environment variable is omitted, this variable will be removed from the resulting environment. If the list is empty, the server environment is inherited by the started process as is.

Parameters

  session | Client session object to which the VM process will be connected (this must be in "Unlocked" state).
  name | Front-end to use for the new VM process. The following are currently supported:

- `"gui"`: VirtualBox Qt GUI front-end
- `"headless"`: VBoxHeadless (VRDE Server) front-end
- `"sdl"`: VirtualBox SDL front-end
- `"emergencystop"`: reserved value, used for aborting the currently running VM or session owner. In this case the session parameter may be `null` (if it is non-null it isn't used in any way), and the progress return value will be always `null`. The operation completes immediately.
- `""`: use the per-VM default frontend if set, otherwise the global default defined in the system properties. If neither are set, the API will launch a `"gui"` session, which may fail if there is no windowing environment available. See IMachine::defaultFrontend and ISystemProperties::defaultFrontend.

Parameters

  environmentChanges | The list of putenv-style changes to the VM process environment.
  progress | Progress object to track the operation completion.

Expected result codes:

  E_UNEXPECTED | Virtual machine not registered.
  E_INVALIDARG | Invalid session type type.
  VBOX_E_OBJECT_NOT_FOUND | No machine matching machineId found.
  VBOX_E_INVALID_OBJECT_STATE | Session already open or being opened.
  VBOX_E_IPRT_ERROR | Launching process for machine failed.
  VBOX_E_VM_ERROR | Failed to assign machine to session.

## ◆ setBootOrder()

void IMachine::setBootOrder | ( | in unsigned long | position,
|  | in DeviceType | device
| ) |  |

Puts the given device to the specified position in the boot order.

To indicate that no device is associated with the given position, DeviceType_Null should be used.

Todo:
  setHardDiskBootOrder(), setNetworkBootOrder()

Parameters

  position | Position in the boot order (`1` to the total number of devices the machine can boot from, as returned by IPlatformProperties::maxBootPosition).
  device | The type of the device used to boot at the given position.

Expected result codes:

  E_INVALIDARG | Boot position out of range.
  E_NOTIMPL | Booting from USB device currently not supported.

## ◆ getBootOrder()

void IMachine::getBootOrder | ( | in unsigned long | position,
|  | [retval] out DeviceType | device
| ) |  |

Returns the device type that occupies the specified position in the boot order.

Todo:
  [remove?] If the machine can have more than one device of the returned type (such as hard disks), then a separate method should be used to retrieve the individual device that occupies the given position.

If here are no devices at the given position, then DeviceType_Null is returned.

Todo:
  getHardDiskBootOrder(), getNetworkBootOrder()

Parameters

  position | Position in the boot order (`1` to the total number of devices the machine can boot from, as returned by IPlatformProperties::maxBootPosition).
  device | Device at the given position.

Expected result codes:

  E_INVALIDARG | Boot position out of range.

## ◆ attachDevice()

void IMachine::attachDevice | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | in DeviceType | type,
|  | in IMedium | medium
| ) |  |

Attaches a device and optionally mounts a medium to the given storage controller (IStorageController, identified by name), at the indicated port and device.

This method is intended for managing storage devices in general while a machine is powered off. It can be used to attach and detach fixed and removable media. The following kind of media can be attached to a machine:

- For fixed and removable media, you can pass in a medium that was previously opened using IVirtualBox::openMedium.
- Only for storage devices supporting removable media (such as DVDs and floppies), you can also specify a null pointer to indicate an empty drive or one of the medium objects listed in the IHost::DVDDrives and IHost::floppyDrives arrays to indicate a host drive. For removable devices, you can also use IMachine::mountMedium to change the media while the machine is running.

In a VM's default configuration of virtual machines, the secondary master of the IDE controller is used for a CD/DVD drive.

After calling this returns successfully, a new instance of IMediumAttachment will appear in the machine's list of medium attachments (see IMachine::mediumAttachments).

See IMedium and IMediumAttachment for more information about attaching media.

The specified device slot must not have a device attached to it, or this method will fail.

Parameters

  name | Name of the storage controller to attach the device to.
  controllerPort | Port to attach the device to. For an IDE controller, 0 specifies the primary controller and 1 specifies the secondary controller. For a SCSI controller, this must range from 0 to 15; for a SATA controller, from 0 to 29; for an SAS controller, from 0 to 7.
  device | Device slot in the given port to attach the device to. This is only relevant for IDE controllers, for which 0 specifies the master device and 1 specifies the slave device. For all other controller types, this must be 0.
  type | Device type of the attached device. For media opened by IVirtualBox::openMedium, this must match the device type specified there.
  medium | Medium to mount or `null` for an empty drive.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range, or file or UUID not found.
  VBOX_E_INVALID_OBJECT_STATE | Machine must be registered before media can be attached.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.
  VBOX_E_OBJECT_IN_USE | A medium is already attached to this or another virtual machine.

Note
  You cannot attach a device to a newly created machine until this machine's settings are saved to disk using saveSettings.
  If the medium is being attached indirectly, a new differencing medium will implicitly be created for it and attached instead. If the changes made to the machine settings (including this indirect attachment) are later cancelled using discardSettings, this implicitly created differencing medium will implicitly be deleted.

## ◆ attachDeviceWithoutMedium()

void IMachine::attachDeviceWithoutMedium | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | in DeviceType | type
| ) |  |

Attaches a device and optionally mounts a medium to the given storage controller (IStorageController, identified by name), at the indicated port and device.

This method is intended for managing storage devices in general while a machine is powered off. It can be used to attach and detach fixed and removable media. The following kind of media can be attached to a machine:

- For fixed and removable media, you can pass in a medium that was previously opened using IVirtualBox::openMedium.
- Only for storage devices supporting removable media (such as DVDs and floppies) with an empty drive or one of the medium objects listed in the IHost::DVDDrives and IHost::floppyDrives arrays to indicate a host drive. For removable devices, you can also use IMachine::mountMedium to change the media while the machine is running.

In a VM's default configuration of virtual machines, the secondary master of the IDE controller is used for a CD/DVD drive. IMediumAttachment will appear in the machine's list of medium attachments (see IMachine::mediumAttachments).

See IMedium and IMediumAttachment for more information about attaching media.

The specified device slot must not have a device attached to it, or this method will fail.

Parameters

  name | Name of the storage controller to attach the device to.
  controllerPort | Port to attach the device to. For an IDE controller, 0 specifies the primary controller and 1 specifies the secondary controller. For a SCSI controller, this must range from 0 to 15; for a SATA controller, from 0 to 29; for an SAS controller, from 0 to 7.
  device | Device slot in the given port to attach the device to. This is only relevant for IDE controllers, for which 0 specifies the master device and 1 specifies the slave device. For all other controller types, this must be 0.
  type | Device type of the attached device. For media opened by IVirtualBox::openMedium, this must match the device type specified there.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range, or file or UUID not found.
  VBOX_E_INVALID_OBJECT_STATE | Machine must be registered before media can be attached.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.
  VBOX_E_OBJECT_IN_USE | A medium is already attached to this or another virtual machine.

Note
  You cannot attach a device to a newly created machine until this machine's settings are saved to disk using saveSettings.
  If the medium is being attached indirectly, a new differencing medium will implicitly be created for it and attached instead. If the changes made to the machine settings (including this indirect attachment) are later cancelled using discardSettings, this implicitly created differencing medium will implicitly be deleted.

## ◆ detachDevice()

void IMachine::detachDevice | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device
| ) |  |

Detaches the device attached to a device slot of the specified bus.

Detaching the device from the virtual machine is deferred. This means that the medium remains associated with the machine when this method returns and gets actually de-associated only after a successful saveSettings call. See IMedium for more detailed information about attaching media.

Parameters

  name | Name of the storage controller to detach the medium from.
  controllerPort | Port number to detach the medium from.
  device | Device slot number to detach the medium from.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Attempt to detach medium from a running virtual machine.
  VBOX_E_OBJECT_NOT_FOUND | No medium attached to given slot/bus.
  VBOX_E_NOT_SUPPORTED | Medium format does not support storage deletion (only for implicitly created differencing media, should not happen).

Note
  You cannot detach a device from a running machine.
  Detaching differencing media implicitly created by attachDevice for the indirect attachment using this method will not implicitly delete them. The IMedium::deleteStorage operation should be explicitly performed by the caller after the medium is successfully detached and the settings are saved with saveSettings, if it is the desired action.

## ◆ passthroughDevice()

void IMachine::passthroughDevice | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | in boolean | passthrough
| ) |  |

Sets the passthrough mode of an existing DVD device.

Changing the setting while the VM is running is forbidden. The setting is only used if at VM start the device is configured as a host DVD drive, in all other cases it is ignored. The device must already exist; see IMachine::attachDevice for how to attach a new device.

The controllerPort and device parameters specify the device slot and have have the same meaning as with IMachine::attachDevice.

Parameters

  name | Name of the storage controller.
  controllerPort | Storage controller port.
  device | Device slot in the given port.
  passthrough | New value for the passthrough setting.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range.
  VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.

## ◆ temporaryEjectDevice()

void IMachine::temporaryEjectDevice | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | in boolean | temporaryEject
| ) |  |

Sets the behavior for guest-triggered medium eject.

In some situations it is desirable that such ejects update the VM configuration, and in others the eject should keep the VM configuration. The device must already exist; see IMachine::attachDevice for how to attach a new device.

The controllerPort and device parameters specify the device slot and have have the same meaning as with IMachine::attachDevice.

Parameters

  name | Name of the storage controller.
  controllerPort | Storage controller port.
  device | Device slot in the given port.
  temporaryEject | New value for the eject behavior.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range.
  VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.

## ◆ nonRotationalDevice()

void IMachine::nonRotationalDevice | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | in boolean | nonRotational
| ) |  |

Sets a flag in the device information which indicates that the medium is not based on rotational technology, i.e.

that the access times are more or less independent of the position on the medium. This may or may not be supported by a particular drive, and is silently ignored in the latter case. At the moment only hard disks (which is a misnomer in this context) accept this setting. Changing the setting while the VM is running is forbidden. The device must already exist; see IMachine::attachDevice for how to attach a new device.

The controllerPort and device parameters specify the device slot and have have the same meaning as with IMachine::attachDevice.

Parameters

  name | Name of the storage controller.
  controllerPort | Storage controller port.
  device | Device slot in the given port.
  nonRotational | New value for the non-rotational device flag.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range.
  VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.

## ◆ setAutoDiscardForDevice()

void IMachine::setAutoDiscardForDevice | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | in boolean | discard
| ) |  |

Sets a flag in the device information which indicates that the medium supports discarding unused blocks (called trimming for SATA or unmap for SCSI devices) .This may or may not be supported by a particular drive, and is silently ignored in the latter case.

At the moment only hard disks (which is a misnomer in this context) accept this setting. Changing the setting while the VM is running is forbidden. The device must already exist; see IMachine::attachDevice for how to attach a new device.

The controllerPort and device parameters specify the device slot and have have the same meaning as with IMachine::attachDevice.

Parameters

  name | Name of the storage controller.
  controllerPort | Storage controller port.
  device | Device slot in the given port.
  discard | New value for the discard device flag.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, SCSI port out of range.
  VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.

## ◆ setHotPluggableForDevice()

void IMachine::setHotPluggableForDevice | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | in boolean | hotPluggable
| ) |  |

Sets a flag in the device information which indicates that the attached device is hot pluggable or not.

This may or may not be supported by a particular controller and/or drive, and is silently ignored in the latter case. Changing the setting while the VM is running is forbidden. The device must already exist; see IMachine::attachDevice for how to attach a new device.

The controllerPort and device parameters specify the device slot and have have the same meaning as with IMachine::attachDevice.

Parameters

  name | Name of the storage controller.
  controllerPort | Storage controller port.
  device | Device slot in the given port.
  hotPluggable | New value for the hot-pluggable device flag.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range.
  VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.
  VBOX_E_NOT_SUPPORTED | Controller doesn't support hot plugging.

## ◆ setBandwidthGroupForDevice()

void IMachine::setBandwidthGroupForDevice | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | in IBandwidthGroup | bandwidthGroup
| ) |  |

Sets the bandwidth group of an existing storage device.

The device must already exist; see IMachine::attachDevice for how to attach a new device.

The controllerPort and device parameters specify the device slot and have have the same meaning as with IMachine::attachDevice.

Parameters

  name | Name of the storage controller.
  controllerPort | Storage controller port.
  device | Device slot in the given port.
  bandwidthGroup | New value for the bandwidth group or `null` for no group.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range.
  VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.

## ◆ setNoBandwidthGroupForDevice()

void IMachine::setNoBandwidthGroupForDevice | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device
| ) |  |

Sets no bandwidth group for an existing storage device.

The device must already exist; see IMachine::attachDevice for how to attach a new device. The controllerPort and device parameters specify the device slot and have have the same meaning as with IMachine::attachDevice.

Parameters

  name | Name of the storage controller.
  controllerPort | Storage controller port.
  device | Device slot in the given port.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range.
  VBOX_E_INVALID_OBJECT_STATE | Attempt to modify an unregistered virtual machine.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.

## ◆ unmountMedium()

void IMachine::unmountMedium | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | in boolean | force
| ) |  |

Unmounts any currently mounted medium (IMedium, identified by the given UUID id) to the given storage controller (IStorageController, identified by name), at the indicated port and device.

The device must already exist;

This method is intended only for managing removable media, where the device is fixed but media is changeable at runtime (such as DVDs and floppies). It cannot be used for fixed media such as hard disks.

The controllerPort and device parameters specify the device slot and have have the same meaning as with IMachine::attachDevice.

The specified device slot must have a medium mounted, which will be unmounted. If there is no mounted medium it will do nothing. See IMedium for more detailed information about attaching/unmounting media.

Parameters

  name | Name of the storage controller to unmount the medium from.
  controllerPort | Port to unmount the medium from.
  device | Device slot in the given port to unmount the medium from.
  force | Allows to force unmount of a medium which is locked by the device slot in the given port medium is attached to.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range.
  VBOX_E_INVALID_OBJECT_STATE | Attempt to unmount medium that is not removable - not DVD or floppy.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.
  VBOX_E_OBJECT_IN_USE | Medium already attached to this or another virtual machine.
  VBOX_E_OBJECT_NOT_FOUND | Medium not attached to specified port, device, controller.

## ◆ mountMedium()

void IMachine::mountMedium | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | in IMedium | medium,
|  | in boolean | force
| ) |  |

Mounts a medium (IMedium, identified by the given UUID id) to the given storage controller (IStorageController, identified by name), at the indicated port and device.

The device must already exist; see IMachine::attachDevice for how to attach a new device.

This method is intended only for managing removable media, where the device is fixed but media is changeable at runtime (such as DVDs and floppies). It cannot be used for fixed media such as hard disks.

The controllerPort and device parameters specify the device slot and have have the same meaning as with IMachine::attachDevice.

The specified device slot can have a medium mounted, which will be unmounted first. Specifying a zero UUID (or an empty string) for medium does just an unmount.

See IMedium for more detailed information about attaching media.

Parameters

  name | Name of the storage controller to attach the medium to.
  controllerPort | Port to attach the medium to.
  device | Device slot in the given port to attach the medium to.
  medium | Medium to mount or `null` for an empty drive.
  force | Allows to force unmount/mount of a medium which is locked by the device slot in the given port to attach the medium to.

Expected result codes:

  E_INVALIDARG | SATA device, SATA port, IDE port or IDE slot out of range.
  VBOX_E_INVALID_OBJECT_STATE | Attempt to attach medium to an unregistered virtual machine.
  VBOX_E_INVALID_VM_STATE | Invalid machine state.
  VBOX_E_OBJECT_IN_USE | Medium already attached to this or another virtual machine.

## ◆ getMedium()

void IMachine::getMedium | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | [retval] out IMedium | medium
| ) |  |

Returns the virtual medium attached to a device slot of the specified bus.

Note that if the medium was indirectly attached by mountMedium to the given device slot then this method will return not the same object as passed to the mountMedium call. See IMedium for more detailed information about mounting a medium.

Parameters

  name | Name of the storage controller the medium is attached to.
  controllerPort | Port to query.
  device | Device slot in the given port to query.
  medium | Attached medium object.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | No medium attached to given slot/bus.

## ◆ getMediumAttachmentsOfController()

void IMachine::getMediumAttachmentsOfController | ( | in wstring | name,
|  | [retval] out IMediumAttachment[] | mediumAttachments
| ) |  |

Returns an array of medium attachments which are attached to the the controller with the given name.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | A storage controller with given name doesn't exist.

## ◆ getMediumAttachment()

void IMachine::getMediumAttachment | ( | in wstring | name,
|  | in long | controllerPort,
|  | in long | device,
|  | [retval] out IMediumAttachment | attachment
| ) |  |

Returns a medium attachment which corresponds to the controller with the given name, on the given port and device slot.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | No attachment exists for the given controller/port/device combination.

## ◆ attachHostPCIDevice()

void IMachine::attachHostPCIDevice | ( | in long | hostAddress,
|  | in long | desiredGuestAddress,
|  | in boolean | tryToUnbind
| ) |  |

Attaches host PCI device with the given (host) PCI address to the PCI bus of the virtual machine.

Please note, that this operation is two phase, as real attachment will happen when VM will start, and most information will be delivered as IHostPCIDevicePlugEvent on IVirtualBox event source.

Parameters

  hostAddress | Address of the host PCI device.
  desiredGuestAddress | Desired position of this device on guest PCI bus.
  tryToUnbind | If VMM shall try to unbind existing drivers from the device before attaching it to the guest.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine state is not stopped (PCI hotplug not yet implemented).
  VBOX_E_PDM_ERROR | Virtual machine does not have a PCI controller allowing attachment of physical devices.
  VBOX_E_NOT_SUPPORTED | Hardware or host OS doesn't allow PCI device passthrough.

See also
  IHostPCIDevicePlugEvent

## ◆ detachHostPCIDevice()

void IMachine::detachHostPCIDevice | ( | in long | hostAddress | ) |

Detach host PCI device from the virtual machine.

Also HostPCIDevicePlugEvent on IVirtualBox event source will be delivered. As currently we don't support hot device unplug, IHostPCIDevicePlugEvent event is delivered immediately.

Parameters

  hostAddress | Address of the host PCI device.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine state is not stopped (PCI hotplug not yet implemented).
  VBOX_E_OBJECT_NOT_FOUND | This host device is not attached to this machine.
  VBOX_E_PDM_ERROR | Virtual machine does not have a PCI controller allowing attachment of physical devices.
  VBOX_E_NOT_SUPPORTED | Hardware or host OS doesn't allow PCI device passthrough.

See also
  IHostPCIDevicePlugEvent

## ◆ getNetworkAdapter()

void IMachine::getNetworkAdapter | ( | in unsigned long | slot,
|  | [retval] out INetworkAdapter | adapter
| ) |  |

Returns the network adapter associated with the given slot.

Slots are numbered sequentially, starting with zero. The total number of adapters per machine is defined by the IPlatformProperties::getMaxNetworkAdapters property, so the maximum slot number is one less than that property's value.

Expected result codes:

  E_INVALIDARG | Invalid slot number.

## ◆ addStorageController()

void IMachine::addStorageController | ( | in wstring | name,
|  | in StorageBus | connectionType,
|  | [retval] out IStorageController | controller
| ) |  |

Adds a new storage controller (SCSI, SAS or SATA controller) to the machine and returns it as an instance of IStorageController.

name identifies the controller for subsequent calls such as getStorageControllerByName, getStorageControllerByInstance, removeStorageController, attachDevice or mountMedium.

After the controller has been added, you can set its exact type by setting the IStorageController::controllerType.

Expected result codes:

  VBOX_E_OBJECT_IN_USE | A storage controller with given name exists already.
  E_INVALIDARG | Invalid controllerType.

## ◆ getStorageControllerByName()

void IMachine::getStorageControllerByName | ( | in wstring | name,
|  | [retval] out IStorageController | storageController
| ) |  |

Returns a storage controller with the given name.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | A storage controller with given name doesn't exist.

## ◆ getStorageControllerByInstance()

void IMachine::getStorageControllerByInstance | ( | in StorageBus | connectionType,
|  | in unsigned long | instance,
|  | [retval] out IStorageController | storageController
| ) |  |

Returns a storage controller of a specific storage bus with the given instance number.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | A storage controller with given instance number doesn't exist.

## ◆ removeStorageController()

void IMachine::removeStorageController | ( | in wstring | name | ) |

Removes a storage controller from the machine with all devices attached to it.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | A storage controller with given name doesn't exist.
  VBOX_E_NOT_SUPPORTED | Medium format does not support storage deletion (only for implicitly created differencing media, should not happen).

## ◆ setStorageControllerBootable()

void IMachine::setStorageControllerBootable | ( | in wstring | name,
|  | in boolean | bootable
| ) |  |

Sets the bootable flag of the storage controller with the given name.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | A storage controller with given name doesn't exist.
  VBOX_E_OBJECT_IN_USE | Another storage controller is marked as bootable already.

## ◆ addUSBController()

void IMachine::addUSBController | ( | in wstring | name,
|  | in USBControllerType | type,
|  | [retval] out IUSBController | controller
| ) |  |

Adds a new USB controller to the machine and returns it as an instance of IUSBController.

Expected result codes:

  VBOX_E_OBJECT_IN_USE | A USB controller with given type exists already.
  E_INVALIDARG | Invalid controllerType.

## ◆ removeUSBController()

void IMachine::removeUSBController | ( | in wstring | name | ) |

Removes a USB controller from the machine.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | A USB controller with given type doesn't exist.

## ◆ getUSBControllerByName()

void IMachine::getUSBControllerByName | ( | in wstring | name,
|  | [retval] out IUSBController | controller
| ) |  |

Returns a USB controller with the given type.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | A USB controller with given name doesn't exist.

## ◆ getUSBControllerCountByType()

void IMachine::getUSBControllerCountByType | ( | in USBControllerType | type,
|  | [retval] out unsigned long | controllers
| ) |  |

Returns the number of USB controllers of the given type attached to the VM.

## ◆ getSerialPort()

void IMachine::getSerialPort | ( | in unsigned long | slot,
|  | [retval] out ISerialPort | port
| ) |  |

Returns the serial port associated with the given slot.

Slots are numbered sequentially, starting with zero. The total number of serial ports per machine is defined by the IPlatformProperties::serialPortCount property, so the maximum slot number is one less than that property's value.

Expected result codes:

  E_INVALIDARG | Invalid slot number.

## ◆ getParallelPort()

void IMachine::getParallelPort | ( | in unsigned long | slot,
|  | [retval] out IParallelPort | port
| ) |  |

Returns the parallel port associated with the given slot.

Slots are numbered sequentially, starting with zero. The total number of parallel ports per machine is defined by the IPlatformProperties::parallelPortCount property, so the maximum slot number is one less than that property's value.

Expected result codes:

  E_INVALIDARG | Invalid slot number.

## ◆ getExtraDataKeys()

void IMachine::getExtraDataKeys | ( | [retval] out wstring[] | keys | ) |

Returns an array representing the machine-specific extra data keys which currently have values defined.

Parameters

  keys | Array of extra data keys.

## ◆ getExtraData()

void IMachine::getExtraData | ( | in wstring | key,
|  | [retval] out wstring | value
| ) |  |

Returns associated machine-specific extra data.

If the requested data key does not exist, this function will succeed and return an empty string in the value argument.

Parameters

  key | Name of the data key to get.
  value | Value of the requested data key.

Expected result codes:

  VBOX_E_FILE_ERROR | Settings file not accessible.
  VBOX_E_XML_ERROR | Could not parse the settings file.

## ◆ setExtraData()

void IMachine::setExtraData | ( | in wstring | key,
|  | in wstring | value
| ) |  |

Sets associated machine-specific extra data.

If you pass `null` or an empty string as a key value, the given key will be deleted.

Parameters

  key | Name of the data key to set.
  value | Value to assign to the key.

Expected result codes:

  VBOX_E_FILE_ERROR | Settings file not accessible.
  VBOX_E_XML_ERROR | Could not parse the settings file.
  E_INVALIDARG | Key contains invalid characters.

Note
  Key must contain printable (non-control) UTF-8 characters only.
  Before performing the actual data change, this method will ask all registered event listeners using the IExtraDataCanChangeEvent notification for a permission. If one of the listeners refuses the new value, the change will not be performed.
  On success, the IExtraDataChangedEvent notification is called to inform all registered listeners about a successful data change.
  This method can be called outside the machine session and therefore it's a caller's responsibility to handle possible race conditions when several clients change the same key at the same time.

## ◆ setSettingsFilePath()

void IMachine::setSettingsFilePath | ( | in wstring | settingsFilePath,
|  | [retval] out IProgress | progress
| ) |  |

Currently, it is an error to change this property on any machine.

Later this will allow setting a new path for the settings file, with automatic relocation of all files (including snapshots and disk images) which are inside the base directory. This operation is only allowed when there are no pending unsaved settings.

Parameters

  settingsFilePath | New settings file path, will be used to determine the new location for the attached media if it is in the same directory or below as the original settings file.
  progress | Progress object to track the operation completion.

Expected result codes:

  E_NOTIMPL | The operation is not implemented yet.

Note
  Setting this property to `null` or to an empty string is forbidden. When setting this property, the specified path must be absolute. The specified path may not exist, it will be created when necessary.

## ◆ saveSettings()

void IMachine::saveSettings | ( |  | ) |

Saves any changes to machine settings made since the session has been opened or a new machine has been created, or since the last call to saveSettings or discardSettings.

For registered machines, new settings become visible to all other VirtualBox clients after successful invocation of this method.

Expected result codes:

  VBOX_E_FILE_ERROR | Settings file not accessible.
  VBOX_E_XML_ERROR | Could not parse the settings file.
  E_ACCESSDENIED | Modification request refused.

Note
  The method sends IMachineDataChangedEvent notification event after the configuration has been successfully saved (only for registered machines).
  Calling this method is only valid on instances returned by ISession::machine and on new machines created by IVirtualBox::createMachine but not yet registered, or on unregistered machines after calling IMachine::unregister.

## ◆ discardSettings()

void IMachine::discardSettings | ( |  | ) |

Discards any changes to the machine settings made since the session has been opened or since the last call to saveSettings or discardSettings.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine is not mutable.

Note
  Calling this method is only valid on instances returned by ISession::machine and on new machines created by IVirtualBox::createMachine or opened by IVirtualBox::openMachine but not yet registered, or on unregistered machines after calling IMachine::unregister.

## ◆ unregister()

void IMachine::unregister | ( | in CleanupMode | cleanupMode,
|  | [retval] out IMedium[] | media
| ) |  |

Unregisters a machine previously registered with IVirtualBox::registerMachine and optionally do additional cleanup before the machine is unregistered.

This method does not delete any files. It only changes the machine configuration and the list of registered machines in the VirtualBox object. To delete the files which belonged to the machine, including the XML file of the machine itself, call deleteConfig, optionally with the array of IMedium objects which was returned from this method.

How thoroughly this method cleans up the machine configuration before unregistering the machine depends on the cleanupMode argument.

- With "UnregisterOnly", the machine will only be unregistered, but no additional cleanup will be performed. The call will fail if the machine has any snapshots or any media attached (see IMediumAttachment). It is the responsibility of the caller to delete all such configuration in this mode. In this mode, the API behaves like the former `IVirtualBox::unregisterMachine()` API which it replaces.
- With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved" state or if it has snapshots or media attached. All media attached to the current machine state or in snapshots will be detached. No medium objects will be returned; all of the machine's media will remain open.
- With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone", except that all the hard disk medium objects which were detached from the machine will be returned as an array. This allows for quickly passing them to the deleteConfig API for closing and deletion.
- With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except that all media will be returned in the array, including removable media like DVDs and floppies. This might be useful if the user wants to inspect in detail which media were attached to the machine. Be careful when passing the media array to deleteConfig in that case because users will typically want to preserve ISO and RAW image files.

A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the resulting IMedium array to deleteConfig. This way, the machine is completely deleted with all its saved states and hard disk images, but images for removable drives (such as ISO and RAW files) will remain on disk.

This API does not verify whether the media files returned in the array are still attached to other machines (i.e. shared between several machines). If such a shared image is passed to deleteConfig however, closing the image will fail there and the image will be silently skipped.

This API may, however, move media from this machine's media registry to other media registries (see IMedium for details on media registries). For machines created with VirtualBox 4.0 or later, if media from this machine's media registry are also attached to another machine (shared attachments), each such medium will be moved to another machine's registry. This is because without this machine's media registry, the other machine cannot find its media any more and would become inaccessible.

This API implicitly calls saveSettings to save all current machine settings before unregistering it. It may also silently call saveSettings on other machines if media are moved to other machines' media registries.

After successful method invocation, the IMachineRegisteredEvent event is fired.

The call will fail if the machine is currently locked (see ISession).

Parameters

  cleanupMode | How to clean up after the machine has been unregistered.
  media | List of media detached from the machine, depending on the cleanupMode parameter.

Expected result codes:

  VBOX_E_INVALID_OBJECT_STATE | Machine is currently locked for a session.

Note
  If the given machine is inaccessible (see accessible), it will be unregistered and fully uninitialized right afterwards. As a result, the returned machine object will be unusable and an attempt to call any method will return the "Object not ready" error.

## ◆ deleteConfig()

void IMachine::deleteConfig | ( | in IMedium[] | media,
|  | [retval] out IProgress | progress
| ) |  |

Deletes the files associated with this machine from disk.

If medium objects are passed in with the aMedia argument, they are closed and, if closing was successful, their storage files are deleted as well. For convenience, this array of media files can be the same as the one returned from a previous unregister call.

This method must only be called on machines which are either write-locked (i.e. on instances returned by ISession::machine) or on unregistered machines (i.e. not yet registered machines created by IVirtualBox::createMachine or opened by IVirtualBox::openMachine, or after having called unregister).

The following files will be deleted by this method:

- If unregister had been previously called with a cleanupMode argument other than "UnregisterOnly", this will delete all saved state files that the machine had in use; possibly one if the machine was in either the "Saved" or "AbortedSaved" state and one for each online snapshot that the machine had.
- On each medium object passed in the aMedia array, this will call IMedium::close. If that succeeds, this will attempt to delete the medium's storage on disk. Since the IMedium::close call will fail if the medium is still in use, e.g. because it is still attached to a second machine; in that case the storage will not be deleted.
- Finally, the machine's own XML file will be deleted.

Since deleting large disk image files can be a time-consuming I/O operation, this method operates asynchronously and returns an IProgress object to allow the caller to monitor the progress. There will be one sub-operation for each file that is being deleted (saved state or medium storage file).

Parameters

  media | List of media to be closed and whose storage files will be deleted.
  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine is registered but not write-locked.
  VBOX_E_IPRT_ERROR | Could not delete the settings file.

Note
  settingsModified will return `true` after this method successfully returns.

## ◆ exportTo()

void IMachine::exportTo | ( | in IAppliance | appliance,
|  | in wstring | location,
|  | [retval] out IVirtualSystemDescription | description
| ) |  |

Exports the machine to an OVF appliance.

See IAppliance for the steps required to export VirtualBox machines to OVF.

Parameters

  appliance | Appliance to export this machine to.
  location | The target location.
  description | VirtualSystemDescription object which is created for this machine.

## ◆ findSnapshot()

void IMachine::findSnapshot | ( | in wstring | nameOrId,
|  | [retval] out ISnapshot | snapshot
| ) |  |

Returns a snapshot of this machine with the given name or UUID.

Returns a snapshot of this machine with the given UUID. A `null` argument can be used to obtain the first snapshot taken on this machine. To traverse the whole tree of snapshots starting from the root, inspect the root snapshot's ISnapshot::children attribute and recurse over those children.

Parameters

  nameOrId | What to search for. Name or UUID of the snapshot to find
  snapshot | Snapshot object with the given name.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | Virtual machine has no snapshots or snapshot not found.

## ◆ createSharedFolder()

void IMachine::createSharedFolder | ( | in wstring | name,
|  | in wstring | hostPath,
|  | in boolean | writable,
|  | in boolean | automount,
|  | in wstring | autoMountPoint
| ) |  |

Creates a new permanent shared folder by associating the given logical name with the given host path, adds it to the collection of shared folders and starts sharing it.

Refer to the description of ISharedFolder to read more about logical names.

Parameters

  name | Unique logical name of the shared folder.
  hostPath | Full path to the shared folder in the host file system.
  writable | Whether the share is writable or read-only.
  automount | Whether the share gets automatically mounted by the guest or not.
  autoMountPoint | Where the guest should automatically mount the folder, if possible. For Windows and OS/2 guests this should be a drive letter, while other guests it should be a absolute directory.

Expected result codes:

  VBOX_E_OBJECT_IN_USE | Shared folder already exists.
  VBOX_E_FILE_ERROR | Shared folder hostPath not accessible.

## ◆ removeSharedFolder()

void IMachine::removeSharedFolder | ( | in wstring | name | ) |

Removes the permanent shared folder with the given name previously created by createSharedFolder from the collection of shared folders and stops sharing it.

Parameters

  name | Logical name of the shared folder to remove.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine is not mutable.
  VBOX_E_OBJECT_NOT_FOUND | Shared folder name does not exist.

## ◆ canShowConsoleWindow()

void IMachine::canShowConsoleWindow | ( | [retval] out boolean | canShow | ) |

Returns `true` if the VM console process can activate the console window and bring it to foreground on the desktop of the host PC.

Parameters

  canShow | `true` if the console window can be shown and `false` otherwise.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.

Note
  This method will fail if a session for this machine is not currently open.

## ◆ showConsoleWindow()

void IMachine::showConsoleWindow | ( | [retval] out long long | winId | ) |

Activates the console window and brings it to foreground on the desktop of the host PC.

Many modern window managers on many platforms implement some sort of focus stealing prevention logic, so that it may be impossible to activate a window without the help of the currently active application. In this case, this method will return a non-zero identifier that represents the top-level window of the VM console process. The caller, if it represents a currently active process, is responsible to use this identifier (in a platform-dependent manner) to perform actual window activation.

Parameters

  winId | Platform-dependent identifier of the top-level VM console window, or zero if this method has performed all actions necessary to implement the show window semantics for the given platform and/or VirtualBox front-end.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.

Note
  This method will fail if a session for this machine is not currently open.

## ◆ getGuestProperty()

void IMachine::getGuestProperty | ( | in wstring | name,
|  | out wstring | value,
|  | out long long | timestamp,
|  | out wstring | flags
| ) |  |

Reads an entry from the machine's guest property store.

Parameters

  name | The name of the property to read.
  value | The value of the property. If the property does not exist then this will be empty.
  timestamp | The time at which the property was last modified, as seen by the server process.
  flags | Additional property parameters, passed as a comma-separated list of "name=value" type entries.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.

## ◆ getGuestPropertyValue()

void IMachine::getGuestPropertyValue | ( | in wstring | property,
|  | [retval] out wstring | value
| ) |  |

Reads a value from the machine's guest property store.

Parameters

  property | The name of the property to read.
  value | The value of the property. If the property does not exist then this will be empty.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.

## ◆ getGuestPropertyTimestamp()

void IMachine::getGuestPropertyTimestamp | ( | in wstring | property,
|  | [retval] out long long | value
| ) |  |

Reads a property timestamp from the machine's guest property store.

Parameters

  property | The name of the property to read.
  value | The timestamp. If the property does not exist then this will be empty.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.

## ◆ setGuestProperty()

void IMachine::setGuestProperty | ( | in wstring | property,
|  | in wstring | value,
|  | in wstring | flags
| ) |  |

Sets, changes or deletes an entry in the machine's guest property store.

Parameters

  property | The name of the property to set, change or delete.
  value | The new value of the property to set, change or delete. If the property does not yet exist and value is non-empty, it will be created. If the value is `null` or empty, the property will be deleted if it exists.
  flags | Additional property parameters, passed as a comma-separated list of "name=value" type entries.

Expected result codes:

  E_ACCESSDENIED | Property cannot be changed.
  E_INVALIDARG | Invalid flags.
  VBOX_E_INVALID_VM_STATE | Virtual machine is not mutable or session not open.
  VBOX_E_INVALID_OBJECT_STATE | Cannot set transient property when machine not running.

## ◆ setGuestPropertyValue()

void IMachine::setGuestPropertyValue | ( | in wstring | property,
|  | in wstring | value
| ) |  |

Sets or changes a value in the machine's guest property store.

The flags field will be left unchanged or created empty for a new property.

Parameters

  property | The name of the property to set or change.
  value | The new value of the property to set or change. If the property does not yet exist and value is non-empty, it will be created.

Expected result codes:

  E_ACCESSDENIED | Property cannot be changed.
  VBOX_E_INVALID_VM_STATE | Virtual machine is not mutable or session not open.
  VBOX_E_INVALID_OBJECT_STATE | Cannot set transient property when machine not running.

## ◆ deleteGuestProperty()

void IMachine::deleteGuestProperty | ( | in wstring | name | ) |

Deletes an entry from the machine's guest property store.

Parameters

  name | The name of the property to delete.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Machine session is not open.

## ◆ enumerateGuestProperties()

void IMachine::enumerateGuestProperties | ( | in wstring | patterns,
|  | out wstring[] | names,
|  | out wstring[] | values,
|  | out long long[] | timestamps,
|  | out wstring[] | flags
| ) |  |

Return a list of the guest properties matching a set of patterns along with their values, timestamps and flags.

Parameters

  patterns | The patterns to match the properties against, separated by '|' characters. If this is empty or `null`, all properties will match.
  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.

## ◆ querySavedGuestScreenInfo()

void IMachine::querySavedGuestScreenInfo | ( | in unsigned long | screenId,
|  | out unsigned long | originX,
|  | out unsigned long | originY,
|  | out unsigned long | width,
|  | out unsigned long | height,
|  | out boolean | enabled
| ) |  |

Returns the guest dimensions from the saved state.

Parameters

  screenId | Saved guest screen to query info from.
  originX | The X position of the guest monitor top left corner.
  originY | The Y position of the guest monitor top left corner.
  width | Guest width at the time of the saved state was taken.
  height | Guest height at the time of the saved state was taken.
  enabled | Whether the monitor is enabled in the guest.

## ◆ readSavedThumbnailToArray()

void IMachine::readSavedThumbnailToArray | ( | in unsigned long | screenId,
|  | in BitmapFormat | bitmapFormat,
|  | out unsigned long | width,
|  | out unsigned long | height,
|  | [retval] out octet[] | data
| ) |  |

Thumbnail is retrieved to an array of bytes in the requested format.

Parameters

  screenId | Saved guest screen to read from.
  bitmapFormat | The requested format.
  width | Bitmap width.
  height | Bitmap height.
  data | Array with resulting bitmap data.

## ◆ querySavedScreenshotInfo()

void IMachine::querySavedScreenshotInfo | ( | in unsigned long | screenId,
|  | out unsigned long | width,
|  | out unsigned long | height,
|  | [retval] out BitmapFormat[] | bitmapFormats
| ) |  |

Returns available formats and size of the screenshot from saved state.

Parameters

  screenId | Saved guest screen to query info from.
  width | Image width.
  height | Image height.
  bitmapFormats | Formats supported by readSavedScreenshotToArray.

## ◆ readSavedScreenshotToArray()

void IMachine::readSavedScreenshotToArray | ( | in unsigned long | screenId,
|  | in BitmapFormat | bitmapFormat,
|  | out unsigned long | width,
|  | out unsigned long | height,
|  | [retval] out octet[] | data
| ) |  |

Screenshot in requested format is retrieved to an array of bytes.

Parameters

  screenId | Saved guest screen to read from.
  bitmapFormat | The requested format.
  width | Image width.
  height | Image height.
  data | Array with resulting image data.

## ◆ hotPlugCPU()

void IMachine::hotPlugCPU | ( | in unsigned long | cpu | ) |

Plugs a CPU into the machine.

Parameters

  cpu | The CPU id to insert.

## ◆ hotUnplugCPU()

void IMachine::hotUnplugCPU | ( | in unsigned long | cpu | ) |

Removes a CPU from the machine.

Parameters

  cpu | The CPU id to remove.

## ◆ getCPUStatus()

void IMachine::getCPUStatus | ( | in unsigned long | cpu,
|  | [retval] out boolean | attached
| ) |  |

Returns the current status of the given CPU.

Parameters

  cpu | The CPU id to check for.
  attached | Status of the CPU.

## ◆ getEffectiveParavirtProvider()

void IMachine::getEffectiveParavirtProvider | ( | [retval] out ParavirtProvider | paravirtProvider | ) |

Returns the effective paravirtualization provider for this VM.

Parameters

  paravirtProvider | The effective paravirtualization provider for this VM.

## ◆ queryLogFilename()

void IMachine::queryLogFilename | ( | in unsigned long | idx,
|  | [retval] out wstring | filename
| ) |  |

Queries for the VM log file name of an given index.

Returns an empty string if a log file with that index doesn't exists.

Parameters

  idx | Which log file name to query. 0=current log file.
  filename | On return the full path to the log file or an empty string on error.

## ◆ readLog()

void IMachine::readLog | ( | in unsigned long | idx,
|  | in long long | offset,
|  | in long long | size,
|  | [retval] out octet[] | data
| ) |  |

Reads the VM log file.

The chunk size is limited, so even if you ask for a big piece there might be less data returned.

Parameters

  idx | Which log file to read. 0=current log file.
  offset | Offset in the log file.
  size | Chunk size to read in the log file.
  data | Data read from the log file. A data size of 0 means end of file if the requested chunk size was not 0. This is the unprocessed file data, i.e. the line ending style depends on the platform of the system the server is running on.

## ◆ cloneTo()

void IMachine::cloneTo | ( | in IMachine | target,
|  | in CloneMode | mode,
|  | in CloneOptions[] | options,
|  | [retval] out IProgress | progress
| ) |  |

Creates a clone of this machine, either as a full clone (which means creating independent copies of the hard disk media, save states and so on), or as a linked clone (which uses its own differencing media, sharing the parent media with the source machine).

The target machine object must have been created previously with IVirtualBox::createMachine, and all the settings will be transferred except the VM name and the hardware UUID. You can set the VM name and the new hardware UUID when creating the target machine. The network MAC addresses are newly created for all enabled network adapters. You can change that behaviour with the options parameter. The operation is performed asynchronously, so the machine object will be not be usable until the progress object signals completion.

Parameters

  target | Target machine object.
  mode | Which states should be cloned.
  options | Options for the cloning operation.
  progress | Progress object to track the operation completion.

Expected result codes:

  E_INVALIDARG | target is `null`.

## ◆ moveTo()

void IMachine::moveTo | ( | in wstring | folder,
|  | in wstring | type,
|  | [retval] out IProgress | progress
| ) |  |

Move machine on to new place/folder.

Parameters

  folder | Target folder where machine is moved. May be the same folder where the VM already is located or the empty string, in which case the machine is kept in this location and the disk images and other files which are stored elsewhere are moved.
  type | Type of moving. Possible values: basic - Only the files which belong solely to this machine are moved from the original machine's folder to a new folder.
  progress | Progress object to track the operation completion.

## ◆ saveState()

void IMachine::saveState | ( | [retval] out IProgress | progress | ) |

Saves the current execution state of a running virtual machine and stops its execution.

After this operation completes, the machine will go to the Saved state. The next time it is powered up this state will be restored and the machine will continue its execution from the place where it was saved.

This operation differs from taking a snapshot to the effect that it doesn't create new differencing media. Also, once the machine is powered up from the state saved using this method, the saved state is deleted, so it will be impossible to return to this state later.

Parameters

  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine state neither Running nor Paused.
  VBOX_E_FILE_ERROR | Failed to create directory for saved state file.

Note
  On success, this method implicitly calls saveSettings to save all current machine settings (including runtime changes to the DVD medium, etc.). Together with the impossibility to change any VM settings when it is in the Saved state, this guarantees adequate hardware configuration of the machine when it is restored from the saved state file.
  The machine must be in the Running or Paused state, otherwise the operation will fail.

See also
  takeSnapshot

## ◆ adoptSavedState()

void IMachine::adoptSavedState | ( | in wstring | savedStateFile | ) |

Associates the given saved state file to the virtual machine.

On success, the machine will go to the Saved state. The next time it is powered up it will be restored from the adopted saved state and continue execution from the place where the saved state file was created.

The specified saved state file path may be absolute or relative to the folder the VM normally saves the state to (usually, snapshotFolder).

Parameters

  savedStateFile | Path to the saved state file to adopt.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine state neither PoweredOff nor Aborted.

Note
  It's a caller's responsibility to make sure the given saved state file is compatible with the settings of this virtual machine that represent its virtual hardware (memory size, storage disk configuration etc.). If there is a mismatch, the behavior of the virtual machine is undefined.

## ◆ discardSavedState()

void IMachine::discardSavedState | ( | in boolean | fRemoveFile | ) |

Forcibly resets the machine to "Powered Off" state if it is currently in the "Saved" state previously created by saveState) or in the "AbortedSaved" state.

The next time the machine is powered up a clean boot will occur.

If fRemoveFile is `true`, the file in the machine directory into which the machine state was saved is also deleted. If this is `false`, then the state can be recovered and later re-inserted into a machine using adoptSavedState. The location of the file can be found in the stateFilePath attribute.

Parameters

  fRemoveFile | Whether to also remove the saved state file.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine not in either the Saved or AbortedSaved state.

Note
  This operation is equivalent to resetting or powering off the machine without doing a proper shutdown of the guest operating system; as with resetting a running phyiscal computer, it can can lead to data loss.

## ◆ takeSnapshot()

void IMachine::takeSnapshot | ( | in wstring | name,
|  | in wstring | description,
|  | in boolean | pause,
|  | out wstringUUID | id,
|  | [retval] out IProgress | progress
| ) |  |

Saves the current execution state and all settings of the machine and creates differencing images for all normal (non-independent) media.

See ISnapshot for an introduction to snapshots.

This method can be called for a PoweredOff, Saved (see saveState), AbortedSaved, Running or Paused virtual machine. When the machine is PoweredOff, an offline snapshot is created. When the machine is Running a live snapshot is created, and an online snapshot is created when Paused.

The taken snapshot is always based on the current snapshot of the associated virtual machine and becomes a new current snapshot.

Parameters

  name | Short name for the snapshot.
  description | Optional description of the snapshot.
  pause | Whether the VM should be paused while taking the snapshot. Only relevant when the VM is running, and distinguishes between online (`true`) and live (`false`) snapshots. When the VM is not running the result is always an offline snapshot.
  id | UUID of the snapshot which will be created. Useful for follow-up operations after the snapshot has been created.
  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine currently changing state.

Note
  This method implicitly calls saveSettings to save all current machine settings before taking an offline snapshot.

## ◆ deleteSnapshot()

void IMachine::deleteSnapshot | ( | in wstringUUID | id,
|  | [retval] out IProgress | progress
| ) |  |

Starts deleting the specified snapshot asynchronously.

See ISnapshot for an introduction to snapshots.

The execution state and settings of the associated machine stored in the snapshot will be deleted. The contents of all differencing media of this snapshot will be merged with the contents of their dependent child media to keep the medium chain valid (in other words, all changes represented by media being deleted will be propagated to their child medium). After that, this snapshot's differencing medium will be deleted. The parent of this snapshot will become a new parent for all its child snapshots.

If the deleted snapshot is the current one, its parent snapshot will become a new current snapshot. The current machine state is not directly affected in this case, except that currently attached differencing media based on media of the deleted snapshot will be also merged as described above.

If the deleted snapshot is the first or current snapshot, then the respective IMachine attributes will be adjusted. Deleting the current snapshot will also implicitly call saveSettings to make all current machine settings permanent.

Deleting a snapshot has the following preconditions:

- Child media of all normal media of the deleted snapshot must be accessible (see IMedium::state) for this operation to succeed. If only one running VM refers to all images which participates in merging the operation can be performed while the VM is running. Otherwise all virtual machines whose media are directly or indirectly based on the media of deleted snapshot must be powered off. In any case, online snapshot deleting usually is slower than the same operation without any running VM.
- You cannot delete the snapshot if a medium attached to it has more than one child medium (differencing images) because otherwise merging would be impossible. This might be the case if there is more than one child snapshot or differencing images were created for other reason (e.g. implicitly because of multiple machine attachments).

The virtual machine's state is changed to "DeletingSnapshot", "DeletingSnapshotOnline" or "DeletingSnapshotPaused" while this operation is in progress.

Parameters

  id | UUID of the snapshot to delete.
  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | The running virtual machine prevents deleting this snapshot. This happens only in very specific situations, usually snapshots can be deleted without trouble while a VM is running. The error message text explains the reason for the failure.

Note
  Merging medium contents can be very time and disk space consuming, if these media are big in size and have many children. However, if the snapshot being deleted is the last (head) snapshot on the branch, the operation will be rather quick.

## ◆ deleteSnapshotAndAllChildren()

void IMachine::deleteSnapshotAndAllChildren | ( | in wstringUUID | id,
|  | [retval] out IProgress | progress
| ) |  |

Starts deleting the specified snapshot and all its children asynchronously.

See ISnapshot for an introduction to snapshots. The conditions and many details are the same as with deleteSnapshot.

This operation is very fast if the snapshot subtree does not include the current state. It is still significantly faster than deleting the snapshots one by one if the current state is in the subtree and there are more than one snapshots from current state to the snapshot which marks the subtree, since it eliminates the incremental image merging.

Parameters

  id | UUID of the snapshot to delete, including all its children.
  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | The running virtual machine prevents deleting this snapshot. This happens only in very specific situations, usually snapshots can be deleted without trouble while a VM is running. The error message text explains the reason for the failure.
  E_NOTIMPL | The method is not implemented yet.

Note
  This API method is right now not implemented!

## ◆ deleteSnapshotRange()

void IMachine::deleteSnapshotRange | ( | in wstringUUID | startId,
|  | in wstringUUID | endId,
|  | [retval] out IProgress | progress
| ) |  |

Starts deleting the specified snapshot range.

This is limited to linear snapshot lists, which means there may not be any other child snapshots other than the direct sequence between the start and end snapshot. If the start and end snapshot point to the same snapshot this method is completely equivalent to deleteSnapshot. See ISnapshot for an introduction to snapshots. The conditions and many details are the same as with deleteSnapshot.

This operation is generally faster than deleting snapshots one by one and often also needs less extra disk space before freeing up disk space by deleting the removed disk images corresponding to the snapshot.

Parameters

  startId | UUID of the first snapshot to delete.
  endId | UUID of the last snapshot to delete.
  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | The running virtual machine prevents deleting this snapshot. This happens only in very specific situations, usually snapshots can be deleted without trouble while a VM is running. The error message text explains the reason for the failure.
  E_NOTIMPL | The method is not implemented yet.

Note
  This API method is right now not implemented!

## ◆ restoreSnapshot()

void IMachine::restoreSnapshot | ( | in ISnapshot | snapshot,
|  | [retval] out IProgress | progress
| ) |  |

Starts resetting the machine's current state to the state contained in the given snapshot, asynchronously.

All current settings of the machine will be reset and changes stored in differencing media will be lost. See ISnapshot for an introduction to snapshots.

After this operation is successfully completed, new empty differencing media are created for all normal media of the machine.

If the given snapshot is an online snapshot, the machine will go to the Saved state, so that the next time it is powered on, the execution state will be restored from the state of the snapshot.

Parameters

  snapshot | The snapshot to restore the VM state from.
  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_INVALID_VM_STATE | Virtual machine is running.

Note
  The machine must not be running, otherwise the operation will fail.
  If the machine is in the Saved state prior to this operation, the saved state file will be implicitly deleted (as if IMachine::discardSavedState were called).

## ◆ applyDefaults()

void IMachine::applyDefaults | ( | in wstring | flags | ) |

Applies the defaults for the configured guest OS type.

This is primarily for getting sane settings straight after creating a new VM, but it can also be applied later.

Parameters

  flags | Additional flags, to be defined later.

Expected result codes:

  E_FAIL | General error.
  VBOX_E_INVALID_VM_STATE | The machine is in invalid state.
  VBOX_E_OBJECT_IN_USE | Some of the applied objects already exist. The method has been called to already configured machine.

Note
  This is primarily a shortcut, centralizing the tedious job of getting the recommended settings and translating them into settings updates. The settings are made at the end of the call, but not saved.

## ◆ changeEncryption()

void IMachine::changeEncryption | ( | in wstring | currentPassword,
|  | in wstring | cipher,
|  | in wstring | newPassword,
|  | in wstring | newPasswordId,
|  | in boolean | force,
|  | [retval] out IProgress | progress
| ) |  |

Starts encryption of this VM.

This means that the stored data of the VM is encrypted.

Please note that the results can be either returned straight away, or later as the result of the background operation via the object returned via the progress parameter.

Parameters

  currentPassword | The current password the VM is protected with. Use an empty string to indicate that the VM isn't encrypted.
  cipher | The cipher to use for encryption. An empty string indicates no encryption for the result.
  newPassword | The new password the VM should be protected with. An empty password and password ID will result in the VM being encrypted with the current password.
  newPasswordId | The ID of the new password when unlocking the VM.
  force | Force reencryption of the data if just password is changed. Otherwise, if data already encrypted and cipher doesn't changed only the password is changed.
  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_NOT_SUPPORTED | Encryption is not supported for various reasons e.g. unsupported cipher.

## ◆ getEncryptionSettings()

void IMachine::getEncryptionSettings | ( | out wstring | cipher,
|  | out wstring | passwordId
| ) |  |

Returns the encryption settings for this VM.

Parameters

  cipher | The cipher used for encryption.
  passwordId | The ID of the password when unlocking the VM.

Expected result codes:

  VBOX_E_NOT_SUPPORTED | Encryption is not configured for this VM.

## ◆ checkEncryptionPassword()

void IMachine::checkEncryptionPassword | ( | in wstring | password | ) |

Checks whether the supplied password is correct for the VM.

Parameters

  password | The password to check.

Expected result codes:

  VBOX_E_NOT_SUPPORTED | Encryption is not configured for this VM.
  VBOX_E_PASSWORD_INCORRECT | The given password is incorrect.

## ◆ addEncryptionPassword()

void IMachine::addEncryptionPassword | ( | in wstring | id,
|  | in wstring | password
| ) |  |

Adds a password used for encryption.

Updates the accesibility state if password used the VM encryption.

Parameters

  id | The identifier used for the password. Must match the identifier used when the encrypted VM was created.
  password | The password.

Expected result codes:

  VBOX_E_PASSWORD_INCORRECT | The password provided wasn't correct for the VM using the provided ID.

## ◆ addEncryptionPasswords()

void IMachine::addEncryptionPasswords | ( | in wstring[] | ids,
|  | in wstring[] | passwords
| ) |  |

Adds passwords used for encryption.

Updates the accesibility state if the list contains password used the VM encryption.

Parameters

  ids | List of identifiers for the passwords. Must match the identifier used when the encrypted VM was created.
  passwords | List of passwords.

Expected result codes:

  VBOX_E_PASSWORD_INCORRECT | The password provided wasn't correct for the VM using the provided ID.
  E_INVALIDARG | Id and passwords arrays have different size.

## ◆ removeEncryptionPassword()

void IMachine::removeEncryptionPassword | ( | in wstring | id | ) |

Removes a password used for the VM encryption/decryption.

The password can be removed only if the VM is powered off. Removing the password causes the VM goes to the inaccessible state and the password must be provided again.

Parameters

  id | The identifier used for the password. Must match the identifier used when the encrypted VM was created.

Note
  If machine becomes inaccessible all passwords are purged. One has to add required passwords again using either IMachine::addEncryptionPassword or IMachine::addEncryptionPasswords methods.

## ◆ clearAllEncryptionPasswords()

void IMachine::clearAllEncryptionPasswords | ( |  | ) |

Clears all provided VM passwords.

The passwords can be removed only if the VM is powered off. Removing the passwords causes the VM goes to the inaccessible state and the password must be provided again.

## Member Data Documentation

## ◆ parent

readonly attribute IVirtualBox IMachine::parent

Associated parent object.

## ◆ icon

attribute octet [] IMachine::icon

Overridden VM Icon details.

## ◆ accessible

readonly attribute boolean IMachine::accessible

Whether this virtual machine is currently accessible or not.

A machine is always deemed accessible unless it is registered and its settings file cannot be read or parsed (either because the file itself is unavailable or has invalid XML contents).

Every time this property is read, the accessibility state of this machine is re-evaluated. If the returned value is `false`, the accessError property may be used to get the detailed error information describing the reason of inaccessibility, including XML error messages.

When the machine is inaccessible, only the following properties can be used on it:

- parent
- id
- settingsFilePath
- accessible
- accessError

An attempt to access any other property or method will return an error.

The only possible action you can perform on an inaccessible machine is to unregister it using the IMachine::unregister call (or, to check for the accessibility state once more by querying this property).

Note
  In the current implementation, once this property returns `true`, the machine will never become inaccessible later, even if its settings file cannot be successfully read/written any more (at least, until the VirtualBox server is restarted). This limitation may be removed in future releases.

## ◆ accessError

readonly attribute IVirtualBoxErrorInfo IMachine::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

attribute wstring IMachine::name

Name of the virtual machine.

Besides being used for human-readable identification purposes everywhere in VirtualBox, the virtual machine name is also used as a name of the machine's settings file and as a name of the subdirectory this settings file resides in. Thus, every time you change the value of this property, the settings file will be renamed once you call saveSettings to confirm the change. The containing subdirectory will be also renamed, but only if it has exactly the same name as the settings file itself prior to changing this property (for backward compatibility with previous API releases). The above implies the following limitations:

- The machine name cannot be empty.
- The machine name can contain only characters that are valid file name characters according to the rules of the file system used to store VirtualBox configuration.
- You cannot have two or more machines with the same name if they use the same subdirectory for storing the machine settings files.
- You cannot change the name of the machine if it is running, or if any file in the directory containing the settings file is being used by another running machine or by any other process in the host operating system at a time when saveSettings is called.

If any of the above limitations are hit, saveSettings will return an appropriate error message explaining the exact reason and the changes you made to this machine will not be saved.

Starting with VirtualBox 4.0, a ".vbox" extension of the settings file is recommended, but not enforced. (Previous versions always used a generic ".xml" extension.)

## ◆ description

attribute wstring IMachine::description

Description of the virtual machine.

The description attribute can contain any text and is typically used to describe the hardware and software configuration of the virtual machine in detail (i.e. network settings, versions of the installed software and so on).

## ◆ id

readonly attribute wstringUUID IMachine::id

UUID of the virtual machine.

## ◆ groups

attribute wstring [] IMachine::groups

Array of machine group names of which this machine is a member.

`""` and `"/"` are synonyms for the toplevel group. Each group is only listed once, however they are listed in no particular order and there is no guarantee that there are no gaps in the group hierarchy (i.e. `"/group"`, `"/group/subgroup/subsubgroup"` is a valid result).

## ◆ OSTypeId

attribute wstring IMachine::OSTypeId

User-defined identifier of the Guest OS type.

You may use IVirtualBox::getGuestOSType to obtain an IGuestOSType object representing details about the given Guest OS type. All Guest OS types are considered valid, even those which are not known to IVirtualBox::getGuestOSType.

Note
  This value may differ from the value returned by IGuest::OSTypeId if Guest Additions are installed to the guest OS.

## ◆ hardwareVersion

attribute wstring IMachine::hardwareVersion

Hardware version identifier.

Internal use only for now.

## ◆ hardwareUUID

attribute wstringUUID IMachine::hardwareUUID

The UUID presented to the guest via memory tables, hardware and guest properties.

For most VMs this is the same as the id, but for VMs which have been cloned or teleported it may be the same as the source VM. The latter is because the guest shouldn't notice that it was cloned or teleported.

## ◆ CPUCount

attribute unsigned long IMachine::CPUCount

Number of virtual CPUs in the VM.

## ◆ CPUHotPlugEnabled

attribute boolean IMachine::CPUHotPlugEnabled

This setting determines whether VirtualBox allows CPU hotplugging for this machine.

## ◆ CPUExecutionCap

attribute unsigned long IMachine::CPUExecutionCap

Means to limit the number of CPU cycles a guest can use.

The unit is percentage of host CPU cycles per second. The valid range is 1 - 100. 100 (the default) implies no limit.

## ◆ CPUIDPortabilityLevel

attribute unsigned long IMachine::CPUIDPortabilityLevel

Virtual CPUID portability level.

The higher the number the fewer vendor-specific or recent CPU features are reported to the guest (via the CPUID instruction). The default level of zero (0) means that all virtualized features supported by the host are passed through to the guest. While the value of three (3) is currently the level suppressing the most features.

Exactly which of the CPUID features are left out by the VMM at which level is subject to change with each major version.

## ◆ memorySize

attribute unsigned long IMachine::memorySize

System memory size in megabytes.

## ◆ memoryBalloonSize

attribute unsigned long IMachine::memoryBalloonSize

Memory balloon size in megabytes.

## ◆ pageFusionEnabled

attribute boolean IMachine::pageFusionEnabled

This setting determines whether VirtualBox allows page fusion for this machine (64-bit hosts only).

## ◆ graphicsAdapter

readonly attribute IGraphicsAdapter IMachine::graphicsAdapter

Graphics adapter object.

## ◆ platform

readonly attribute IPlatform IMachine::platform

Associated platform object.

## ◆ firmwareSettings

readonly attribute IFirmwareSettings IMachine::firmwareSettings

Object containing all firmware settings.

## ◆ trustedPlatformModule

readonly attribute ITrustedPlatformModule IMachine::trustedPlatformModule

Object containing all TPM settings.

## ◆ nonVolatileStore

readonly attribute INvramStore IMachine::nonVolatileStore

Object to manipulate data in the non volatile storage file.

## ◆ recordingSettings

readonly attribute IRecordingSettings IMachine::recordingSettings

Object containing all recording settings.

## ◆ pointingHIDType

attribute PointingHIDType IMachine::pointingHIDType

Type of pointing HID (such as mouse or tablet) used in this VM.

The default is typically "PS2Mouse" but can vary depending on the requirements of the guest operating system.

## ◆ keyboardHIDType

attribute KeyboardHIDType IMachine::keyboardHIDType

Type of keyboard HID used in this VM.

The default is typically "PS2Keyboard" but can vary depending on the requirements of the guest operating system.

## ◆ snapshotFolder

attribute wstring IMachine::snapshotFolder

Full path to the directory used to store snapshot data (differencing media and saved state files) of this machine.

The initial value of this property is `<`path_to_settings_file`>/<`machine_uuid`>`.

Currently, it is an error to try to change this property on a machine that has snapshots (because this would require to move possibly large files to a different location). A separate method will be available for this purpose later.

Note
  Setting this property to `null` or to an empty string will restore the initial value.
  When setting this property, the specified path can be absolute (full path) or relative to the directory where the machine settings file is located. When reading this property, a full path is always returned.
  The specified path may not exist, it will be created when necessary.

## ◆ VRDEServer

readonly attribute IVRDEServer IMachine::VRDEServer

VirtualBox Remote Desktop Extension (VRDE) server object.

## ◆ emulatedUSBCardReaderEnabled

attribute boolean IMachine::emulatedUSBCardReaderEnabled

## ◆ mediumAttachments

readonly attribute IMediumAttachment [] IMachine::mediumAttachments

Array of media attached to this machine.

## ◆ USBControllers

readonly attribute IUSBController [] IMachine::USBControllers

Array of USB controllers attached to this machine.

Note
  If USB functionality is not available in the given edition of VirtualBox, this method will set the result code to `E_NOTIMPL`.

## ◆ USBDeviceFilters

readonly attribute IUSBDeviceFilters IMachine::USBDeviceFilters

Associated USB device filters object.

Note
  If USB functionality is not available in the given edition of VirtualBox, this method will set the result code to `E_NOTIMPL`.

## ◆ audioSettings

readonly attribute IAudioSettings IMachine::audioSettings

The machine's audio settings.

## ◆ storageControllers

readonly attribute IStorageController [] IMachine::storageControllers

Array of storage controllers attached to this machine.

## ◆ settingsFilePath

readonly attribute wstring IMachine::settingsFilePath

Full name of the file containing machine settings data.

## ◆ settingsAuxFilePath

readonly attribute wstring IMachine::settingsAuxFilePath

Full name of the file containing auxiliary machine settings data.

## ◆ settingsModified

readonly attribute boolean IMachine::settingsModified

Whether the settings of this machine have been modified (but neither yet saved nor discarded).

Note
  Reading this property is only valid on instances returned by ISession::machine and on new machines created by IVirtualBox::createMachine or opened by IVirtualBox::openMachine but not yet registered, or on unregistered machines after calling IMachine::unregister. For all other cases, the settings can never be modified.
  For newly created unregistered machines, the value of this property is always `true` until saveSettings is called (no matter if any machine settings have been changed after the creation or not). For opened machines the value is set to `false` (and then follows to normal rules).

## ◆ sessionState

readonly attribute SessionState IMachine::sessionState

Current session state for this machine.

## ◆ sessionName

readonly attribute wstring IMachine::sessionName

Name of the session.

If sessionState is Spawning or Locked, this attribute contains the same value as passed to the IMachine::launchVMProcess method in the name parameter. If the session was established with IMachine::lockMachine, it is the name of the session (if set, otherwise empty string). If sessionState is SessionClosed, the value of this attribute is an empty string.

## ◆ sessionPID

readonly attribute unsigned long IMachine::sessionPID

Identifier of the session process.

This attribute contains the platform-dependent identifier of the process whose session was used with IMachine::lockMachine call. The returned value is only valid if sessionState is Locked or Unlocking by the time this property is read.

## ◆ state

readonly attribute MachineState IMachine::state

Current execution state of this machine.

## ◆ lastStateChange

readonly attribute long long IMachine::lastStateChange

Timestamp of the last execution state change, in milliseconds since 1970-01-01 UTC.

## ◆ stateFilePath

readonly attribute wstring IMachine::stateFilePath

Full path to the file that stores the execution state of the machine when it is in either the MachineState_Saved or MachineState_AbortedSaved state.

Note
  When the machine is not in the Saved or AbortedSaved state, this attribute is an empty string.

## ◆ logFolder

readonly attribute wstring IMachine::logFolder

Full path to the folder that stores a set of rotated log files recorded during machine execution.

The most recent log file is named `VBox.log`, the previous log file is named `VBox.log.1` and so on (up to `VBox.log.3` in the current version).

## ◆ currentSnapshot

readonly attribute ISnapshot IMachine::currentSnapshot

Current snapshot of this machine.

This is `null` if the machine currently has no snapshots. If it is not `null`, then it was set by one of takeSnapshot, deleteSnapshot or restoreSnapshot, depending on which was called last. See ISnapshot for details.

## ◆ snapshotCount

readonly attribute unsigned long IMachine::snapshotCount

Number of snapshots taken on this machine.

Zero means the machine doesn't have any snapshots.

## ◆ currentStateModified

readonly attribute boolean IMachine::currentStateModified

Returns `true` if the current state of the machine is not identical to the state stored in the current snapshot.

The current state is identical to the current snapshot only directly after one of the following calls are made:

- restoreSnapshot
- takeSnapshot (issued on a "powered off" or "saved" machine, for which settingsModified returns `false`)

The current state remains identical until one of the following happens:

- settings of the machine are changed
- the saved state is deleted
- the current snapshot is deleted
- an attempt to execute the machine is made

Note
  For machines that don't have snapshots, this property is always `false`.

## ◆ sharedFolders

readonly attribute ISharedFolder [] IMachine::sharedFolders

Collection of shared folders for this machine (permanent shared folders).

These folders are shared automatically at machine startup and available only to the guest OS installed within this machine.

New shared folders are added to the collection using createSharedFolder. Existing shared folders can be removed using removeSharedFolder.

## ◆ clipboardMode

attribute ClipboardMode IMachine::clipboardMode

Synchronization mode between the host OS clipboard and the guest OS clipboard.

## ◆ clipboardFileTransfersEnabled

attribute boolean IMachine::clipboardFileTransfersEnabled

Sets or retrieves whether clipboard file transfers are allowed or not.

When set to true, clipboard file transfers between supported host and guest OSes are allowed.

## ◆ dnDMode

attribute DnDMode IMachine::dnDMode

Sets or retrieves the current drag'n drop mode.

## ◆ teleporterEnabled

attribute boolean IMachine::teleporterEnabled

When set to true, the virtual machine becomes a target teleporter the next time it is powered on.

This can only set to true when the VM is in the PoweredOff or Aborted state.

## ◆ teleporterPort

attribute unsigned long IMachine::teleporterPort

The TCP port the target teleporter will listen for incoming teleportations on.

0 means the port is automatically selected upon power on. The actual value can be read from this property while the machine is waiting for incoming teleportations.

## ◆ teleporterAddress

attribute wstring IMachine::teleporterAddress

The address the target teleporter will listen on.

If set to an empty string, it will listen on all addresses.

## ◆ teleporterPassword

attribute wstring IMachine::teleporterPassword

The password to check for on the target teleporter.

This is just a very basic measure to prevent simple hacks and operators accidentally beaming a virtual machine to the wrong place.

Note that you SET a plain text password while reading back a HASHED password. Setting a hashed password is currently not supported.

## ◆ paravirtProvider

attribute ParavirtProvider IMachine::paravirtProvider

The paravirtualized guest interface provider.

## ◆ IOCacheEnabled

attribute boolean IMachine::IOCacheEnabled

When set to true, the builtin I/O cache of the virtual machine will be enabled.

## ◆ IOCacheSize

attribute unsigned long IMachine::IOCacheSize

Maximum size of the I/O cache in MB.

## ◆ PCIDeviceAssignments

readonly attribute IPCIDeviceAttachment [] IMachine::PCIDeviceAssignments

Array of PCI devices assigned to this machine, to get list of all PCI devices attached to the machine use IConsole::attachedPCIDevices attribute, as this attribute is intended to list only devices additional to what described in virtual hardware config.

Usually, this list keeps host's physical devices assigned to the particular machine.

## ◆ bandwidthControl

readonly attribute IBandwidthControl IMachine::bandwidthControl

Bandwidth control manager.

## ◆ tracingEnabled

attribute boolean IMachine::tracingEnabled

Enables the tracing facility in the VMM (including PDM devices + drivers).

The VMM will consume about 0.5MB of more memory when enabled and there may be some extra overhead from tracepoints that are always enabled.

## ◆ tracingConfig

attribute wstring IMachine::tracingConfig

Tracepoint configuration to apply at startup when IMachine::tracingEnabled is true.

The string specifies a space separated of tracepoint group names to enable. The special group 'all' enables all tracepoints. Check DBGFR3TracingConfig for more details on available tracepoint groups and such.

Note that on hosts supporting DTrace (or similar), a lot of the tracepoints may be implemented exclusively as DTrace probes. So, the effect of the same config may differ between Solaris and Windows for example.

## ◆ allowTracingToAccessVM

attribute boolean IMachine::allowTracingToAccessVM

Enables tracepoints in PDM devices and drivers to use the VMCPU or VM structures when firing off trace points.

This is especially useful with DTrace tracepoints, as it allows you to use the VMCPU or VM pointer to obtain useful information such as guest register state.

This is disabled by default because devices and drivers normally has no business accessing the VMCPU or VM structures, and are therefore unable to get any pointers to these.

## ◆ autostartEnabled

attribute boolean IMachine::autostartEnabled

Enables autostart of the VM during system boot.

## ◆ autostartDelay

attribute unsigned long IMachine::autostartDelay

Number of seconds to wait until the VM should be started during system boot.

## ◆ autostopType

attribute AutostopType IMachine::autostopType

Action type to do when the system is shutting down.

## ◆ defaultFrontend

attribute wstring IMachine::defaultFrontend

Selects which VM frontend should be used by default when launching this VM through the IMachine::launchVMProcess method.

Empty or `null` strings do not define a particular default, it is up to IMachine::launchVMProcess to select one. See the description of IMachine::launchVMProcess for the valid frontend types.

This per-VM setting overrides the default defined by ISystemProperties::defaultFrontend attribute, and is overridden by a frontend type passed to IMachine::launchVMProcess.

## ◆ USBProxyAvailable

readonly attribute boolean IMachine::USBProxyAvailable

Returns whether there is a USB proxy available.

## ◆ VMProcessPriority

attribute VMProcPriority IMachine::VMProcessPriority

Sets the priority of the VM process.

It is a VM setting which can be changed both before starting the VM and at runtime.

The default value is 'Default', which selects the default process priority.

Expected result codes:

  E_NOTIMPL | This attribute is currently not implemented.

## ◆ VMExecutionEngine

attribute VMExecutionEngine IMachine::VMExecutionEngine

The configured VM execution engine.

It is a VM setting which can be changed both before starting the VM and when a VM is saved.

The default value is 'Default', which selects the default aka best available execution engine available on the host.

## ◆ paravirtDebug

attribute wstring IMachine::paravirtDebug

Debug parameters for the paravirtualized guest interface provider.

## ◆ CPUProfile

attribute wstring IMachine::CPUProfile

Experimental feature to select the guest CPU profile.

The default is "host", which indicates the host CPU. All other names are subject to change.

Use the ISystemProperties::getCPUProfiles method to get currently available CPU profiles.

## ◆ stateKeyId

readonly attribute wstring IMachine::stateKeyId

Key Id of the password used for encrypting the state file.

Internal use only for now.

## ◆ stateKeyStore

readonly attribute wstring IMachine::stateKeyStore

Key store used for encrypting the state file.

Internal use only for now.

## ◆ logKeyId

readonly attribute wstring IMachine::logKeyId

Key Id of the password used for encrypting the log files.

Internal use only for now.

## ◆ logKeyStore

readonly attribute wstring IMachine::logKeyStore

Key store used for encrypting the log files.

Internal use only for now.

## ◆ guestDebugControl

readonly attribute IGuestDebugControl IMachine::guestDebugControl

Guest debugging configuration.