public class IGuestSession extends IUnknown
IGuest.createSession(String,String,String,String)
.
There can be a maximum of 32 sessions at once per VM, whereas session 0
always is reserved for the root session (the root session is part of that
limit).
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_7_0.FileAccessMode,org.virtualbox_7_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 (see
the corresponding functions for more).
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_7_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: {234F0627-866D-48C2-91A5-4C9D50F04928}
Constructor and Description |
---|
IGuestSession(java.lang.String wrapped,
org.virtualbox_7_0.ObjectRefManager objMgr,
org.virtualbox_7_0.jaxws.VboxPortType port) |
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes this session.
|
IProgress |
copyFromGuest(java.util.List<java.lang.String> sources,
java.util.List<java.lang.String> filters,
java.util.List<java.lang.String> flags,
java.lang.String destination)
Copies directories and/or files from guest to the host.
|
IProgress |
copyToGuest(java.util.List<java.lang.String> sources,
java.util.List<java.lang.String> filters,
java.util.List<java.lang.String> flags,
java.lang.String destination)
Copies directories and/or files from host to the guest.
|
IProgress |
directoryCopy(java.lang.String source,
java.lang.String destination,
java.util.List<DirectoryCopyFlag> flags)
Recursively copies a directory from one guest location to another.
|
IProgress |
directoryCopyFromGuest(java.lang.String source,
java.lang.String destination,
java.util.List<DirectoryCopyFlag> flags)
Recursively copies a directory from the guest to the host.
|
IProgress |
directoryCopyToGuest(java.lang.String source,
java.lang.String destination,
java.util.List<DirectoryCopyFlag> 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 a
IGuestDirectory object 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 a
IGuestFile object 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<FileOpenExFlag> flags)
Opens a file and creates a
IGuestFile object 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.
|
IProgress |
fsObjCopyArray(java.util.List<java.lang.String> source,
java.lang.String destination,
java.util.List<FileCopyFlag> flags)
Copies file system objects (files, directories, symlinks, etc) from one
guest location to another.
|
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<FsObjMoveFlag> flags)
Moves a file system object (file, directory, symlink, etc) from one
guest location to another.
|
IProgress |
fsObjMoveArray(java.util.List<java.lang.String> source,
java.lang.String destination,
java.util.List<FsObjMoveFlag> flags)
Moves file system objects (files, directories, symlinks, 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.
|
IProgress |
fsObjRemoveArray(java.util.List<java.lang.String> path)
Removes multiple file system objects (files, directories, symlinks, 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.Long |
fsQueryFreeSpace(java.lang.String path)
Returns the free space (in bytes) of a given path.
|
IGuestFsInfo |
fsQueryInfo(java.lang.String path)
Returns file system information for a given path.
|
java.lang.String |
getCurrentDirectory()
Gets or sets 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.
|
java.lang.String |
getUserDocuments()
Returns the user's documents directory.
|
java.lang.String |
getUserHome()
Returns the user's home / profile directory.
|
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)
Gets or sets 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.
|
getObjMgr, getRemoteWSPort, getWrapped, releaseRemote
public IGuestSession(java.lang.String wrapped, org.virtualbox_7_0.ObjectRefManager objMgr, org.virtualbox_7_0.jaxws.VboxPortType port)
public java.lang.String getUser()
public java.lang.String getDomain()
public java.lang.String getName()
public java.lang.Long getId()
public java.lang.Long getTimeout()
E_NOTIMPL
- This attribute is not implemented yet.public void setTimeout(java.lang.Long value)
E_NOTIMPL
- This attribute is not implemented yet.value
- Longpublic java.lang.Long getProtocolVersion()
public GuestSessionStatus getStatus()
public java.util.List<java.lang.String> getEnvironmentChanges()
public void setEnvironmentChanges(java.util.List<java.lang.String> value)
value
- List<String>public java.util.List<java.lang.String> getEnvironmentBase()
public java.util.List<IGuestProcess> getProcesses()
public PathStyle getPathStyle()
fileOpen(String,org.virtualbox_7_0.FileAccessMode,org.virtualbox_7_0.FileOpenAction,Long)
and similar methods.public java.lang.String getCurrentDirectory()
E_NOTIMPL
- This attribute is not implemented yet.public void setCurrentDirectory(java.lang.String value)
E_NOTIMPL
- This attribute is not implemented yet.value
- Stringpublic java.lang.String getUserHome()
public java.lang.String getUserDocuments()
public java.util.List<IGuestDirectory> getDirectories()
public java.util.List<IGuestFile> getFiles()
public IEventSource getEventSource()
public static IGuestSession queryInterface(IUnknown obj)
public void close()
public IProgress copyFromGuest(java.util.List<java.lang.String> sources, java.util.List<java.lang.String> filters, java.util.List<java.lang.String> flags, java.lang.String destination)
sources
- Paths to directories and/or files on the guest side that should be
copied to the host. If the path ends with a path delimiter, only
the directory's content is being copied. Guest path style.filters
- Array of source filters. This uses the
DOS/NT style wildcard characters '?' and '*'.flags
- Array of comma-separated list of source flags.
The following flags are available:CopyIntoExisting
NoReplace
FollowLinks
Update
destination
- Where to put the sources on the host. Host path style.public IProgress copyToGuest(java.util.List<java.lang.String> sources, java.util.List<java.lang.String> filters, java.util.List<java.lang.String> flags, java.lang.String destination)
sources
- Paths to directories and/or files on the host side that should be
copied to the guest. If the path ends with a path delimiter, only
the directory's content is being copied. Host path style.filters
- Array of source filters. This uses the
DOS/NT style wildcard characters '?' and '*'.flags
- Array of comma-separated list of source flags.
The following flags are available:CopyIntoExisting
NoReplace
FollowLinks
Update
destination
- Where to put the sources on the guest. Guest path style.public IProgress directoryCopy(java.lang.String source, java.lang.String destination, java.util.List<DirectoryCopyFlag> flags)
E_NOTIMPL
- Not yet implemented.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 theDirectoryCopyFlag.CopyIntoExisting
flag is given, the
directory shall not already exist. Guest path style.flags
- Zero or moreDirectoryCopyFlag
values.public IProgress directoryCopyFromGuest(java.lang.String source, java.lang.String destination, java.util.List<DirectoryCopyFlag> flags)
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 theDirectoryCopyFlag.CopyIntoExisting
flag is given, the
directory shall not already exist. Host path style.flags
- Zero or moreDirectoryCopyFlag
values.public IProgress directoryCopyToGuest(java.lang.String source, java.lang.String destination, java.util.List<DirectoryCopyFlag> flags)
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 theDirectoryCopyFlag.CopyIntoExisting
flag is given, the
directory shall not already exist. Guest style path.flags
- Zero or moreDirectoryCopyFlag
values.public void directoryCreate(java.lang.String path, java.lang.Long mode, java.util.List<DirectoryCreateFlag> flags)
VBOX_E_IPRT_ERROR
- Error while creating the directory.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 moreDirectoryCreateFlag
flags.public java.lang.String directoryCreateTemp(java.lang.String templateName, java.lang.Long mode, java.lang.String path, java.lang.Boolean secure)
VBOX_E_NOT_SUPPORTED
- The operation is not possible as requested on this particular
guest type.E_INVALIDARG
- Invalid argument. This includes an incorrectly formatted template,
or a non-absolute path.VBOX_E_IPRT_ERROR
- The temporary directory could not be created. Possible reasons
include a non-existing path or an insecure path when the secure
option was requested.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 ignored 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.public java.lang.Boolean directoryExists(java.lang.String path, java.lang.Boolean followSymlinks)
VBOX_E_IPRT_ERROR
- Error while checking existence of the directory specified.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).public IGuestDirectory directoryOpen(java.lang.String path, java.lang.String filter, java.util.List<DirectoryOpenFlag> flags)
IGuestDirectory
object that can be used for further operations.
VBOX_E_OBJECT_NOT_FOUND
- Directory to open was not found.VBOX_E_IPRT_ERROR
- Error while opening the directory.VBOX_E_MAXIMUM_REACHED
- The maximum of concurrent guest directories has been reached.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 moreDirectoryOpenFlag
flags.IGuestDirectory
object containing the opened directory.
NOTE: This method follows symbolic links by default at the moment, this
may change in the future.
NOTE: One idiosyncrasy of the current implementation is that you will NOT
get VBOX_E_OBJECT_NOT_FOUND returned here if the directory doesn't exist.
Instead the read function will fail with VBOX_E_IPRT_ERROR. This will
be fixed soon.public void directoryRemove(java.lang.String path)
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.public IProgress directoryRemoveRecursive(java.lang.String path, java.util.List<DirectoryRemoveRecFlag> flags)
path
- Path of the directory that is to be removed recursively. Guest
path style.flags
- Zero or moreDirectoryRemoveRecFlag
flags.DirectoryRemoveRecFlag.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.ContentAndDir
IS
MANDATORY AT THE MOMENT!!public void environmentScheduleSet(java.lang.String name, java.lang.String value)
getEnvironmentChanges()
attribute.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.public void environmentScheduleUnset(java.lang.String name)
getEnvironmentChanges()
attribute.name
- Name of the environment variable to unset. This cannot be empty
nor can it contain any equal signs.public java.lang.String environmentGetBaseVariable(java.lang.String name)
getEnvironmentBase()
).
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.VBOX_E_INVALID_OBJECT_STATE
- If the Guest Additions has
yet to report the session base environment.name
- Name of the environment variable to get.This cannot be empty
nor can it contain any equal signs.environmentDoesBaseVariableExist(String)
.public java.lang.Boolean environmentDoesBaseVariableExist(java.lang.String name)
getEnvironmentBase()
).
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.VBOX_E_INVALID_OBJECT_STATE
- If the Guest Additions has
yet to report the session base environment.name
- Name of the environment variable to look for. This cannot be
empty nor can it contain any equal signs.public IProgress fileCopy(java.lang.String source, java.lang.String destination, java.util.List<FileCopyFlag> flags)
E_NOTIMPL
- Not yet implemented.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 moreFileCopyFlag
values.FileCopyFlag.NoReplace
is specified.public IProgress fileCopyFromGuest(java.lang.String source, java.lang.String destination, java.util.List<FileCopyFlag> flags)
VBOX_E_IPRT_ERROR
- Error starting the copy operation.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 moreFileCopyFlag
values.FileCopyFlag.NoReplace
is specified.public IProgress fileCopyToGuest(java.lang.String source, java.lang.String destination, java.util.List<FileCopyFlag> flags)
VBOX_E_IPRT_ERROR
- Error starting the copy operation.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 moreFileCopyFlag
values.FileCopyFlag.NoReplace
is specified.public IGuestFile fileCreateTemp(java.lang.String templateName, java.lang.Long mode, java.lang.String path, java.lang.Boolean secure)
VBOX_E_NOT_SUPPORTED
- The operation is not possible as requested on this particular
guest OS.E_INVALIDARG
- Invalid argument. This includes an incorrectly formatted template,
or a non-absolute path.VBOX_E_IPRT_ERROR
- The temporary file could not be created. Possible reasons include
a non-existing path or an insecure path when the secure
option was requested.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.public java.lang.Boolean fileExists(java.lang.String path, java.lang.Boolean followSymlinks)
VBOX_E_IPRT_ERROR
- Error while checking existence of the file specified.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).public IGuestFile fileOpen(java.lang.String path, FileAccessMode accessMode, FileOpenAction openAction, java.lang.Long creationMode)
IGuestFile
object that
can be used for further operations.
VBOX_E_OBJECT_NOT_FOUND
- File to open was not found.VBOX_E_IPRT_ERROR
- Error while opening the file.VBOX_E_MAXIMUM_REACHED
- The maximum of concurrent guest files has been reached.path
- Path to file to open. Guest path style.accessMode
- The file access mode (read, write and/or append).
SeeFileAccessMode
for details.openAction
- What action to take depending on whether the file exists or not.
SeeFileOpenAction
for 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.IGuestFile
object representing the opened file.public IGuestFile fileOpenEx(java.lang.String path, FileAccessMode accessMode, FileOpenAction openAction, FileSharingMode sharingMode, java.lang.Long creationMode, java.util.List<FileOpenExFlag> flags)
IGuestFile
object that
can be used for further operations, extended version.
VBOX_E_OBJECT_NOT_FOUND
- File to open was not found.VBOX_E_IPRT_ERROR
- Error while opening the file.path
- Path to file to open. Guest path style.accessMode
- The file access mode (read, write and/or append).
SeeFileAccessMode
for details.openAction
- What action to take depending on whether the file exists or not.
SeeFileOpenAction
for 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 moreFileOpenExFlag
values.IGuestFile
object representing the opened file.public java.lang.Long fileQuerySize(java.lang.String path, java.lang.Boolean followSymlinks)
VBOX_E_OBJECT_NOT_FOUND
- File to was not found.VBOX_E_IPRT_ERROR
- Error querying file size.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).public java.lang.Boolean fsObjExists(java.lang.String path, java.lang.Boolean followSymlinks)
VBOX_E_IPRT_ERROR
- Error while checking existence of the file specified.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.public IGuestFsObjInfo fsObjQueryInfo(java.lang.String path, java.lang.Boolean followSymlinks)
VBOX_E_OBJECT_NOT_FOUND
- The file system object was not found.VBOX_E_IPRT_ERROR
- Error while querying information.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.IGuestFsObjInfo
object containing the information.public void fsObjRemove(java.lang.String path)
directoryRemove(String)
to remove directories.
E_NOTIMPL
- The method has not been implemented yet.VBOX_E_OBJECT_NOT_FOUND
- The file system object was not found.VBOX_E_IPRT_ERROR
- For most other errors. We know this is unhelpful, will fix shortly...path
- Path to the file system object to remove. Guest style path.
NOTE: This method will remove symbolic links in the final path
component, not follow them.public IProgress fsObjRemoveArray(java.util.List<java.lang.String> path)
E_NOTIMPL
- The method has not been implemented yet.path
- Array of paths to the file system objects to remove. Guest style path.public void fsObjRename(java.lang.String oldPath, java.lang.String newPath, java.util.List<FsObjRenameFlag> flags)
VBOX_E_OBJECT_NOT_FOUND
- The file system object was not found.VBOX_E_IPRT_ERROR
- For most other errors. We know this is unhelpful, will fix shortly...oldPath
- The current path to the object. Guest path style.newPath
- The new path to the object. Guest path style.flags
- Zero or moreFsObjRenameFlag
values.public IProgress fsObjMove(java.lang.String source, java.lang.String destination, java.util.List<FsObjMoveFlag> flags)
fsObjRename(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.
E_NOTIMPL
- Not yet implemented.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 moreFsObjMoveFlag
values.public IProgress fsObjMoveArray(java.util.List<java.lang.String> source, java.lang.String destination, java.util.List<FsObjMoveFlag> flags)
E_NOTIMPL
- Not yet implemented.source
- Array of paths to the file system objects to move. Guest style path.destination
- Where to move the file system objects to (directory). Guest path
style.flags
- Zero or moreFsObjMoveFlag
values.public IProgress fsObjCopyArray(java.util.List<java.lang.String> source, java.lang.String destination, java.util.List<FileCopyFlag> flags)
E_NOTIMPL
- Not yet implemented.source
- Array of paths to the file system objects to copy. Guest style path.destination
- Where to copy the file system objects to (directory). Guest path
style.flags
- Zero or moreFileCopyFlag
values.public void fsObjSetACL(java.lang.String path, java.lang.Boolean followSymlinks, java.lang.String acl, java.lang.Long mode)
E_NOTIMPL
- The method is not implemented yet.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.public java.lang.Long fsQueryFreeSpace(java.lang.String path)
E_NOTIMPL
- The method is not implemented yet.path
- Full path to return the free space for.public IGuestFsInfo fsQueryInfo(java.lang.String path)
E_NOTIMPL
- The method is not implemented yet.path
- Full path to return file system information for.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)
IProcess.waitFor(Long,Long)
call.
VBOX_E_IPRT_ERROR
- Error creating guest process.VBOX_E_MAXIMUM_REACHED
- The maximum of concurrent guest processes has been reached.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;
seeProcessCreateFlag
for 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. SeeProcessStatus
for more information.getProtocolVersion()
is 3 or higher.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)
processCreate(String,List,List,List,Long)
for more information.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, seeProcessCreateFlag
for
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. SeeProcessStatus
for more information.priority
- Process priority to use for execution, seeProcessPriority
for 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.getProtocolVersion()
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.public IGuestProcess processGet(java.lang.Long pid)
pid
- Process ID (PID) to get guest process for.public void symlinkCreate(java.lang.String symlink, java.lang.String target, SymlinkType type)
E_NOTIMPL
- The method is not implemented yet.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). SeeSymlinkType
for more information.public java.lang.Boolean symlinkExists(java.lang.String symlink)
E_NOTIMPL
- The method is not implemented yet.symlink
- Path to the alleged symbolic link. Guest path style.public java.lang.String symlinkRead(java.lang.String symlink, java.util.List<SymlinkReadFlag> flags)
E_NOTIMPL
- The method is not implemented yet.symlink
- Path to the symbolic link to read.flags
- Zero or moreSymlinkReadFlag
values.public GuestSessionWaitResult waitFor(java.lang.Long waitFor, java.lang.Long timeoutMS)
waitFor
- Specifies what to wait for;
seeGuestSessionWaitForFlag
for more information.timeoutMS
- Timeout (in ms) to wait for the operation to complete.
Pass 0 for an infinite timeout.GuestSessionWaitResult
for more information.public GuestSessionWaitResult waitForArray(java.util.List<GuestSessionWaitForFlag> waitFor, java.lang.Long timeoutMS)
waitFor(Long,Long)
.waitFor
- Specifies what to wait for;
seeGuestSessionWaitForFlag
for more information.timeoutMS
- Timeout (in ms) to wait for the operation to complete.
Pass 0 for an infinite timeout.GuestSessionWaitResult
for more information.