The IHost interface represents the physical machine that this VirtualBox installation runs on. More...

Inheritance diagram for IHost:

Public Member Functions
void	getProcessorSpeed (in unsigned long cpuId, [retval] out unsigned long speed)
	Query the (approximate) maximum speed of a specified host CPU in Megahertz.

void	getProcessorFeature (in ProcessorFeature feature, [retval] out boolean supported)
	Query whether a CPU feature is supported or not.

void	getProcessorDescription (in unsigned long cpuId, [retval] out wstring description)
	Query the model string of a specified host CPU.

void	createHostOnlyNetworkInterface (out IHostNetworkInterface hostInterface, [retval] out IProgress progress)
	Creates a new adapter for Host Only Networking.

void	removeHostOnlyNetworkInterface (in wstringUUID id, [retval] out IProgress progress)
	Removes the given Host Only Networking interface.

void	createUSBDeviceFilter (in wstring name, [retval] out IHostUSBDeviceFilter filter)
	Creates a new USB device filter.

void	insertUSBDeviceFilter (in unsigned long position, in IHostUSBDeviceFilter filter)
	Inserts the given USB device to the specified position in the list of filters.

void	removeUSBDeviceFilter (in unsigned long position)
	Removes a USB device filter from the specified position in the list of filters.

void	findHostDVDDrive (in wstring name, [retval] out IMedium drive)
	Searches for a host DVD drive with the given `name`.

void	findHostFloppyDrive (in wstring name, [retval] out IMedium drive)
	Searches for a host floppy drive with the given `name`.

void	findHostNetworkInterfaceByName (in wstring name, [retval] out IHostNetworkInterface networkInterface)
	Searches through all host network interfaces for an interface with the given `name`.

void	findHostNetworkInterfaceById (in wstringUUID id, [retval] out IHostNetworkInterface networkInterface)
	Searches through all host network interfaces for an interface with the given GUID.

void	findHostNetworkInterfacesOfType (in HostNetworkInterfaceType type, [retval] out IHostNetworkInterface[] networkInterfaces)
	Searches through all host network interfaces and returns a list of interfaces of the specified type.

void	findUSBDeviceById (in wstringUUID id, [retval] out IHostUSBDevice device)
	Searches for a USB device with the given UUID.

void	findUSBDeviceByAddress (in wstring name, [retval] out IHostUSBDevice device)
	Searches for a USB device with the given host address.

void	generateMACAddress ([retval] out wstring address)
	Generates a valid Ethernet MAC address, 12 hexadecimal characters.

void	addUSBDeviceSource (in wstring backend, in wstring id, in wstring address, in wstring[] propertyNames, in wstring[] propertyValues)
	Adds a new USB device source.

void	removeUSBDeviceSource (in wstring id)
	Removes a previously added USB device source.

void	isExecutionEngineSupported (in CPUArchitecture cpuArchitecture, in VMExecutionEngine executionEngine, [retval] out boolean isSupported)
	Returns whether the given execution engine is supported on the host.

Public Attributes
readonly attribute PlatformArchitecture	architecture
	Platform architecture type.

readonly attribute IHostX86	x86
	Associated object for x86 host specifics.

readonly attribute IMedium[]	DVDDrives
	List of DVD drives available on the host.

readonly attribute IMedium[]	floppyDrives
	List of floppy drives available on the host.

readonly attribute IHostAudioDevice[]	audioDevices
	List of audio devices currently available on the host.

readonly attribute IHostUSBDevice[]	USBDevices
	List of USB devices currently attached to the host.

readonly attribute IHostUSBDeviceFilter[]	USBDeviceFilters
	List of USB device filters in action.

readonly attribute IHostNetworkInterface[]	networkInterfaces
	List of host network interfaces currently defined on the host.

readonly attribute wstring[]	nameServers
	The list of nameservers registered in host's name resolving system.

readonly attribute wstring	domainName
	Domain name used for name resolving.

readonly attribute wstring[]	searchStrings
	Search string registered for name resolving.

readonly attribute unsigned long	processorCount
	Number of (logical) CPUs installed in the host system.

readonly attribute unsigned long	processorOnlineCount
	Number of (logical) CPUs online in the host system.

readonly attribute unsigned long	processorCoreCount
	Number of physical processor cores installed in the host system.

readonly attribute unsigned long	processorOnlineCoreCount
	Number of physical processor cores online in the host system.

readonly attribute IHostDrive[]	hostDrives
	List of the host drive available to use in the VirtualBox.

readonly attribute unsigned long	memorySize
	Amount of system memory in megabytes installed in the host system.

