|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.virtualbox_4_3.IUnknown
org.virtualbox_4_3.IGuestSession
public class IGuestSession
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 IGuest.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 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 fileOpen(String,String,String,Long)
or
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
processCreate(String,List,List,List,Long)
or processCreateEx(String,List,List,List,Long,org.virtualbox_4_3.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.
Interface ID: {5B28703C-07B6-4FCB-AFBA-AC199B309752}
Field Summary |
---|
Fields inherited from class org.virtualbox_4_3.IUnknown |
---|
obj, port |
Constructor Summary | |
---|---|
IGuestSession(java.lang.String wrapped,
org.virtualbox_4_3.jaxws.VboxPortType port)
|
Method Summary | |
---|---|
void |
close()
Closes this session. |
IProgress |
copyFrom(java.lang.String source,
java.lang.String dest,
java.util.List<CopyFileFlag> flags)
Copies a file from guest to the host. |
IProgress |
copyTo(java.lang.String source,
java.lang.String dest,
java.util.List<CopyFileFlag> flags)
Copies a file from host to the guest. |
void |
directoryCreate(java.lang.String path,
java.lang.Long mode,
java.util.List<DirectoryCreateFlag> flags)
Create a directory on the guest. |
java.lang.String |
directoryCreateTemp(java.lang.String templateName,
java.lang.Long mode,
java.lang.String path,
java.lang.Boolean secure)
Create a temporary directory on the guest. |
java.lang.Boolean |
directoryExists(java.lang.String path)
Checks whether a directory exists on the guest or not. |
IGuestDirectory |
directoryOpen(java.lang.String path,
java.lang.String filter,
java.util.List<DirectoryOpenFlag> flags)
Opens a directory and creates a IGuestDirectory object that
can be used for further operations. |
IGuestFsObjInfo |
directoryQueryInfo(java.lang.String path)
Queries information of a directory on the guest. |
void |
directoryRemove(java.lang.String path)
Removes a guest directory if not empty. |
IProgress |
directoryRemoveRecursive(java.lang.String path,
java.util.List<DirectoryRemoveRecFlag> flags)
Removes a guest directory recursively. |
void |
directoryRename(java.lang.String source,
java.lang.String dest,
java.util.List<PathRenameFlag> flags)
Renames a directory on the guest. |
void |
directorySetACL(java.lang.String path,
java.lang.String acl)
Sets the ACL (Access Control List) of a guest directory. |
void |
environmentClear()
Clears (deletes) all session environment variables. |
java.lang.String |
environmentGet(java.lang.String name)
Gets the value of a session environment variable. |
void |
environmentSet(java.lang.String name,
java.lang.String value)
Sets a session environment variable. |
void |
environmentUnset(java.lang.String name)
Unsets a session environment variable. |
IGuestFile |
fileCreateTemp(java.lang.String templateName,
java.lang.Long mode,
java.lang.String path,
java.lang.Boolean secure)
Creates a temporary file on the guest. |
java.lang.Boolean |
fileExists(java.lang.String path)
Checks whether a file exists on the guest or not. |
IGuestFile |
fileOpen(java.lang.String path,
java.lang.String openMode,
java.lang.String disposition,
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,
java.lang.String openMode,
java.lang.String disposition,
java.lang.String sharingMode,
java.lang.Long creationMode,
java.lang.Long offset)
Opens a file and creates a IGuestFile object that
can be used for further operations, extended version. |
IGuestFsObjInfo |
fileQueryInfo(java.lang.String path)
Queries information of a file on the guest. |
java.lang.Long |
fileQuerySize(java.lang.String path)
Queries the size of a file on the guest. |
void |
fileRemove(java.lang.String path)
Removes a single file on the guest. |
void |
fileRename(java.lang.String source,
java.lang.String dest,
java.util.List<PathRenameFlag> flags)
Renames a file on the guest. |
void |
fileSetACL(java.lang.String file,
java.lang.String acl)
Sets the ACL (Access Control List) of a file on the guest. |
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 on the guest. |
java.util.List<java.lang.String> |
getEnvironment()
Returns the current session environment. |
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. |
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 on the guest. |
IGuestProcess |
processCreate(java.lang.String command,
java.util.List<java.lang.String> arguments,
java.util.List<java.lang.String> environment,
java.util.List<ProcessCreateFlag> flags,
java.lang.Long timeoutMS)
Creates a new process running on the guest. |
IGuestProcess |
processCreateEx(java.lang.String command,
java.util.List<java.lang.String> arguments,
java.util.List<java.lang.String> environment,
java.util.List<ProcessCreateFlag> flags,
java.lang.Long timeoutMS,
ProcessPriority priority,
java.util.List<java.lang.Integer> affinity)
|
IGuestProcess |
processGet(java.lang.Long pid)
Gets a certain guest process by its process ID (PID). |
static IGuestSession |
queryInterface(IUnknown obj)
|
void |
setEnvironment(java.util.List<java.lang.String> value)
Returns the current session environment. |
void |
setTimeout(java.lang.Long value)
Returns the session timeout (in ms). |
void |
symlinkCreate(java.lang.String source,
java.lang.String target,
SymlinkType type)
Creates a symbolic link on the guest. |
java.lang.Boolean |
symlinkExists(java.lang.String symlink)
Checks whether a symbolic link exists on the guest or not. |
java.lang.String |
symlinkRead(java.lang.String symlink,
java.util.List<SymlinkReadFlag> flags)
Reads a symbolic link on the guest. |
void |
symlinkRemoveDirectory(java.lang.String path)
Removes a symbolic link on the guest if it's a directory. |
void |
symlinkRemoveFile(java.lang.String file)
Removes a symbolic link on the guest if it's a file. |
GuestSessionWaitResult |
waitFor(java.lang.Long waitFor,
java.lang.Long timeoutMS)
Waits for one more events to happen. |
GuestSessionWaitResult |
waitForArray(java.util.List<GuestSessionWaitForFlag> waitFor,
java.lang.Long timeoutMS)
Waits for one more events to happen. |
Methods inherited from class org.virtualbox_4_3.IUnknown |
---|
getRemoteWSPort, getWrapped, releaseRemote |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public IGuestSession(java.lang.String wrapped, org.virtualbox_4_3.jaxws.VboxPortType port)
Method Detail |
---|
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 | The method is not implemented yet. |
public void setTimeout(java.lang.Long value)
E_NOTIMPL | The method is not implemented yet. |
value
- Longpublic java.lang.Long getProtocolVersion()
public GuestSessionStatus getStatus()
public java.util.List<java.lang.String> getEnvironment()
public void setEnvironment(java.util.List<java.lang.String> value)
value
- Listpublic java.util.List<IGuestProcess> getProcesses()
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 copyFrom(java.lang.String source, java.lang.String dest, java.util.List<CopyFileFlag> flags)
source
- Source file on the guest to copy to the host.dest
- Destination file name on the host.flags
- Copy flags; see CopyFileFlag
for more information.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error starting the copy operation. |
public IProgress copyTo(java.lang.String source, java.lang.String dest, java.util.List<CopyFileFlag> flags)
source
- Source file on the host to copy to the guest.dest
- Destination file name on the guest.flags
- Copy flags; see CopyFileFlag
for more information.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error starting the copy operation. |
public void directoryCreate(java.lang.String path, java.lang.Long mode, java.util.List<DirectoryCreateFlag> flags)
path
- Full path of directory to create.mode
- File creation mode.flags
- Creation flags; see DirectoryCreateFlag
for more information.
Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while creating the directory. |
public java.lang.String directoryCreateTemp(java.lang.String templateName, java.lang.Long mode, java.lang.String path, java.lang.Boolean secure)
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 mode of the directory to create. Use 0700 unless there are
reasons not to. This parameter is ignored if "secure" is specified.path
- The absolute path to create the temporary directory in.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.
@link ::VBOX_E_NOT_SUPPORTED 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. |
@link ::VBOX_E_IPRT_ERROR 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. |
public java.lang.Boolean directoryExists(java.lang.String path)
path
- Directory to check existence for.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while checking existence of the directory specified. |
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.
path
- Full path to file to open.filter
- Open filter to apply. This can include wildcards like ? and *.flags
- Open flags; see DirectoryOpenFlag
for more information.
IGuestDirectory
object containing the opened directory.
Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | Directory to open was not found. |
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while opening the directory. |
public IGuestFsObjInfo directoryQueryInfo(java.lang.String path)
path
- Directory to query information for.
IGuestFsObjInfo
object containing the queried information.
Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | Directory to query information for was not found. |
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error querying information. |
public void directoryRemove(java.lang.String path)
path
- Full path of directory to remove.public IProgress directoryRemoveRecursive(java.lang.String path, java.util.List<DirectoryRemoveRecFlag> flags)
path
- Full path of directory to remove recursively.flags
- Remove flags; see DirectoryRemoveRecFlag
for more information.
public void directoryRename(java.lang.String source, java.lang.String dest, java.util.List<PathRenameFlag> flags)
source
- Source directory to rename.dest
- Destination directory to rename the source to.flags
- Rename flags; see PathRenameFlag
for more information.public void directorySetACL(java.lang.String path, java.lang.String acl)
path
- Full path of directory to set the ACL for.acl
- Actual ACL string to set. Must comply with the guest OS.
Expected result codes:
E_NOTIMPL | The method is not implemented yet. |
public void environmentClear()
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while clearing the session environment variables. |
public java.lang.String environmentGet(java.lang.String name)
name
- Name of session environment variable to get the value for.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while getting the value of the session environment variable. |
public void environmentSet(java.lang.String name, java.lang.String value)
name
- Name of session environment variable to set.value
- Value to set the session environment variable to.
Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while setting the session environment variable. |
public void environmentUnset(java.lang.String name)
name
- Name of session environment variable to unset (clear).
Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while unsetting the session environment variable. |
public IGuestFile fileCreateTemp(java.lang.String templateName, java.lang.Long mode, java.lang.String path, java.lang.Boolean secure)
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 mode of the file to create. Use 0700 unless there are
reasons not to. This parameter is ignored if "secure" is specified.path
- The absolute path to create the temporary file in.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.
@link ::VBOX_E_NOT_SUPPORTED 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. |
@link ::VBOX_E_IPRT_ERROR 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. |
public java.lang.Boolean fileExists(java.lang.String path)
path
- File to check existence for.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while checking existence of the file specified. |
public void fileRemove(java.lang.String path)
path
- Path to the file to remove.
Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | File to remove was not found. |
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while removing the file. |
public IGuestFile fileOpen(java.lang.String path, java.lang.String openMode, java.lang.String disposition, java.lang.Long creationMode)
IGuestFile
object that
can be used for further operations.
path
- Full path to file to open.openMode
- The file opening mode. This describes the wanted access to a file, whereas
the parameter must be one of the following:
disposition
- The file disposition. This describes the action to take in case a
file exists or does not exist, whereas the parameter must be one of the
following:
creationMode
- The mode to create the file with. Must be a three-digit octal number which
represents the access rights for the file.
IGuestFile
object representing the opened file.
Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | File to open was not found. |
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while opening the file. |
public IGuestFile fileOpenEx(java.lang.String path, java.lang.String openMode, java.lang.String disposition, java.lang.String sharingMode, java.lang.Long creationMode, java.lang.Long offset)
IGuestFile
object that
can be used for further operations, extended version.
path
- Full path to file to open.openMode
- The file opening mode. This describes the wanted access to a file, whereas
the parameter must be one of the following:
disposition
- The file disposition. This describes the action to take in case a
file exists or does not exist, whereas the parameter must be one of the
following:
sharingMode
- The file sharing mode on the guest. This parameter
is not implemented yet. Pass an empty string here.creationMode
- The mode to create the file with. Must be a three-digit octal number which
represents the access rights for the file.offset
- The initial read/write offset (in bytes).
IGuestFile
object representing the opened file.
Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | File to open was not found. |
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error while opening the file. |
public IGuestFsObjInfo fileQueryInfo(java.lang.String path)
path
- File to query information for.
IGuestFsObjInfo
object containing the queried information.
Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | File to query information for was not found. |
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error querying information. |
public java.lang.Long fileQuerySize(java.lang.String path)
path
- File to query the size for.
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUND | File to rename was not found. |
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error querying file size. |
public void fileRename(java.lang.String source, java.lang.String dest, java.util.List<PathRenameFlag> flags)
source
- Source file to rename.dest
- Destination file to rename the source to.flags
- Rename flags; see PathRenameFlag
for more information.public void fileSetACL(java.lang.String file, java.lang.String acl)
file
- Full path of file to set the ACL for.acl
- Actual ACL string to set. Must comply with the guest OS.
Expected result codes:
E_NOTIMPL | The method is not implemented yet. |
public IGuestProcess processCreate(java.lang.String command, java.util.List<java.lang.String> arguments, java.util.List<java.lang.String> environment, java.util.List<ProcessCreateFlag> flags, java.lang.Long timeoutMS)
IProcess.waitFor(Long,Long)
call.
command
- Full path name of the command to execute on the guest; the
commands has to exists in the guest VM in order to be executed.arguments
- Array of arguments passed to the execution command.environment
- flags
- Process creation flags;
see ProcessCreateFlag
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. See
ProcessStatus
for more information.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Error creating guest process. |
public IGuestProcess processCreateEx(java.lang.String command, java.util.List<java.lang.String> arguments, java.util.List<java.lang.String> environment, 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.
command
- Full path name of the command to execute on the guest; the
commands has to exists in the guest VM in order to be executed.arguments
- Array of arguments passed to the execution command.environment
- flags
- Process creation flags;
see ProcessCreateFlag
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. See
ProcessStatus
for more information.priority
- Process priority to use for execution;
see see ProcessPriority
for more information.affinity
- Process affinity to use for execution. This parameter
is not implemented yet.
public IGuestProcess processGet(java.lang.Long pid)
pid
- Process ID (PID) to get guest process for.
public void symlinkCreate(java.lang.String source, java.lang.String target, SymlinkType type)
source
- The name of the symbolic link.target
- The path to the symbolic link target.type
- The symbolic link type;
see SymlinkReadFlag
for more information.
Expected result codes:
E_NOTIMPL | The method is not implemented yet. |
public java.lang.Boolean symlinkExists(java.lang.String symlink)
symlink
- Symbolic link to check existence for.
E_NOTIMPL | The method is not implemented yet. |
public java.lang.String symlinkRead(java.lang.String symlink, java.util.List<SymlinkReadFlag> flags)
symlink
- Full path to symbolic link to read.flags
- Read flags; see SymlinkReadFlag
for more information.
E_NOTIMPL | The method is not implemented yet. |
public void symlinkRemoveDirectory(java.lang.String path)
path
- Symbolic link to remove.
Expected result codes:
E_NOTIMPL | The method is not implemented yet. |
public void symlinkRemoveFile(java.lang.String file)
file
- Symbolic link to remove.
Expected result codes:
E_NOTIMPL | The method is not implemented yet. |
public GuestSessionWaitResult waitFor(java.lang.Long waitFor, java.lang.Long timeoutMS)
waitFor
- Specifies what to wait for;
see GuestSessionWaitForFlag
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;
see GuestSessionWaitForFlag
for more information.timeoutMS
- Timeout (in ms) to wait for the operation to complete.
Pass 0 for an infinite timeout.
GuestSessionWaitResult
for more information.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |