org.virtualbox_5_0
Class IGuestSession

java.lang.Object
  extended by org.virtualbox_5_0.IUnknown
      extended by org.virtualbox_5_0.IGuestSession

public class IGuestSession
extends IUnknown

A guest session represents one impersonated user account in the guest, so every operation will use the same credentials specified when creating the session object viaIGuest.createSession(String,String,String,String). There can be a maximum of 32 sessions at once per VM, whereas session 0 is reserved for the root session.This root session is controlling all other guest sessions and also is responsible for actions which require system level privileges. Each guest session keeps track of the guest directories and files that it opened as well as guest processes it has created. To work on guest files or directories a guest session offers methods to open or create such objects (seefileOpen(String,org.virtualbox_5_0.FileAccessMode,org.virtualbox_5_0.FileOpenAction,Long)ordirectoryOpen(String,String,List)for instance). Similarly, there a methods for creating guest processes. There can be up to 2048 objects (guest processes, files and directories) a time per guest session. Exceeding the limit will result in an error.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. Closing a session viaclose()will try to close all the mentioned objects above unless these objects are still used by a client. A set of environment variables changes is associated with each session (getEnvironmentChanges()). These are applied to the base environment of the impersonated guest user when creating a new guest process. For additional flexibility theprocessCreate(String,List,List,List,Long)andprocessCreateEx(String,List,List,List,Long,org.virtualbox_5_0.ProcessPriority,List)methods allows you to specify individual environment changes for each process you create. With newer guest addition versions, the base environment is also made available viagetEnvironmentBase(). (One reason for why we record changes to a base environment instead of working directly on an environment block is that we need to be compatible with older guest additions. Another reason is that this way it is always possible to undo all the changes you've scheduled.) Interface ID: {3CBF62CF-C9CD-48C6-9623-D1DBE54CA557}


Field Summary
 
Fields inherited from class org.virtualbox_5_0.IUnknown
obj, port
 
Constructor Summary
IGuestSession(java.lang.String wrapped, org.virtualbox_5_0.jaxws.VboxPortType port)
           
 
Method Summary
 void close()
          Closes this session.
 IProgress directoryCopy(java.lang.String source, java.lang.String destination, java.util.List<DirectoryCopyFlags> flags)
          Recursively copies a directory from one guest location to another.
 IProgress directoryCopyFromGuest(java.lang.String source, java.lang.String destination, java.util.List<DirectoryCopyFlags> flags)
          Recursively copies a directory from the guest to the host.
 IProgress directoryCopyToGuest(java.lang.String source, java.lang.String destination, java.util.List<DirectoryCopyFlags> flags)
          Recursively copies a directory from the host to the guest.
 void directoryCreate(java.lang.String path, java.lang.Long mode, java.util.List<DirectoryCreateFlag> flags)
          Creates a directory in the guest.
 java.lang.String directoryCreateTemp(java.lang.String templateName, java.lang.Long mode, java.lang.String path, java.lang.Boolean secure)
          Creates a temporary directory in the guest.
 java.lang.Boolean directoryExists(java.lang.String path, java.lang.Boolean followSymlinks)
          Checks whether a directory exists in the guest or not.
 IGuestDirectory directoryOpen(java.lang.String path, java.lang.String filter, java.util.List<DirectoryOpenFlag> flags)
          Opens a directory in the guest and creates aIGuestDirectoryobject that can be used for further operations.
 void directoryRemove(java.lang.String path)
          Removes a guest directory if empty.
 IProgress directoryRemoveRecursive(java.lang.String path, java.util.List<DirectoryRemoveRecFlag> flags)
          Removes a guest directory recursively.
 java.lang.Boolean environmentDoesBaseVariableExist(java.lang.String name)
          Checks if the given environment variable exists in the session's base environment (getEnvironmentBase()).
 java.lang.String environmentGetBaseVariable(java.lang.String name)
          Gets an environment variable from the session's base environment (getEnvironmentBase()).
 void environmentScheduleSet(java.lang.String name, java.lang.String value)
          Schedules setting an environment variable when creating the next guest process.
 void environmentScheduleUnset(java.lang.String name)
          Schedules unsetting (removing) an environment variable when creating the next guest process.
 IProgress fileCopy(java.lang.String source, java.lang.String destination, java.util.List<FileCopyFlag> flags)
          Copies a file from one guest location to another.
 IProgress fileCopyFromGuest(java.lang.String source, java.lang.String destination, java.util.List<FileCopyFlag> flags)
          Copies a file from the guest to the host.
 IProgress fileCopyToGuest(java.lang.String source, java.lang.String destination, java.util.List<FileCopyFlag> flags)
          Copies a file from the host to the guest.
 IGuestFile fileCreateTemp(java.lang.String templateName, java.lang.Long mode, java.lang.String path, java.lang.Boolean secure)
          Creates a temporary file in the guest.
 java.lang.Boolean fileExists(java.lang.String path, java.lang.Boolean followSymlinks)
          Checks whether a regular file exists in the guest or not.
 IGuestFile fileOpen(java.lang.String path, FileAccessMode accessMode, FileOpenAction openAction, java.lang.Long creationMode)
          Opens a file and creates aIGuestFileobject that can be used for further operations.
 IGuestFile fileOpenEx(java.lang.String path, FileAccessMode accessMode, FileOpenAction openAction, FileSharingMode sharingMode, java.lang.Long creationMode, java.util.List<FileOpenExFlags> flags)
          Opens a file and creates aIGuestFileobject that can be used for further operations, extended version.
 java.lang.Long fileQuerySize(java.lang.String path, java.lang.Boolean followSymlinks)
          Queries the size of a regular file in the guest.
 java.lang.Boolean fsObjExists(java.lang.String path, java.lang.Boolean followSymlinks)
          Checks whether a file system object (file, directory, etc) exists in the guest or not.
 IProgress fsObjMove(java.lang.String source, java.lang.String destination, java.util.List<FsObjMoveFlags> flags)
          Moves a file system object (file, directory, symlink, etc) from one guest location to another.
 IGuestFsObjInfo fsObjQueryInfo(java.lang.String path, java.lang.Boolean followSymlinks)
          Queries information about a file system object (file, directory, etc) in the guest.
 void fsObjRemove(java.lang.String path)
          Removes a file system object (file, symlink, etc) in the guest.
 void fsObjRename(java.lang.String oldPath, java.lang.String newPath, java.util.List<FsObjRenameFlag> flags)
          Renames a file system object (file, directory, symlink, etc) in the guest.
 void fsObjSetACL(java.lang.String path, java.lang.Boolean followSymlinks, java.lang.String acl, java.lang.Long mode)
          Sets the access control list (ACL) of a file system object (file, directory, etc) in the guest.
 java.lang.String getCurrentDirectory()
          The current directory of the session.
 java.util.List<IGuestDirectory> getDirectories()
          Returns all currently opened guest directories.
 java.lang.String getDomain()
          Returns the domain name used by this session to impersonate users in the guest.
 java.util.List<java.lang.String> getEnvironmentBase()
          The base environment of the session.
 java.util.List<java.lang.String> getEnvironmentChanges()
          The set of scheduled environment changes to the base environment of the session.
 IEventSource getEventSource()
          Event source for guest session events.
 java.util.List<IGuestFile> getFiles()
          Returns all currently opened guest files.
 java.lang.Long getId()
          Returns the internal session ID.
 java.lang.String getName()
          Returns the session's friendly name.
 PathStyle getPathStyle()
          The style of paths used by the guest.
 java.util.List<IGuestProcess> getProcesses()
          Returns all current guest processes.
 java.lang.Long getProtocolVersion()
          Returns the protocol version which is used by this session to communicate with the guest.
 GuestSessionStatus getStatus()
          Returns the current session status.
 java.lang.Long getTimeout()
          Returns the session timeout (in ms).
 java.lang.String getUser()
          Returns the user name used by this session to impersonate users in the guest.
 IGuestProcess processCreate(java.lang.String executable, java.util.List<java.lang.String> arguments, java.util.List<java.lang.String> environmentChanges, java.util.List<ProcessCreateFlag> flags, java.lang.Long timeoutMS)
          Creates a new process running in the guest.
 IGuestProcess processCreateEx(java.lang.String executable, java.util.List<java.lang.String> arguments, java.util.List<java.lang.String> environmentChanges, java.util.List<ProcessCreateFlag> flags, java.lang.Long timeoutMS, ProcessPriority priority, java.util.List<java.lang.Integer> affinity)
          Creates a new process running in the guest with the extended options for setting the process priority and affinity.
 IGuestProcess processGet(java.lang.Long pid)
          Gets a certain guest process by its process ID (PID).
static IGuestSession queryInterface(IUnknown obj)
           
 void setCurrentDirectory(java.lang.String value)
          The current directory of the session.
 void setEnvironmentChanges(java.util.List<java.lang.String> value)
          The set of scheduled environment changes to the base environment of the session.
 void setTimeout(java.lang.Long value)
          Returns the session timeout (in ms).
 void symlinkCreate(java.lang.String symlink, java.lang.String target, SymlinkType type)
          Creates a symbolic link in the guest.
 java.lang.Boolean symlinkExists(java.lang.String symlink)
          Checks whether a symbolic link exists in the guest.
 java.lang.String symlinkRead(java.lang.String symlink, java.util.List<SymlinkReadFlag> flags)
          Reads the target value of a symbolic link in the guest.
 GuestSessionWaitResult waitFor(java.lang.Long waitFor, java.lang.Long timeoutMS)
          Waits for one or more events to happen.
 GuestSessionWaitResult waitForArray(java.util.List<GuestSessionWaitForFlag> waitFor, java.lang.Long timeoutMS)
          Waits for one or more events to happen.
 
Methods inherited from class org.virtualbox_5_0.IUnknown
getRemoteWSPort, getWrapped, releaseRemote
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IGuestSession

public IGuestSession(java.lang.String wrapped,
                     org.virtualbox_5_0.jaxws.VboxPortType port)
Method Detail

getUser

public java.lang.String getUser()
Returns the user name used by this session to impersonate users in the guest.

Returns:
String

getDomain

public java.lang.String getDomain()
Returns the domain name used by this session to impersonate users in the guest.

Returns:
String

getName

public java.lang.String getName()
Returns the session's friendly name.

Returns:
String

getId

public java.lang.Long getId()
Returns the internal session ID.

Returns:
Long

getTimeout

public java.lang.Long getTimeout()
Returns the session timeout (in ms). Expected result codes:
E_NOTIMPLThis attribute is not implemented yet.

Returns:
Long

setTimeout

public void setTimeout(java.lang.Long value)
Returns the session timeout (in ms). Expected result codes:
E_NOTIMPLThis attribute is not implemented yet.

Parameters:
value - Long

getProtocolVersion

public java.lang.Long getProtocolVersion()
Returns the protocol version which is used by this session to communicate with the guest.

Returns:
Long

getStatus

public GuestSessionStatus getStatus()
Returns the current session status.

Returns:
org.virtualbox_5_0.GuestSessionStatus

getEnvironmentChanges

public java.util.List<java.lang.String> getEnvironmentChanges()
The set of scheduled environment changes to the base environment of the session. They are in putenv format, i.e. "VAR=VALUE" for setting and "VAR" for unsetting. One entry per variable (change). The changes are applied when creating new guest processes. This is writable, so to undo all the scheduled changes, assign it an empty array.

Returns:
List<String>

setEnvironmentChanges

public void setEnvironmentChanges(java.util.List<java.lang.String> value)
The set of scheduled environment changes to the base environment of the session. They are in putenv format, i.e. "VAR=VALUE" for setting and "VAR" for unsetting. One entry per variable (change). The changes are applied when creating new guest processes. This is writable, so to undo all the scheduled changes, assign it an empty array.

Parameters:
value - List<String>

getEnvironmentBase

public java.util.List<java.lang.String> getEnvironmentBase()
The base environment of the session. They are on the "VAR=VALUE" form, one array entry per variable.Access fails with VBOX_E_NOT_SUPPORTED if the guest additions does not support the session base environment feature. Support for this was introduced with protocol version XXXX. Access fails with VBOX_E_INVALID_OBJECT_STATE if the guest additions has yet to report the session base environment.

Returns:
List<String>

getProcesses

public java.util.List<IGuestProcess> getProcesses()
Returns all current guest processes.

Returns:
List<org.virtualbox_5_0.IGuestProcess>

getPathStyle

public PathStyle getPathStyle()
The style of paths used by the guest. Handy for giving the right kind of path specifications tofileOpen(String,org.virtualbox_5_0.FileAccessMode,org.virtualbox_5_0.FileOpenAction,Long)and similar methods.

Returns:
org.virtualbox_5_0.PathStyle

getCurrentDirectory

public java.lang.String getCurrentDirectory()
The current directory of the session. Guest path style. Expected result codes:
E_NOTIMPLThis attribute is not implemented yet.

Returns:
String

setCurrentDirectory

public void setCurrentDirectory(java.lang.String value)
The current directory of the session. Guest path style. Expected result codes:
E_NOTIMPLThis attribute is not implemented yet.

Parameters:
value - String

getDirectories

public java.util.List<IGuestDirectory> getDirectories()
Returns all currently opened guest directories.

Returns:
List<org.virtualbox_5_0.IGuestDirectory>

getFiles

public java.util.List<IGuestFile> getFiles()
Returns all currently opened guest files.

Returns:
List<org.virtualbox_5_0.IGuestFile>

getEventSource

public IEventSource getEventSource()
Event source for guest session events.

Returns:
org.virtualbox_5_0.IEventSource

queryInterface

public static IGuestSession queryInterface(IUnknown obj)

close

public void close()
Closes this session. All opened guest directories, files and processes which are not referenced by clients anymore will be closed. Guest processes which fall into this category and still are running in the guest will be terminated automatically.


directoryCopy

public IProgress directoryCopy(java.lang.String source,
                               java.lang.String destination,
                               java.util.List<DirectoryCopyFlags> flags)
Recursively copies a directory from one guest location to another.

Parameters:
source - The path to the directory to copy (in the guest). Guest path style.
destination - The path to the target directory (in the guest). Unless theDirectoryCopyFlags.CopyIntoExistingflag is given, the directory shall not already exist. Guest path style.
flags - Zero or moreDirectoryCopyFlagsvalues.
Returns:
Progress object to track the operation to completion. Expected result codes:
E_NOTIMPLNot yet implemented.

directoryCopyFromGuest

public IProgress directoryCopyFromGuest(java.lang.String source,
                                        java.lang.String destination,
                                        java.util.List<DirectoryCopyFlags> flags)
Recursively copies a directory from the guest to the host.

Parameters:
source - Path to the directory on the guest side that should be copied to the host. Guest path style.
destination - Where to put the directory on the host. Unless theDirectoryCopyFlags.CopyIntoExistingflag is given, the directory shall not already exist. Host path style.
flags - Zero or moreDirectoryCopyFlagsvalues.
Returns:
Progress object to track the operation to completion. Expected result codes:
E_NOTIMPLNot yet implemented.

directoryCopyToGuest

public IProgress directoryCopyToGuest(java.lang.String source,
                                      java.lang.String destination,
                                      java.util.List<DirectoryCopyFlags> flags)
Recursively copies a directory from the host to the guest.

Parameters:
source - Path to the directory on the host side that should be copied to the guest. Host path style.
destination - Where to put the file in the guest. Unless theDirectoryCopyFlags.CopyIntoExistingflag is given, the directory shall not already exist. Guest style path.
flags - Zero or moreDirectoryCopyFlagsvalues.
Returns:
Progress object to track the operation to completion. Expected result codes:
E_NOTIMPLNot yet implemented.

directoryCreate

public void directoryCreate(java.lang.String path,
                            java.lang.Long mode,
                            java.util.List<DirectoryCreateFlag> flags)
Creates a directory in the guest.

Parameters:
path - Path to the directory directory to be created. Guest path style.
mode - The UNIX-style access mode mask to create the directory with. Whether/how all three access groups and associated access rights are realized is guest OS dependent. The API does the best it can on each OS.
flags - Zero or moreDirectoryCreateFlagflags. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError while creating the directory.

directoryCreateTemp

public java.lang.String directoryCreateTemp(java.lang.String templateName,
                                            java.lang.Long mode,
                                            java.lang.String path,
                                            java.lang.Boolean secure)
Creates a temporary directory in the guest.

Parameters:
templateName - Template for the name of the directory to create. This must contain at least one 'X' character. The first group of consecutive 'X' characters in the template will be replaced by a random alphanumeric string to produce a unique name.
mode - The UNIX-style access mode mask to create the directory with. Whether/how all three access groups and associated access rights are realized is guest OS dependent. The API does the best it can on each OS. This parameter is ignore if the secure parameter is set to true.
path - The path to the directory in which the temporary directory should be created. Guest path style.
secure - Whether to fail if the directory can not be securely created. Currently this means that another unprivileged user cannot manipulate the path specified or remove the temporary directory after it has been created. Also causes the mode specified to be ignored. May not be supported on all guest types.
Returns:
On success this will contain the full path to the created directory. Guest path style. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDThe operation is not possible as requested on this particular guest type.
E_INVALIDARGInvalid argument. This includes an incorrectly formatted template, or a non-absolute path.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORThe temporary directory could not be created. Possible reasons include a non-existing path or an insecure path when the secure option was requested.
NOTE: It is strongly recommended to use 0700.

directoryExists

public java.lang.Boolean directoryExists(java.lang.String path,
                                         java.lang.Boolean followSymlinks)
Checks whether a directory exists in the guest or not.

Parameters:
path - Path to the directory to check if exists. Guest path style.
followSymlinks - If true, symbolic links in the final component will be followed and the existance of the symlink target made the question for this method. If false, a symbolic link in the final component will make the method return false (because a symlink isn't a directory).
Returns:
Returns true if the directory exists, false if not. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError while checking existence of the directory specified.

directoryOpen

public IGuestDirectory directoryOpen(java.lang.String path,
                                     java.lang.String filter,
                                     java.util.List<DirectoryOpenFlag> flags)
Opens a directory in the guest and creates aIGuestDirectoryobject that can be used for further operations.

Parameters:
path - Path to the directory to open. Guest path style.
filter - Optional directory listing filter to apply. This uses the DOS/NT style wildcard characters '?' and '*'.
flags - Zero or moreDirectoryOpenFlagflags.
Returns:
IGuestDirectoryobject containing the opened directory. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDDirectory to open was not found.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError while opening the directory.
NOTE: This method follows symbolic links by default at the moment, this may change in the future.

directoryRemove

public void directoryRemove(java.lang.String path)
Removes a guest directory if empty.

Parameters:
path - Path to the directory that should be removed. Guest path style. NOTE: Symbolic links in the final component will not be followed, instead an not-a-directory error is reported.

directoryRemoveRecursive

public IProgress directoryRemoveRecursive(java.lang.String path,
                                          java.util.List<DirectoryRemoveRecFlag> flags)
Removes a guest directory recursively.

Parameters:
path - Path of the directory that is to be removed recursively. Guest path style.
flags - Zero or moreDirectoryRemoveRecFlagflags.
Returns:
Progress object to track the operation completion. This is not implemented yet and therefore this method call will block until deletion is completed. NOTE: WARNING!! THE FLAGS ARE NOT CURRENTLY IMPLEMENTED. THE IMPLEMENTATION WORKS AS IF FLAGS WAS SET TODirectoryRemoveRecFlag.ContentAndDir. NOTE: If the final path component is a symbolic link, this method will fail as it can only be applied to directories. NOTE: WARNING! SPECIFYINGDirectoryRemoveRecFlag.ContentAndDirIS MANDATORY AT THE MOMENT!!

environmentScheduleSet

public void environmentScheduleSet(java.lang.String name,
                                   java.lang.String value)
Schedules setting an environment variable when creating the next guest process. This affects thegetEnvironmentChanges()attribute.

Parameters:
name - Name of the environment variable to set. This cannot be empty nor can it contain any equal signs.
value - Value to set the session environment variable to.

environmentScheduleUnset

public void environmentScheduleUnset(java.lang.String name)
Schedules unsetting (removing) an environment variable when creating the next guest process. This affects thegetEnvironmentChanges()attribute.

Parameters:
name - Name of the environment variable to unset. This cannot be empty nor can it contain any equal signs.

environmentGetBaseVariable

public java.lang.String environmentGetBaseVariable(java.lang.String name)
Gets an environment variable from the session's base environment (getEnvironmentBase()).

Parameters:
name - Name of the environment variable to get.This cannot be empty nor can it contain any equal signs.
Returns:
The value of the variable. Empty if not found. To deal with variables that may have empty values, useenvironmentDoesBaseVariableExist(String). Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDIf the guest additions does not support the session base environment feature. Support for this was introduced with protocol version XXXX.
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATEIf the guest additions has yet to report the session base environment.

environmentDoesBaseVariableExist

public java.lang.Boolean environmentDoesBaseVariableExist(java.lang.String name)
Checks if the given environment variable exists in the session's base environment (getEnvironmentBase()).

Parameters:
name - Name of the environment variable to look for. This cannot be empty nor can it contain any equal signs.
Returns:
TRUE if the variable exists, FALSE if not. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDIf the guest additions does not support the session base environment feature. Support for this was introduced with protocol version XXXX.
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATEIf the guest additions has yet to report the session base environment.

fileCopy

public IProgress fileCopy(java.lang.String source,
                          java.lang.String destination,
                          java.util.List<FileCopyFlag> flags)
Copies a file from one guest location to another.

Parameters:
source - The path to the file to copy (in the guest). Guest path style.
destination - The path to the target file (in the guest). This cannot be a directory. Guest path style.
flags - Zero or moreFileCopyFlagvalues.
Returns:
Progress object to track the operation to completion. Expected result codes:
E_NOTIMPLNot yet implemented.
NOTE: Will overwrite the destination file unlessFileCopyFlag.NoReplaceis specified.

fileCopyFromGuest

public IProgress fileCopyFromGuest(java.lang.String source,
                                   java.lang.String destination,
                                   java.util.List<FileCopyFlag> flags)
Copies a file from the guest to the host.

Parameters:
source - Path to the file on the guest side that should be copied to the host. Guest path style.
destination - Where to put the file on the host (file, not directory). Host path style.
flags - Zero or moreFileCopyFlagvalues.
Returns:
Progress object to track the operation to completion. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError starting the copy operation.
NOTE: Will overwrite the destination file unlessFileCopyFlag.NoReplaceis specified.

fileCopyToGuest

public IProgress fileCopyToGuest(java.lang.String source,
                                 java.lang.String destination,
                                 java.util.List<FileCopyFlag> flags)
Copies a file from the host to the guest.

Parameters:
source - Path to the file on the host side that should be copied to the guest. Host path style.
destination - Where to put the file in the guest (file, not directory). Guest style path.
flags - Zero or moreFileCopyFlagvalues.
Returns:
Progress object to track the operation to completion. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError starting the copy operation.
NOTE: Will overwrite the destination file unlessFileCopyFlag.NoReplaceis specified.

fileCreateTemp

public IGuestFile fileCreateTemp(java.lang.String templateName,
                                 java.lang.Long mode,
                                 java.lang.String path,
                                 java.lang.Boolean secure)
Creates a temporary file in the guest.

Parameters:
templateName - Template for the name of the file to create. This must contain at least one 'X' character. The first group of consecutive 'X' characters in the template will be replaced by a random alphanumeric string to produce a unique name.
mode - The UNIX-style access mode mask to create the file with. Whether/how all three access groups and associated access rights are realized is guest OS dependent. The API does the best it can on each OS. This parameter is ignore if the secure parameter is set to true.
path - The path to the directory in which the temporary file should be created.
secure - Whether to fail if the file can not be securely created. Currently this means that another unprivileged user cannot manipulate the path specified or remove the temporary file after it has been created. Also causes the mode specified to be ignored. May not be supported on all guest types.
Returns:
On success this will contain an open file object for the new temporary file. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDThe operation is not possible as requested on this particular guest OS.
E_INVALIDARGInvalid argument. This includes an incorrectly formatted template, or a non-absolute path.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORThe temporary file could not be created. Possible reasons include a non-existing path or an insecure path when the secure option was requested.
NOTE: It is strongly recommended to use 0600.

fileExists

public java.lang.Boolean fileExists(java.lang.String path,
                                    java.lang.Boolean followSymlinks)
Checks whether a regular file exists in the guest or not.

Parameters:
path - Path to the alleged regular file. Guest path style.
followSymlinks - If true, symbolic links in the final component will be followed and the existance of the symlink target made the question for this method. If false, a symbolic link in the final component will make the method return false (because a symlink isn't a regular file).
Returns:
Returns true if the file exists, false if not. false is also return if this path does not point to a file object. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError while checking existence of the file specified.

fileOpen

public IGuestFile fileOpen(java.lang.String path,
                           FileAccessMode accessMode,
                           FileOpenAction openAction,
                           java.lang.Long creationMode)
Opens a file and creates aIGuestFileobject that can be used for further operations.

Parameters:
path - Path to file to open. Guest path style.
accessMode - The file access mode (read, write and/or append). SeeFileAccessModefor details.
openAction - What action to take depending on whether the file exists or not. SeeFileOpenActionfor details.
creationMode - The UNIX-style access mode mask to create the file with if openAction requested the file to be created (otherwise ignored). Whether/how all three access groups and associated access rights are realized is guest OS dependent. The API does the best it can on each OS.
Returns:
IGuestFileobject representing the opened file. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDFile to open was not found.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError while opening the file.

fileOpenEx

public IGuestFile fileOpenEx(java.lang.String path,
                             FileAccessMode accessMode,
                             FileOpenAction openAction,
                             FileSharingMode sharingMode,
                             java.lang.Long creationMode,
                             java.util.List<FileOpenExFlags> flags)
Opens a file and creates aIGuestFileobject that can be used for further operations, extended version.

Parameters:
path - Path to file to open. Guest path style.
accessMode - The file access mode (read, write and/or append). SeeFileAccessModefor details.
openAction - What action to take depending on whether the file exists or not. SeeFileOpenActionfor details.
sharingMode - The file sharing mode in the guest. This parameter is currently ignore for all guest OSes. It will in the future be implemented for Windows, OS/2 and maybe Solaris guests only, the others will ignore it. UseFileSharingMode.All.
creationMode - The UNIX-style access mode mask to create the file with if openAction requested the file to be created (otherwise ignored). Whether/how all three access groups and associated access rights are realized is guest OS dependent. The API does the best it can on each OS.
flags - Zero or moreFileOpenExFlagsvalues.
Returns:
IGuestFileobject representing the opened file. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDFile to open was not found.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError while opening the file.

fileQuerySize

public java.lang.Long fileQuerySize(java.lang.String path,
                                    java.lang.Boolean followSymlinks)
Queries the size of a regular file in the guest.

Parameters:
path - Path to the file which size is requested. Guest path style.
followSymlinks - It true, symbolic links in the final path component will be followed to their target, and the size of the target is returned. If false, symbolic links in the final path component will make the method call fail (symblink is not a regular file).
Returns:
Queried file size. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDFile to was not found.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError querying file size.

fsObjExists

public java.lang.Boolean fsObjExists(java.lang.String path,
                                     java.lang.Boolean followSymlinks)
Checks whether a file system object (file, directory, etc) exists in the guest or not.

Parameters:
path - Path to the file system object to check the existance of. Guest path style.
followSymlinks - If true, symbolic links in the final component will be followed and the method will instead check if the target exists. If false, symbolic links in the final component will satisfy the method and it will return true in exists.
Returns:
Returns true if the file exists, false if not. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError while checking existence of the file specified.

fsObjQueryInfo

public IGuestFsObjInfo fsObjQueryInfo(java.lang.String path,
                                      java.lang.Boolean followSymlinks)
Queries information about a file system object (file, directory, etc) in the guest.

Parameters:
path - Path to the file system object to gather information about. Guest path style.
followSymlinks - Information about symbolic links is returned if false. Otherwise, symbolic links are followed and the returned information concerns itself with the symlink target if true.
Returns:
IGuestFsObjInfoobject containing the information. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDThe file system object was not found.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError while querying information.

fsObjRemove

public void fsObjRemove(java.lang.String path)
Removes a file system object (file, symlink, etc) in the guest. Will not work on directories, usedirectoryRemove(String)to remove directories.

Parameters:
path - Path to the file system object to remove. Guest style path. Expected result codes:
E_NOTIMPLThe method has not been implemented yet.
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDThe file system object was not found.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORFor most other errors. We know this is unhelpful, will fix shortly...
NOTE: This method will remove symbolic links in the final path component, not follow them.

fsObjRename

public void fsObjRename(java.lang.String oldPath,
                        java.lang.String newPath,
                        java.util.List<FsObjRenameFlag> flags)
Renames a file system object (file, directory, symlink, etc) in the guest.

Parameters:
oldPath - The current path to the object. Guest path style.
newPath - The new path to the object. Guest path style.
flags - Zero or moreFsObjRenameFlagvalues. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDThe file system object was not found.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORFor most other errors. We know this is unhelpful, will fix shortly...

fsObjMove

public IProgress fsObjMove(java.lang.String source,
                           java.lang.String destination,
                           java.util.List<FsObjMoveFlags> flags)
Moves a file system object (file, directory, symlink, etc) from one guest location to another. This differs fromfsObjRename(String,String,List)in that it can move accross file system boundraries. In that case it will perform a copy and then delete the original. For directories, this can take a while and is subject to races.

Parameters:
source - Path to the file to move. Guest path style.
destination - Where to move the file to (file, not directory). Guest path style.
flags - Zero or moreFsObjMoveFlagsvalues.
Returns:
Progress object to track the operation to completion. Expected result codes:
E_NOTIMPLNot yet implemented.

fsObjSetACL

public void fsObjSetACL(java.lang.String path,
                        java.lang.Boolean followSymlinks,
                        java.lang.String acl,
                        java.lang.Long mode)
Sets the access control list (ACL) of a file system object (file, directory, etc) in the guest.

Parameters:
path - Full path of the file system object which ACL to set
followSymlinks - If true symbolic links in the final component will be followed, otherwise, if false, the method will work directly on a symbolic link in the final component.
acl - The ACL specification string. To-be-defined.
mode - UNIX-style mode mask to use if acl is empty. As mention indirectoryCreate(String,Long,List)this is realized on a best effort basis and the exact behavior depends on the Guest OS. Expected result codes:
E_NOTIMPLThe method is not implemented yet.

processCreate

public IGuestProcess processCreate(java.lang.String executable,
                                   java.util.List<java.lang.String> arguments,
                                   java.util.List<java.lang.String> environmentChanges,
                                   java.util.List<ProcessCreateFlag> flags,
                                   java.lang.Long timeoutMS)
Creates a new process running in the guest. The new process will be started asynchronously, meaning on return of this function it is not be guaranteed that the guest process is in a started state. To wait for successful startup, use theIProcess.waitFor(Long,Long)call.

Parameters:
executable - Full path to the file to execute in the guest. The file has to exists in the guest VM with executable right to the session user in order to succeed. If empty/null, the first entry in the arguments array will be used instead (i.e. argv[0]).
arguments - Array of arguments passed to the new process.
environmentChanges - Set of environment changes to complementgetEnvironmentChanges(). Takes precedence over the session ones. The changes are in putenv format, i.e. "VAR=VALUE" for setting and "VAR" for unsetting. The changes are applied to the base environment of the impersonated guest user (getEnvironmentBase()) when creating the process. (This is done on the guest side of things in order to be compatible with older guest additions. That is one of the motivations for not passing in the whole environment here.)
flags - Process creation flags; seeProcessCreateFlagfor more information.
timeoutMS - Timeout (in ms) for limiting the guest process' running time. Pass 0 for an infinite timeout. On timeout the guest process will be killed and its status will be put to an appropriate value. SeeProcessStatusfor more information.
Returns:
Guest process object of the newly created process. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORError creating guest process.
NOTE: Starting at VirtualBox 4.2 guest process execution by is default limited to serve up to 255 guest processes at a time. If all 255 guest processes are active and running, creating a new guest process will result in an error. If ProcessCreateFlag_WaitForStdOut and/or ProcessCreateFlag_WaitForStdErr are set, the guest process will not enter the terminated state until all data from the specified streams have been read read. NOTE: Starting with VirtualBox 5.0 this array starts with argument 0 instead of argument 1 as in previous versions. Whether the zeroth argument can be passed to the guest depends on the VBoxService version running there. If you depend on this, check that thegetProtocolVersion()is 3 or higher.

processCreateEx

public IGuestProcess processCreateEx(java.lang.String executable,
                                     java.util.List<java.lang.String> arguments,
                                     java.util.List<java.lang.String> environmentChanges,
                                     java.util.List<ProcessCreateFlag> flags,
                                     java.lang.Long timeoutMS,
                                     ProcessPriority priority,
                                     java.util.List<java.lang.Integer> affinity)
Creates a new process running in the guest with the extended options for setting the process priority and affinity. SeeprocessCreate(String,List,List,List,Long)for more information.

Parameters:
executable - Full path to the file to execute in the guest. The file has to exists in the guest VM with executable right to the session user in order to succeed. If empty/null, the first entry in the arguments array will be used instead (i.e. argv[0]).
arguments - Array of arguments passed to the new process.
environmentChanges - Set of environment changes to complementgetEnvironmentChanges(). Takes precedence over the session ones. The changes are in putenv format, i.e. "VAR=VALUE" for setting and "VAR" for unsetting. The changes are applied to the base environment of the impersonated guest user (getEnvironmentBase()) when creating the process. (This is done on the guest side of things in order to be compatible with older guest additions. That is one of the motivations for not passing in the whole environment here.)
flags - Process creation flags, seeProcessCreateFlagfor detailed description of available flags.
timeoutMS - Timeout (in ms) for limiting the guest process' running time. Pass 0 for an infinite timeout. On timeout the guest process will be killed and its status will be put to an appropriate value. SeeProcessStatusfor more information.
priority - Process priority to use for execution, seeProcessPriorityfor available priority levels.
affinity - Processor affinity to set for the new process. This is a list of guest CPU numbers the process is allowed to run on.
Returns:
Guest process object of the newly created process. NOTE: Starting with VirtualBox 5.0 this array starts with argument 0 instead of argument 1 as in previous versions. Whether the zeroth argument can be passed to the guest depends on the VBoxService version running there. If you depend on this, check that thegetProtocolVersion()is 3 or higher. NOTE: This is silently ignored if not supported by guest additions. NOTE: This is silently ignored if the guest does not support setting the affinity of processes, or if the guest additions does not implemet this feature.

processGet

public IGuestProcess processGet(java.lang.Long pid)
Gets a certain guest process by its process ID (PID).

Parameters:
pid - Process ID (PID) to get guest process for.
Returns:
Guest process of specified process ID (PID).

symlinkCreate

public void symlinkCreate(java.lang.String symlink,
                          java.lang.String target,
                          SymlinkType type)
Creates a symbolic link in the guest.

Parameters:
symlink - Path to the symbolic link that should be created. Guest path style.
target - The path to the symbolic link target. If not an absolute, this will be relative to the symlink location at access time. Guest path style.
type - The symbolic link type (mainly for Windows). SeeSymlinkTypefor more information. Expected result codes:
E_NOTIMPLThe method is not implemented yet.

symlinkExists

public java.lang.Boolean symlinkExists(java.lang.String symlink)
Checks whether a symbolic link exists in the guest.

Parameters:
symlink - Path to the alleged symbolic link. Guest path style.
Returns:
Returns true if the symbolic link exists. Returns false if it does not exist, if the file system object identified by the path is not a symbolic link, or if the object type is inaccessible to the user, or if the symlink argument is empty. Expected result codes:
E_NOTIMPLThe method is not implemented yet.

symlinkRead

public java.lang.String symlinkRead(java.lang.String symlink,
                                    java.util.List<SymlinkReadFlag> flags)
Reads the target value of a symbolic link in the guest.

Parameters:
symlink - Path to the symbolic link to read.
flags - Zero or moreSymlinkReadFlagvalues.
Returns:
Target value of the symbolic link. Guest path style. Expected result codes:
E_NOTIMPLThe method is not implemented yet.

waitFor

public GuestSessionWaitResult waitFor(java.lang.Long waitFor,
                                      java.lang.Long timeoutMS)
Waits for one or more events to happen.

Parameters:
waitFor - Specifies what to wait for; seeGuestSessionWaitForFlagfor more information.
timeoutMS - Timeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
Returns:
The overall wait result; seeGuestSessionWaitResultfor more information.

waitForArray

public GuestSessionWaitResult waitForArray(java.util.List<GuestSessionWaitForFlag> waitFor,
                                           java.lang.Long timeoutMS)
Waits for one or more events to happen. Scriptable version ofwaitFor(Long,Long).

Parameters:
waitFor - Specifies what to wait for; seeGuestSessionWaitForFlagfor more information.
timeoutMS - Timeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
Returns:
The overall wait result; seeGuestSessionWaitResultfor more information.