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. |
Used in IConsole::guest.
IGuest provides information about the guest operating system, whether Guest Additions are installed and other OS-specific virtual machine properties.
{7CE7E4D8-CDAA-4D83-A0F4-510C8EE70AEA}
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.
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.
level | Status level to check | |
active | Flag whether the status level has been reached or not |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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.
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. |
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).
source | Path to the Guest Additions .ISO file to use for the upate. | |
flags | AdditionsUpdateFlag flags. | |
progress | Progress object to track the operation completion. |
VBOX_E_IPRT_ERROR | Error while updating. |
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.
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 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.