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 | 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 | setBandwidthGroupForDevice (in wstring name, in long controllerPort, in long device, in IBandwidthGroup bandwidthGroup) |
Sets the bandwidth group of an existing storage 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 IEventContext eventContext, 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. | |
void | setStorageControllerBootable (in wstring name, in boolean bootable) |
Sets the bootable flag of the storage controller with the given name. | |
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[] value) |
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 | 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[] aMedia) |
Unregisters a machine previously registered with IVirtualBox::registerMachine and optionally do additional cleanup before the machine is unregistered. | |
void | delete (in IMedium[] aMedia,[retval] out IProgress aProgress) |
Deletes the files associated with this machine from disk. | |
void | export (in IAppliance aAppliance, in wstring location,[retval] out IVirtualSystemDescription aDescription) |
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, changes or deletes a value in the machine's guest property store. | |
void | enumerateGuestProperties (in wstring patterns, out wstring[] name, out wstring[] value, out long long[] timestamp, out wstring[] flags) |
Return a list of the guest properties matching a set of patterns along with their values, time stamps and flags. | |
void | querySavedGuestSize (in unsigned long screenId, out unsigned long width, out unsigned long height) |
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. | |
Public Attributes | |
readonly attribute IVirtualBox | parent |
Associated parent object. | |
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 | 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 bits host only). | |
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. | |
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. | |
readonly attribute IMediumAttachment[] | mediumAttachments |
Array of media attached to this machine. | |
readonly attribute IUSBController | USBController |
Associated USB controller 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 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 IBandwidthControl | bandwidthControl |
Bandwidth control manager. | |
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. |
The IMachine interface represents a virtual machine, or guest, created in VirtualBox.
This interface is used in two contexts. First of all, a collection of objects implementing this interface is stored in the IVirtualBox::machines attribute which lists all the virtual machines that are currently registered with this VirtualBox installation. Also, once a session has been opened for the given virtual machine (e.g. the virtual machine is running), the machine object associated with the open session can be queried from the session object; see ISession for details.
The main role of this interface is to expose the settings of the virtual machine and provide methods to change various aspects of the virtual machine's configuration. For machine objects stored in the IVirtualBox::machines collection, all attributes are read-only unless explicitly stated otherwise in individual attribute and method descriptions.
In order to change a machine setting, a session for this machine must be opened using one of the IMachine::lockMachine or IMachine::launchVMProcess methods. After the machine has been successfully locked for a session, a mutable machine object needs to be queried from the session object and then the desired settings changes can be applied to the returned object using IMachine attributes and methods. See the ISession interface description for more information about sessions.
Note that IMachine does not provide methods to control virtual machine execution (such as start the machine, or power it down) -- these methods are grouped in a separate interface called IConsole.
{662C175E-A69D-40B8-A77A-1D719D0AB062}
Locks the machine for the given session to enable the caller to make changes to the machine or start the VM or control VM execution.
There are two ways to lock a machine for such uses:
If you want to make changes to the machine settings, you must obtain an exclusive write lock on the machine by setting lockType to Write
.
This will only succeed if no other process has locked the machine to prevent conflicting changes. Only after an exclusive write lock has been obtained using this method, one can change all VM settings or execute the VM in the process space of the session object. (Note that the latter is only of interest if you actually want to write a new front-end for virtual machines; but this API gets called internally by the existing front-ends such as VBoxHeadless and the VirtualBox GUI to acquire a write lock on the machine that they are running.)
On success, write-locking the machine for a session creates a second copy of the IMachine object. It is this second object upon which changes can be made; in VirtualBox terminology, the second copy is "mutable". It is only this second, mutable machine object upon which you can call methods that change the machine state. After having called this method, you can obtain this second, mutable machine object using the ISession::machine attribute.
If you only want to check the machine state or control machine execution without actually changing machine settings (e.g. to get access to VM statistics or take a snapshot or save the machine state), then set the lockType argument to Shared
.
If no other session has obtained a lock, you will obtain an exclusive write lock as described above. However, if another session has already obtained such a lock, then a link to that existing session will be established which allows you to control that existing session.
To find out which type of lock was obtained, you can inspect ISession::type, which will have been set to either WriteLock
or Shared
.
In either case, you can get access to the IConsole object which controls VM execution.
Also in all of the above cases, one must always call ISession::unlockMachine to release the lock on the machine, or the machine's state will eventually be set to "Aborted".
To change settings on a machine, the following sequence is typically performed:
session | Session object for which the machine will be locked. | |
lockType | If set to Write , then attempt to acquire an exclusive write lock or fail. If set to Shared , then either acquire an exclusive write lock or establish a link to an existing session. |
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 IConsole object which can be used to control machine execution, but it cannot be used to change all VM settings which would be available after a lockMachine call.
The caller must eventually release the session's shared lock by calling ISession::unlockMachine on the local session object once this call has returned. However, the session's state (see ISession::state) will not return to "Unlocked" until the remote session has also unlocked the machine (i.e. the machine has stopped running).
Launching a VM process can take some time (a new VM is started in a new process, for which memory and other resources need to be set up). Because of this, an IProgress object is returned to allow the caller to wait for this asynchronous operation to be completed. Until then, the caller's session object remains in the "Unlocked" state, and its ISession::machine and ISession::console attributes cannot be accessed. It is recommended to use IProgress::waitForCompletion or similar calls to wait for completion. Completion is signalled when the VM is powered on. If launching the VM fails, error messages can be queried via the progress object, if available.
The progress object will have at least 2 sub-operations. The first operation covers the period up to the new VM process calls powerUp. The subsequent operations mirror the IConsole::powerUp progress object. Because IConsole::powerUp may require some extra sub-operations, the IProgress::operationCount may change at the completion of operation.
For details on the teleportation progress operation, see IConsole::powerUp.
The environment argument is a string containing definitions of environment variables in the following format:
NAME[=VALUE]\n NAME[=VALUE]\n ...
where \n
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 null
or empty, the server environment is inherited by the started process as is.
session | Client session object to which the VM process will be connected (this must be in "Unlocked" state). | |
type | Front-end to use for the new VM process. The following are currently supported:
| |
environment | Environment to pass to the VM process. | |
progress | Progress object to track the operation completion. |
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, DeviceType_Null should be used.
position | Position in the boot order (1 to the total number of devices the machine can boot from, as returned by ISystemProperties::maxBootPosition). | |
device | The type of the device used to boot at the given position. |
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.
If here are no devices at the given position, then DeviceType_Null is returned.
position | Position in the boot order (1 to the total number of devices the machine can boot from, as returned by ISystemProperties::maxBootPosition). | |
device | Device at the given position. |
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:
In a VM's default configuration of virtual machines, the secondary master of the IDE controller is used for a CD/DVD drive.
After calling this returns successfully, a new instance of IMediumAttachment will appear in the machine's list of medium attachments (see IMachine::mediumAttachments).
See IMedium and IMediumAttachment for more information about attaching media.
The specified device slot must not have a device attached to it, or this method will fail.
name | Name of the storage controller to attach the device to. | |
controllerPort | Port to attach the device to. For an IDE controller, 0 specifies the primary controller and 1 specifies the secondary controller. For a SCSI controller, this must range from 0 to 15; for a SATA controller, from 0 to 29; for an SAS controller, from 0 to 7. | |
device | Device slot in the given port to attach the device to. This is only relevant for IDE controllers, for which 0 specifies the master device and 1 specifies the slave device. For all other controller types, this must be 0. | |
type | Device type of the attached device. For media opened by IVirtualBox::openMedium, this must match the device type specified there. | |
medium | Medium to mount or NULL for an empty drive. |
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. |
void IMachine::detachDevice | ( | in wstring | name, | |
in long | controllerPort, | |||
in long | device | |||
) |
Detaches the device attached to a device slot of the specified bus.
Detaching the device from the virtual machine is deferred. This means that the medium remains associated with the machine when this method returns and gets actually de-associated only after a successful saveSettings call. See IMedium for more detailed information about attaching media.
name | Name of the storage controller to detach the medium from. | |
controllerPort | Port number to detach the medium from. | |
device | Device slot number to detach the medium from. |
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. |
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.
name | Name of the storage controller. | |
controllerPort | Storage controller port. | |
device | Device slot in the given port. | |
passthrough | New value for the passthrough setting. |
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::setBandwidthGroupForDevice | ( | in wstring | name, | |
in long | controllerPort, | |||
in long | device, | |||
in IBandwidthGroup | bandwidthGroup | |||
) |
Sets the bandwidth group of an existing storage device.
The device must already exist; see IMachine::attachDevice for how to attach a new device.
The controllerPort and device parameters specify the device slot and have have the same meaning as with IMachine::attachDevice.
name | Name of the storage controller. | |
controllerPort | Storage controller port. | |
device | Device slot in the given port. | |
bandwidthGroup | New value for the bandwidth group or NULL for no group. |
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::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.
name | Name of the storage controller to attach the medium to. | |
controllerPort | Port to attach the medium to. | |
device | Device slot in the given port to attach the medium to. | |
medium | Medium to mount or NULL for an empty drive. | |
force | Allows to force unmount/mount of a medium which is locked by the device slot in the given port to attach the medium to. |
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 mountMedium to the given device slot then this method will return not the same object as passed to the mountMedium call. See IMedium for more detailed information about mounting a medium.
name | Name of the storage controller the medium is attached to. | |
controllerPort | Port to query. | |
device | Device slot in the given port to query. | |
medium | Attached medium object. |
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.
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.
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 IEventContext | eventContext, | |||
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.
hostAddress | Address of the host PCI device. | |
desiredGuestAddress | Desired position of this device on guest PCI bus. | |
eventContext | Context passed into IHostPciDevicePlugEvent event. | |
tryToUnbind | If VMM shall try to unbind existing drivers from the device before attaching it to the guest. |
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 passthrought. |
void IMachine::detachHostPciDevice | ( | in long | hostAddress | ) |
Detach host PCI device from the virtual machine.
Also HostPciDevicePlugEvent on IVirtualBox event source will be delivered.
hostAddress | Address of the host PCI device. |
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 passthrought. |
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 ISystemProperties::networkAdapterCount property, so the maximum slot number is one less than that property's value.
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.
name identifies the controller for subsequent calls such as getStorageControllerByName, getStorageControllerByInstance, removeStorageController, attachDevice or mountMedium.
After the controller has been added, you can set its exact type by setting the IStorageController::controllerType.
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.
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.
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.
VBOX_E_OBJECT_NOT_FOUND | A storage controller with given name doesn't exist. |
void IMachine::setStorageControllerBootable | ( | in wstring | name, | |
in boolean | bootable | |||
) |
Sets the bootable flag of the storage controller with the given name.
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::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 ISystemProperties::serialPortCount property, so the maximum slot number is one less than that property's value.
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 ISystemProperties::parallelPortCount property, so the maximum slot number is one less than that property's value.
E_INVALIDARG | Invalid slot number. |
void IMachine::getExtraDataKeys | ( | [retval] out wstring[] | value | ) |
Returns an array representing the machine-specific extra data keys which currently have values defined.
value | Array of extra data keys. |
void IMachine::getExtraData | ( | in wstring | key, | |
[retval] out wstring | value | |||
) |
Returns associated machine-specific extra data.
If the requested data key does not exist, this function will succeed and return an empty string in the value argument.
key | Name of the data key to get. | |
value | Value of the requested data key. |
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 null
or an empty string as a key value, the given key will be deleted.
key | Name of the data key to set. | |
value | Value to assign to the key. |
VBOX_E_FILE_ERROR | Settings file not accessible. |
VBOX_E_XML_ERROR | Could not parse the settings file. |
void IMachine::getCPUProperty | ( | in CPUPropertyType | property, | |
[retval] out boolean | value | |||
) |
Returns the virtual CPU boolean value of the specified property.
property | Property type to query. | |
value | Property value. |
E_INVALIDARG | Invalid property. |
void IMachine::setCPUProperty | ( | in CPUPropertyType | property, | |
in boolean | value | |||
) |
Sets the virtual CPU boolean value of the specified property.
property | Property type to query. | |
value | Property value. |
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.
id | CPUID leaf index. | |
valEax | CPUID leaf value for register eax. | |
valEbx | CPUID leaf value for register ebx. | |
valEcx | CPUID leaf value for register ecx. | |
valEdx | CPUID leaf value for register edx. |
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.
id | CPUID leaf index. | |
valEax | CPUID leaf value for register eax. | |
valEbx | CPUID leaf value for register ebx. | |
valEcx | CPUID leaf value for register ecx. | |
valEdx | CPUID leaf value for register edx. |
E_INVALIDARG | Invalid id. |
void IMachine::removeCPUIDLeaf | ( | in unsigned long | id | ) |
Removes the virtual CPU cpuid leaf for the specified index.
id | CPUID leaf index. |
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.
property | Property type to query. | |
value | Property value. |
E_INVALIDARG | Invalid property. |
void IMachine::setHWVirtExProperty | ( | in HWVirtExPropertyType | property, | |
in boolean | value | |||
) |
Sets a new value for the specified hardware virtualization boolean property.
property | Property type to set. | |
value | New property value. |
E_INVALIDARG | Invalid property. |
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.
VBOX_E_FILE_ERROR | Settings file not accessible. |
VBOX_E_XML_ERROR | Could not parse the settings file. |
E_ACCESSDENIED | Modification request refused. |
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.
VBOX_E_INVALID_VM_STATE | Virtual machine is not mutable. |
void IMachine::unregister | ( | in CleanupMode | cleanupMode, | |
[retval] out IMedium[] | aMedia | |||
) |
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 delete, optionally with the array of IMedium objects which was returned from this method.
How thoroughly this method cleans up the machine configuration before unregistering the machine depends on the cleanupMode argument.
IVirtualBox::unregisterMachine()
API which it replaces. A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the resulting IMedium array to delete. 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 delete however, closing the image will fail there and the image will be silently skipped.
This API may, however, move media from this machine's media registry to other media registries (see IMedium for details on media registries). For machines created with VirtualBox 4.0 or later, if media from this machine's media registry are also attached to another machine (shared attachments), each such medium will be moved to another machine's registry. This is because without this machine's media registry, the other machine cannot find its media any more and would become inaccessible.
This API implicitly calls saveSettings to save all current machine settings before unregistering it. It may also silently call saveSettings() on other machines if media are moved to other machines' media registries.
After successful method invocation, the IMachineRegisteredEvent event is fired.
The call will fail if the machine is currently locked (see ISession).
cleanupMode | How to clean up after the machine has been unregistered. | |
aMedia | List of media detached from the machine, depending on the cleanupMode parameter. |
VBOX_E_INVALID_OBJECT_STATE | Machine is currently locked for a session. |
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:
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).
aMedia | List of media to be closed and whose storage files will be deleted. | |
aProgress | Progress object to track the operation completion. |
VBOX_E_INVALID_VM_STATE | Machine is registered but not write-locked. |
VBOX_E_IPRT_ERROR | Could not delete the settings file. |
true
after this method successfully returns. void IMachine::export | ( | in IAppliance | aAppliance, | |
in wstring | location, | |||
[retval] out IVirtualSystemDescription | aDescription | |||
) |
Exports the machine to an OVF appliance.
See IAppliance for the steps required to export VirtualBox machines to OVF.
aAppliance | Appliance to export this machine to. | |
location | The target location. | |
aDescription | VirtualSystemDescription 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 null
argument can be used to obtain the first snapshot taken on this machine. To traverse the whole tree of snapshots starting from the root, inspect the root snapshot's ISnapshot::children attribute and recurse over those children.
nameOrId | What to search for. Name or UUID of the snapshot to find | |
snapshot | Snapshot object with the given name. |
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.
name | Unique logical name of the shared folder. | |
hostPath | Full path to the shared folder in the host file system. | |
writable | Whether the share is writable or readonly. | |
automount | Whether the share gets automatically mounted by the guest or not. |
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.
name | Logical name of the shared folder to remove. |
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.
canShow | true if the console window can be shown and false otherwise. |
VBOX_E_INVALID_VM_STATE | Machine session is not 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.
winId | Platform-dependent identifier of the top-level VM console window, or zero if this method has performed all actions necessary to implement the show window semantics for the given platform and/or VirtualBox front-end. |
VBOX_E_INVALID_VM_STATE | Machine session is not 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.
name | The name of the property to read. | |
value | The value of the property. If the property does not exist then this will be empty. | |
timestamp | The time at which the property was last modified, as seen by the server process. | |
flags | Additional property parameters, passed as a comma-separated list of "name=value" type entries. |
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.
property | The name of the property to read. | |
value | The value of the property. If the property does not exist then this will be empty. |
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.
property | The name of the property to read. | |
value | The timestamp. If the property does not exist then this will be empty. |
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.
property | The name of the property to set, change or delete. | |
value | The new value of the property to set, change or delete. If the property does not yet exist and value is non-empty, it will be created. If the value is null or empty, the property will be deleted if it exists. | |
flags | Additional property parameters, passed as a comma-separated list of "name=value" type entries. |
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, changes or deletes a value in the machine's guest property store.
The flags field will be left unchanged or created empty for a new property.
property | The name of the property to set, change or delete. | |
value | The new value of the property to set, change or delete. If the property does not yet exist and value is non-empty, it will be created. If the value is null or empty, the property will be deleted if it exists. |
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::enumerateGuestProperties | ( | in wstring | patterns, | |
out wstring[] | name, | |||
out wstring[] | value, | |||
out long long[] | timestamp, | |||
out wstring[] | flags | |||
) |
Return a list of the guest properties matching a set of patterns along with their values, time stamps and flags.
patterns | The patterns to match the properties against, separated by '|' characters. If this is empty or null , all properties will match. | |
name | The names of the properties returned. | |
value | The values of the properties returned. The array entries match the corresponding entries in the name array. | |
timestamp | The time stamps of the properties returned. The array entries match the corresponding entries in the name array. | |
flags | The flags of the properties returned. The array entries match the corresponding entries in the name array. |
void IMachine::querySavedGuestSize | ( | in unsigned long | screenId, | |
out unsigned long | width, | |||
out unsigned long | height | |||
) |
Returns the guest dimensions from the saved state.
screenId | Saved guest screen to query info from. | |
width | Guest width at the time of the saved state was taken. | |
height | Guest height at the time of the saved state was taken. |
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.
screenId | Saved guest screen to query info from. | |
size | Size of buffer required to store the bitmap. | |
width | Bitmap width. | |
height | Bitmap 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.
screenId | Saved guest screen to read from. | |
BGR | How 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. | |
width | Bitmap width. | |
height | Bitmap height. | |
data | Array 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.
screenId | Saved guest screen to read from. | |
width | Image width. | |
height | Image height. | |
data | Array 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.
screenId | Saved guest screen to query info from. | |
size | Size of buffer required to store the PNG binary data. | |
width | Image width. | |
height | Image 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.
screenId | Saved guest screen to read from. | |
width | Image width. | |
height | Image height. | |
data | Array with resulting PNG data. |
void IMachine::hotPlugCPU | ( | in unsigned long | cpu | ) |
Plugs a CPU into the machine.
cpu | The CPU id to insert. |
void IMachine::hotUnplugCPU | ( | in unsigned long | cpu | ) |
Removes a CPU from the machine.
cpu | The CPU id to remove. |
void IMachine::getCPUStatus | ( | in unsigned long | cpu, | |
[retval] out boolean | attached | |||
) |
Returns the current status of the given CPU.
cpu | The CPU id to check for. | |
attached | Status 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.
idx | Which log file name to query. 0=current log file. | |
filename | On return the full path to the log file or an empty string on error. |
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.
idx | Which log file to read. 0=current log file. | |
offset | Offset in the log file. | |
size | Chunk size to read in the log file. | |
data | Data read from the log file. A data size of 0 means end of file if the requested chunk size was not 0. This is the unprocessed file data, i.e. the line ending style depends on the platform of the system the server is running on. |
readonly attribute IVirtualBox IMachine::parent |
Associated parent object.
readonly attribute boolean IMachine::accessible |
Whether this virtual machine is currently accessible or not.
A machine is always deemed accessible unless it is registered and its settings file cannot be read or parsed (either because the file itself is unavailable or has invalid XML contents).
Every time this property is read, the accessibility state of this machine is re-evaluated. If the returned value is false
, the accessError property may be used to get the detailed error information describing the reason of inaccessibility, including XML error messages.
When the machine is inaccessible, only the following properties can be used on it:
An attempt to access any other property or method will return an error.
The only possible action you can perform on an inaccessible machine is to unregister it using the IMachine::unregister call (or, to check for the accessibility state once more by querying this property).
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 saveSettings to confirm the change. The containing subdirectory will be also renamed, but only if it has exactly the same name as the settings file itself prior to changing this property (for backward compatibility with previous API releases). The above implies the following limitations:
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::OSTypeId |
User-defined identifier of the Guest OS type.
You may use IVirtualBox::getGuestOSType to obtain an IGuestOSType object representing details about the given Guest OS type.
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. This 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 bits host only).
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.
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 <
path_to_settings_file>/<
machine_uuid>
.
Currently, it is an error to try to change this property on a machine that has snapshots (because this would require to move possibly large files to a different location). A separate method will be available for this purpose later.
null
or to an empty string will restore the initial value.readonly attribute IVRDEServer IMachine::VRDEServer |
VirtualBox Remote Desktop Extension (VRDE) server object.
readonly attribute IMediumAttachment [] IMachine::mediumAttachments |
Array of media attached to this machine.
readonly attribute IUSBController IMachine::USBController |
Associated USB controller object.
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).
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.
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:
false
) The current state remains identical until one of the following happens:
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 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.
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 IBandwidthControl IMachine::bandwidthControl |
Bandwidth control manager.
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.