org.virtualbox_4_1
Class IGuest

java.lang.Object
  extended by org.virtualbox_4_1.IUnknown
      extended by org.virtualbox_4_1.IGuest

public class IGuest
extends IUnknown

The IGuest interface represents information about the operating system running inside the virtual machine. Used in IConsole.getGuest(). 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}


Field Summary
 
Fields inherited from class org.virtualbox_4_1.IUnknown
obj, port
 
Constructor Summary
IGuest(java.lang.String wrapped, org.virtualbox_4_1.jaxws.VboxPortType port)
           
 
Method Summary
 IProgress copyFromGuest(java.lang.String source, java.lang.String dest, java.lang.String userName, java.lang.String password, java.lang.Long flags)
          Copies files/directories from guest to the host.
 IProgress copyToGuest(java.lang.String source, java.lang.String dest, java.lang.String userName, java.lang.String password, java.lang.Long flags)
          Copies files/directories from host to the guest.
 void directoryClose(java.lang.Long handle)
          Closes a formerly opened guest directory.
 void directoryCreate(java.lang.String directory, java.lang.String userName, java.lang.String password, java.lang.Long mode, java.lang.Long flags)
          Creates a directory on the guest.
 java.lang.Long directoryOpen(java.lang.String directory, java.lang.String filter, java.lang.Long flags, java.lang.String userName, java.lang.String password)
          Opens a directory on the guest.
 IGuestDirEntry directoryRead(java.lang.Long handle)
          Reads the next directory entry of an opened guest directory.
 IProgress executeProcess(java.lang.String execName, java.lang.Long flags, java.util.List<java.lang.String> arguments, java.util.List<java.lang.String> environment, java.lang.String userName, java.lang.String password, java.lang.Long timeoutMS, Holder<java.lang.Long> pid)
          Executes an existing program inside the guest VM.
 java.lang.Boolean fileExists(java.lang.String file, java.lang.String userName, java.lang.String password)
          Checks if the specified file name exists and is a regular file.
 java.lang.Long fileQuerySize(java.lang.String file, java.lang.String userName, java.lang.String password)
          Queries the size of a file, given the path to it.
 AdditionsRunLevelType getAdditionsRunLevel()
          Current run level of the Guest Additions.
 java.lang.Boolean getAdditionsStatus(AdditionsRunLevelType level)
          Retrieve the current status of a certain Guest Additions run level.
 java.lang.String getAdditionsVersion()
          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.
 java.util.List<IAdditionsFacility> getFacilities()
          Array of current known facilities.
 AdditionsFacilityStatus getFacilityStatus(AdditionsFacilityType facility, Holder<java.lang.Long> timestamp)
          Get the current status of a Guest Additions facility.
 java.lang.Long getMemoryBalloonSize()
          Guest system memory balloon size in megabytes (transient property).
 java.lang.String getOSTypeId()
          Identifier of the Guest OS type as reported by the Guest Additions.
 byte[] getProcessOutput(java.lang.Long pid, java.lang.Long flags, java.lang.Long timeoutMS, java.lang.Long size)
          Retrieves output of a formerly started and running guest process.
 ExecuteProcessStatus getProcessStatus(java.lang.Long pid, Holder<java.lang.Long> exitcode, Holder<java.lang.Long> flags)
          Retrieves status, exit code and the exit reason of a formerly started guest process.
 java.lang.Long getStatisticsUpdateInterval()
          Interval to update guest statistics in seconds.
 void internalGetStatistics(Holder<java.lang.Long> cpuUser, Holder<java.lang.Long> cpuKernel, Holder<java.lang.Long> cpuIdle, Holder<java.lang.Long> memTotal, Holder<java.lang.Long> memFree, Holder<java.lang.Long> memBalloon, Holder<java.lang.Long> memShared, Holder<java.lang.Long> memCache, Holder<java.lang.Long> pagedTotal, Holder<java.lang.Long> memAllocTotal, Holder<java.lang.Long> memFreeTotal, Holder<java.lang.Long> memBalloonTotal, Holder<java.lang.Long> memSharedTotal)
          Internal method; do not use as it might change at any time.
