Public Member Functions | Public Attributes

ISystemProperties Interface Reference

The ISystemProperties interface represents global properties of the given VirtualBox installation. More...

List of all members.

Public Member Functions

void getMaxNetworkAdapters (in ChipsetType chipset,[retval] out unsigned long maxNetworkAdapters)
 Maximum total number of network adapters associated with every IMachine instance.
void getMaxNetworkAdaptersOfType (in ChipsetType chipset, in NetworkAttachmentType type,[retval] out unsigned long maxNetworkAdapters)
 Maximum number of network adapters of a given attachment type, associated with every IMachine instance.
void getMaxDevicesPerPortForStorageBus (in StorageBus bus,[retval] out unsigned long maxDevicesPerPort)
 Returns the maximum number of devices which can be attached to a port for the given storage bus.
void getMinPortCountForStorageBus (in StorageBus bus,[retval] out unsigned long minPortCount)
 Returns the minimum number of ports the given storage bus supports.
void getMaxPortCountForStorageBus (in StorageBus bus,[retval] out unsigned long maxPortCount)
 Returns the maximum number of ports the given storage bus supports.
void getMaxInstancesOfStorageBus (in ChipsetType chipset, in StorageBus bus,[retval] out unsigned long maxInstances)
 Returns the maximum number of storage bus instances which can be configured for each VM.
void getDeviceTypesForStorageBus (in StorageBus bus,[retval] out DeviceType[] deviceTypes)
 Returns list of all the supported device types (DeviceType) for the given type of storage bus.
void getDefaultIoCacheSettingForStorageController (in StorageControllerType controllerType,[retval] out boolean enabled)
 Returns the default I/O cache setting for the given storage controller.
void getMaxInstancesOfUSBControllerType (in ChipsetType chipset, in USBControllerType type,[retval] out unsigned long maxInstances)
 Returns the maximum number of USB controller instances which can be configured for each VM.

Public Attributes

readonly attribute unsigned long minGuestRAM
 Minimum guest system memory in Megabytes.
readonly attribute unsigned long maxGuestRAM
 Maximum guest system memory in Megabytes.
readonly attribute unsigned long minGuestVRAM
 Minimum guest video memory in Megabytes.
readonly attribute unsigned long maxGuestVRAM
 Maximum guest video memory in Megabytes.
readonly attribute unsigned long minGuestCPUCount
 Minimum CPU count.
readonly attribute unsigned long maxGuestCPUCount
 Maximum CPU count.
readonly attribute unsigned long maxGuestMonitors
 Maximum of monitors which could be connected.
readonly attribute long long infoVDSize
 Maximum size of a virtual disk image in bytes.
readonly attribute unsigned long serialPortCount
 Maximum number of serial ports associated with every IMachine instance.
readonly attribute unsigned long parallelPortCount
 Maximum number of parallel ports associated with every IMachine instance.
readonly attribute unsigned long maxBootPosition
 Maximum device position in the boot order.
attribute boolean exclusiveHwVirt
 Exclusive use of hardware virtualization by VirtualBox.
attribute wstring defaultMachineFolder
 Full path to the default directory used to create new or open existing machines when a machine settings file name contains no path.
attribute wstring loggingLevel
 Specifies the logging level in current use by VirtualBox.
readonly attribute IMediumFormat[] mediumFormats
 List of all medium storage formats supported by this VirtualBox installation.
attribute wstring defaultHardDiskFormat
 Identifier of the default medium format used by VirtualBox.
attribute long long freeDiskSpaceWarning
 Issue a warning if the free disk space is below (or in some disk intensive operation is expected to go below) the given size in bytes.
attribute unsigned long freeDiskSpacePercentWarning
 Issue a warning if the free disk space is below (or in some disk intensive operation is expected to go below) the given percentage.
attribute long long freeDiskSpaceError
 Issue an error if the free disk space is below (or in some disk intensive operation is expected to go below) the given size in bytes.
attribute unsigned long freeDiskSpacePercentError
 Issue an error if the free disk space is below (or in some disk intensive operation is expected to go below) the given percentage.
attribute wstring VRDEAuthLibrary
 Library that provides authentication for Remote Desktop clients.
attribute wstring webServiceAuthLibrary
 Library that provides authentication for webservice clients.
attribute wstring defaultVRDEExtPack
 The name of the extension pack providing the default VRDE.
attribute unsigned long logHistoryCount
 This value specifies how many old release log files are kept.
readonly attribute AudioDriverType defaultAudioDriver
 This value hold the default audio driver for the current system.
attribute wstring autostartDatabasePath
 The path to the autostart database.
attribute wstring defaultAdditionsISO
 The path to the default Guest Additions ISO image.
attribute wstring defaultFrontend
 Selects which VM frontend should be used by default when launching a VM through the IMachine::launchVMProcess method.

