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

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
cpuUserPercentage of processor time spent in user mode as seen by the guest.
cpuKernelPercentage of processor time spent in kernel mode as seen by the guest.
cpuIdlePercentage of processor time spent idling as seen by the guest.
memTotalTotal amount of physical guest RAM.
memFreeFree amount of physical guest RAM.
memBalloonAmount of ballooned physical guest RAM.
memSharedAmount of shared physical guest RAM.
memCacheTotal amount of guest (disk) cache memory.
pagedTotalTotal amount of space in the page file.
memAllocTotalTotal amount of memory allocated by the hypervisor.
memFreeTotalTotal amount of free memory available in the hypervisor.
memBalloonTotalTotal amount of memory ballooned by the hypervisor.
memSharedTotalTotal 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
facilityFacility to check status for.
timestampTimestamp (in ms) of last status update seen by the host.
statusThe 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
levelStatus level to check
activeFlag whether the status level has been reached or not
  @par Expected result codes:
<table><tr>

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
userNameUser name string, can be empty
passwordPassword string, can be empty
domainDomain name (guest logon scheme specific), can be empty
allowInteractiveLogonFlag 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
screenIdThe screen id where the Drag and Drop event occured.
yy-position of the event.
xx-position of the event.
defaultActionThe default action to use.
allowedActionsThe actions which are allowed.
formatsThe supported mime types.
resultActionThe resulting action of this event.
  @par Expected result codes:
<table><tr>

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
screenIdThe screen id where the Drag and Drop event occured.
xx-position of the event.
yy-position of the event.
defaultActionThe default action to use.
allowedActionsThe actions which are allowed.
formatsThe supported mime types.
resultActionThe resulting action of this event.
  @par Expected result codes:
<table><tr>

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
screenIdThe screen id where the Drag and Drop event occured.
  @par Expected result codes:
<table><tr>

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
screenIdThe screen id where the Drag and Drop event occured.
xx-position of the event.
yy-position of the event.
defaultActionThe default action to use.
allowedActionsThe actions which are allowed.
formatsThe supported mime types.
formatThe resulting format of this event.
resultActionThe resulting action of this event.
  @par Expected result codes:
<table><tr>

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
screenIdThe screen id where the Drag and Drop event occured.
formatThe mime type the data is in.
dataThe actual data.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table><tr>

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
screenIdThe screen id where the Drag and Drop event occured.
formatOn return the supported mime types.
allowedActionsOn return the actions which are allowed.
defaultActionOn return the default action to use.
  @par Expected result codes:
<table><tr>

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
formatThe mime type the data must be in.
actionThe action to use.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table><tr>

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
dataThe actual data.
  @par Expected result codes:
<table><tr>

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 @link IGuest::createSession IGuest::createSession@endlink<b></b>. 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 @link IGuestSession::fileOpen IGuestSession::fileOpen@endlink<b></b> or
    @link IGuestSession::directoryOpen IGuestSession::directoryOpen@endlink<b></b> 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
    @link IGuestSession::processCreate IGuestSession::processCreate@endlink<b></b> or @link IGuestSession::processCreateEx IGuestSession::processCreateEx@endlink<b></b>.
    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 @link IGuestSession::close IGuestSession::close@endlink<b></b> will try to close
    all the mentioned objects above unless these objects are still used by
    a client.
Parameters
userUser 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.
passwordPassword of the user account to be used. Empty passwords are allowed.
domainDomain name of the user account to be used if the guest is part of a domain. Optional. This feature is not implemented yet.
sessionNameThe session's friendly name. Optional, can be empty.
guestSessionThe 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
sessionNameThe session's friendly name to find. Wildcards like ? and * are allowed.
sessionsArray 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
    @link ::AdditionsUpdateFlag AdditionsUpdateFlag@endlink<b></b> for more information.
Parameters
sourcePath to the Guest Additions .ISO file to use for the upate.
flagsAdditionsUpdateFlag flags.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table>

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 @link IVirtualBox::getGuestOSType IVirtualBox::getGuestOSType@endlink<b></b> 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.