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 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 executeProcess (in wstring execName, in unsigned long flags, in wstring[] arguments, in wstring[] environment, in wstring userName, in wstring password, in unsigned long timeoutMS, out unsigned long pid,[retval] out IProgress progress)
 Executes an existing program inside the guest VM.
void getProcessOutput (in unsigned long pid, in unsigned long flags, in unsigned long timeoutMS, in long long size,[retval] out octet[] data)
 Retrieves output of a formerly started process.
void getProcessStatus (in unsigned long pid, out unsigned long exitcode, out unsigned long flags,[retval] out unsigned long reason)
 Retrieves status, exit code and the exit reason of a formerly started process.
void copyToGuest (in wstring source, in wstring dest, in wstring userName, in wstring password, in unsigned long flags,[retval] out IProgress progress)
 Copies files/directories from host to the guest.
void createDirectory (in wstring directory, in wstring userName, in wstring password, in unsigned long mode, in unsigned long flags,[retval] out IProgress progress)
 Creates a directory on the guest.
void setProcessInput (in unsigned long pid, in unsigned long flags, in unsigned long timeoutMS, in octet[] data,[retval] out unsigned long written)
 Sends input into a formerly started process.
void updateGuestAdditions (in wstring source, in unsigned long flags,[retval] out IProgress progress)
 Updates already installed Guest Additions in a VM (Windows guests only).

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 including the revision (3 decimal numbers separated by dots + revision number) installed on the guest or empty when the Additions are not installed.
readonly attribute boolean supportsSeamless
 Flag whether seamless guest display rendering (seamless desktop integration) is supported.
readonly attribute boolean supportsGraphics
 Flag whether the guest is in graphics mode.
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:
{7CE7E4D8-CDAA-4D83-A0F4-510C8EE70AEA}

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::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::executeProcess ( in wstring  execName,
in unsigned long  flags,
in wstring[]  arguments,
in wstring[]  environment,
in wstring  userName,
in wstring  password,
in unsigned long  timeoutMS,
out unsigned long  pid,
[retval] out IProgress  progress 
)

Executes an existing program inside the guest VM.

Parameters:
execName Full path name of the command to execute on the guest; the commands has to exists in the guest VM in order to be executed.
flags ExecuteProcessFlag flags.
arguments Array of arguments passed to the execution command.
environment Environment variables that can be set while the command is being executed, in form of "NAME=VALUE"; one pair per entry. To unset a variable just set its name ("NAME") without a value.
userName User name under which the command will be executed; has to exist and have the appropriate rights to execute programs in the VM.
password Password of the user account specified.
timeoutMS The maximum timeout value (in msec) to wait for finished program execution. Pass 0 for an infinite timeout.
pid The PID (process ID) of the started command for later reference.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_IPRT_ERROR Could not execute process.
void IGuest::getProcessOutput ( in unsigned long  pid,
in unsigned long  flags,
in unsigned long  timeoutMS,
in long long  size,
[retval] out octet[]  data 
)

Retrieves output of a formerly started process.

Parameters:
pid Process id returned by earlier executeProcess() call.
flags Flags describing which output to retrieve.
timeoutMS The maximum timeout value (in msec) to wait for output data. Pass 0 for an infinite timeout.
size Size in bytes to read in the buffer.
data Buffer for retrieving the actual output. A data size of 0 means end of file if the requested size was not 0. This is the unprocessed output data, i.e. the line ending style depends on the platform of the system the server is running on.
Expected result codes:
VBOX_E_IPRT_ERROR Could not retrieve output.
void IGuest::getProcessStatus ( in unsigned long  pid,
out unsigned long  exitcode,
out unsigned long  flags,
[retval] out unsigned long  reason 
)

Retrieves status, exit code and the exit reason of a formerly started process.

Parameters:
pid Process id returned by earlier executeProcess() call.
exitcode The exit code (if available).
flags Additional flags of process status. Not used at the moment and must be set to 0.
reason The current process status.
Expected result codes:
VBOX_E_IPRT_ERROR Process with specified PID was not found.
void IGuest::copyToGuest ( in wstring  source,
in wstring  dest,
in wstring  userName,
in wstring  password,
in unsigned long  flags,
[retval] out IProgress  progress 
)

Copies files/directories from host to the guest.

Parameters:
source Source file on the host to copy.
dest Destination path on the guest.
userName User name under which the copy command will be executed; the user has to exist and have the appropriate rights to write to the destination path.
password Password of the user account specified.
flags CopyFileFlag flags. Not used at the moment and should be set to 0.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_IPRT_ERROR Error while copying.
void IGuest::createDirectory ( in wstring  directory,
in wstring  userName,
in wstring  password,
in unsigned long  mode,
in unsigned long  flags,
[retval] out IProgress  progress 
)

Creates a directory on the guest.

Parameters:
directory Directory to create.
userName User name under which the directory creation will be executed; the user has to exist and have the appropriate rights to create the desired directory.
password Password of the user account specified.
mode File mode.
flags CreateDirectoryFlag flags.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_IPRT_ERROR Error while creating directory.
void IGuest::setProcessInput ( in unsigned long  pid,
in unsigned long  flags,
in unsigned long  timeoutMS,
in octet[]  data,
[retval] out unsigned long  written 
)

Sends input into a formerly started process.

Parameters:
pid Process id returned by earlier executeProcess() call.
flags ProcessInputFlag flags.
timeoutMS The maximum timeout value (in msec) to wait for getting the data transfered to the guest. Pass 0 for an infinite timeout.
data Buffer of input data to send to the started process to.
written Number of bytes written.
Expected result codes:
VBOX_E_IPRT_ERROR Could not send input.
void IGuest::updateGuestAdditions ( in wstring  source,
in unsigned long  flags,
[retval] out IProgress  progress 
)

Updates already installed Guest Additions in a VM (Windows guests only).

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

Current run level of the Guest Additions.

readonly attribute wstring IGuest::additionsVersion

Version of the Guest Additions including the revision (3 decimal numbers separated by dots + revision number) installed on the guest or empty when the Additions are not installed.

readonly attribute boolean IGuest::supportsSeamless

Flag whether seamless guest display rendering (seamless desktop integration) is supported.

readonly attribute boolean IGuest::supportsGraphics

Flag whether the guest is in graphics mode.

If it is not, then seamless rendering will not work, resize hints are not immediately acted on and guest display resizes are probably not initiated by the guest additions.

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.