Public Member Functions | |
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 order,[retval] out DeviceType device) |
Returns the device type that occupies the specified position in the boot order. | |
void | attachHardDisk (in uuid id, in StorageBus bus, in long channel, in long device) |
Attaches a virtual hard disk identified by the given UUID to the given device slot of the given channel on the given bus. | |
void | getHardDisk (in StorageBus bus, in long channel, in long device,[retval] out IHardDisk hardDisk) |
Returns the hard disk attached to the given controller under the specified device number. | |
void | detachHardDisk (in StorageBus bus, in long channel, in long device) |
Detaches the hard disk drive attached to the given device slot of the given controller. | |
void | getNetworkAdapter (in unsigned long slot,[retval] out INetworkAdapter adapter) |
Returns the network adapter associated with the given slot. | |
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 | getNextExtraDataKey (in wstring key, out wstring nextKey, out wstring nextValue) |
Returns the machine-specific extra data key name following the supplied key. | |
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 | 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 | saveSettingsWithBackup ([retval] out wstring bakFileName) |
Creates a backup copy of the machine settings file (settingsFilePath) in case of auto-conversion, and then calls saveSettings(). | |
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 | deleteSettings () |
Deletes the settings file of this machine from disk. | |
void | getSnapshot (in uuid id,[retval] out ISnapshot snapshot) |
Returns a snapshot of this machine with the given UUID. | |
void | findSnapshot (in wstring name,[retval] out ISnapshot snapshot) |
Returns a snapshot of this machine with the given name. | |
void | setCurrentSnapshot (in uuid id) |
Sets the current snapshot of this machine. | |
void | createSharedFolder (in wstring name, in wstring hostPath, in boolean writable) |
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 unsigned 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 unsigned 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 unsigned 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 unsigned long long[] timestamp, out wstring[] flags) |
Return a list of the guest properties matching a set of patterns along with their values, timestamps and flags. | |
Public Attributes | |
readonly attribute IVirtualBox | parent |
Associated parent obect. | |
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 uuid | id |
UUID of the virtual machine. | |
attribute wstring | OSTypeId |
User-defined identifier of the Guest OS type. | |
attribute unsigned long | memorySize |
System memory size in megabytes. | |
attribute unsigned long | memoryBalloonSize |
Initial memory balloon size in megabytes. | |
attribute unsigned long | statisticsUpdateInterval |
Initial interval to update guest statistics in seconds. | |
attribute unsigned long | VRAMSize |
Video memory size in megabytes. | |
attribute unsigned long | MonitorCount |
Number of virtual monitors. | |
readonly attribute IBIOSSettings | BIOSSettings |
Object containing all BIOS settings. | |
attribute TSBool | HWVirtExEnabled |
This setting determines whether VirtualBox will try to make use of the host CPU's hardware virtualization extensions such as Intel VT-x and AMD-V. | |
attribute boolean | HWVirtExNestedPagingEnabled |
This setting determines whether VirtualBox will try to make use of the nested paging extension of Intel VT-x and AMD-V. | |
attribute boolean | PAEEnabled |
This setting determines whether VirtualBox will expose the Physical Address Extension (PAE) feature of the host CPU to the guest. | |
attribute wstring | snapshotFolder |
Full path to the directory used to store snapshot data (difrerencing hard disks and saved state files) of this machine. | |
readonly attribute IVRDPServer | VRDPServer |
VRDP server object. | |
readonly attribute IHardDiskAttachmentCollection | hardDiskAttachments |
Collection of hard disks attached to the machine. | |
readonly attribute IDVDDrive | DVDDrive |
Associated DVD drive object. | |
readonly attribute IFloppyDrive | FloppyDrive |
Associated floppy drive object. | |
readonly attribute IUSBController | USBController |
Associated USB controller object. | |
readonly attribute IAudioAdapter | audioAdapter |
Associated audio adapter, always present. | |
readonly attribute ISATAController | SATAController |
Associated SATA controller object. | |
readonly attribute wstring | settingsFilePath |
Full name of the file containing machine settings data. | |
readonly attribute wstring | settingsFileVersion |
Current version of the format of the settings file of this machine (settingsFilePath). | |
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 ISharedFolderCollection | 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. |
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 explicitely 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 IVirtualBox::openSession, IVirtualBox::openRemoteSession or IVirtualBox::openExistingSession methdods. After the session has been successfully opened, 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 the IMachine interface 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 IConsole interface. Refer to the IConsole interface description to get more information about this topic.
{1E509DE4-D96C-4F44-8B94-860194F710AC}
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. |
void IMachine::getBootOrder | ( | in unsigned long | order, | |
[retval] out DeviceType | device | |||
) |
Returns the device type that occupies the specified position in the boot order.
order | 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. |
void IMachine::attachHardDisk | ( | in uuid | id, | |
in StorageBus | bus, | |||
in long | channel, | |||
in long | device | |||
) |
Attaches a virtual hard disk identified by the given UUID to the given device slot of the given channel on the given bus.
The specified device slot must not have another disk attached and the given hard disk must not be already attached to this machine.
See IHardDisk for detailed information about attaching hard disks.
id | UUID of the hard disk to attach. | |
bus | Type of storage bus to use (IDE or SATA). | |
channel | Channel to attach the hard disk to. For IDE controllers, this can either be 0 or 1, for the primary or secondary controller, respectively. | |
device | Device slot in the given channel to attach the hard disk to. For IDE devices, within each channel (0 or 1), this can again be 0 or 1, for master or slave, respectively. |
Attaching a hard disk to a machine creates a lazy attachment. In particular, no differeincing images are actually created until saveSettings() is called to commit all changed settings.
void IMachine::getHardDisk | ( | in StorageBus | bus, | |
in long | channel, | |||
in long | device, | |||
[retval] out IHardDisk | hardDisk | |||
) |
Returns the hard disk attached to the given controller under the specified device number.
void IMachine::detachHardDisk | ( | in StorageBus | bus, | |
in long | channel, | |||
in long | device | |||
) |
Detaches the hard disk drive attached to the given device slot of the given controller.
See IHardDisk for detailed information about attaching hard disks.
bus | Bus to dettach the hard disk from. | |
channel | Channel number to dettach the hard disk from. | |
device | Device slot number to dettach the hard disk from. |
Detaching a hard disk from a machine creates a lazy detachment. In particular, if the detached hard disk is a differencing hard disk, it is not actually deleted until saveSettings() is called to commit all changed settings. Keep in mind, that doing saveSettings() will physically delete all detached differencing hard disks, so be careful.
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 every machine is defined by the ISystemProperties::networkAdapterCount property, so the maximum slot number is one less than that property's value.
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 every machine is defined by the ISystemProperties::serialPortCount property, so the maximum slot number is one less than that property's value.
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 every machine is defined by the ISystemProperties::parallelPortCount property, so the maximum slot number is one less than that property's value.
void IMachine::getNextExtraDataKey | ( | in wstring | key, | |
out wstring | nextKey, | |||
out wstring | nextValue | |||
) |
Returns the machine-specific extra data key name following the supplied key.
An error is returned if the supplied key does not exist. NULL
is returned in nextKey if the supplied key is the last key. When supplying NULL
for the key, the first key item is returned in nextKey (if there is any). nextValue is an optional parameter and if supplied, the next key's value is returned in it.
key | Name of the data key to follow. | |
nextKey | Name of the next data key. | |
nextValue | Value of the next data key. |
void IMachine::getExtraData | ( | in wstring | key, | |
[retval] out wstring | value | |||
) |
Returns associated machine-specific extra data.
If the reuqested data key does not exist, this function will succeed and return NULL
in the value argument.
key | Name of the data key to get. | |
value | Value of the requested data key. |
void IMachine::setExtraData | ( | in wstring | key, | |
in wstring | value | |||
) |
Sets associated machine-specific extra data.
If you pass NULL
as a key vaule, the given key will be deleted.
key | Name of the data key to set. | |
value | Value to assign to the key. |
On success, the IVirtualBoxCallback::onExtraDataChange() notification is called to inform all registered callbacks 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::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.
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 IVirtualBox::unregisterMachine.
void IMachine::saveSettingsWithBackup | ( | [retval] out wstring | bakFileName | ) |
Creates a backup copy of the machine settings file (settingsFilePath) in case of auto-conversion, and then calls saveSettings().
Note that the backup copy is created only if the settings file auto-conversion took place (see settingsFileVersion for details). Otherwise, this call is fully equivalent to saveSettings() and no backup copying is done.
The backup copy is created in the same directory where the original settings file is located. It is given the following file name:
original.xml.x.y-platform.bakwhere
original.xml
is the original settings file name (excluding path), and x.y-platform
is the version of the old format of the settings file (before auto-conversion).
If the given backup file already exists, this method will try to add the .N
suffix to the backup file name (where N
counts from 0 to 9) and copy it again until it succeeds. If all suffixes are occupied, or if any other copy error occurs, this method will return a failure.
If the copy operation succeeds, the bakFileName return argument will receive a full path to the created backup file (for informational purposes). Note that this will happen even if the subsequent saveSettings() call performed by this method after the copy operation, fails.
bakFileName | Full path to the created backup copy. |
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.
void IMachine::deleteSettings | ( | ) |
Deletes the settings file of this machine from disk.
The machine must not be registered in order for this operation to succeed.
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 IVirtualBox::unregisterMachine.
The deleted machine settings file can be restored (saved again) by calling saveSettings().
void IMachine::getSnapshot | ( | in uuid | id, | |
[retval] out ISnapshot | snapshot | |||
) |
Returns a snapshot of this machine with the given UUID.
A null
UUID can be used to obtain the first snapshot taken on this machine. This is useful if you want to traverse the whole tree of snapshots starting from the root.
id | UUID of the snapshot to get | |
snapshot | Snapshot object with the given UUID. |
void IMachine::findSnapshot | ( | in wstring | name, | |
[retval] out ISnapshot | snapshot | |||
) |
Returns a snapshot of this machine with the given name.
name | Name of the snapshot to find | |
snapshot | Snapshot object with the given name. |
void IMachine::setCurrentSnapshot | ( | in uuid | id | ) |
Sets the current snapshot of this machine.
id | UUID of the snapshot to set as the current snapshot. |
void IMachine::createSharedFolder | ( | in wstring | name, | |
in wstring | hostPath, | |||
in boolean | writable | |||
) |
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 |
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. |
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. |
void IMachine::showConsoleWindow | ( | [retval] out unsigned 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. |
void IMachine::getGuestProperty | ( | in wstring | name, | |
out wstring | value, | |||
out unsigned 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. |
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. |
void IMachine::getGuestPropertyTimestamp | ( | in wstring | property, | |
[retval] out unsigned 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. |
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 empty, the key will be deleted if it exists. | |
flags | Additional property parameters, passed as a comma-separated list of "name=value" type entries. |
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 value is empty, the property will be deleted if it exists. |
void IMachine::enumerateGuestProperties | ( | in wstring | patterns, | |
out wstring[] | name, | |||
out wstring[] | value, | |||
out unsigned long long[] | timestamp, | |||
out wstring[] | flags | |||
) |
Return a list of the guest properties matching a set of patterns along with their values, timestamps and flags.
patterns | The patterns to match the properties against as a comma-separated string with no spaces. If this is empty, all properties currently set will be returned. | |
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 timestamps of the properties returned. The array entries match the corresponding entries in the name array. | |
flags | The flags of the properties returned. The array entries match the corresponding entries in the name array. |
readonly attribute IVirtualBox IMachine::parent |
Associated parent obect.
readonly attribute boolean IMachine::accessible |
Whether this virtual machine is currently accessible or not.
The machine is considered to be inaccessible when:
Otherwise, the value of this property is always true
.
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.
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 IVirtualBox::unregisterMachine 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 unaccessible). 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:
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 uuid 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 unsigned long IMachine::memorySize |
System memory size in megabytes.
attribute unsigned long IMachine::memoryBalloonSize |
Initial memory balloon size in megabytes.
attribute unsigned long IMachine::statisticsUpdateInterval |
Initial interval to update guest statistics in seconds.
attribute unsigned long IMachine::VRAMSize |
Video memory size in megabytes.
attribute unsigned long IMachine::MonitorCount |
Number of virtual monitors.
readonly attribute IBIOSSettings IMachine::BIOSSettings |
Object containing all BIOS settings.
attribute TSBool IMachine::HWVirtExEnabled |
This setting determines whether VirtualBox will try to make use of the host CPU's hardware virtualization extensions such as Intel VT-x and AMD-V.
Note that in case such extensions are not available, they will not be used.
attribute boolean IMachine::HWVirtExNestedPagingEnabled |
This setting determines whether VirtualBox will try to make use of the nested paging extension of Intel VT-x and AMD-V.
Note that in case such extensions are not available, they will not be used.
attribute boolean IMachine::PAEEnabled |
This setting determines whether VirtualBox will expose the Physical Address Extension (PAE) feature of the host CPU to the guest.
Note that in case PAE is not available, it will not be reported.
attribute wstring IMachine::snapshotFolder |
Full path to the directory used to store snapshot data (difrerencing hard disks 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
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 IVRDPServer IMachine::VRDPServer |
VRDP server object.
readonly attribute IHardDiskAttachmentCollection IMachine::hardDiskAttachments |
Collection of hard disks attached to the machine.
readonly attribute IDVDDrive IMachine::DVDDrive |
Associated DVD drive object.
readonly attribute IFloppyDrive IMachine::FloppyDrive |
Associated floppy drive object.
readonly attribute IUSBController IMachine::USBController |
Associated USB controller object.
If USB functionality is not avaliable 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 ISATAController IMachine::SATAController |
Associated SATA controller object.
readonly attribute wstring IMachine::settingsFilePath |
Full name of the file containing machine settings data.
readonly attribute wstring IMachine::settingsFileVersion |
Current version of the format of the settings file of this machine (settingsFilePath).
The version string has the following format:
x.y-platformwhere
x
and y
are the major and the minor format versions, and platform
is the platform identifier.The current version usually matches the value of the IVirtualBox::settingsFormatVersion attribute unless the settings file was created by an older version of VirtualBox and there was a change of the settings file format since then.
Note that VirtualBox automatically converts settings files from older versions to the most recent version when reading them (usually at VirtualBox startup) but it doesn't save the changes back until you call a method that implicitly saves settings (such as setExtraData()) or call saveSettings() explicitly. Therefore, if the value of this attribute differs from the value of IVirtualBox::settingsFormatVersion, then it means that the settings file was converted but the result of the conversion is not yet saved to disk.
The above feature may be used by interactive front-ends to inform users about the settings file format change and offer them to explicitly save all converted settings files (the global and VM-specific ones), optionally create bacup copies of the old settings files before saving, etc.
readonly attribute boolean IMachine::settingsModified |
Whether the settings of this machine have been modified (but neither yet saved nor discarded).
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 SessionSpawning or SessionOpen, this attribute contains the same value as passed to the IVirtualBox::openRemoteSession() method in the type parameter. If the session was opened directly using IVirtualBox::openSession(), or if sessionState is SessionClosed, the value of this attribute is null
.
readonly attribute unsigned long IMachine::sessionPid |
Identifier of the session process.
This attribute contains the platform-dependent identifier of the process that has opened a direct session for this machine using the IVirtualBox::openSession() call. The returned value is only valid if sessionState is SessionOpen or SessionClosing (i.e. a session is currently open or being closed) 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.
null
. 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 (upto VBox.log.3
in the current version).
readonly attribute ISnapshot IMachine::currentSnapshot |
Current snapshot of this machine.
null
object is returned if the machine doesn't have snapshots.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 right after one of the following calls are made:
false
) The current state remains identical until one of the following happens:
false
. readonly attribute ISharedFolderCollection 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.