VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IGuest Interface Reference

The IGuest interface represents information about the operating system running inside the virtual machine. More...

Inheritance diagram for IGuest:

## Public Member Functions
void | internalGetStatistics (out unsigned long cpuUser, out unsigned long cpuKernel, out unsigned long cpuIdle, out unsigned long memTotal, out unsigned long memFree, out unsigned long memBalloon, out unsigned long memShared, out unsigned long memCache, out unsigned long pagedTotal, out unsigned long memAllocTotal, out unsigned long memFreeTotal, out unsigned long memBalloonTotal, out unsigned long memSharedTotal)
| Internal method; do not use as it might change at any time.
void | getFacilityStatus (in AdditionsFacilityType facility, out long long timestamp, [retval] out AdditionsFacilityStatus status)
| Get the current status of a Guest Additions facility.
void | getAdditionsStatus (in AdditionsRunLevelType level, [retval] out boolean active)
| Retrieve the current status of a certain Guest Additions run level.
void | setCredentials (in wstring userName, in wstring password, in wstring domain, in boolean allowInteractiveLogon)
| Store login credentials that can be queried by guest operating systems with Additions installed.
void | createSession (in wstring user, in wstring password, in wstring domain, in wstring sessionName, [retval] out IGuestSession guestSession)
| Creates a new guest session for controlling the guest.
void | findSession (in wstring sessionName, [retval] out IGuestSession[] sessions)
| Finds guest sessions by their friendly name and returns an interface array with all found guest sessions.
void | shutdown (in GuestShutdownFlag[] flags)
| Shuts down (and optionally halts and/or reboots) the guest.
void | updateGuestAdditions (in wstring source, in wstring[] arguments, in AdditionsUpdateFlag[] flags, [retval] out IProgress progress)
| Automatically updates already installed Guest Additions in a VM.

## Public Attributes
readonly attribute wstring | OSTypeId
| Identifier of the Guest OS type as reported by the Guest Additions.
readonly attribute AdditionsRunLevelType | additionsRunLevel
| Current run level of the installed Guest Additions.
readonly attribute wstring | additionsVersion
| Version of the installed Guest Additions in the same format as IVirtualBox::version.
readonly attribute unsigned long | additionsRevision
| The internal build revision number of the installed Guest Additions.
readonly attribute IGuestDnDSource | dnDSource
| Retrieves the drag'n drop source implementation for the guest side, that is, handling and retrieving drag'n drop data from the guest.
readonly attribute IGuestDnDTarget | dnDTarget
| Retrieves the drag'n drop source implementation for the host side.
readonly attribute IEventSource | eventSource
| Event source for guest events.
readonly attribute IAdditionsFacility[] | facilities
| Returns a collection of current known facilities.
readonly attribute IGuestSession[] | sessions
| Returns a collection of all opened guest sessions.
attribute unsigned long | memoryBalloonSize
| Guest system memory balloon size in megabytes (transient property).
attribute unsigned long | statisticsUpdateInterval
| Interval to update guest statistics in seconds.

## Detailed Description

The IGuest interface represents information about the operating system running inside the virtual machine.

Used in IConsole::guest.

IGuest provides information about the guest operating system, whether Guest Additions are installed and other OS-specific virtual machine properties.

Interface ID:
  `{00892186-A4AF-4627-B21F-FC561CE4473C}`

## Member Function Documentation

## ◆ internalGetStatistics()

void IGuest::internalGetStatistics | ( | out unsigned long | cpuUser,
|  | out unsigned long | cpuKernel,
|  | out unsigned long | cpuIdle,
|  | out unsigned long | memTotal,
|  | out unsigned long | memFree,
|  | out unsigned long | memBalloon,
|  | out unsigned long | memShared,
|  | out unsigned long | memCache,
|  | out unsigned long | pagedTotal,
|  | out unsigned long | memAllocTotal,
|  | out unsigned long | memFreeTotal,
|  | out unsigned long | memBalloonTotal,
|  | out unsigned long | memSharedTotal
| ) |  |

