VirtualBox Main API
Public Member Functions | Public Attributes | List of all members
IHost Interface Reference

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. More...
 
void getProcessorFeature (in ProcessorFeature feature, [retval] out boolean supported)
 Query whether a CPU feature is supported or not. More...
 
void getProcessorDescription (in unsigned long cpuId, [retval] out wstring description)
 Query the model string of a specified host CPU. More...
 
void getProcessorCPUIDLeaf (in unsigned long cpuId, in unsigned long leaf, in unsigned long subLeaf, out unsigned long valEax, out unsigned long valEbx, out unsigned long valEcx, out unsigned long valEdx)
 Returns the CPU cpuid information for the specified leaf. More...
 
void createHostOnlyNetworkInterface (out IHostNetworkInterface hostInterface, [retval] out IProgress progress)
 Creates a new adapter for Host Only Networking. More...
 
void removeHostOnlyNetworkInterface (in wstringUUID id, [retval] out IProgress progress)
 Removes the given Host Only Networking interface. More...
 
void createUSBDeviceFilter (in wstring name, [retval] out IHostUSBDeviceFilter filter)
 Creates a new USB device filter. More...
 
void insertUSBDeviceFilter (in unsigned long position, in IHostUSBDeviceFilter filter)
 Inserts the given USB device to the specified position in the list of filters. More...
 
void removeUSBDeviceFilter (in unsigned long position)
 Removes a USB device filter from the specified position in the list of filters. More...
 
void findHostDVDDrive (in wstring name, [retval] out IMedium drive)
 Searches for a host DVD drive with the given name. More...
 
void findHostFloppyDrive (in wstring name, [retval] out IMedium drive)
 Searches for a host floppy drive with the given name. More...
 
void findHostNetworkInterfaceByName (in wstring name, [retval] out IHostNetworkInterface networkInterface)
 Searches through all host network interfaces for an interface with the given name. More...
 
void findHostNetworkInterfaceById (in wstringUUID id, [retval] out IHostNetworkInterface networkInterface)
 Searches through all host network interfaces for an interface with the given GUID. More...
 
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. More...
 
void findUSBDeviceById (in wstringUUID id, [retval] out IHostUSBDevice device)
 Searches for a USB device with the given UUID. More...
 
void findUSBDeviceByAddress (in wstring name, [retval] out IHostUSBDevice device)
 Searches for a USB device with the given host address. More...
 
void generateMACAddress ([retval] out wstring address)
 Generates a valid Ethernet MAC address, 12 hexadecimal characters. More...
 

Public Attributes

readonly attribute IMedium[] DVDDrives
 List of DVD drives available on the host. More...
 
readonly attribute IMedium[] floppyDrives
 List of floppy drives available on the host. More...
 
readonly attribute IHostUSBDevice[] USBDevices
 List of USB devices currently attached to the host. More...
 
readonly attribute IHostUSBDeviceFilter[] USBDeviceFilters
 List of USB device filters in action. More...
 
readonly attribute IHostNetworkInterface[] networkInterfaces
 List of host network interfaces currently defined on the host. More...
 
readonly attribute wstring[] nameServers
 The list of nameservers registered in host's name resolving system. More...
 
readonly attribute wstring domainName
 Domain name used for name resolving. More...
 
readonly attribute wstring[] searchStrings
 Search string registered for name resolving. More...
 
readonly attribute unsigned long processorCount
 Number of (logical) CPUs installed in the host system. More...
 
readonly attribute unsigned long processorOnlineCount
 Number of (logical) CPUs online in the host system. More...
 
readonly attribute unsigned long processorCoreCount
 Number of physical processor cores installed in the host system. More...
 
readonly attribute unsigned long processorOnlineCoreCount
 Number of physical processor cores online in the host system. More...
 
readonly attribute unsigned long memorySize
 Amount of system memory in megabytes installed in the host system. More...
 
readonly attribute unsigned long memoryAvailable
 Available system memory in the host system. More...
 
readonly attribute wstring operatingSystem
 Name of the host system's operating system. More...
 
readonly attribute wstring OSVersion
 Host operating system's version string. More...
 
readonly attribute long long UTCTime
 Returns the current host time in milliseconds since 1970-01-01 UTC. More...
 
readonly attribute boolean acceleration3DAvailable
 Returns true when the host supports 3D hardware acceleration. More...
 
readonly attribute IHostVideoInputDevice[] videoInputDevices
 List of currently available host video capture devices. More...
 

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:
{AFCA788C-4477-787D-60B2-3FA70E56FBBC}

Member Function Documentation

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
cpuIdIdentifier of the CPU.
speedSpeed value. 0 is returned if value is not known or cpuId is invalid.
void IHost::getProcessorFeature ( in ProcessorFeature  feature,
[retval] out boolean  supported 
)

Query whether a CPU feature is supported or not.

Parameters
featureCPU Feature identifier.
supportedFeature is supported or not.
void IHost::getProcessorDescription ( in unsigned long  cpuId,
[retval] out wstring  description 
)

Query the model string of a specified host CPU.

