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...

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 type, in wstring environment,[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 unsigned long instance,[retval] out IStorageController storageController)
 Returns a storage controller 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 getCPUProperty (in CPUPropertyType property,[retval] out boolean value)
 Returns the virtual CPU boolean value of the specified property.
void setCPUProperty (in CPUPropertyType property, in boolean value)
 Sets the virtual CPU boolean value of the specified property.
void getCPUIDLeaf (in unsigned long id, out unsigned long valEax, out unsigned long valEbx, out unsigned long valEcx, out unsigned long valEdx)
 Returns the virtual CPU cpuid information for the specified leaf.
void setCPUIDLeaf (in unsigned long id, in unsigned long valEax, in unsigned long valEbx, in unsigned long valEcx, in unsigned long valEdx)
 Sets the virtual CPU cpuid information for the specified leaf.
void removeCPUIDLeaf (in unsigned long id)
 Removes the virtual CPU cpuid leaf for the specified index.
void removeAllCPUIDLeaves ()
 Removes all the virtual CPU cpuid leaves.
void getHWVirtExProperty (in HWVirtExPropertyType property,[retval] out boolean value)
 Returns the value of the specified hardware virtualization boolean property.
void setHWVirtExProperty (in HWVirtExPropertyType property, in boolean value)
 Sets a new value for the specified hardware virtualization boolean property.
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)
 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, time stamps 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 querySavedThumbnailSize (in unsigned long screenId, out unsigned long size, out unsigned long width, out unsigned long height)
 Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
void readSavedThumbnailToArray (in unsigned long screenId, in boolean BGR, out unsigned long width, out unsigned long height,[retval] out octet[] data)
 Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
void readSavedThumbnailPNGToArray (in unsigned long screenId, out unsigned long width, out unsigned long height,[retval] out octet[] data)
 Thumbnail in PNG format is retrieved to an array of bytes.
void querySavedScreenshotPNGSize (in unsigned long screenId, out unsigned long size, out unsigned long width, out unsigned long height)
 Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
void readSavedScreenshotPNGToArray (in unsigned long screenId, out unsigned long width, out unsigned long height,[retval] out octet[] data)
 Screenshot in PNG 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 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).

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 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).
attribute GraphicsControllerType graphicsControllerType
 Graphics controller type.
attribute unsigned long VRAMSize
 Video memory size in megabytes.
attribute boolean accelerate3DEnabled
 This setting determines whether VirtualBox allows this machine to make use of the 3D graphics support available on the host.
attribute boolean accelerate2DVideoEnabled
 This setting determines whether VirtualBox allows this machine to make use of the 2D video acceleration support available on the host.
attribute unsigned long monitorCount
 Number of virtual monitors.
attribute boolean videoCaptureEnabled
 This setting determines whether VirtualBox uses video recording to record VM session.
attribute boolean[] videoCaptureScreens
 This setting determines for which screens video recording is enabled.
attribute wstring videoCaptureFile
 This setting determines the filename VirtualBox uses to save the recorded content.
attribute unsigned long videoCaptureWidth
 This setting determines the horizontal resolution of the recorded video.
attribute unsigned long videoCaptureHeight
 This setting determines the vertical resolution of the recorded video.
attribute unsigned long videoCaptureRate
 This setting determines the bitrate in kilobits per second.
attribute unsigned long videoCaptureFPS
 This setting determines the maximum number of frames per second.
readonly attribute IBIOSSettings BIOSSettings
 Object containing all BIOS settings.
attribute FirmwareType firmwareType
 Type of firmware (such as legacy BIOS or EFI), used for initial bootstrap in this VM.
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 boolean HPETEnabled
 This attribute controls if High Precision Event Timer (HPET) is enabled in this VM.
attribute ChipsetType chipsetType
 Chipset type 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 IAudioAdapter audioAdapter
 Associated audio adapter, always present.
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 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 sessionType
 Type 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
 Time stamp 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 the MachineState_Saved 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 DragAndDropMode dragAndDropMode
 Which mode is allowed for drag'n'drop.
attribute wstring guestPropertyNotificationPatterns
 A comma-separated list of simple glob patterns.
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 FaultToleranceState faultToleranceState
 Fault tolerance state; disabled, source or target.
attribute unsigned long faultTolerancePort
 The TCP port the fault tolerance source or target will use for communication.
attribute wstring faultToleranceAddress
 The address the fault tolerance source or target.
attribute wstring faultTolerancePassword
 The password to check for on the standby VM.
