org.virtualbox_4_2
Class IGuest

java.lang.Object
  extended by org.virtualbox_4_2.IUnknown
      extended by org.virtualbox_4_2.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: {19C32350-0618-4EDE-B0C3-2B4311BF0D9B}


Field Summary
 
Fields inherited from class org.virtualbox_4_2.IUnknown
obj, port
 
Constructor Summary
IGuest(java.lang.String wrapped, org.virtualbox_4_2.jaxws.VboxPortType port)
           
 
Method Summary
 IGuestSession createSession(java.lang.String user, java.lang.String password, java.lang.String domain, java.lang.String sessionName)
          Creates a new guest session for controlling the guest.
 IProgress dragGHDropped(java.lang.String format, DragAndDropAction action)
          Informs the guest that a drop event occured for a pending Drag and Drop event.
 byte[] dragGHGetData()
          Fetch the data of a previously Drag and Drop event from the guest.
 DragAndDropAction dragGHPending(java.lang.Long screenId, Holder<java.util.List<java.lang.String>> format, Holder<java.util.List<DragAndDropAction>> allowedActions)
          Ask the guest if there is any Drag and Drop operation pending in the guest.
 DragAndDropAction dragHGDrop(java.lang.Long screenId, java.lang.Long x, java.lang.Long y, DragAndDropAction defaultAction, java.util.List<DragAndDropAction> allowedActions, java.util.List<java.lang.String> formats, Holder<java.lang.String> format)
          Informs the guest about a drop event.
 DragAndDropAction dragHGEnter(java.lang.Long screenId, java.lang.Long y, java.lang.Long x, DragAndDropAction defaultAction, java.util.List<DragAndDropAction> allowedActions, java.util.List<java.lang.String> formats)
          Informs the guest about a Drag and Drop enter event.
 void dragHGLeave(java.lang.Long screenId)
          Informs the guest about a Drag and Drop leave event.
 DragAndDropAction dragHGMove(java.lang.Long screenId, java.lang.Long x, java.lang.Long y, DragAndDropAction defaultAction, java.util.List<DragAndDropAction> allowedActions, java.util.List<java.lang.String> formats)
          Informs the guest about a Drag and Drop move event.
 IProgress dragHGPutData(java.lang.Long screenId, java.lang.String format, byte[] data)
          Informs the guest about a drop data event.
 java.util.List<IGuestSession> findSession(java.lang.String sessionName)
          Finds guest sessions by their friendly name and returns an interface array with all found guest sessions.
 java.lang.Long getAdditionsRevision()
          The internal build revision number of the additions.
 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 in the same format as IVirtualBox.getVersion().
 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.
 java.util.List<IGuestSession> getSessions()
          Returns a collection of all opened guest sessions.
 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).
 void setStatisticsUpdateInterval(java.lang.Long value)
          Interval to update guest statistics in seconds.
 IProgress updateGuestAdditions(java.lang.String source, java.util.List<AdditionsUpdateFlag> flags)
          Automatically updates already installed Guest Additions in a VM.
 
Methods inherited from class org.virtualbox_4_2.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_2.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_2.AdditionsRunLevelType

getAdditionsVersion

public java.lang.String getAdditionsVersion()
Version of the Guest Additions in the same format as IVirtualBox.getVersion().

Returns:
String

getAdditionsRevision

public java.lang.Long getAdditionsRevision()
The internal build revision number of the additions. See also IVirtualBox.getRevision().

Returns:
Long

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

getSessions

public java.util.List<IGuestSession> getSessions()
Returns a collection of all opened guest sessions.

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.

dragHGEnter

public DragAndDropAction dragHGEnter(java.lang.Long screenId,
                                     java.lang.Long y,
                                     java.lang.Long x,
                                     DragAndDropAction defaultAction,
                                     java.util.List<DragAndDropAction> allowedActions,
                                     java.util.List<java.lang.String> formats)
Informs the guest about a Drag and Drop enter event. This is used in Host - Guest direction.

Parameters:
screenId - The screen id where the Drag and Drop event occured.
y - y-position of the event.
x - x-position of the event.
defaultAction - The default action to use.
allowedActions - The actions which are allowed.
formats - The supported mime types.
Returns:
The resulting action of this event. Expected result codes:
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR VMM device is not available.

dragHGMove

public DragAndDropAction dragHGMove(java.lang.Long screenId,
                                    java.lang.Long x,
                                    java.lang.Long y,
                                    DragAndDropAction defaultAction,
                                    java.util.List<DragAndDropAction> allowedActions,
                                    java.util.List<java.lang.String> formats)
