IMachine Interface Reference

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

List of all members.

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 position,[retval] out DeviceType device)
 Returns the device type that occupies the specified position in the boot order.
void attachHardDisk (in uuid id, in wstring name, in long controllerPort, in long device)
 Attaches a virtual hard disk (IHardDisk, identified by the given UUID id) to the given hard disk controller (IStorageController, identified by name), at the indicated port and device.
void getHardDisk (in wstring name, in long controllerPort, in long device,[retval] out IHardDisk hardDisk)
 Returns the virtual hard disk attached to a device slot of the specified bus.
void detachHardDisk (in wstring name, in long controllerPort, in long device)
 Detaches the virtual hard disk attached to a device slot of the specified bus.
void getHardDiskAttachmentsOfController (in wstring name,[retval] out IHardDiskAttachment[] hardDiskAttachments)
 Returns an array of hard disk attachments which are attached to the the controller with the given name.
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 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 removeStorageController (in wstring name)
 Removes a storage controller from the machine.
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 (IMachine::settingsFilePath) in case of auto-conversion, and then calls IMachine::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 export (in IAppliance aAppliance,[retval] out IVirtualSystemDescription aDescription)
 Exports the machine to an OVF appliance.
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, time stamps and flags.

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 uuid id
 UUID of the virtual machine.
attribute wstring OSTypeId
 User-defined identifier of the Guest OS type.
attribute wstring HardwareVersion
 Hardware version identifier.
attribute unsigned long CPUCount
 Number of virtual CPUs in the VM.
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 boolean accelerate3DEnabled
 This setting determines whether VirtualBox allows guests to make use of the 3D graphics support available on the host.
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 HWVirtExVPIDEnabled
 This setting determines whether VirtualBox will try to make use of the VPID extension of Intel VT-x.
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 (differencing hard disks and saved state files) of this machine.
readonly attribute IVRDPServer VRDPServer
 VRDP server object.
readonly attribute
IHardDiskAttachment[] 
hardDiskAttachments
 Array of hard disks attached to this 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
IStorageController[] 
storageControllers
 Array of storage controllers attached to this machine.
readonly attribute wstring settingsFilePath
 Full name of the file containing machine settings data.