attribute unsigned long faultToleranceSyncInterval
 The interval in ms used for syncing the state between source and target.
attribute boolean RTCUseUTC
 When set to true, the RTC device of the virtual machine will run in UTC time, otherwise in local time.
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 an USB proxy available.

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
  @link IVirtualBox::machines IVirtualBox::machines@endlink<b></b> 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 @link ::ISession ISession@endlink<b></b> 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
  @link IVirtualBox::machines IVirtualBox::machines@endlink<b></b> 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 @link IMachine::lockMachine IMachine::lockMachine@endlink<b></b> or
  @link IMachine::launchVMProcess IMachine::launchVMProcess@endlink<b></b> 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 @link ::ISession ISession@endlink<b></b> 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 @link ::IConsole IConsole@endlink<b></b>.
See Also
ISession, IConsole
Interface ID:
{480CF695-2D8D-4256-9C7C-CCE4184FA048}

Member Function Documentation

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:

    <ul>

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 @link ::IConsole IConsole@endlink<b></b>
    object which controls VM execution.

    Also in all of the above cases, one must always call
    @link ISession::unlockMachine ISession::unlockMachine@endlink<b></b> 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:

    <ol>

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

Parameters
sessionSession object for which the machine will be locked.
lockTypeIf 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 OpenRemoteSession.
VBOX_E_INVALID_OBJECT_STATE Session already open or being opened.
VBOX_E_VM_ERROR Failed to assign machine to session.
void IMachine::launchVMProcess ( in ISession  session,
in wstring  type,
in wstring  environment,
[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 @link ::IConsole IConsole@endlink<b></b> 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 @link #lockMachine lockMachine@endlink<b></b> call.

    The caller must eventually release the session's shared lock by calling
    @link ISession::unlockMachine ISession::unlockMachine@endlink<b></b> on the local session object once this call
    has returned. However, the session's state (see @link ISession::state ISession::state@endlink<b></b>)
    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 @link ::IProgress IProgress@endlink<b></b> 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 @link ISession::machine ISession::machine@endlink<b></b>
    and @link ISession::console ISession::console@endlink<b></b> attributes cannot be accessed.
    It is recommended to use @link IProgress::waitForCompletion IProgress::waitForCompletion@endlink<b></b> 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 @link IConsole::powerUp IConsole::powerUp@endlink<b></b>
    progress object. Because @link IConsole::powerUp IConsole::powerUp@endlink<b></b> may require
    some extra sub-operations, the @link IProgress::operationCount IProgress::operationCount@endlink<b></b>
    may change at the completion of operation.

    For details on the teleportation progress operation, see
    @link IConsole::powerUp IConsole::powerUp@endlink<b></b>.

    The @a environment argument is a string containing definitions of
    environment variables in the following format:
    <pre>
    NAME[=VALUE]\n
    NAME[=VALUE]\n
    ...
    </pre>
    where <tt>\\n</tt> is the new line character. These environment
    variables will be appended 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 environment string is @c null or empty, the server environment
    is inherited by the started process as is.
Parameters
sessionClient session object to which the VM process will be connected (this must be in "Unlocked" state).
typeFront-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.
environmentEnvironment to pass to the VM process.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table>

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.

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,
    @link ::DeviceType_Null DeviceType_Null@endlink<b></b> should be used.

    \xrefitem todo 1.
Parameters
positionPosition in the boot order (1 to the total number of devices the machine can boot from, as returned by ISystemProperties::maxBootPosition).
deviceThe 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.
void IMachine::getBootOrder ( in unsigned long  position,
[retval] out DeviceType  device 
)

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

    \xrefitem todo 2.

    If here are no devices at the given position, then
    @link ::DeviceType_Null DeviceType_Null@endlink<b></b> is returned.

    \xrefitem todo 3.
Parameters
positionPosition in the boot order (1 to the total number of devices the machine can boot from, as returned by ISystemProperties::maxBootPosition).
deviceDevice at the given position.
Expected result codes:
E_INVALIDARG Boot position out of range.
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:

    <ul>

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
    @link ::IMediumAttachment IMediumAttachment@endlink<b></b> will appear in the machine's list of medium
    attachments (see @link IMachine::mediumAttachments IMachine::mediumAttachments@endlink<b></b>).

    See @link ::IMedium IMedium@endlink<b></b> and @link ::IMediumAttachment IMediumAttachment@endlink<b></b> for more
    information about attaching media.

    The specified device slot must not have a device attached to it,
    or this method will fail.
Parameters
nameName of the storage controller to attach the device to.
controllerPortPort 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.
deviceDevice 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.
typeDevice type of the attached device. For media opened by IVirtualBox::openMedium, this must match the device type specified there.
mediumMedium to mount or null for an empty drive.
  @par Expected result codes:
<table>

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.
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:
  <ul>

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.
  @link ::IMediumAttachment IMediumAttachment@endlink<b></b> will appear in the machine's list of medium
  attachments (see @link IMachine::mediumAttachments IMachine::mediumAttachments@endlink<b></b>).

  See @link ::IMedium IMedium@endlink<b></b> and @link ::IMediumAttachment IMediumAttachment@endlink<b></b> for more
  information about attaching media.

  The specified device slot must not have a device attached to it,
  or this method will fail.
Parameters
nameName of the storage controller to attach the device to.
controllerPortPort 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.
deviceDevice 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.
typeDevice 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.
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
    @link #saveSettings saveSettings@endlink<b></b> call. See @link ::IMedium IMedium@endlink<b></b>
    for more detailed information about attaching media.
Parameters
nameName of the storage controller to detach the medium from.
controllerPortPort number to detach the medium from.
deviceDevice slot number to detach the medium from.
  @par Expected result codes:
<table>

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.
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
nameName of the storage controller.
controllerPortStorage controller port.
deviceDevice slot in the given port.
passthroughNew value for the passthrough setting.
  @par Expected result codes:
<table>

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.

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
nameName of the storage controller.
controllerPortStorage controller port.
deviceDevice slot in the given port.
temporaryEjectNew value for the eject behavior.
  @par Expected result codes:
<table>

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.

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
nameName of the storage controller.
controllerPortStorage controller port.
deviceDevice slot in the given port.
nonRotationalNew value for the non-rotational device flag.
  @par Expected result codes:
<table>

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.

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
nameName of the storage controller.
controllerPortStorage controller port.
deviceDevice slot in the given port.
discardNew value for the discard device flag.
  @par Expected result codes:
<table>

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.

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
nameName of the storage controller.
controllerPortStorage controller port.
deviceDevice slot in the given port.
hotPluggableNew value for the hot-pluggable device flag.
  @par Expected result codes:
<table>

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.

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 @link IMachine::attachDevice IMachine::attachDevice@endlink<b></b>
    for how to attach a new device.

    The @a controllerPort and @a device parameters specify the device slot and
    have have the same meaning as with @link IMachine::attachDevice IMachine::attachDevice@endlink<b></b>.
Parameters
nameName of the storage controller.
controllerPortStorage controller port.
deviceDevice slot in the given port.
bandwidthGroupNew value for the bandwidth group or null for no group.
  @par Expected result codes:
<table>

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.

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 @link IMachine::attachDevice IMachine::attachDevice@endlink<b></b>
  for how to attach a new device.
  The @a controllerPort and @a device parameters specify the device slot and
  have have the same meaning as with @link IMachine::attachDevice IMachine::attachDevice@endlink<b></b>.
Parameters
nameName of the storage controller.
controllerPortStorage controller port.
deviceDevice slot in the given port.
  @par Expected result codes:
<table>

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.

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 @a controllerPort and @a device parameters specify the device slot
   and have have the same meaning as with
   @link IMachine::attachDevice IMachine::attachDevice@endlink<b></b>.

   The specified device slot must have a medium mounted, which will be
   unmounted. If there is no mounted medium it will do nothing.
   See @link ::IMedium IMedium@endlink<b></b> for more detailed information about
   attaching/unmounting media.
Parameters
nameName of the storage controller to unmount the medium from.
controllerPortPort to unmount the medium from.
deviceDevice slot in the given port to unmount the medium from.
forceAllows 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.
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
nameName of the storage controller to attach the medium to.
controllerPortPort to attach the medium to.
deviceDevice slot in the given port to attach the medium to.
mediumMedium to mount or null for an empty drive.
forceAllows 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.
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
    @link #mountMedium mountMedium@endlink<b></b> to the given device slot then this
    method will return not the same object as passed to the
    @link #mountMedium mountMedium@endlink<b></b> call. See @link ::IMedium IMedium@endlink<b></b> for
    more detailed information about mounting a medium.
Parameters
nameName of the storage controller the medium is attached to.
controllerPortPort to query.
deviceDevice slot in the given port to query.
mediumAttached medium object.
  @par Expected result codes:
<table><tr>

VBOX_E_OBJECT_NOT_FOUND

No medium attached to given slot/bus.

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.

  @par Expected result codes:
<table><tr>

VBOX_E_OBJECT_NOT_FOUND

A storage controller with given name doesn't exist.

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.

  @par Expected result codes:
<table><tr>

VBOX_E_OBJECT_NOT_FOUND

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

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
hostAddressAddress of the host PCI device.
desiredGuestAddressDesired position of this device on guest PCI bus.
tryToUnbindIf 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
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
hostAddressAddress of the host PCI device.
  @par Expected result codes:
<table>

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
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
    @link ISystemProperties::getMaxNetworkAdapters ISystemProperties::getMaxNetworkAdapters@endlink<b></b> property,
    so the maximum slot number is one less than that property's value.

  @par Expected result codes:
<table><tr>

E_INVALIDARG

Invalid slot number.

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.

    @a name identifies the controller for subsequent calls such as
    @link #getStorageControllerByName getStorageControllerByName@endlink<b></b>,
    @link #getStorageControllerByInstance getStorageControllerByInstance@endlink<b></b>,
    @link #removeStorageController removeStorageController@endlink<b></b>,
    @link #attachDevice attachDevice@endlink<b></b> or @link #mountMedium mountMedium@endlink<b></b>.

    After the controller has been added, you can set its exact
    type by setting the @link IStorageController::controllerType IStorageController::controllerType@endlink<b></b>.

  @par Expected result codes:
<table>

VBOX_E_OBJECT_IN_USE

A storage controller with given name exists already.

E_INVALIDARG

Invalid controllerType.

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

Returns a storage controller with the given name.

  @par Expected result codes:
<table><tr>

VBOX_E_OBJECT_NOT_FOUND

A storage controller with given name doesn't exist.

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

Returns a storage controller with the given instance number.

  @par Expected result codes:
<table><tr>

VBOX_E_OBJECT_NOT_FOUND

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

void IMachine::removeStorageController ( in wstring  name)

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

  @par Expected result codes:
<table>

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).

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

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

  @par Expected result codes:
<table>

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.

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.

  @par Expected result codes:
<table>

VBOX_E_OBJECT_IN_USE

A USB controller with given type exists already.

E_INVALIDARG

Invalid controllerType.

void IMachine::removeUSBController ( in wstring  name)

Removes a USB controller from the machine.

  @par Expected result codes:
<table><tr>

VBOX_E_OBJECT_NOT_FOUND

A USB controller with given type doesn't exist.

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

Returns a USB controller with the given type.

  @par Expected result codes:
<table><tr>

VBOX_E_OBJECT_NOT_FOUND

A USB controller with given name doesn't exist.

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.

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
    @link ISystemProperties::serialPortCount ISystemProperties::serialPortCount@endlink<b></b> property,
    so the maximum slot number is one less than that property's value.

  @par Expected result codes:
<table><tr>

E_INVALIDARG

Invalid slot number.

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
    @link ISystemProperties::parallelPortCount ISystemProperties::parallelPortCount@endlink<b></b> property,
    so the maximum slot number is one less than that property's value.

  @par Expected result codes:
<table><tr>

E_INVALIDARG

Invalid slot number.

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

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

Parameters
keysArray of extra data keys.
void IMachine::getExtraData ( in wstring  key,
[retval] out wstring  value 
)

Returns associated machine-specific extra data.

    If the requested data @a key does not exist, this function will
    succeed and return an empty string in the @a value argument.
Parameters
keyName of the data key to get.
valueValue of the requested data key.
  @par Expected result codes:
<table>

VBOX_E_FILE_ERROR

Settings file not accessible.

VBOX_E_XML_ERROR

Could not parse the settings file.

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

Sets associated machine-specific extra data.

    If you pass @c null or an empty string as a key @a value, the given
    @a key will be deleted.
Parameters
keyName of the data key to set.
valueValue to assign to the key.
  @par Expected result codes:
<table>

VBOX_E_FILE_ERROR

Settings file not accessible.

VBOX_E_XML_ERROR

Could not parse the settings file.

Note
Before performing the actual data change, this method will ask all registered 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.
void IMachine::getCPUProperty ( in CPUPropertyType  property,
[retval] out boolean  value 
)

Returns the virtual CPU boolean value of the specified property.

Parameters
propertyProperty type to query.
valueProperty value.
Expected result codes:
E_INVALIDARG Invalid property.
void IMachine::setCPUProperty ( in CPUPropertyType  property,
in boolean  value 
)

Sets the virtual CPU boolean value of the specified property.

Parameters
propertyProperty type to query.
valueProperty value.
Expected result codes:
E_INVALIDARG Invalid property.
void IMachine::getCPUIDLeaf ( in unsigned long  id,
out unsigned long  valEax,
out unsigned long  valEbx,
out unsigned long  valEcx,
out unsigned long  valEdx 
)

Returns the virtual CPU cpuid information for the specified leaf.

    Currently supported index values for cpuid:
    Standard CPUID leafs: 0 - 0xA
    Extended CPUID leafs: 0x80000000 - 0x8000000A

    See the Intel and AMD programmer's manuals for detailed information
    about the cpuid instruction and its leafs.
Parameters
idCPUID leaf index.
valEaxCPUID leaf value for register eax.
valEbxCPUID leaf value for register ebx.
valEcxCPUID leaf value for register ecx.
valEdxCPUID leaf value for register edx.
Expected result codes:
E_INVALIDARG Invalid id.
void IMachine::setCPUIDLeaf ( in unsigned long  id,
in unsigned long  valEax,
in unsigned long  valEbx,
in unsigned long  valEcx,
in unsigned long  valEdx 
)

Sets the virtual CPU cpuid information for the specified leaf.

Note that these values are not passed unmodified. VirtualBox clears features that it doesn't support.

Currently supported index values for cpuid: Standard CPUID leafs: 0 - 0xA Extended CPUID leafs: 0x80000000 - 0x8000000A

See the Intel and AMD programmer's manuals for detailed information about the cpuid instruction and its leafs.

Do not use this method unless you know exactly what you're doing. Misuse can lead to random crashes inside VMs.

Parameters
idCPUID leaf index.
valEaxCPUID leaf value for register eax.
valEbxCPUID leaf value for register ebx.
valEcxCPUID leaf value for register ecx.
valEdxCPUID leaf value for register edx.
Expected result codes:
E_INVALIDARG Invalid id.
void IMachine::removeCPUIDLeaf ( in unsigned long  id)

Removes the virtual CPU cpuid leaf for the specified index.

Parameters
idCPUID leaf index.
Expected result codes:
E_INVALIDARG Invalid id.
void IMachine::removeAllCPUIDLeaves ( )

Removes all the virtual CPU cpuid leaves.

void IMachine::getHWVirtExProperty ( in HWVirtExPropertyType  property,
[retval] out boolean  value 
)

Returns the value of the specified hardware virtualization boolean property.

Parameters
propertyProperty type to query.
valueProperty value.
Expected result codes:
E_INVALIDARG Invalid property.
void IMachine::setHWVirtExProperty ( in HWVirtExPropertyType  property,
in boolean  value 
)

Sets a new value for the specified hardware virtualization boolean property.

Parameters
propertyProperty type to set.
valueNew property value.
Expected result codes:
E_INVALIDARG Invalid property.
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
settingsFilePathNew 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.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table><tr>

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.
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.

  @par Expected result codes:
<table>

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.
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.

  @par Expected result codes:
<table><tr>

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.
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
    @link #deleteConfig deleteConfig@endlink<b></b>, 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 @a cleanupMode argument.

    <ul>

With "UnregisterOnly", the machine will only be unregistered, but no additional cleanup will be performed. The call will fail if the machine is in "Saved" state or 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 @link #deleteConfig deleteConfig@endlink<b></b>. 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 @link #deleteConfig deleteConfig@endlink<b></b> 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 @link ::IMedium IMedium@endlink<b></b> 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 @link #saveSettings saveSettings@endlink<b></b> to save all current machine settings
    before unregistering it. It may also silently call @link #saveSettings saveSettings@endlink<b></b> on other machines
    if media are moved to other machines' media registries.

    After successful method invocation, the @link ::IMachineRegisteredEvent IMachineRegisteredEvent@endlink<b></b> event
    is fired.

    The call will fail if the machine is currently locked (see @link ::ISession ISession@endlink<b></b>).
Parameters
cleanupModeHow to clean up after the machine has been unregistered.
mediaList of media detached from the machine, depending on the cleanupMode parameter.
  @par Expected result codes:
<table><tr>

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.
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 "Saved" 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
mediaList of media to be closed and whose storage files will be deleted.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table>

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.
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
applianceAppliance to export this machine to.
locationThe target location.
descriptionVirtualSystemDescription object which is created for this machine.
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 @c 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
    @link ISnapshot::children ISnapshot::children@endlink<b></b> attribute and recurse over those children.
Parameters
nameOrIdWhat to search for. Name or UUID of the snapshot to find
snapshotSnapshot object with the given name.
  @par Expected result codes:
<table><tr>

VBOX_E_OBJECT_NOT_FOUND

Virtual machine has no snapshots or snapshot not found.

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

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
nameUnique logical name of the shared folder.
hostPathFull path to the shared folder in the host file system.
writableWhether the share is writable or read-only.
automountWhether the share gets automatically mounted by the guest or not.
Expected result codes:
VBOX_E_OBJECT_IN_USE Shared folder already exists.
VBOX_E_FILE_ERROR Shared folder hostPath not accessible.
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
nameLogical name of the shared folder to remove.
  @par Expected result codes:
<table>

VBOX_E_INVALID_VM_STATE

Virtual machine is not mutable.

VBOX_E_OBJECT_NOT_FOUND

Shared folder name does not exist.

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
canShowtrue 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.
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
winIdPlatform-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.
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
nameThe name of the property to read.
valueThe value of the property. If the property does not exist then this will be empty.
timestampThe time at which the property was last modified, as seen by the server process.
flagsAdditional 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.
void IMachine::getGuestPropertyValue ( in wstring  property,
[retval] out wstring  value 
)

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

Parameters
propertyThe name of the property to read.
valueThe 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.
void IMachine::getGuestPropertyTimestamp ( in wstring  property,
[retval] out long long  value 
)

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

Parameters
propertyThe name of the property to read.
valueThe 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.
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
propertyThe name of the property to set, change or delete.
valueThe 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.
flagsAdditional 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.
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
propertyThe name of the property to set or change.
valueThe 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.
void IMachine::deleteGuestProperty ( in wstring  name)

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

Parameters
nameThe name of the property to delete.
Expected result codes:
VBOX_E_INVALID_VM_STATE Machine session is not open.
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, time stamps and flags.

Parameters
patternsThe patterns to match the properties against, separated by '|' characters. If this is empty or null, all properties will match.
namesThe names of the properties returned.
valuesThe values of the properties returned. The array entries match the corresponding entries in the name array.
timestampsThe time stamps of the properties returned. The array entries match the corresponding entries in the name array.
flagsThe flags of the properties returned. The array entries match the corresponding entries in the name array.
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
screenIdSaved guest screen to query info from.
originXThe X position of the guest monitor top left corner.
originYThe Y position of the guest monitor top left corner.
widthGuest width at the time of the saved state was taken.
heightGuest height at the time of the saved state was taken.
enabledWhether the monitor is enabled in the guest.
void IMachine::querySavedThumbnailSize ( in unsigned long  screenId,
out unsigned long  size,
out unsigned long  width,
out unsigned long  height 
)

Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.

Parameters
screenIdSaved guest screen to query info from.
sizeSize of buffer required to store the bitmap.
widthBitmap width.
heightBitmap height.
void IMachine::readSavedThumbnailToArray ( in unsigned long  screenId,
in boolean  BGR,
out unsigned long  width,
out unsigned long  height,
[retval] out octet[]  data 
)

Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.

Parameters
screenIdSaved guest screen to read from.
BGRHow to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
widthBitmap width.
heightBitmap height.
dataArray with resulting bitmap data.
void IMachine::readSavedThumbnailPNGToArray ( in unsigned long  screenId,
out unsigned long  width,
out unsigned long  height,
[retval] out octet[]  data 
)

Thumbnail in PNG format is retrieved to an array of bytes.

Parameters
screenIdSaved guest screen to read from.
widthImage width.
heightImage height.
dataArray with resulting PNG data.
void IMachine::querySavedScreenshotPNGSize ( in unsigned long  screenId,
out unsigned long  size,
out unsigned long  width,
out unsigned long  height 
)

Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.

Parameters
screenIdSaved guest screen to query info from.
sizeSize of buffer required to store the PNG binary data.
widthImage width.
heightImage height.
void IMachine::readSavedScreenshotPNGToArray ( in unsigned long  screenId,
out unsigned long  width,
out unsigned long  height,
[retval] out octet[]  data 
)

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

Parameters
screenIdSaved guest screen to read from.
widthImage width.
heightImage height.
dataArray with resulting PNG data.
void IMachine::hotPlugCPU ( in unsigned long  cpu)

Plugs a CPU into the machine.

Parameters
cpuThe CPU id to insert.
void IMachine::hotUnplugCPU ( in unsigned long  cpu)

Removes a CPU from the machine.

Parameters
cpuThe CPU id to remove.
void IMachine::getCPUStatus ( in unsigned long  cpu,
[retval] out boolean  attached 
)

Returns the current status of the given CPU.

Parameters
cpuThe CPU id to check for.
attachedStatus of the CPU.
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
idxWhich log file name to query. 0=current log file.
filenameOn return the full path to the log file or an empty string on error.
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
idxWhich log file to read. 0=current log file.
offsetOffset in the log file.
sizeChunk size to read in the log file.
dataData 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.
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 @link IVirtualBox::createMachine IVirtualBox::createMachine@endlink<b></b>, 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 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 @a progress object signals completion.
Parameters
targetTarget machine object.
modeWhich states should be cloned.
optionsOptions for the cloning operation.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table><tr>

E_INVALIDARG

target is null.

Member Data Documentation

readonly attribute IVirtualBox IMachine::parent

Associated parent object.

attribute octet [] IMachine::icon

Overridden VM Icon details.

readonly attribute boolean IMachine::accessible

Whether this virtual machine is currently accessible or not.

    A machine is always deemed accessible unless it is registered <i>and</i>
    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 @c false,
    the @link #accessError accessError@endlink<b></b> 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:
    <ul>

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
    @link IMachine::unregister IMachine::unregister@endlink<b></b> 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.
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.

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 @link #saveSettings saveSettings@endlink<b></b> 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:
    <ul>

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.)

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).