Internal method; do not use as it might change at any time.

Parameters

  cpuUser | Percentage of processor time spent in user mode as seen by the guest.
  cpuKernel | Percentage of processor time spent in kernel mode as seen by the guest.
  cpuIdle | Percentage of processor time spent idling as seen by the guest.
  memTotal | Total amount of physical guest RAM.
  memFree | Free amount of physical guest RAM.
  memBalloon | Amount of ballooned physical guest RAM.
  memShared | Amount of shared physical guest RAM.
  memCache | Total amount of guest (disk) cache memory.
  pagedTotal | Total amount of space in the page file.
  memAllocTotal | Total amount of memory allocated by the hypervisor.
  memFreeTotal | Total amount of free memory available in the hypervisor.
  memBalloonTotal | Total amount of memory ballooned by the hypervisor.
  memSharedTotal | Total amount of shared memory in the hypervisor.

## ◆ getFacilityStatus()

void IGuest::getFacilityStatus | ( | in AdditionsFacilityType | facility,
|  | out long long | timestamp,
|  | [retval] out AdditionsFacilityStatus | status
| ) |  |

Get the current status of a Guest Additions facility.

Parameters

  facility | Facility to check status for.
  timestamp | Timestamp (in ms) of last status update seen by the host.
  status | The current (latest) facility status.

## ◆ getAdditionsStatus()

void IGuest::getAdditionsStatus | ( | in AdditionsRunLevelType | level,
|  | [retval] out boolean | active
| ) |  |

Retrieve the current status of a certain Guest Additions run level.

Parameters

  level | Status level to check
  active | Flag whether the status level has been reached or not

Expected result codes:

  VBOX_E_NOT_SUPPORTED | Wrong status level specified.

## ◆ setCredentials()

void IGuest::setCredentials | ( | in wstring | userName,
|  | in wstring | password,
|  | in wstring | domain,
|  | in boolean | allowInteractiveLogon
| ) |  |

Store login credentials that can be queried by guest operating systems with Additions installed.

The credentials are transient to the session and the guest may also choose to erase them. Note that the caller cannot determine whether the guest operating system has queried or made use of the credentials.

Parameters

  userName | User name string, can be empty
  password | Password string, can be empty
  domain | Domain name (guest logon scheme specific), can be empty
  allowInteractiveLogon | Flag whether the guest should alternatively allow the user to interactively specify different credentials. This flag might not be supported by all versions of the Additions.

Expected result codes:

  VBOX_E_VM_ERROR | VMM device is not available.

## ◆ createSession()

void IGuest::createSession | ( | in wstring | user,
|  | in wstring | password,
|  | in wstring | domain,
|  | in wstring | sessionName,
|  | [retval] out IGuestSession | guestSession
| ) |  |

Creates a new guest session for controlling the guest.

The new session will be started asynchronously, meaning on return of this function it is not guaranteed that the guest session is in a started and/or usable state. To wait for successful startup, use the IGuestSession::waitFor call.

A guest session represents one impersonated user account in the guest, so every operation will use the same credentials specified when creating the session object via IGuest::createSession. Anonymous sessions, that is, sessions without specifying a valid user account in the guest are not allowed reasons of security.

There can be a maximum of 32 sessions at once per VM. An error will be returned if this has been reached.

For more information please consult IGuestSession

Parameters

  user | User name this session will be using to control the guest; has to exist and have the appropriate rights to execute programs in the VM. Must not be empty.
  password | Password of the user account to be used. Empty passwords are allowed.
  domain | Domain name of the user account to be used if the guest is part of a domain. Optional. This feature is not implemented yet.
  sessionName | The session's friendly name. Optional, can be empty.
  guestSession | The newly created session object.

Expected result codes:

  VBOX_E_IPRT_ERROR | Error creating guest session.
  VBOX_E_MAXIMUM_REACHED | The maximum of concurrent guest sessions has been reached.

## ◆ findSession()

void IGuest::findSession | ( | in wstring | sessionName,
|  | [retval] out IGuestSession[] | sessions
| ) |  |