Informs the guest about a Drag and Drop move event. This is used in Host - Guest direction.

Parameters:
screenId - The screen id where the Drag and Drop event occured.
x - x-position of the event.
y - y-position of the event.
defaultAction - The default action to use.
allowedActions - The actions which are allowed.
formats - The supported mime types.
Returns:
The resulting action of this event. Expected result codes:
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR VMM device is not available.

dragHGLeave

public void dragHGLeave(java.lang.Long screenId)
Informs the guest about a Drag and Drop leave event. This is used in Host - Guest direction.

Parameters:
screenId - The screen id where the Drag and Drop event occured. Expected result codes:
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR VMM device is not available.

dragHGDrop

public DragAndDropAction dragHGDrop(java.lang.Long screenId,
                                    java.lang.Long x,
                                    java.lang.Long y,
                                    DragAndDropAction defaultAction,
                                    java.util.List<DragAndDropAction> allowedActions,
                                    java.util.List<java.lang.String> formats,
                                    Holder<java.lang.String> format)
Informs the guest about a drop event. This is used in Host - Guest direction.

Parameters:
screenId - The screen id where the Drag and Drop event occured.
x - x-position of the event.
y - y-position of the event.
defaultAction - The default action to use.
allowedActions - The actions which are allowed.
formats - The supported mime types.
format - The resulting format of this event.
Returns:
The resulting action of this event. Expected result codes:
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR VMM device is not available.

dragHGPutData

public IProgress dragHGPutData(java.lang.Long screenId,
                               java.lang.String format,
                               byte[] data)
Informs the guest about a drop data event. This is used in Host - Guest direction.

Parameters:
screenId - The screen id where the Drag and Drop event occured.
format - The mime type the data is in.
data - The actual data.
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR VMM device is not available.

dragGHPending

public DragAndDropAction dragGHPending(java.lang.Long screenId,
                                       Holder<java.util.List<java.lang.String>> format,
                                       Holder<java.util.List<DragAndDropAction>> allowedActions)
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:
screenId - The screen id where the Drag and Drop event occured.
format - On return the supported mime types.
allowedActions - On return the actions which are allowed.
Returns:
On return the default action to use. Expected result codes:
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR VMM device is not available.

dragGHDropped

public IProgress dragGHDropped(java.lang.String format,
                               DragAndDropAction action)
Informs the guest that a drop event occured for a pending Drag and Drop event. This is used in Guest - Host direction.

Parameters:
format - The mime type the data must be in.
action - The action to use.
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR VMM device is not available.

dragGHGetData

public byte[] dragGHGetData()
Fetch the data of a previously Drag and Drop event from the guest. This is used in Guest - Host direction.

Returns:
The actual data. Expected result codes:
@link ::VBOX_E_VM_ERROR VBOX_E_VM_ERROR VMM device is not available.

createSession

public IGuestSession createSession(java.lang.String user,
                                   java.lang.String password,
                                   java.lang.String domain,
                                   java.lang.String sessionName)
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 createSession(String,String,String,String). 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 IGuestSession.fileOpen(String,String,String,Long,Long) or IGuestSession.directoryOpen(String,String,List) 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 IGuestSession.processCreate(String,List,List,List,Long) or IGuestSession.processCreateEx(String,List,List,List,Long,org.virtualbox_4_2.ProcessPriority,List). 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 IGuestSession.close() will try to close all the mentioned objects above unless these objects are still used by a client.

Parameters:
user - User 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.
password - Password of the user account to be used. Empty passwords are allowed.
domain - Domain name of the user account to be used if the guest is part of a domain. Optional. This feature is not implemented yet.
sessionName - The session's friendly name. Optional, can be empty.
Returns:
The newly created session object.

findSession

public java.util.List<IGuestSession> findSession(java.lang.String sessionName)
Finds guest sessions by their friendly name and returns an interface array with all found guest sessions.

Parameters:
sessionName - The session's friendly name to find. Wildcards like ? and * are allowed.
Returns:
Array with all guest sessions found matching the name specified.

updateGuestAdditions

public IProgress updateGuestAdditions(java.lang.String source,
                                      java.util.List<AdditionsUpdateFlag> flags)
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 AdditionsUpdateFlag for more information.

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_NOT_SUPPORTED VBOX_E_NOT_SUPPORTED Guest OS is not supported for automated Guest Additions updates or the already installed Guest Additions are not ready yet.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR Error while updating.