readonly attribute unsigned long	memoryAvailable
	Available system memory in the host system.

readonly attribute wstring	operatingSystem
	Name of the host system's operating system.

readonly attribute wstring	OSVersion
	Host operating system's version string.

readonly attribute long long	UTCTime
	Returns the current host time in milliseconds since 1970-01-01 UTC.

readonly attribute IHostVideoInputDevice[]	videoInputDevices
	List of currently available host video capture devices.

readonly attribute IUpdateAgent	updateHost
	Checks for new VirtualBox host versions.

readonly attribute IUpdateAgent	updateExtPack
	Checks for new VirtualBox Extension Pack versions.

readonly attribute IUpdateAgent	updateGuestAdditions
	Checks for new Guest Additions versions.

Detailed Description

The IHost interface represents the physical machine that this VirtualBox installation runs on.

An object implementing this interface is returned by the IVirtualBox::host attribute. This interface contains read-only information about the host's physical hardware (such as what processors and disks are available, what the host operating system is, and so on) and also allows for manipulating some of the host's hardware, such as global USB device filters and host interface networking.

Interface ID:: {D5DCECE0-B202-4416-A138-03502784CC07}

Member Function Documentation

◆ getProcessorSpeed()

void IHost::getProcessorSpeed	(	in unsigned long	cpuId,
		[retval] out unsigned long	speed
	)

Query the (approximate) maximum speed of a specified host CPU in Megahertz.

Parameters

cpuId	Identifier of the CPU.
speed	Speed value. 0 is returned if value is not known or cpuId is invalid.

◆ getProcessorFeature()

void IHost::getProcessorFeature	(	in ProcessorFeature	feature,
		[retval] out boolean	supported
	)

Query whether a CPU feature is supported or not.

Parameters

feature	CPU Feature identifier.
supported	Feature is supported or not.

◆ getProcessorDescription()

void IHost::getProcessorDescription	(	in unsigned long	cpuId,
		[retval] out wstring	description
	)

Query the model string of a specified host CPU.

Parameters

cpuId	Identifier of the CPU.
description	Model string. An empty string is returned if value is not known or cpuId is invalid.

Note: The current implementation might not necessarily return the description for this exact CPU.

◆ createHostOnlyNetworkInterface()

void IHost::createHostOnlyNetworkInterface	(	out IHostNetworkInterface	hostInterface,
		[retval] out IProgress	progress
	)

Creates a new adapter for Host Only Networking.

Parameters

hostInterface	Created host interface object.
progress	Progress object to track the operation completion.

Expected result codes:

E_INVALIDARG

Host network interface name already exists.

◆ removeHostOnlyNetworkInterface()

void IHost::removeHostOnlyNetworkInterface	(	in wstringUUID	id,
		[retval] out IProgress	progress
	)

Removes the given Host Only Networking interface.

Parameters

id	Adapter GUID.
progress	Progress object to track the operation completion.

Expected result codes:

VBOX_E_OBJECT_NOT_FOUND

No host network interface matching id found.

◆ createUSBDeviceFilter()

void IHost::createUSBDeviceFilter	(	in wstring	name,
		[retval] out IHostUSBDeviceFilter	filter
	)

Creates a new USB device filter.

All attributes except the filter name are set to empty (any match), active is false (the filter is not active).

The created filter can be added to the list of filters using insertUSBDeviceFilter.

Parameters

name	Filter name. See IUSBDeviceFilter::name for more information.
filter	Created filter object.

See also: USBDeviceFilters

◆ insertUSBDeviceFilter()

void IHost::insertUSBDeviceFilter	(	in unsigned long	position,
		in IHostUSBDeviceFilter	filter
	)

Inserts the given USB device to the specified position in the list of filters.

Positions are numbered starting from 0. If the specified position is equal to or greater than the number of elements in the list, the filter is added at the end of the collection.

Parameters

position	Position to insert the filter to.
filter	USB device filter to insert.

Expected result codes:

VBOX_E_INVALID_OBJECT_STATE	USB device filter is not created within this VirtualBox instance.
E_INVALIDARG	USB device filter already in list.

Note: Duplicates are not allowed, so an attempt to insert a filter already in the list is an error.; If USB functionality is not available in the given edition of VirtualBox, this method will set the result code to E_NOTIMPL.

See also: USBDeviceFilters

◆ removeUSBDeviceFilter()

void IHost::removeUSBDeviceFilter ( in unsigned long position )

Removes a USB device filter from the specified position in the list of filters.

Positions are numbered starting from 0. Specifying a position equal to or greater than the number of elements in the list will produce an error.

Parameters

position Position to remove the filter from.

Expected result codes:

E_INVALIDARG

USB device filter list empty or invalid position.

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

See also: USBDeviceFilters

◆ findHostDVDDrive()

void IHost::findHostDVDDrive	(	in wstring	name,
		[retval] out IMedium	drive
	)

Searches for a host DVD drive with the given name.

Parameters

name	Name of the host drive to search for
drive	Found host drive object

Expected result codes:

VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any host drive.

◆ findHostFloppyDrive()

void IHost::findHostFloppyDrive	(	in wstring	name,
		[retval] out IMedium	drive
	)

Searches for a host floppy drive with the given name.

Parameters

name	Name of the host floppy drive to search for
drive	Found host floppy drive object

Expected result codes:

VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any host floppy drive.

◆ findHostNetworkInterfaceByName()

void IHost::findHostNetworkInterfaceByName	(	in wstring	name,
		[retval] out IHostNetworkInterface	networkInterface
	)

Searches through all host network interfaces for an interface with the given name.

Parameters

name	Name of the host network interface to search for.
networkInterface	Found host network interface object.

Note: The method returns an error if the given name does not correspond to any host network interface.

◆ findHostNetworkInterfaceById()

void IHost::findHostNetworkInterfaceById	(	in wstringUUID	id,
		[retval] out IHostNetworkInterface	networkInterface
	)

Searches through all host network interfaces for an interface with the given GUID.

Parameters

id	GUID of the host network interface to search for.
networkInterface	Found host network interface object.

Note: The method returns an error if the given GUID does not correspond to any host network interface.

◆ findHostNetworkInterfacesOfType()

void IHost::findHostNetworkInterfacesOfType	(	in HostNetworkInterfaceType	type,
		[retval] out IHostNetworkInterface[]	networkInterfaces
	)

Searches through all host network interfaces and returns a list of interfaces of the specified type.

Parameters

type	type of the host network interfaces to search for.
networkInterfaces	Found host network interface objects.

◆ findUSBDeviceById()

void IHost::findUSBDeviceById	(	in wstringUUID	id,
		[retval] out IHostUSBDevice	device
	)

Searches for a USB device with the given UUID.

Parameters

id	UUID of the USB device to search for.
device	Found USB device object.

Expected result codes:

VBOX_E_OBJECT_NOT_FOUND Given id does not correspond to any USB device.

See also: IUSBDevice::id

◆ findUSBDeviceByAddress()

void IHost::findUSBDeviceByAddress	(	in wstring	name,
		[retval] out IHostUSBDevice	device
	)

Searches for a USB device with the given host address.

Parameters

name	Address of the USB device (as assigned by the host) to search for.
device	Found USB device object.

Expected result codes:

VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any USB device.

See also: IUSBDevice::address

◆ generateMACAddress()

void IHost::generateMACAddress ( [retval] out wstring address )

Generates a valid Ethernet MAC address, 12 hexadecimal characters.

Parameters

address New Ethernet MAC address.

◆ addUSBDeviceSource()

void IHost::addUSBDeviceSource	(	in wstring	backend,
		in wstring	id,
		in wstring	address,
		in wstring[]	propertyNames,
		in wstring[]	propertyValues
	)

Adds a new USB device source.

Parameters

backend	The backend to use as the new device source.
id	Unique ID to identify the source.
address	Address to use, the format is dependent on the backend. For USB/IP backends for example the notation is host[:port].
propertyNames	Array of property names for more detailed configuration. Not used at the moment.
propertyValues	Array of property values for more detailed configuration. Not used at the moment.

◆ removeUSBDeviceSource()

void IHost::removeUSBDeviceSource ( in wstring id )

Removes a previously added USB device source.

Parameters

id	The identifier used when the source was added.

◆ isExecutionEngineSupported()

void IHost::isExecutionEngineSupported	(	in CPUArchitecture	cpuArchitecture,
		in VMExecutionEngine	executionEngine,
		[retval] out boolean	isSupported
	)

Returns whether the given execution engine is supported on the host.

This is primarily to check whether the native API is supported (think of Hyper-V not being available due to not running in a Hyper-V root partition).

Parameters

cpuArchitecture	The guest CPU architecture to check the execution engine for.
executionEngine	The execution engine to check.
isSupported	Flag indicating whether the given execution engine is supported on the host.

Member Data Documentation

◆ architecture

readonly attribute PlatformArchitecture IHost::architecture

Platform architecture type.

◆ x86

readonly attribute IHostX86 IHost::x86

Associated object for x86 host specifics.

◆ DVDDrives

readonly attribute IMedium [] IHost::DVDDrives

List of DVD drives available on the host.

◆ floppyDrives