static IGuest queryInterface(IUnknown obj)
           
 void setCredentials(java.lang.String userName, java.lang.String password, java.lang.String domain, java.lang.Boolean allowInteractiveLogon)
          Store login credentials that can be queried by guest operating systems with Additions installed.
 void setMemoryBalloonSize(java.lang.Long value)
          Guest system memory balloon size in megabytes (transient property).
 java.lang.Long setProcessInput(java.lang.Long pid, java.lang.Long flags, java.lang.Long timeoutMS, byte[] data)
          Sends input into a formerly started process.
 void setStatisticsUpdateInterval(java.lang.Long value)
          Interval to update guest statistics in seconds.
 IProgress updateGuestAdditions(java.lang.String source, java.lang.Long flags)
          Updates already installed Guest Additions in a VM (Windows guests only).
 
Methods inherited from class org.virtualbox_4_1.IUnknown
getRemoteWSPort, getWrapped, releaseRemote
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IGuest

public IGuest(java.lang.String wrapped,
              org.virtualbox_4_1.jaxws.VboxPortType port)
Method Detail

getOSTypeId

public java.lang.String getOSTypeId()
Identifier of the Guest OS type as reported by the Guest Additions. You may use IVirtualBox.getGuestOSType(String) 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.getOSTypeId().

Returns:
String

getAdditionsRunLevel

public AdditionsRunLevelType getAdditionsRunLevel()
Current run level of the Guest Additions.

Returns:
org.virtualbox_4_1.AdditionsRunLevelType

getAdditionsVersion

public java.lang.String getAdditionsVersion()
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.

Returns:
String

getFacilities

public java.util.List<IAdditionsFacility> getFacilities()
Array of current known facilities. Only returns facilities where a status is known, e.g. facilities with an unknown status will not be returned.

Returns:
List

getMemoryBalloonSize

public java.lang.Long getMemoryBalloonSize()
Guest system memory balloon size in megabytes (transient property).

Returns:
Long

setMemoryBalloonSize

public void setMemoryBalloonSize(java.lang.Long value)
Guest system memory balloon size in megabytes (transient property).

Parameters:
value - Long

getStatisticsUpdateInterval

public java.lang.Long getStatisticsUpdateInterval()
Interval to update guest statistics in seconds.

Returns:
Long

setStatisticsUpdateInterval

public void setStatisticsUpdateInterval(java.lang.Long value)
Interval to update guest statistics in seconds.

Parameters:
value - Long

queryInterface

public static IGuest queryInterface(IUnknown obj)

internalGetStatistics