Finds guest sessions by their friendly name and returns an interface array with all found guest sessions.

Parameters

  sessionName | The session's friendly name to find. Wildcards like ? and * are allowed.
  sessions | Array with all guest sessions found matching the name specified.

## ◆ shutdown()

void IGuest::shutdown | ( | in GuestShutdownFlag[] | flags | ) |

Shuts down (and optionally halts and/or reboots) the guest.

Needs supported Guest Additions installed.

Parameters

  flags | GuestShutdownFlag flags.

Expected result codes:

  VBOX_E_NOT_SUPPORTED | Guest OS is not supported for shutting down, or the already installed Guest Additions are not supported.
  VBOX_E_IPRT_ERROR | Error while shutting down.

## ◆ updateGuestAdditions()

void IGuest::updateGuestAdditions | ( | in wstring | source,
|  | in wstring[] | arguments,
|  | in AdditionsUpdateFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Automatically updates already installed Guest Additions in a VM.

At the moment only Windows and Linux guests are supported.

Because the VirtualBox Guest Additions drivers are not WHQL-certified yet there might be warning dialogs during the actual Guest Additions update. These need to be confirmed manually in order to continue the installation process. This applies to Windows 2000 and Windows XP guests and therefore these guests can't be updated in a fully automated fashion without user interaction. However, to start a Guest Additions update for the mentioned Windows versions anyway, the flag AdditionsUpdateFlag_WaitForUpdateStartOnly can be specified. See AdditionsUpdateFlag for more information.

The guest needs to be restarted in order to make use of the updated Guest Additions.

Parameters

  source | Path to the Guest Additions .ISO file to use for the update.
  arguments | Optional command line arguments to use for the Guest Additions installer. Useful for retrofitting features which weren't installed before in the guest.
  flags | AdditionsUpdateFlag flags.
  progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_NOT_SUPPORTED | Guest OS is not supported for automated Guest Additions updates or the already installed Guest Additions are not ready yet.
  VBOX_E_IPRT_ERROR | Error while updating.

## Member Data Documentation

## ◆ OSTypeId

readonly attribute wstring IGuest::OSTypeId

Identifier of the Guest OS type as reported by the Guest Additions.

You may use IVirtualBox::getGuestOSType to obtain an IGuestOSType object representing details about the given Guest OS type.

Note
  If Guest Additions are not installed, this value will be the same as IMachine::OSTypeId.

## ◆ additionsRunLevel

readonly attribute AdditionsRunLevelType IGuest::additionsRunLevel

Current run level of the installed Guest Additions.

## ◆ additionsVersion

readonly attribute wstring IGuest::additionsVersion

Version of the installed Guest Additions in the same format as IVirtualBox::version.

## ◆ additionsRevision

readonly attribute unsigned long IGuest::additionsRevision

The internal build revision number of the installed Guest Additions.

See also IVirtualBox::revision.

## ◆ dnDSource

readonly attribute IGuestDnDSource IGuest::dnDSource

Retrieves the drag'n drop source implementation for the guest side, that is, handling and retrieving drag'n drop data from the guest.

## ◆ dnDTarget

readonly attribute IGuestDnDTarget IGuest::dnDTarget

Retrieves the drag'n drop source implementation for the host side.

This will allow the host to handle and initiate a drag'n drop operation to copy data from the host to the guest.

## ◆ eventSource

readonly attribute IEventSource IGuest::eventSource

Event source for guest events.

## ◆ facilities

readonly attribute IAdditionsFacility [] IGuest::facilities

Returns a collection of current known facilities.

Only returns facilities where a status is known, e.g. facilities with an unknown status will not be returned.

## ◆ sessions

readonly attribute IGuestSession [] IGuest::sessions

Returns a collection of all opened guest sessions.

## ◆ memoryBalloonSize

attribute unsigned long IGuest::memoryBalloonSize

Guest system memory balloon size in megabytes (transient property).

## ◆ statisticsUpdateInterval

attribute unsigned long IGuest::statisticsUpdateInterval

Interval to update guest statistics in seconds.