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 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 and running guest process.
void getProcessStatus (in unsigned long pid, out unsigned long exitcode, out unsigned long flags,[retval] out ExecuteProcessStatus reason)
 Retrieves status, exit code and the exit reason of a formerly started guest process.
void copyFromGuest (in wstring source, in wstring dest, in wstring userName, in wstring password, in unsigned long flags,[retval] out IProgress progress)
 Copies files/directories from guest to the host.
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 directoryClose (in unsigned long handle)
 Closes a formerly opened guest directory.
void directoryCreate (in wstring directory, in wstring userName, in wstring password, in unsigned long mode, in unsigned long flags)
 Creates a directory on the guest.
void directoryOpen (in wstring directory, in wstring filter, in unsigned long flags, in wstring userName, in wstring password,[retval] out unsigned long handle)
 Opens a directory on the guest.
void directoryRead (in unsigned long handle,[retval] out IGuestDirEntry entry)
 Reads the next directory entry of an opened guest directory.
void fileExists (in wstring file, in wstring userName, in wstring password,[retval] out boolean exists)
 Checks if the specified file name exists and is a regular file.
void fileQuerySize (in wstring file, in wstring userName, in wstring password,[retval] out long long size)
 Queries the size of a file, given the path to it.
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
IAdditionsFacility[] 
facilities
 Array of current known facilities.
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:
{ED109B6E-0578-4B17-8ACE-52646789F1A0}

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::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
execNameFull path name of the command to execute on the guest; the commands has to exists in the guest VM in order to be executed.
flagsExecuteProcessFlag flags.
argumentsArray of arguments passed to the execution command.
environmentEnvironment 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.
userNameUser name under which the command will be executed; has to exist and have the appropriate rights to execute programs in the VM.
passwordPassword of the user account specified.
timeoutMSThe maximum timeout value (in msec) to wait for finished program execution. Pass 0 for an infinite timeout.
pidThe PID (process ID) of the started command for later reference.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Could not execute process.

Note
Starting at VirtualBox 4.1.8 guest process execution by default is limited to serve up to 25 guest processes at a time. If all 25 guest processes are still active and running, starting a new guest process will result in an appropriate error message.

If ExecuteProcessFlag_WaitForStdOut and/or respectively ExecuteProcessFlag_WaitForStdErr of ExecuteProcessFlag is set, the guest process will not exit until all data from the specified stream(s) is/are read out.

To raise or lower the guest process execution limit, either the guest property "/VirtualBox/GuestAdd/VBoxService/&ndash;control-procs-max-kept" or VBoxService' command line by specifying "&ndash;control-procs-max-kept" needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited guest processes, a value of "0" needs to be set (not recommended).

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 and running guest process.

Parameters
pidProcess id returned by earlier executeProcess call.
flagsProcessOutputFlag flags.
timeoutMSThe maximum timeout value (in msec) to wait for output data. Pass 0 for an infinite timeout.
sizeSize in bytes to read in the buffer.
dataBuffer 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.
Note
Starting with VirtualBox 4.1.8 this only will return output data from stdout or stderr if flag ExecuteProcessFlag_WaitForStdOut and/or respectively ExecuteProcessFlag_WaitForStdErr of ExecuteProcessFlag is set in the former executeProcess call for this guest process.
void IGuest::getProcessStatus ( in unsigned long  pid,
out unsigned long  exitcode,
out unsigned long  flags,
[retval] out ExecuteProcessStatus  reason 
)

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

If a guest process exited or got terminated this function returns its final status and removes this process from the list of known guest processes for further retrieval.

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

Copies files/directories from guest to the host.

Parameters
sourceSource file on the guest to copy.
destDestination path on the host.
userNameUser name under which the copy command will be executed; the user has to exist and have the appropriate rights to read from the source path.
passwordPassword of the user account specified.
flagsCopyFileFlag flags. Not used at the moment and should be set to 0.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error while copying.

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
sourceSource file on the host to copy.
destDestination path on the guest.
userNameUser 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.
passwordPassword of the user account specified.
flagsCopyFileFlag flags. Not used at the moment and should be set to 0.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error while copying.

void IGuest::directoryClose ( in unsigned long  handle)

Closes a formerly opened guest directory.

Parameters
handleHandle of opened directory to close.
Expected result codes:
VBOX_E_IPRT_ERROR Error while closing directory.
void IGuest::directoryCreate ( in wstring  directory,
in wstring  userName,
in wstring  password,
in unsigned long  mode,
in unsigned long  flags 
)

Creates a directory on the guest.

Parameters
directoryDirectory to create.
userNameUser name under which the directory creation will be executed; the user has to exist and have the appropriate rights to create the desired directory.
passwordPassword of the user account specified.
modeFile mode.
flagsDirectoryCreateFlag flags.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error while creating directory.

void IGuest::directoryOpen ( in wstring  directory,
in wstring  filter,
in unsigned long  flags,
in wstring  userName,
in wstring  password,
[retval] out unsigned long  handle 
)

Opens a directory on the guest.

Parameters
directoryDirectory to read.
filterDirectory filter (DOS style wildcards). Set to empty string if no filter required.
flagsDirectoryOpenFlag flags.
userNameUser name under which the directory reading will be performed; the user has to exist and have the appropriate rights to access / read the desired directory.
passwordPassword of the user account specified.
handleHandle of opened directory returned by openDirectory.
Expected result codes:
VBOX_E_IPRT_ERROR Error while opening / reading directory.
void IGuest::directoryRead ( in unsigned long  handle,
[retval] out IGuestDirEntry  entry 
)

Reads the next directory entry of an opened guest directory.

Parameters
handleHandle of opened directory returned by openDirectory.
entryInformation about next directory entry on success.
Expected result codes:
E_ABORT When the end of the directory has been reached.
VBOX_E_IPRT_ERROR Error while opening / reading directory.
void IGuest::fileExists ( in wstring  file,
in wstring  userName,
in wstring  password,
[retval] out boolean  exists 
)

Checks if the specified file name exists and is a regular file.

    If the file name ends with a slash or backslash, the function assumes
    it's a directory and will check if the specified directory exists and
    is a regular directory.
Parameters
fileFull path of file to check.
userNameUser name under which the lookup will be performed; the user has to exist and have the appropriate rights to access / read the desired directory.
passwordPassword of the user account specified.
existsTrue if it's a regular file, false if it isn't (or doesn't exist).
Expected result codes:
VBOX_E_IPRT_ERROR Error while looking up information.
void IGuest::fileQuerySize ( in wstring  file,
in wstring  userName,
in wstring  password,
[retval] out long long  size 
)

Queries the size of a file, given the path to it.

Parameters
fileFull path of file to query file size for.
userNameUser name under which the lookup will be performed; the user has to exist and have the appropriate rights to access / read the desired directory.
passwordPassword of the user account specified.
sizeSize (in bytes) of file specified.
Expected result codes:
VBOX_E_IPRT_ERROR Error while looking up information.
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
pidProcess id returned by earlier executeProcess call.
flagsProcessInputFlag flags.
timeoutMSThe maximum timeout value (in msec) to wait for getting the data transfered to the guest. Pass 0 for an infinite timeout.
dataBuffer of input data to send to the started process to.
writtenNumber 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
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><tr>

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

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.