readonly attribute wstringUUID IMachine::id

UUID of the virtual machine.

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).

attribute wstring IMachine::OSTypeId

User-defined identifier of the Guest OS type.

    You may use @link IVirtualBox::getGuestOSType IVirtualBox::getGuestOSType@endlink<b></b> to obtain
    an IGuestOSType object representing details about the given
    Guest OS type.
Note
This value may differ from the value returned by IGuest::OSTypeId if Guest Additions are installed to the guest OS.
attribute wstring IMachine::hardwareVersion

Hardware version identifier.

Internal use only for now.

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.

attribute unsigned long IMachine::CPUCount

Number of virtual CPUs in the VM.

attribute boolean IMachine::CPUHotPlugEnabled

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

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.

attribute unsigned long IMachine::memorySize

System memory size in megabytes.

attribute unsigned long IMachine::memoryBalloonSize

Memory balloon size in megabytes.

attribute boolean IMachine::pageFusionEnabled

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

attribute GraphicsControllerType IMachine::graphicsControllerType

Graphics controller type.

attribute unsigned long IMachine::VRAMSize

Video memory size in megabytes.

attribute boolean IMachine::accelerate3DEnabled

This setting determines whether VirtualBox allows this machine to make use of the 3D graphics support available on the host.

attribute boolean IMachine::accelerate2DVideoEnabled

