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...
void | addUSBDeviceSource (in wstring backend, in wstring id, in wstring address, in wstring[] propertyNames, in wstring[] propertyValues)
| Adds a new USB device source. More...
void | removeUSBDeviceSource (in wstring id)
| Removes a previously added USB device source. 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

## ◆ 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.

## ◆ getProcessorCPUIDLeaf()

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

  cpuId | Identifier of the CPU. The CPU most be online.
  leaf | CPUID leaf index (eax).
  subLeaf | CPUID leaf sub index (ecx). This currently only applies to cache information on Intel CPUs. Use 0 if retrieving values for IMachine::setCPUIDLeaf.
  valEax | CPUID leaf value for register eax.
  valEbx | CPUID leaf value for register ebx.
  valEcx | CPUID leaf value for register ecx.
  valEdx | CPUID leaf value for register edx.

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.

## Member Data Documentation

## ◆ 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.

## ◆ 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.

## ◆ 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.

## ◆ acceleration3DAvailable

readonly attribute boolean IHost::acceleration3DAvailable

Returns `true` when the host supports 3D hardware acceleration.

## ◆ videoInputDevices

readonly attribute IHostVideoInputDevice [] IHost::videoInputDevices

List of currently available host video capture devices.