Detailed Description

The ISystemProperties interface represents global properties of the given VirtualBox installation.

These properties define limits and default values for various attributes and parameters. Most of the properties are read-only, but some can be changed by a user.

Interface ID:
{1254A96A-AE57-4484-946A-22D86C1F98AF}

Member Function Documentation

void ISystemProperties::getMaxNetworkAdapters ( in ChipsetType  chipset,
[retval] out unsigned long  maxNetworkAdapters 
)

Maximum total number of network adapters associated with every IMachine instance.

Parameters:
chipset The chipset type to get the value for.
maxNetworkAdapters The maximum total number of network adapters allowed.
void ISystemProperties::getMaxNetworkAdaptersOfType ( in ChipsetType  chipset,
in NetworkAttachmentType  type,
[retval] out unsigned long  maxNetworkAdapters 
)

Maximum number of network adapters of a given attachment type, associated with every IMachine instance.

Parameters:
chipset The chipset type to get the value for.
type Type of attachment.
maxNetworkAdapters The maximum number of network adapters allowed for particular chipset and attachment type.
void ISystemProperties::getMaxDevicesPerPortForStorageBus ( in StorageBus  bus,
[retval] out unsigned long  maxDevicesPerPort 
)

Returns the maximum number of devices which can be attached to a port for the given storage bus.

Parameters:
bus The storage bus type to get the value for.
maxDevicesPerPort The maximum number of devices which can be attached to the port for the given storage bus.
void ISystemProperties::getMinPortCountForStorageBus ( in StorageBus  bus,
[retval] out unsigned long  minPortCount 
)

Returns the minimum number of ports the given storage bus supports.

Parameters:
bus The storage bus type to get the value for.
minPortCount The minimum number of ports for the given storage bus.
void ISystemProperties::getMaxPortCountForStorageBus ( in StorageBus  bus,
[retval] out unsigned long  maxPortCount 
)

Returns the maximum number of ports the given storage bus supports.

Parameters:
bus The storage bus type to get the value for.
maxPortCount The maximum number of ports for the given storage bus.
void ISystemProperties::getMaxInstancesOfStorageBus ( in ChipsetType  chipset,
in StorageBus  bus,
[retval] out unsigned long  maxInstances 
)

Returns the maximum number of storage bus instances which can be configured for each VM.

This corresponds to the number of storage controllers one can have. Value may depend on chipset type used.

Parameters:
chipset The chipset type to get the value for.
bus The storage bus type to get the value for.
maxInstances The maximum number of instances for the given storage bus.
void ISystemProperties::getDeviceTypesForStorageBus ( in StorageBus  bus,
[retval] out DeviceType[]  deviceTypes 
)

Returns list of all the supported device types (DeviceType) for the given type of storage bus.

Parameters:
bus The storage bus type to get the value for.
deviceTypes The list of all supported device types for the given storage bus.
void ISystemProperties::getDefaultIoCacheSettingForStorageController ( in StorageControllerType  controllerType,
[retval] out boolean  enabled 
)

Returns the default I/O cache setting for the given storage controller.

Parameters:
controllerType The storage controller to the setting for.
enabled Returned flag indicating the default value
void ISystemProperties::getMaxInstancesOfUSBControllerType ( in ChipsetType  chipset,
in USBControllerType  type,
[retval] out unsigned long  maxInstances 
)

Returns the maximum number of USB controller instances which can be configured for each VM.

This corresponds to the number of USB controllers one can have. Value may depend on chipset type used.

Parameters:
chipset The chipset type to get the value for.
type The USB controller type to get the value for.
maxInstances The maximum number of instances for the given USB controller type.

Member Data Documentation

readonly attribute unsigned long ISystemProperties::minGuestRAM

Minimum guest system memory in Megabytes.

readonly attribute unsigned long ISystemProperties::maxGuestRAM

Maximum guest system memory in Megabytes.

readonly attribute unsigned long ISystemProperties::minGuestVRAM

Minimum guest video memory in Megabytes.

readonly attribute unsigned long ISystemProperties::maxGuestVRAM

Maximum guest video memory in Megabytes.

readonly attribute unsigned long ISystemProperties::minGuestCPUCount

Minimum CPU count.

readonly attribute unsigned long ISystemProperties::maxGuestCPUCount

Maximum CPU count.

readonly attribute unsigned long ISystemProperties::maxGuestMonitors

Maximum of monitors which could be connected.

readonly attribute long long ISystemProperties::infoVDSize

Maximum size of a virtual disk image in bytes.

Informational value, does not reflect the limits of any virtual disk image format.

readonly attribute unsigned long ISystemProperties::serialPortCount

Maximum number of serial ports associated with every IMachine instance.

readonly attribute unsigned long ISystemProperties::parallelPortCount