This setting determines whether VirtualBox allows this machine to make use of the 2D video acceleration support available on the host.

attribute unsigned long IMachine::monitorCount

Number of virtual monitors.

Note
Only effective on Windows XP and later guests with Guest Additions installed.
attribute boolean IMachine::videoCaptureEnabled

This setting determines whether VirtualBox uses video recording to record VM session.

attribute boolean [] IMachine::videoCaptureScreens

This setting determines for which screens video recording is enabled.

attribute wstring IMachine::videoCaptureFile

This setting determines the filename VirtualBox uses to save the recorded content.

This setting cannot be changed while video capturing is enabled.

Note
When setting this attribute, the specified path has to be absolute (full path). When reading this attribute, a full path is always returned.
attribute unsigned long IMachine::videoCaptureWidth

This setting determines the horizontal resolution of the recorded video.

This setting cannot be changed while video capturing is enabled.

attribute unsigned long IMachine::videoCaptureHeight

This setting determines the vertical resolution of the recorded video.

This setting cannot be changed while video capturing is enabled.

attribute unsigned long IMachine::videoCaptureRate

This setting determines the bitrate in kilobits per second.

Increasing this value makes the video look better for the cost of an increased file size. This setting cannot be changed while video capturing is enabled.

attribute unsigned long IMachine::videoCaptureFPS