public void internalGetStatistics(Holder<java.lang.Long> cpuUser,
                                  Holder<java.lang.Long> cpuKernel,
                                  Holder<java.lang.Long> cpuIdle,
                                  Holder<java.lang.Long> memTotal,
                                  Holder<java.lang.Long> memFree,
                                  Holder<java.lang.Long> memBalloon,
                                  Holder<java.lang.Long> memShared,
                                  Holder<java.lang.Long> memCache,
                                  Holder<java.lang.Long> pagedTotal,
                                  Holder<java.lang.Long> memAllocTotal,
                                  Holder<java.lang.Long> memFreeTotal,
                                  Holder<java.lang.Long> memBalloonTotal,
                                  Holder<java.lang.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.

getFacilityStatus

public AdditionsFacilityStatus getFacilityStatus(AdditionsFacilityType facility,
                                                 Holder<java.lang.Long> timestamp)
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.
Returns:
The current (latest) facility status.

getAdditionsStatus

public java.lang.Boolean getAdditionsStatus(AdditionsRunLevelType level)
Retrieve the current status of a certain Guest Additions run level.

Parameters:
level - Status level to check
Returns:
Flag whether the status level has been reached or not Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTED Wrong status level specified.

setCredentials

public void setCredentials(java.lang.String userName,
                           java.lang.String password,
                           java.lang.String domain,
                           java.lang.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:
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR VMM device is not available.

executeProcess

public IProgress executeProcess(java.lang.String execName,
                                java.lang.Long flags,
                                java.util.List<java.lang.String> arguments,
                                java.util.List<java.lang.String> environment,
                                java.lang.String userName,
                                java.lang.String password,
                                java.lang.Long timeoutMS,
                                Holder<java.lang.Long> pid)
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.
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_IPRT_ERROR 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/--control-procs-max-kept" or VBoxService' command line by specifying "--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).

getProcessOutput

public byte[] getProcessOutput(java.lang.Long pid,
                               java.lang.Long flags,
                               java.lang.Long timeoutMS,
                               java.lang.Long size)
Retrieves output of a formerly started and running guest process.

Parameters:
pid - Process id returned by earlier executeProcess(String,Long,List,List,String,String,Long,Holder) call.
flags - ProcessOutputFlag flags.
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.
Returns:
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:
@link ::VBOX_E_IPRT_ERROR 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(String,Long,List,List,String,String,Long,Holder) call for this guest process.

getProcessStatus

public ExecuteProcessStatus getProcessStatus(java.lang.Long pid,
                                             Holder<java.lang.Long> exitcode,
                                             Holder<java.lang.Long> flags)
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:
pid - Process id returned by earlier executeProcess(String,Long,List,List,String,String,Long,Holder) call.
exitcode - The exit code (if available).
flags - Additional flags of process status. Not used at the moment and must be set to 0.
Returns:
The current process status. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Process with specified PID was not found.

copyFromGuest

public IProgress copyFromGuest(java.lang.String source,
                               java.lang.String dest,
                               java.lang.String userName,
                               java.lang.String password,
                               java.lang.Long flags)
Copies files/directories from guest to the host.

Parameters:
source - Source file on the guest to copy.
dest - Destination path on the host.
userName - User 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.
password - Password of the user account specified.
flags - CopyFileFlag flags. Not used at the moment and should be set to 0.
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Error while copying.

copyToGuest

public IProgress copyToGuest(java.lang.String source,
                             java.lang.String dest,
                             java.lang.String userName,
                             java.lang.String password,
                             java.lang.Long flags)
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.
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Error while copying.

directoryClose

public void directoryClose(java.lang.Long handle)
Closes a formerly opened guest directory.

Parameters:
handle - Handle of opened directory to close. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Error while closing directory.

directoryCreate

public void directoryCreate(java.lang.String directory,
                            java.lang.String userName,
                            java.lang.String password,
                            java.lang.Long mode,
                            java.lang.Long flags)
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 - DirectoryCreateFlag flags. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Error while creating directory.

directoryOpen

public java.lang.Long directoryOpen(java.lang.String directory,
                                    java.lang.String filter,
                                    java.lang.Long flags,
                                    java.lang.String userName,
                                    java.lang.String password)
Opens a directory on the guest.

Parameters:
directory - Directory to read.
filter - Directory filter (DOS style wildcards). Set to empty string if no filter required.
flags - DirectoryOpenFlag flags.
userName - User 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.
password - Password of the user account specified.
Returns:
Handle of opened directory returned by openDirectory. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Error while opening / reading directory.

directoryRead

public IGuestDirEntry directoryRead(java.lang.Long handle)
Reads the next directory entry of an opened guest directory.

Parameters:
handle - Handle of opened directory returned by openDirectory.
Returns:
Information about next directory entry on success. Expected result codes:
E_ABORT When the end of the directory has been reached.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Error while opening / reading directory.

fileExists

public java.lang.Boolean fileExists(java.lang.String file,
                                    java.lang.String userName,
                                    java.lang.String password)
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:
file - Full path of file to check.
userName - User name under which the lookup will be performed; the user has to exist and have the appropriate rights to access / read the desired directory.
password - Password of the user account specified.
Returns:
True if it's a regular file, false if it isn't (or doesn't exist). Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Error while looking up information.

fileQuerySize

public java.lang.Long fileQuerySize(java.lang.String file,
                                    java.lang.String userName,
                                    java.lang.String password)
Queries the size of a file, given the path to it.

Parameters:
file - Full path of file to query file size for.
userName - User name under which the lookup will be performed; the user has to exist and have the appropriate rights to access / read the desired directory.
password - Password of the user account specified.
Returns:
Size (in bytes) of file specified. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Error while looking up information.

setProcessInput

public java.lang.Long setProcessInput(java.lang.Long pid,
                                      java.lang.Long flags,
                                      java.lang.Long timeoutMS,
                                      byte[] data)
Sends input into a formerly started process.

Parameters:
pid - Process id returned by earlier executeProcess(String,Long,List,List,String,String,Long,Holder) 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.
Returns:
Number of bytes written. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Could not send input.

updateGuestAdditions

public IProgress updateGuestAdditions(java.lang.String source,
                                      java.lang.Long flags)
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.
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Error while updating.