readonly attribute wstring settingsFileVersion
 Current version of the format of the settings file of this machine (IMachine::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 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.


Detailed Description

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

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

The main role of this interface is to expose the settings of the virtual machine and provide methods to change various aspects of the virtual machine's configuration. For machine objects stored in the IVirtualBox::machines collection, all attributes are read-only unless explicitly stated otherwise in individual attribute and method descriptions. In order to change a machine setting, a session for this machine must be opened using one of IVirtualBox::openSession, IVirtualBox::openRemoteSession or IVirtualBox::openExistingSession methods. 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.

See also:
ISession, IConsole
Interface ID:
{13420CBB-175A-4456-85D0-301126DFDEC7}

Member Function Documentation

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

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

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

Todo:
setHardDiskBootOrder(), setNetworkBootOrder()
Parameters:
position Position in the boot order (1 to the total number of devices the machine can boot from, as returned by ISystemProperties::maxBootPosition).
device The type of the device used to boot at the given position.
Expected result codes:
E_INVALIDARG Boot position out of range.
E_NOTIMPL Booting from USB device currently not supported.

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

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

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

Todo:
getHardDiskBootOrder(), getNetworkBootOrder()
Parameters:
position Position in the boot order (1 to the total number of devices the machine can boot from, as returned by ISystemProperties::maxBootPosition).
device Device at the given position.
Expected result codes:
E_INVALIDARG Boot position out of range.

void IMachine::attachHardDisk ( in uuid  id,
in wstring  name,
in long  controllerPort,
in long  device 
)

Attaches a virtual hard disk (IHardDisk, identified by the given UUID id) to the given hard disk controller (IStorageController, identified by name), at the indicated port and device.

For the IDE bus, the controllerPort parameter can be either 0 or 1, to specify the primary or secondary IDE controller, respectively. For the primary controller of the IDE bus, device can be either 0 or 1, to specify the master or the slave device, respectively. For the secondary IDE controller, the device number must be 1 because VirtualBox reserves the secondary master for the CD-ROM drive.

For an SATA controller, controllerPort must be a number ranging from 0 to 29. For a SCSI controller, controllerPort must be a number ranging from 0 to 15.

For both SCSI and SATA, the device parameter is unused and must be 0.

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

See IHardDisk for more detailed information about attaching hard disks.

Parameters:
id UUID of the hard disk to attach.
name Name of the storage controller to attach the hard disk to.
controllerPort Port to attach the hard disk to.
device Device slot in the given port to attach the hard disk to.
Expected result codes:
E_INVALIDARG SATA device, SATA port, IDE port or IDE slot out of range.
VBOX_E_INVALID_OBJECT_STATE Attempt to attach hard disk to an unregistered virtual machine.
VBOX_E_INVALID_VM_STATE Invalid machine state.
VBOX_E_OBJECT_IN_USE Hard disk already attached to this or another virtual machine.
Note:
You cannot attach a hard disk to a running machine. Also, you cannot attach a hard disk to a newly created machine until this machine's settings are saved to disk using saveSettings.

If the hard disk is being attached indirectly, a new differencing hard disk will implicitly be created for it and attached instead. If the changes made to the machine settings (including this indirect attachment) are later cancelled using discardSettings, this implicitly created differencing hard disk will implicitly be deleted.

void IMachine::getHardDisk ( in wstring  name,
in long  controllerPort,
in long  device,
[retval] out IHardDisk  hardDisk 
)

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

Note that if the hard disk was indirectly attached by attachHardDisk to the given device slot then this method will return not the same object as passed to the attachHardDisk call. See IHardDisk for more detailed information about attaching hard disks.

Parameters:
name Name of the storage controller the hard disk is attached to.
controllerPort Port to query.
device Device slot in the given port to query.
hardDisk Attached hard disk object.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND No hard disk attached to given slot/bus.

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

Detaches the virtual hard disk attached to a device slot of the specified bus.

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

Parameters:
name name of the storage controller to detach the hard disk from.
controllerPort Port number to detach the hard disk from.
device Device slot number to detach the hard disk from.
Expected result codes:
VBOX_E_INVALID_VM_STATE Attempt to detach hard disk from a running virtual machine.
VBOX_E_OBJECT_NOT_FOUND No hard disk attached to given slot/bus.
VBOX_E_NOT_SUPPORTED Hard disk format does not support storage deletion.
Note:
You cannot detach the hard disk from a running machine.

Detaching differencing hard disks implicitly created by attachHardDisk for the indirect attachment using this method will not implicitly delete them. The IHardDisk::deleteStorage operation should be explicitly performed by the caller after the hard disk is successfully detached and the settings are saved with saveSettings, if it is the desired action.

void IMachine::getHardDiskAttachmentsOfController ( in wstring  name,
[retval] out IHardDiskAttachment[]  hardDiskAttachments 
)

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

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND A storage controller with given name doesn't exist.

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.

Expected result codes:
E_INVALIDARG Invalid slot number.

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

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

name identifies the controller for subsequent calls such as getStorageControllerByName or removeStorageController or attachHardDisk.

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

Expected result codes:
VBOX_E_OBJECT_IN_USE A storage controller with given name exists already.
E_INVALIDARG Invalid controllerType.

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

Returns a storage controller with the given name.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND A storage controller with given name doesn't exist.

void IMachine::removeStorageController ( in wstring  name  ) 

Removes a storage controller from the machine.

Expected result codes:
VBOX_E_OBJECT_NOT_FOUND A storage controller with given name doesn't exist.

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.

Expected result codes:
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.

Expected result codes:
E_INVALIDARG Invalid slot number.

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.

Parameters:
key Name of the data key to follow.
nextKey Name of the next data key.
nextValue Value of the next data key.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Extra data key not found.

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 NULL in the value argument.

Parameters:
key Name of the data key to get.
value Value of the requested data key.
Expected result codes:
VBOX_E_FILE_ERROR Settings file not accessible.
VBOX_E_XML_ERROR Could not parse the settings file.

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

Sets associated machine-specific extra data.

If you pass NULL as a key value, the given key will be deleted.

Parameters:
key Name of the data key to set.
value Value to assign to the key.
Expected result codes:
VBOX_E_FILE_ERROR Settings file not accessible.
VBOX_E_XML_ERROR Could not parse the settings file.
Note:
Before performing the actual data change, this method will ask all registered callbacks using the IVirtualBoxCallback::onExtraDataCanChange notification for a permission. If one of the callbacks refuses the new value, the change will not be performed.

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.

Expected result codes:
VBOX_E_FILE_ERROR Settings file not accessible.
VBOX_E_XML_ERROR Could not parse the settings file.
E_ACCESSDENIED Modification request refused.
Note:
The method sends IVirtualBoxCallback::onMachineDataChange notification event after the configuration has been successfully saved (only for registered machines).

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

void IMachine::saveSettingsWithBackup ( [retval] out wstring  bakFileName  ) 

Creates a backup copy of the machine settings file (IMachine::settingsFilePath) in case of auto-conversion, and then calls IMachine::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 IMachine::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.bak
        
where 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.

Parameters:
bakFileName Full path to the created backup copy.
Expected result codes:
VBOX_E_FILE_ERROR Settings file not accessible.
VBOX_E_XML_ERROR Could not parse the settings file.
VBOX_E_INVALID_VM_STATE Virtual machine is not mutable.
E_ACCESSDENIED Modification request refused.
Note:
The VirtualBox API never calls this method. It is intended purely for the purposes of creating backup copies of the settings files by front-ends before saving the results of the automatically performed settings conversion to disk.
See also:
settingsFileVersion

void IMachine::discardSettings (  ) 

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

Expected result codes:
VBOX_E_INVALID_VM_STATE Virtual machine is not mutable.
Note:
Calling this method is only valid on instances returned by ISession::machine and on new machines created by IVirtualBox::createMachine or opened by IVirtualBox::openMachine but not yet registered, or on unregistered machines after calling IVirtualBox::unregisterMachine.

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.

Expected result codes:
VBOX_E_INVALID_VM_STATE Cannot delete settings of a registered machine or machine not mutable.
VBOX_E_IPRT_ERROR Could not delete the settings file.
Note:
settingsModified will return TRUE after this method successfully returns.

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::export ( in IAppliance  aAppliance,
[retval] out IVirtualSystemDescription  aDescription 
)

Exports the machine to an OVF appliance.

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

Parameters:
aAppliance Appliance to export this machine to.
aDescription VirtualSystemDescription object which is created for this machine.

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.

Parameters:
id UUID of the snapshot to get
snapshot Snapshot object with the given UUID.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Virtual machine has no snapshots or snapshot not found.

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

Returns a snapshot of this machine with the given name.

Parameters:
name Name of the snapshot to find
snapshot Snapshot object with the given name.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Virtual machine has no snapshots or snapshot not found.

void IMachine::setCurrentSnapshot ( in uuid  id  ) 

Sets the current snapshot of this machine.

Parameters:
id UUID of the snapshot to set as the current snapshot.
Note:
In the current implementation, this operation is not implemented.

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.

Parameters:
name Unique logical name of the shared folder.
hostPath Full path to the shared folder in the host file system.
writable Whether the share is writable or readonly
Expected result codes:
VBOX_E_OBJECT_IN_USE Shared folder already exists.
VBOX_E_FILE_ERROR Shared folder hostPath not accessible.

void IMachine::removeSharedFolder ( in wstring  name  ) 

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

Parameters:
name Logical name of the shared folder to remove.
Expected result codes:
VBOX_E_INVALID_VM_STATE Virtual machine is not mutable.
VBOX_E_OBJECT_NOT_FOUND Shared folder name does not exist.

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

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

Parameters:
canShow true if the console window can be shown and false otherwise.
Expected result codes:
VBOX_E_INVALID_VM_STATE Machine session is not open.
Note:
This method will fail if a session for this machine is not currently open.

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.

Parameters:
winId Platform-dependent identifier of the top-level VM console window, or zero if this method has performed all actions necessary to implement the show window semantics for the given platform and/or VirtualBox front-end.
Expected result codes:
VBOX_E_INVALID_VM_STATE Machine session is not open.
Note:
This method will fail if a session for this machine is not currently open.

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.

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

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

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

Parameters:
property The name of the property to read.
value The value of the property. If the property does not exist then this will be empty.
Expected result codes:
VBOX_E_INVALID_VM_STATE Machine session is not open.

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

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

Parameters:
property The name of the property to read.
value The timestamp. If the property does not exist then this will be empty.
Expected result codes:
VBOX_E_INVALID_VM_STATE Machine session is not open.

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

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

Parameters:
property The name of the property to set, change or delete.
value The new value of the property to set, change or delete. If the property does not yet exist and value is non-empty, it will be created. If the value is empty, the key will be deleted if it exists.
flags Additional property parameters, passed as a comma-separated list of "name=value" type entries.
Expected result codes:
E_ACCESSDENIED Property cannot be changed.
E_INVALIDARG Invalid flags.
VBOX_E_INVALID_VM_STATE Virtual machine is not mutable or session not open.
VBOX_E_INVALID_OBJECT_STATE Cannot set transient property when machine not running.

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.

Parameters:
property The name of the property to set, change or delete.
value The new value of the property to set, change or delete. If the property does not yet exist and value is non-empty, it will be created. If value is empty, the property will be deleted if it exists.
Expected result codes:
E_ACCESSDENIED Property cannot be changed.
VBOX_E_INVALID_VM_STATE Virtual machine is not mutable or session not open.
VBOX_E_INVALID_OBJECT_STATE Cannot set transient property when machine not running.

void IMachine::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, time stamps and flags.

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


Member Data Documentation

readonly attribute IVirtualBox IMachine::parent

Associated parent object.

readonly attribute boolean IMachine::accessible

Whether this virtual machine is currently accessible or not.

The machine is considered to be inaccessible when:

  • It is a registered virtual machine, and
  • Its settings file is inaccessible (for example, it is located on a network share that is not accessible during VirtualBox startup, or becomes inaccessible later, or if the settings file can be read but is invalid).

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

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

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:

  • The machine name cannot be empty.
  • The machine name can contain only characters that are valid file name characters according to the rules of the file system used to store VirtualBox configuration.
  • You cannot have two or more machines with the same name if they use the same subdirectory for storing the machine settings files.
  • You cannot change the name of the machine if it is running, or if any file in the directory containing the settings file is being used by another running machine or by any other process in the host operating system at a time when saveSettings is called.
If any of the above limitations are hit, saveSettings will return an appropriate error message explaining the exact reason and the changes you made to this machine will not be saved.

Note:
For "legacy" machines created using the IVirtualBox::createLegacyMachine call, the above naming limitations do not apply because the machine name does not affect the settings file name. The settings file name remains the same as it was specified during machine creation and never changes.

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.

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

attribute wstring IMachine::HardwareVersion

Hardware version identifier.

Internal use only for now.

attribute unsigned long IMachine::CPUCount

Number of virtual CPUs in the VM.

In the current version of the product, this is always 1.

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 boolean IMachine::accelerate3DEnabled

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

Currently limited to OpenGL only.

attribute unsigned long IMachine::monitorCount

Number of virtual monitors.

Note:
Only effective on Windows XP and later guests with Guest Additions installed.

Object containing all BIOS settings.

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.

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::HWVirtExVPIDEnabled

This setting determines whether VirtualBox will try to make use of the VPID extension of Intel VT-x.

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

Note:
Setting this property to 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.

Array of hard disks attached to this machine.

readonly attribute IDVDDrive IMachine::DVDDrive

Associated DVD drive object.

readonly attribute IFloppyDrive IMachine::floppyDrive

Associated floppy drive object.

Associated USB controller object.

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

Associated audio adapter, always present.

Array of storage controllers attached to this machine.

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 (IMachine::settingsFilePath).

The version string has the following format:

          x.y-platform
        
where 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 backup copies of the old settings files before saving, etc.

See also:
IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()

readonly attribute boolean IMachine::settingsModified

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

Note:
Reading this property is only valid on instances returned by ISession::machine and on new machines created by IVirtualBox::createMachine or opened by IVirtualBox::openMachine but not yet registered, or on unregistered machines after calling IVirtualBox::unregisterMachine. For all other cases, the settings can never be modified.

For newly created unregistered machines, the value of this property is always TRUE until saveSettings is called (no matter if any machine settings have been changed after the creation or not). For opened machines the value is set to FALSE (and then follows to normal rules).

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.

Note:
When the machine is not in the Saved state, this attribute 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 (up to VBox.log.3 in the current version).

Current snapshot of this machine.

Note:
A null object is returned if the machine doesn't have snapshots.
See also:
ISnapshot

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:

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

  • settings of the machine are changed
  • the saved state is discarded
  • the current snapshot is discarded
  • an attempt to execute the machine is made
Note:
For machines that don't have snapshots, this property is always false.

readonly attribute ISharedFolder [] IMachine::sharedFolders

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

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

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

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

A comma-separated list of simple glob patterns.

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


Generated on Tue Apr 7 21:43:44 2009 for VirtualBox Main API by  doxygen 1.5.6