This setting determines the maximum number of frames per second.

Frames with a higher frequency will be skipped. Reducing this value increases the number of skipped frames and reduces the file size. This setting cannot be changed while video capturing is enabled.

readonly attribute IBIOSSettings IMachine::BIOSSettings

Object containing all BIOS settings.

attribute FirmwareType IMachine::firmwareType

Type of firmware (such as legacy BIOS or EFI), used for initial bootstrap in this VM.

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.

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.

attribute boolean IMachine::HPETEnabled

This attribute controls if High Precision Event Timer (HPET) is enabled in this VM.

Use this property if you want to provide guests with additional time source, or if guest requires HPET to function correctly. Default is false.

attribute ChipsetType IMachine::chipsetType

Chipset type used in this VM.

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
    <tt>&lt;</tt>@link #settingsFilePath path_to_settings_file@endlink<b></b><tt>&gt;/&lt;</tt>@link #id machine_uuid@endlink<b></b><tt>&gt;</tt>.

    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.
readonly attribute IVRDEServer IMachine::VRDEServer

VirtualBox Remote Desktop Extension (VRDE) server object.

attribute boolean IMachine::emulatedUSBCardReaderEnabled
readonly attribute IMediumAttachment [] IMachine::mediumAttachments

Array of media attached to this machine.

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.
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.
readonly attribute IAudioAdapter IMachine::audioAdapter