Maximum number of parallel ports associated with every IMachine instance.

readonly attribute unsigned long ISystemProperties::maxBootPosition

Maximum device position in the boot order.

This value corresponds to the total number of devices a machine can boot from, to make it possible to include all possible devices to the boot list.

See also:
IMachine::setBootOrder

Exclusive use of hardware virtualization by VirtualBox.

When enabled, VirtualBox assumes it can obtain full and exclusive access to the VT-x or AMD-V feature of the host. To share hardware virtualization with other hypervisors, this property must be disabled.

Full path to the default directory used to create new or open existing machines when a machine settings file name contains no path.

Starting with VirtualBox 4.0, by default, this attribute contains the full path of folder named "VirtualBox VMs" in the user's home directory, which depends on the host platform.

When setting this attribute, a full path must be specified. Setting this property to null or an empty string or the special value "Machines" (for compatibility reasons) will restore that default value.

If the folder specified herein does not exist, it will be created automatically as needed.

See also:
IVirtualBox::createMachine, IVirtualBox::openMachine

Specifies the logging level in current use by VirtualBox.

List of all medium storage formats supported by this VirtualBox installation.

Keep in mind that the medium format identifier (IMediumFormat::id) used in other API calls like IVirtualBox::createHardDisk to refer to a particular medium format is a case-insensitive string. This means that, for example, all of the following strings:

          "VDI"
          "vdi"
          "VdI"

refer to the same medium format.

Note that the virtual medium framework is backend-based, therefore the list of supported formats depends on what backends are currently installed.

See also:
IMediumFormat

Identifier of the default medium format used by VirtualBox.

The medium format set by this attribute is used by VirtualBox when the medium format was not specified explicitly. One example is IVirtualBox::createHardDisk with the empty format argument. A more complex example is implicit creation of differencing media when taking a snapshot of a virtual machine: this operation will try to use a format of the parent medium first and if this format does not support differencing media the default format specified by this argument will be used.

The list of supported medium formats may be obtained by the mediumFormats call. Note that the default medium format must have a capability to create differencing media; otherwise operations that create media implicitly may fail unexpectedly.

The initial value of this property is "VDI" in the current version of the VirtualBox product, but may change in the future.

Note:
Setting this property to null or empty string will restore the initial value.
See also:
mediumFormats, IMediumFormat::id, IVirtualBox::createHardDisk

Issue a warning if the free disk space is below (or in some disk intensive operation is expected to go below) the given size in bytes.

Issue a warning if the free disk space is below (or in some disk intensive operation is expected to go below) the given percentage.

Issue an error if the free disk space is below (or in some disk intensive operation is expected to go below) the given size in bytes.

Issue an error if the free disk space is below (or in some disk intensive operation is expected to go below) the given percentage.

Library that provides authentication for Remote Desktop clients.

The library is used if a virtual machine's authentication type is set to "external" in the VM RemoteDisplay configuration.

The system library extension (".DLL" or ".so") must be omitted. A full path can be specified; if not, then the library must reside on the system's default library path.

The default value of this property is "VBoxAuth". There is a library of that name in one of the default VirtualBox library directories.

For details about VirtualBox authentication libraries and how to implement them, please refer to the VirtualBox manual.

Note:
Setting this property to null or empty string will restore the initial value.

Library that provides authentication for webservice clients.

The library is used if a virtual machine's authentication type is set to "external" in the VM RemoteDisplay configuration and will be called from within the IWebsessionManager::logon implementation.

As opposed to ISystemProperties::VRDEAuthLibrary, there is no per-VM setting for this, as the webservice is a global resource (if it is running). Only for this setting (for the webservice), setting this value to a literal "null" string disables authentication, meaning that IWebsessionManager::logon will always succeed, no matter what user name and password are supplied.

The initial value of this property is "VBoxAuth", meaning that the webservice will use the same authentication library that is used by default for VRDE (again, see ISystemProperties::VRDEAuthLibrary). The format and calling convention of authentication libraries is the same for the webservice as it is for VRDE.

Note:
Setting this property to null or empty string will restore the initial value.

The name of the extension pack providing the default VRDE.

This attribute is for choosing between multiple extension packs providing VRDE. If only one is installed, it will automatically be the default one. The attribute value can be empty if no VRDE extension pack is installed.

For details about VirtualBox Remote Desktop Extension and how to implement one, please refer to the VirtualBox SDK.

attribute unsigned long ISystemProperties::logHistoryCount

This value specifies how many old release log files are kept.

This value hold the default audio driver for the current system.

The path to the autostart database.

Depending on the host this might be a filesystem path or something else.

The path to the default Guest Additions ISO image.

Can be empty if the location is not known in this installation.

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

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

This global setting is overridden by the per-VM attribute IMachine::defaultFrontend or a frontend type passed to IMachine::launchVMProcess.