Public Member Functions | Public Attributes

# IGuest Interface Reference

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

List of all members.

## 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 | dragHGEnter (in unsigned long screenId, in unsigned long y, in unsigned long x, in DragAndDropAction defaultAction, in DragAndDropAction[] allowedActions, in wstring[] formats,[retval] out DragAndDropAction resultAction)
| Informs the guest about a Drag and Drop enter event.
void | dragHGMove (in unsigned long screenId, in unsigned long x, in unsigned long y, in DragAndDropAction defaultAction, in DragAndDropAction[] allowedActions, in wstring[] formats,[retval] out DragAndDropAction resultAction)
| Informs the guest about a Drag and Drop move event.
void | dragHGLeave (in unsigned long screenId)
| Informs the guest about a Drag and Drop leave event.
void | dragHGDrop (in unsigned long screenId, in unsigned long x, in unsigned long y, in DragAndDropAction defaultAction, in DragAndDropAction[] allowedActions, in wstring[] formats, out wstring format,[retval] out DragAndDropAction resultAction)
| Informs the guest about a drop event.
void | dragHGPutData (in unsigned long screenId, in wstring format, in octet[] data,[retval] out IProgress progress)
| Informs the guest about a drop data event.
void | dragGHPending (in unsigned long screenId, out wstring[] format, out DragAndDropAction[] allowedActions,[retval] out DragAndDropAction defaultAction)
| Ask the guest if there is any Drag and Drop operation pending in the guest.
void | dragGHDropped (in wstring format, in DragAndDropAction action,[retval] out IProgress progress)
| Informs the guest that a drop event occured for a pending Drag and Drop event.
void | dragGHGetData ([retval] out octet[] data)
| Fetch the data of a previously Drag and Drop event from the guest.
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 | updateGuestAdditions (in wstring source, 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 Guest Additions.
readonly attribute wstring | additionsVersion
| Version of the Guest Additions in the same format as IVirtualBox::version.
readonly attribute unsigned long | additionsRevision
| The internal build revision number of the additions.
readonly attribute IAdditionsFacility[] | facilities
| Array 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:
  `{19C32350-0618-4EDE-B0C3-2B4311BF0D9B}`

## Member Function Documentation

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.

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.

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.

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.

void IGuest::dragHGEnter | ( | in unsigned long | screenId,
|  | in unsigned long | y,
|  | in unsigned long | x,
|  | in DragAndDropAction | defaultAction,
|  | in DragAndDropAction[] | allowedActions,
|  | in wstring[] | formats,
|  | [retval] out DragAndDropAction | resultAction |
| ) |  |  |

Informs the guest about a Drag and Drop enter event.

This is used in Host - Guest direction.

Parameters:

  | screenId | The screen id where the Drag and Drop event occured.
  | y | y-position of the event.
  | x | x-position of the event.
  | defaultAction | The default action to use.
  | allowedActions | The actions which are allowed.
  | formats | The supported mime types.
  | resultAction | The resulting action of this event.

Expected result codes:

  VBOX_E_VM_ERROR | VMM device is not available.

void IGuest::dragHGMove | ( | in unsigned long | screenId,
|  | in unsigned long | x,
|  | in unsigned long | y,
|  | in DragAndDropAction | defaultAction,
|  | in DragAndDropAction[] | allowedActions,
|  | in wstring[] | formats,
|  | [retval] out DragAndDropAction | resultAction |
| ) |  |  |

Informs the guest about a Drag and Drop move event.

This is used in Host - Guest direction.

Parameters:

  | screenId | The screen id where the Drag and Drop event occured.
  | x | x-position of the event.
  | y | y-position of the event.
  | defaultAction | The default action to use.
  | allowedActions | The actions which are allowed.
  | formats | The supported mime types.
  | resultAction | The resulting action of this event.

Expected result codes:

  VBOX_E_VM_ERROR | VMM device is not available.

void IGuest::dragHGLeave | ( | in unsigned long | screenId | ) |

Informs the guest about a Drag and Drop leave event.

This is used in Host - Guest direction.

Parameters:

  | screenId | The screen id where the Drag and Drop event occured.

Expected result codes:

  VBOX_E_VM_ERROR | VMM device is not available.

void IGuest::dragHGDrop | ( | in unsigned long | screenId,
|  | in unsigned long | x,
|  | in unsigned long | y,
|  | in DragAndDropAction | defaultAction,
|  | in DragAndDropAction[] | allowedActions,
|  | in wstring[] | formats,
|  | out wstring | format,
|  | [retval] out DragAndDropAction | resultAction |
| ) |  |  |

Informs the guest about a drop event.

This is used in Host - Guest direction.

Parameters:

  | screenId | The screen id where the Drag and Drop event occured.
  | x | x-position of the event.
  | y | y-position of the event.
  | defaultAction | The default action to use.
  | allowedActions | The actions which are allowed.
  | formats | The supported mime types.
  | format | The resulting format of this event.
  | resultAction | The resulting action of this event.

Expected result codes:

  VBOX_E_VM_ERROR | VMM device is not available.

void IGuest::dragHGPutData | ( | in unsigned long | screenId,
|  | in wstring | format,
|  | in octet[] | data,
|  | [retval] out IProgress | progress |
| ) |  |  |

Informs the guest about a drop data event.

This is used in Host - Guest direction.

Parameters:

  | screenId | The screen id where the Drag and Drop event occured.
  | format | The mime type the data is in.
  | data | The actual data.
  | progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_VM_ERROR | VMM device is not available.

void IGuest::dragGHPending | ( | in unsigned long | screenId,
|  | out wstring[] | format,
|  | out DragAndDropAction[] | allowedActions,
|  | [retval] out DragAndDropAction | defaultAction |
| ) |  |  |

Ask the guest if there is any Drag and Drop operation pending in the guest.

If no Drag and Drop operation is pending currently, Ignore is returned.

This is used in Guest - Host direction.

Parameters:

  | screenId | The screen id where the Drag and Drop event occured.
  | format | On return the supported mime types.
  | allowedActions | On return the actions which are allowed.
  | defaultAction | On return the default action to use.

Expected result codes:

  VBOX_E_VM_ERROR | VMM device is not available.

void IGuest::dragGHDropped | ( | in wstring | format,
|  | in DragAndDropAction | action,
|  | [retval] out IProgress | progress |
| ) |  |  |

Informs the guest that a drop event occured for a pending Drag and Drop event.

This is used in Guest - Host direction.

Parameters:

  | format | The mime type the data must be in.
  | action | The action to use.
  | progress | Progress object to track the operation completion.

Expected result codes:

  VBOX_E_VM_ERROR | VMM device is not available.

void IGuest::dragGHGetData | ( | [retval] out octet[] | data | ) |

Fetch the data of a previously Drag and Drop event from the guest.

This is used in Guest - Host direction.

Parameters:

  | data | The actual data.

Expected result codes:

  VBOX_E_VM_ERROR | VMM device is not available.

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.

A guest session represents one impersonated user account on 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 on the guest are not allowed due to security reasons.

There can be a maximum of 32 sessions at once per VM. Each session keeps track of its started guest processes, opened guest files or guest directories. To work on guest files or directories a guest session offers methods to open or create such objects (see IGuestSession::fileOpen or IGuestSession::directoryOpen for example).

When done with either of these objects, including the guest session itself, use the appropriate close() method to let the object do its cleanup work.

Every guest session has its own environment variable block which gets automatically applied when starting a new guest process via IGuestSession::processCreate or IGuestSession::processCreateEx. To override (or unset) certain environment variables already set by the guest session, one can specify a per-process environment block when using one of the both above mentioned process creation calls.

Closing a session via IGuestSession::close will try to close all the mentioned objects above unless these objects are still used by a client.

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.

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.

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

Automatically updates already installed Guest Additions in a VM.

At the moment only Windows 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.

Parameters:

  | source | Path to the Guest Additions .ISO file to use for the upate.
  | 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

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.

readonly attribute AdditionsRunLevelType IGuest::additionsRunLevel

Current run level of the Guest Additions.

readonly attribute wstring IGuest::additionsVersion

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

readonly attribute unsigned long IGuest::additionsRevision

The internal build revision number of the additions.

See also IVirtualBox::revision.

readonly attribute IAdditionsFacility [] IGuest::facilities

Array of current known facilities.

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

readonly attribute IGuestSession [] IGuest::sessions

Returns a collection of all opened guest sessions.

attribute unsigned long IGuest::memoryBalloonSize

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

attribute unsigned long IGuest::statisticsUpdateInterval

Interval to update guest statistics in seconds.