Associated audio adapter, always present.

readonly attribute IStorageController [] IMachine::storageControllers

Array of storage controllers attached to this machine.

readonly attribute wstring IMachine::settingsFilePath

Full name of the file containing machine settings data.

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).
readonly attribute SessionState IMachine::sessionState

Current session state for this machine.

readonly attribute wstring IMachine::sessionType

Type of the session.

If sessionState is Spawning or Locked, this attribute contains the same value as passed to the IMachine::launchVMProcess method in the type parameter. If the session was used with IMachine::lockMachine, or if sessionState is SessionClosed, the value of this attribute is an empty string.

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.

readonly attribute MachineState IMachine::state

Current execution state of this machine.

readonly attribute long long IMachine::lastStateChange

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

readonly attribute wstring IMachine::stateFilePath

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

Note
When the machine is not in the Saved state, this attribute is an empty string.
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).

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 IConsole::takeSnapshot, IConsole::deleteSnapshot or IConsole::restoreSnapshot, depending on which was called last. See ISnapshot for details.

readonly attribute unsigned long IMachine::snapshotCount

Number of snapshots taken on this machine.

Zero means the machine doesn't have any snapshots.

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:

    <ul>

IConsole::restoreSnapshot IConsole::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:
    <ul>

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.
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.

attribute ClipboardMode IMachine::clipboardMode

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

