|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.virtualbox_4_2.IUnknown
org.virtualbox_4_2.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. Each session keeps
track of its started guest processes, opened guest files or guest directories.
To work on guest files or directories a guest session offers methods to open
or create such objects (see fileOpen(String,String,String,Long,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_2.ProcessPriority,List)
.
To override (or unset) certain environment variables already set by the
guest session, one can specify a per-process environment block when using
one of the both above mentioned process creation calls.
Interface ID: {57EB82A8-822B-42C1-9D1C-5C54BC3D3250}
Field Summary |
---|
Fields inherited from class org.virtualbox_4_2.IUnknown |
---|
obj, port |
Constructor Summary | |
---|---|
IGuestSession(java.lang.String wrapped,
org.virtualbox_4_2.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 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,
java.lang.Long offset)
Opens a file and creates a IGuestFile object that
can be used for further operations. |
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. |
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 |
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)
Executes an existing program inside the guest VM. |
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)
Executes an existing program inside the guest VM. |
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. |
Methods inherited from class org.virtualbox_4_2.IUnknown |
---|
getRemoteWSPort, getWrapped, releaseRemote |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public IGuestSession(java.lang.String wrapped, org.virtualbox_4_2.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.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 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.
Expected result codes:
E_NOTIMPL | The method is not implemented yet. |
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.
E_NOTIMPL | The method is not implemented yet. |
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.
Expected result codes:
E_NOTIMPL | The method is not implemented yet. |
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, java.lang.Long offset)
IGuestFile
object that
can be used for further operations.
path
- Full path to file to open.openMode
- The file open mode.disposition
- The file disposition.creationMode
- The file creation mode.offset
- The initial read/write offset.
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.
Expected result codes:
E_NOTIMPL | The method is not implemented yet. |
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)
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
- Environment variables that can be set while the command is being
executed, in form of "NAME=VALUE"; one pair per entry. To unset a
variable just set its name ("NAME") without a value.
This parameter can be used to override environment variables set by
the guest session, which will be applied to the newly started process
in any case.flags
- Process creation flags;
see ProcessCreateFlag
for more information.timeoutMS
- Timeout (in ms) to wait for the operation to complete.
Pass 0 for an infinite timeout.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Could not create 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)
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
- Environment variables that can be set while the command is being
executed, in form of "NAME=VALUE"; one pair per entry. To unset a
variable just set its name ("NAME") without a value.
This parameter can be used to override environment variables set by
the guest session, which will be applied to the newly started process
in any case.flags
- Process creation flags;
see ProcessCreateFlag
for more information.timeoutMS
- Timeout (in ms) to wait for the operation to complete.
Pass 0 for an infinite timeout.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.
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR | Could not create process. |
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. |
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |