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

Inheritance diagram for ISystemProperties:

Public Member Functions
void	getDefaultIoCacheSettingForStorageController (in StorageControllerType controllerType, [retval] out boolean enabled)
	Returns the default I/O cache setting for the given storage controller.

void	getCPUProfiles (in CPUArchitecture architecture, in wstring namePattern, [retval] out ICPUProfile[] profiles)
	Returns CPU profiles matching the given criteria.

void	getExecutionEnginesForVmCpuArchitecture (in CPUArchitecture cpuArchitecture, [retval] out VMExecutionEngine[] executionEngine)
	Returns the possible VMExecutionEngine enum values for a given VM CPU architecture.

Public Attributes
readonly attribute IPlatformProperties	platform
	Platform properties of the VirtualBox installation.

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.

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 wstring	defaultCryptoExtPack
	The name of the extension pack providing the default cryptographic support for full VM encryption.

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.

readonly attribute BitmapFormat[]	screenShotFormats
	Supported bitmap formats which can be used with takeScreenShot and takeScreenShotToArray methods.

attribute ProxyMode	proxyMode
	The proxy mode setting: System, NoProxy or Manual.

attribute wstring	proxyURL
	Proxy server URL for the ProxyMode_Manual proxy mode.

readonly attribute PlatformArchitecture[]	supportedPlatformArchitectures
	Returns an array of officially supported values for enum PlatformArchitecture, in the sense of what is e.g.

readonly attribute ClipboardMode[]	supportedClipboardModes
	Returns an array of officially supported values for enum ClipboardMode, in the sense of what is e.g.

readonly attribute DnDMode[]	supportedDnDModes
	Returns an array of officially supported values for enum DnDMode, in the sense of what is e.g.

readonly attribute PointingHIDType[]	supportedPointingHIDTypes
	Returns an array of officially supported values for enum PointingHIDType, in the sense of what is e.g.

readonly attribute KeyboardHIDType[]	supportedKeyboardHIDTypes
	Returns an array of officially supported values for enum KeyboardHIDType, in the sense of what is e.g.

readonly attribute VFSType[]	supportedVFSTypes
	Returns an array of officially supported values for enum VFSType, in the sense of what is e.g.

readonly attribute ImportOptions[]	supportedImportOptions
	Returns an array of officially supported values for enum ImportOptions, in the sense of what is e.g.

readonly attribute ExportOptions[]	supportedExportOptions
	Returns an array of officially supported values for enum ExportOptions, in the sense of what is e.g.

readonly attribute GraphicsFeature[]	supportedGraphicsFeatures
	Returns an array of officially supported values for enum GraphicsFeature on the host side.

readonly attribute RecordingFeature[]	supportedRecordingFeatures
	Returns an array of officially supported values for enum RecordingFeature, in the sense of what is e.g.

readonly attribute RecordingAudioCodec[]	supportedRecordingAudioCodecs
	Returns an array of officially supported values for enum RecordingAudioCodec, in the sense of what is e.g.

readonly attribute RecordingVideoCodec[]	supportedRecordingVideoCodecs
	Returns an array of officially supported values for enum RecordingVideoCodec, in the sense of what is e.g.

readonly attribute RecordingVideoScalingMode[]	supportedRecordingVSModes
	Returns an array of officially supported values for enum RecordingVideoScalingMode, in the sense of what is e.g.

readonly attribute RecordingRateControlMode[]	supportedRecordingARCModes
	Returns an array of officially supported audio codec values for enum RecordingRateControlMode, in the sense of what is e.g.

readonly attribute RecordingRateControlMode[]	supportedRecordingVRCModes
	Returns an array of officially supported video codec values for enum RecordingRateControlMode, in the sense of what is e.g.

readonly attribute CloneOptions[]	supportedCloneOptions
	Returns an array of officially supported values for enum CloneOptions, in the sense of what is e.g.

readonly attribute AutostopType[]	supportedAutostopTypes
	Returns an array of officially supported values for enum AutostopType, in the sense of what is e.g.

readonly attribute VMProcPriority[]	supportedVMProcPriorities
	Returns an array of officially supported values for enum VMProcPriority, in the sense of what is e.g.

readonly attribute NetworkAttachmentType[]	supportedNetworkAttachmentTypes
	Returns an array of officially supported values for enum NetworkAttachmentType, in the sense of what is e.g.

readonly attribute PortMode[]	supportedPortModes
	Returns an array of officially supported values for enum PortMode, in the sense of what is e.g.

readonly attribute AudioDriverType[]	supportedAudioDriverTypes
	Returns an array of officially supported values for enum AudioDriverType, in the sense of what is e.g.

attribute wstring	languageId
	The API language ID used to translate messages to client.

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:: {925084B0-625F-422F-A67D-0EDE1880A56C}

Member Function Documentation

◆ getDefaultIoCacheSettingForStorageController()

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 type to get the setting for.
enabled	Returned flag indicating the default value

◆ getCPUProfiles()

void ISystemProperties::getCPUProfiles	(	in CPUArchitecture	architecture,
		in wstring	namePattern,
		[retval] out ICPUProfile[]	profiles
	)

Returns CPU profiles matching the given criteria.

Parameters

architecture	The architecture to get profiles for. Required.
namePattern	Name pattern. Simple wildcard matching using asterisk (*) and question mark (?).
profiles	The matching CPU profiles.

◆ getExecutionEnginesForVmCpuArchitecture()

void ISystemProperties::getExecutionEnginesForVmCpuArchitecture	(	in CPUArchitecture	cpuArchitecture,
		[retval] out VMExecutionEngine[]	executionEngine
	)

Returns the possible VMExecutionEngine enum values for a given VM CPU architecture.

Parameters

cpuArchitecture	The CPU architecture type to get the values for.
executionEngine	The enum values (sorted by what should be a sensible decreasing importance of the type) which are valid.

Member Data Documentation

◆ platform

readonly attribute IPlatformProperties ISystemProperties::platform

Platform properties of the VirtualBox installation.

◆ minGuestRAM

readonly attribute unsigned long ISystemProperties::minGuestRAM

Minimum guest system memory in Megabytes.

◆ maxGuestRAM

readonly attribute unsigned long ISystemProperties::maxGuestRAM

Maximum guest system memory in Megabytes.

◆ minGuestVRAM

readonly attribute unsigned long ISystemProperties::minGuestVRAM

Minimum guest video memory in Megabytes.

◆ maxGuestVRAM

readonly attribute unsigned long ISystemProperties::maxGuestVRAM

Maximum guest video memory in Megabytes.

◆ minGuestCPUCount

readonly attribute unsigned long ISystemProperties::minGuestCPUCount

Minimum CPU count.

◆ maxGuestCPUCount

readonly attribute unsigned long ISystemProperties::maxGuestCPUCount

Maximum CPU count.

◆ maxGuestMonitors

readonly attribute unsigned long ISystemProperties::maxGuestMonitors

Maximum of monitors which could be connected.

◆ infoVDSize

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.

◆ defaultMachineFolder

attribute wstring ISystemProperties::defaultMachineFolder

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

◆ loggingLevel

attribute wstring ISystemProperties::loggingLevel

Specifies the logging level in current use by VirtualBox.

◆ mediumFormats

readonly attribute IMediumFormat [] ISystemProperties::mediumFormats

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

◆ defaultHardDiskFormat

attribute wstring ISystemProperties::defaultHardDiskFormat

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

◆ freeDiskSpaceWarning

attribute long long ISystemProperties::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.

◆ freeDiskSpacePercentWarning

attribute unsigned long ISystemProperties::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.

◆ freeDiskSpaceError

attribute long long ISystemProperties::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.

◆ freeDiskSpacePercentError

attribute unsigned long ISystemProperties::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.

◆ VRDEAuthLibrary

attribute wstring ISystemProperties::VRDEAuthLibrary

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.

◆ webServiceAuthLibrary

attribute wstring ISystemProperties::webServiceAuthLibrary

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.

◆ defaultVRDEExtPack

attribute wstring ISystemProperties::defaultVRDEExtPack

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.

◆ defaultCryptoExtPack

attribute wstring ISystemProperties::defaultCryptoExtPack

The name of the extension pack providing the default cryptographic support for full VM encryption.

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

◆ logHistoryCount

attribute unsigned long ISystemProperties::logHistoryCount

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

◆ defaultAudioDriver

readonly attribute AudioDriverType ISystemProperties::defaultAudioDriver

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

◆ autostartDatabasePath

attribute wstring ISystemProperties::autostartDatabasePath

The path to the autostart database.

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

◆ defaultAdditionsISO

attribute wstring ISystemProperties::defaultAdditionsISO

The path to the default Guest Additions ISO image.

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

◆ defaultFrontend

attribute wstring ISystemProperties::defaultFrontend

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.

◆ screenShotFormats

readonly attribute BitmapFormat [] ISystemProperties::screenShotFormats

Supported bitmap formats which can be used with takeScreenShot and takeScreenShotToArray methods.

◆ proxyMode

attribute ProxyMode ISystemProperties::proxyMode

The proxy mode setting: System, NoProxy or Manual.

◆ proxyURL

attribute wstring ISystemProperties::proxyURL

Proxy server URL for the ProxyMode_Manual proxy mode.

The format is: [{type}"://"][{userid}[:{password}]@]{server}[":"{port}]