attribute DragAndDropMode IMachine::dragAndDropMode

Which mode is allowed for drag'n'drop.

attribute wstring IMachine::guestPropertyNotificationPatterns

A comma-separated list of simple glob patterns.

Changes to guest properties whose name matches one of the patterns will generate an IGuestPropertyChangedEvent signal.

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.

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.

attribute wstring IMachine::teleporterAddress

The address the target teleporter will listen on.

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

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.

attribute FaultToleranceState IMachine::faultToleranceState

Fault tolerance state; disabled, source or target.

This property can be changed at any time. If you change it for a running VM, then the fault tolerance address and port must be set beforehand.

attribute unsigned long IMachine::faultTolerancePort

The TCP port the fault tolerance source or target will use for communication.

attribute wstring IMachine::faultToleranceAddress

The address the fault tolerance source or target.

attribute wstring IMachine::faultTolerancePassword

The password to check for on the standby VM.

This is just a very basic measure to prevent simple hacks and operators accidentally choosing the wrong standby VM.

attribute unsigned long IMachine::faultToleranceSyncInterval

The interval in ms used for syncing the state between source and target.

attribute boolean IMachine::RTCUseUTC

When set to true, the RTC device of the virtual machine will run in UTC time, otherwise in local time.

Especially Unix guests prefer the time in UTC.

attribute boolean IMachine::IOCacheEnabled

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

attribute unsigned long IMachine::IOCacheSize

Maximum size of the I/O cache in MB.

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.

readonly attribute IBandwidthControl IMachine::bandwidthControl

Bandwidth control manager.

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.

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.

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.

attribute boolean IMachine::autostartEnabled

Enables autostart of the VM during system boot.

attribute unsigned long IMachine::autostartDelay

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

attribute AutostopType IMachine::autostopType

Action type to do when the system is shutting down.

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.

readonly attribute boolean IMachine::USBProxyAvailable

Returns whether there is an USB proxy available.