Parameters
cpuIdIdentifier of the CPU.
descriptionModel 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.
void IHost::getProcessorCPUIDLeaf ( in unsigned long  cpuId,
in unsigned long  leaf,
in unsigned long  subLeaf,
out unsigned long  valEax,
out unsigned long  valEbx,
out unsigned long  valEcx,
out unsigned long  valEdx 
)

Returns the CPU cpuid information for the specified leaf.

Parameters
cpuIdIdentifier of the CPU. The CPU most be online.
leafCPUID leaf index (eax).
subLeafCPUID leaf sub index (ecx). This currently only applies to cache information on Intel CPUs. Use 0 if retrieving values for IMachine::setCPUIDLeaf.
valEaxCPUID leaf value for register eax.
valEbxCPUID leaf value for register ebx.
valEcxCPUID leaf value for register ecx.
valEdxCPUID leaf value for register edx.
Note
The current implementation might not necessarily return the description for this exact CPU.
void IHost::createHostOnlyNetworkInterface ( out IHostNetworkInterface  hostInterface,
[retval] out IProgress  progress 
)

Creates a new adapter for Host Only Networking.

Parameters
hostInterfaceCreated host interface object.
progressProgress object to track the operation completion.
Expected result codes:
E_INVALIDARG Host network interface name already exists.
void IHost::removeHostOnlyNetworkInterface ( in wstringUUID  id,
[retval] out IProgress  progress 
)

Removes the given Host Only Networking interface.

Parameters
idAdapter GUID.
progressProgress object to track the operation completion.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND No host network interface matching id found.
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
nameFilter name. See IUSBDeviceFilter::name for more information.
filterCreated filter object.
See also
USBDeviceFilters
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
positionPosition to insert the filter to.
filterUSB 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
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
positionPosition 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
void IHost::findHostDVDDrive ( in wstring  name,
[retval] out IMedium  drive 
)

Searches for a host DVD drive with the given name.

Parameters
nameName of the host drive to search for
driveFound host drive object
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any host drive.
void IHost::findHostFloppyDrive ( in wstring  name,
[retval] out IMedium  drive 
)

Searches for a host floppy drive with the given name.

Parameters
nameName of the host floppy drive to search for
driveFound host floppy drive object
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any host floppy drive.
void IHost::findHostNetworkInterfaceByName ( in wstring  name,
[retval] out IHostNetworkInterface  networkInterface 
)

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

Parameters
nameName of the host network interface to search for.
networkInterfaceFound host network interface object.
Note
The method returns an error if the given name does not correspond to any host network interface.
void IHost::findHostNetworkInterfaceById ( in wstringUUID  id,
[retval] out IHostNetworkInterface  networkInterface 
)

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

Parameters
idGUID of the host network interface to search for.
networkInterfaceFound host network interface object.
Note
The method returns an error if the given GUID does not correspond to any host network interface.
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
typetype of the host network interfaces to search for.
networkInterfacesFound host network interface objects.
void IHost::findUSBDeviceById ( in wstringUUID  id,
[retval] out IHostUSBDevice  device 
)

Searches for a USB device with the given UUID.

Parameters
idUUID of the USB device to search for.
deviceFound USB device object.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Given id does not correspond to any USB device.
See also
IUSBDevice::id
void IHost::findUSBDeviceByAddress ( in wstring  name,
[retval] out IHostUSBDevice  device 
)

Searches for a USB device with the given host address.

Parameters
nameAddress of the USB device (as assigned by the host) to search for.
deviceFound USB device object.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Given name does not correspond to any USB device.
See also
IUSBDevice::address
void IHost::generateMACAddress ( [retval] out wstring  address)

Generates a valid Ethernet MAC address, 12 hexadecimal characters.

Parameters
addressNew Ethernet MAC address.

Member Data Documentation

readonly attribute IMedium [] IHost::DVDDrives

List of DVD drives available on the host.

readonly attribute IMedium [] IHost::floppyDrives

List of floppy drives available on the host.

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.
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
readonly attribute IHostNetworkInterface [] IHost::networkInterfaces

List of host network interfaces currently defined on the host.

readonly attribute wstring [] IHost::nameServers

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

readonly attribute wstring IHost::domainName

Domain name used for name resolving.

readonly attribute wstring [] IHost::searchStrings

Search string registered for name resolving.

readonly attribute unsigned long IHost::processorCount

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

readonly attribute unsigned long IHost::processorOnlineCount

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

readonly attribute unsigned long IHost::processorCoreCount

Number of physical processor cores installed in the host system.

readonly attribute unsigned long IHost::processorOnlineCoreCount

Number of physical processor cores online in the host system.

readonly attribute unsigned long IHost::memorySize

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

readonly attribute unsigned long IHost::memoryAvailable

Available system memory in the host system.

readonly attribute wstring IHost::operatingSystem

Name of the host system's operating system.

readonly attribute wstring IHost::OSVersion

Host operating system's version string.

readonly attribute long long IHost::UTCTime

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

readonly attribute boolean IHost::acceleration3DAvailable

Returns true when the host supports 3D hardware acceleration.

readonly attribute IHostVideoInputDevice [] IHost::videoInputDevices

List of currently available host video capture devices.