readonly attribute IMedium [] IHost::floppyDrives

List of floppy drives available on the host.

◆ audioDevices

readonly attribute IHostAudioDevice [] IHost::audioDevices

List of audio devices currently available on the host.

Expected result codes:

E_NOTIMPL

This attribute is not implemented yet.

◆ USBDevices

readonly attribute IHostUSBDevice [] IHost::USBDevices

List of USB devices currently attached to the host.

Once a new device is physically attached to the host computer, it appears in this list and remains there until detached.

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

◆ USBDeviceFilters

readonly attribute IHostUSBDeviceFilter [] IHost::USBDeviceFilters

List of USB device filters in action.

When a new device is physically attached to the host computer, filters from this list are applied to it (in order they are stored in the list). The first matched filter will determine the action performed on the device.

Unless the device is ignored by these filters, filters of all currently running virtual machines (IUSBDeviceFilters::deviceFilters) are applied to it.

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

See also: IHostUSBDeviceFilter, USBDeviceState

◆ networkInterfaces

readonly attribute IHostNetworkInterface [] IHost::networkInterfaces

List of host network interfaces currently defined on the host.

◆ nameServers

readonly attribute wstring [] IHost::nameServers

The list of nameservers registered in host's name resolving system.

◆ domainName

readonly attribute wstring IHost::domainName

Domain name used for name resolving.

◆ searchStrings

readonly attribute wstring [] IHost::searchStrings

Search string registered for name resolving.

◆ processorCount

readonly attribute unsigned long IHost::processorCount

Number of (logical) CPUs installed in the host system.

◆ processorOnlineCount

readonly attribute unsigned long IHost::processorOnlineCount

Number of (logical) CPUs online in the host system.

◆ processorCoreCount

readonly attribute unsigned long IHost::processorCoreCount

Number of physical processor cores installed in the host system.

◆ processorOnlineCoreCount

readonly attribute unsigned long IHost::processorOnlineCoreCount

Number of physical processor cores online in the host system.

◆ hostDrives

readonly attribute IHostDrive [] IHost::hostDrives

List of the host drive available to use in the VirtualBox.

◆ memorySize

readonly attribute unsigned long IHost::memorySize

Amount of system memory in megabytes installed in the host system.

◆ memoryAvailable

readonly attribute unsigned long IHost::memoryAvailable

Available system memory in the host system.

◆ operatingSystem

readonly attribute wstring IHost::operatingSystem

Name of the host system's operating system.

◆ OSVersion

readonly attribute wstring IHost::OSVersion

Host operating system's version string.

◆ UTCTime

readonly attribute long long IHost::UTCTime

Returns the current host time in milliseconds since 1970-01-01 UTC.

◆ videoInputDevices

readonly attribute IHostVideoInputDevice [] IHost::videoInputDevices

List of currently available host video capture devices.

◆ updateHost

readonly attribute IUpdateAgent IHost::updateHost

Checks for new VirtualBox host versions.

◆ updateExtPack

readonly attribute IUpdateAgent IHost::updateExtPack

Checks for new VirtualBox Extension Pack versions.

◆ updateGuestAdditions

readonly attribute IUpdateAgent IHost::updateGuestAdditions

Checks for new Guest Additions versions.

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ getProcessorSpeed()

◆ getProcessorFeature()

◆ getProcessorDescription()

◆ createHostOnlyNetworkInterface()

◆ removeHostOnlyNetworkInterface()

◆ createUSBDeviceFilter()

◆ insertUSBDeviceFilter()

◆ removeUSBDeviceFilter()

◆ findHostDVDDrive()

◆ findHostFloppyDrive()

◆ findHostNetworkInterfaceByName()

◆ findHostNetworkInterfaceById()

◆ findHostNetworkInterfacesOfType()

◆ findUSBDeviceById()

◆ findUSBDeviceByAddress()

◆ generateMACAddress()

◆ addUSBDeviceSource()

◆ removeUSBDeviceSource()

◆ isExecutionEngineSupported()

Member Data Documentation

◆ architecture

◆ x86

◆ DVDDrives

◆ floppyDrives

◆ audioDevices

◆ USBDevices

◆ USBDeviceFilters

◆ networkInterfaces

◆ nameServers

◆ domainName

◆ searchStrings

◆ processorCount

◆ processorOnlineCount

◆ processorCoreCount

◆ processorOnlineCoreCount

◆ hostDrives

◆ memorySize

◆ memoryAvailable

◆ operatingSystem

◆ OSVersion

◆ UTCTime

◆ videoInputDevices

◆ updateHost

◆ updateExtPack

◆ updateGuestAdditions