Valid types are: http (default), https, socks4, socks4a, socks5, socks5h and direct. Please note that these are proxy types defining how the proxy operates rather than how to proxy any similarly named protocol (i.e. don't confuse a http-proxy with proxying the http protocol, as a http-proxy usually can proxy https and other protocols too).

The port number defaults to 80 for http, 443 for https and 1080 for the socks ones.

An empty string will cause the behavior to be identical to ProxyMode_System. For compatibility with libproxy, an URL starting with "direct://" will cause ProxyMode_NoProxy behavior.

Note: The password is currently stored as plain text! Use the ProxyMode_System mode if you consider the proxy password to be sensitive.

◆ supportedPlatformArchitectures

readonly attribute PlatformArchitecture [] ISystemProperties::supportedPlatformArchitectures

Returns an array of officially supported values for enum PlatformArchitecture, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedClipboardModes

readonly attribute ClipboardMode [] ISystemProperties::supportedClipboardModes

Returns an array of officially supported values for enum ClipboardMode, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedDnDModes

readonly attribute DnDMode [] ISystemProperties::supportedDnDModes

Returns an array of officially supported values for enum DnDMode, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedPointingHIDTypes

readonly attribute PointingHIDType [] ISystemProperties::supportedPointingHIDTypes

Returns an array of officially supported values for enum PointingHIDType, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedKeyboardHIDTypes

readonly attribute KeyboardHIDType [] ISystemProperties::supportedKeyboardHIDTypes

Returns an array of officially supported values for enum KeyboardHIDType, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedVFSTypes

readonly attribute VFSType [] ISystemProperties::supportedVFSTypes

Returns an array of officially supported values for enum VFSType, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedImportOptions

readonly attribute ImportOptions [] ISystemProperties::supportedImportOptions

Returns an array of officially supported values for enum ImportOptions, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedExportOptions

readonly attribute ExportOptions [] ISystemProperties::supportedExportOptions

Returns an array of officially supported values for enum ExportOptions, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedGraphicsFeatures

readonly attribute GraphicsFeature [] ISystemProperties::supportedGraphicsFeatures

Returns an array of officially supported values for enum GraphicsFeature on the host side.

For querying supported features of a specific graphics controller, use IPlatformProperties::getSupportedGfxFeaturesForType.

◆ supportedRecordingFeatures

readonly attribute RecordingFeature [] ISystemProperties::supportedRecordingFeatures

Returns an array of officially supported values for enum RecordingFeature, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedRecordingAudioCodecs

readonly attribute RecordingAudioCodec [] ISystemProperties::supportedRecordingAudioCodecs

Returns an array of officially supported values for enum RecordingAudioCodec, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedRecordingVideoCodecs

readonly attribute RecordingVideoCodec [] ISystemProperties::supportedRecordingVideoCodecs

Returns an array of officially supported values for enum RecordingVideoCodec, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedRecordingVSModes

readonly attribute RecordingVideoScalingMode [] ISystemProperties::supportedRecordingVSModes

Returns an array of officially supported values for enum RecordingVideoScalingMode, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedRecordingARCModes

readonly attribute RecordingRateControlMode [] ISystemProperties::supportedRecordingARCModes

Returns an array of officially supported audio codec values for enum RecordingRateControlMode, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedRecordingVRCModes

readonly attribute RecordingRateControlMode [] ISystemProperties::supportedRecordingVRCModes

Returns an array of officially supported video codec values for enum RecordingRateControlMode, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedCloneOptions

readonly attribute CloneOptions [] ISystemProperties::supportedCloneOptions

Returns an array of officially supported values for enum CloneOptions, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedAutostopTypes

readonly attribute AutostopType [] ISystemProperties::supportedAutostopTypes

Returns an array of officially supported values for enum AutostopType, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedVMProcPriorities

readonly attribute VMProcPriority [] ISystemProperties::supportedVMProcPriorities

Returns an array of officially supported values for enum VMProcPriority, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedNetworkAttachmentTypes

readonly attribute NetworkAttachmentType [] ISystemProperties::supportedNetworkAttachmentTypes

Returns an array of officially supported values for enum NetworkAttachmentType, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedPortModes

readonly attribute PortMode [] ISystemProperties::supportedPortModes

Returns an array of officially supported values for enum PortMode, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ supportedAudioDriverTypes

readonly attribute AudioDriverType [] ISystemProperties::supportedAudioDriverTypes

Returns an array of officially supported values for enum AudioDriverType, in the sense of what is e.g.

worth offering in the VirtualBox GUI.

◆ languageId

attribute wstring ISystemProperties::languageId

The API language ID used to translate messages to client.

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ getDefaultIoCacheSettingForStorageController()

◆ getCPUProfiles()

◆ getExecutionEnginesForVmCpuArchitecture()

Member Data Documentation

◆ platform

◆ minGuestRAM

◆ maxGuestRAM

◆ minGuestVRAM

◆ maxGuestVRAM

◆ minGuestCPUCount

◆ maxGuestCPUCount

◆ maxGuestMonitors

◆ infoVDSize

◆ defaultMachineFolder

◆ loggingLevel

◆ mediumFormats

◆ defaultHardDiskFormat

◆ freeDiskSpaceWarning

◆ freeDiskSpacePercentWarning

◆ freeDiskSpaceError

◆ freeDiskSpacePercentError

◆ VRDEAuthLibrary

◆ webServiceAuthLibrary

◆ defaultVRDEExtPack

◆ defaultCryptoExtPack

◆ logHistoryCount

◆ defaultAudioDriver

◆ autostartDatabasePath

◆ defaultAdditionsISO

◆ defaultFrontend

◆ screenShotFormats

◆ proxyMode

◆ proxyURL

◆ supportedPlatformArchitectures

◆ supportedClipboardModes

◆ supportedDnDModes

◆ supportedPointingHIDTypes

◆ supportedKeyboardHIDTypes

◆ supportedVFSTypes

◆ supportedImportOptions

◆ supportedExportOptions

◆ supportedGraphicsFeatures

◆ supportedRecordingFeatures

◆ supportedRecordingAudioCodecs

◆ supportedRecordingVideoCodecs

◆ supportedRecordingVSModes

◆ supportedRecordingARCModes

◆ supportedRecordingVRCModes

◆ supportedCloneOptions

◆ supportedAutostopTypes

◆ supportedVMProcPriorities

◆ supportedNetworkAttachmentTypes

◆ supportedPortModes

◆ supportedAudioDriverTypes

◆ languageId