Public Member Functions | Public Attributes

IGuestSession Interface Reference

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. More...

List of all members.

Public Member Functions

void close ()
 Closes this session.
void copyFrom (in wstring source, in wstring dest, in CopyFileFlag[] flags,[retval] out IProgress progress)
 Copies a file from guest to the host.
void copyTo (in wstring source, in wstring dest, in CopyFileFlag[] flags,[retval] out IProgress progress)
 Copies a file from host to the guest.
void directoryCreate (in wstring path, in unsigned long mode, in DirectoryCreateFlag[] flags)
 Create a directory on the guest.
void directoryCreateTemp (in wstring templateName, in unsigned long mode, in wstring path, in boolean secure,[retval] out wstring directory)
 Create a temporary directory on the guest.
void directoryExists (in wstring path,[retval] out boolean exists)
 Checks whether a directory exists on the guest or not.
void directoryOpen (in wstring path, in wstring filter, in DirectoryOpenFlag[] flags,[retval] out IGuestDirectory directory)
 Opens a directory and creates a IGuestDirectory object that can be used for further operations.
void directoryQueryInfo (in wstring path,[retval] out IGuestFsObjInfo info)
 Queries information of a directory on the guest.
void directoryRemove (in wstring path)
 Removes a guest directory if not empty.
void directoryRemoveRecursive (in wstring path, in DirectoryRemoveRecFlag[] flags,[retval] out IProgress progress)
 Removes a guest directory recursively.
void directoryRename (in wstring source, in wstring dest, in PathRenameFlag[] flags)
 Renames a directory on the guest.
void directorySetACL (in wstring path, in wstring acl)
 Sets the ACL (Access Control List) of a guest directory.
void environmentClear ()
 Clears (deletes) all session environment variables.
void environmentGet (in wstring name,[retval] out wstring value)
 Gets the value of a session environment variable.
void environmentSet (in wstring name, in wstring value)
 Sets a session environment variable.
void environmentUnset (in wstring name)
 Unsets session environment variable.
void fileCreateTemp (in wstring templateName, in unsigned long mode, in wstring path, in boolean secure,[retval] out IGuestFile file)
 Creates a temporary file on the guest.
void fileExists (in wstring path,[retval] out boolean exists)
 Checks whether a file exists on the guest or not.
void fileRemove (in wstring path)
 Removes a single file on the guest.
void fileOpen (in wstring path, in wstring openMode, in wstring disposition, in unsigned long creationMode, in long long offset,[retval] out IGuestFile file)
 Opens a file and creates a IGuestFile object that can be used for further operations.
void fileQueryInfo (in wstring path,[retval] out IGuestFsObjInfo info)
 Queries information of a file on the guest.
void fileQuerySize (in wstring path,[retval] out long long size)
 Queries the size of a file on the guest.
void fileRename (in wstring source, in wstring dest, in PathRenameFlag[] flags)
 Renames a file on the guest.
void fileSetACL (in wstring file, in wstring acl)
 Sets the ACL (Access Control List) of a file on the guest.
void processCreate (in wstring command, in wstring[] arguments, in wstring[] environment, in ProcessCreateFlag[] flags, in unsigned long timeoutMS,[retval] out IGuestProcess guestProcess)
 Executes an existing program inside the guest VM.
void processCreateEx (in wstring command, in wstring[] arguments, in wstring[] environment, in ProcessCreateFlag[] flags, in unsigned long timeoutMS, in ProcessPriority priority, in long[] affinity,[retval] out IGuestProcess guestProcess)
 Executes an existing program inside the guest VM.
void processGet (in unsigned long pid,[retval] out IGuestProcess guestProcess)
 Gets a certain guest process by its process ID (PID).
void symlinkCreate (in wstring source, in wstring target, in SymlinkType type)
 Creates a symbolic link on the guest.
void symlinkExists (in wstring symlink,[retval] out boolean exists)
 Checks whether a symbolic link exists on the guest or not.
void symlinkRead (in wstring symlink, in SymlinkReadFlag[] flags,[retval] out wstring target)
 Reads a symbolic link on the guest.
void symlinkRemoveDirectory (in wstring path)
 Removes a symbolic link on the guest if it's a directory.
void symlinkRemoveFile (in wstring file)
 Removes a symbolic link on the guest if it's a file.

Public Attributes

readonly attribute wstring user
 Returns the user name used by this session to impersonate users on the guest.
readonly attribute wstring domain
 Returns the domain name used by this session to impersonate users on the guest.
readonly attribute wstring name
 Returns the session's friendly name.
readonly attribute unsigned long id
 Returns the internal session ID.
attribute unsigned long timeout
 Returns the session timeout (in ms).
attribute wstring[] environment
 Returns the current session environment.
readonly attribute IGuestProcess[] processes
 Returns all current guest processes.
readonly attribute
IGuestDirectory[] 
directories
 Returns all currently opened guest directories.
readonly attribute IGuestFile[] files
 Returns all currently opened guest files.

Detailed Description

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.

There can be a maximum of 32 sessions at once per VM. Each session keeps track of its started guest processes, opened guest files or guest directories. To work on guest files or directories a guest session offers methods to open or create such objects (see IGuestSession::fileOpen or IGuestSession::directoryOpen for example).

When done with either of these objects, including the guest session itself, use the appropriate close() method to let the object do its cleanup work.

Every guest session has its own environment variable block which gets automatically applied when starting a new guest process via IGuestSession::processCreate or IGuestSession::processCreateEx. 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}

Member Function Documentation

void IGuestSession::close (  ) 

Closes this session.

All opened guest directories, files and processes which are not referenced by clients anymore will be uninitialized.

void IGuestSession::copyFrom ( in wstring  source,
in wstring  dest,
in CopyFileFlag[]  flags,
[retval] out IProgress  progress 
)

Copies a file from guest to the host.

Parameters:
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.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_IPRT_ERROR Error starting the copy operation.
void IGuestSession::copyTo ( in wstring  source,
in wstring  dest,
in CopyFileFlag[]  flags,
[retval] out IProgress  progress 
)

Copies a file from host to the guest.

Parameters:
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.
progress Progress object to track the operation completion.
Expected result codes:
VBOX_E_IPRT_ERROR Error starting the copy operation.
void IGuestSession::directoryCreate ( in wstring  path,
in unsigned long  mode,
in DirectoryCreateFlag[]  flags 
)

Create a directory on the guest.

Parameters:
path Full path of directory to create.
mode File creation mode.
flags Creation flags; see DirectoryCreateFlag for more information.
Expected result codes:
VBOX_E_IPRT_ERROR Error while creating the directory.
void IGuestSession::directoryCreateTemp ( in wstring  templateName,
in unsigned long  mode,
in wstring  path,
in boolean  secure,
[retval] out wstring  directory 
)

Create a temporary directory on 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 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.
directory On success this will contain the name of the directory created with full path.
Expected result codes:
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.
void IGuestSession::directoryExists ( in wstring  path,
[retval] out boolean  exists 
)

Checks whether a directory exists on the guest or not.

Parameters:
path Directory to check existence for.
exists Returns true if the directory exists, false if not.
Expected result codes:
VBOX_E_IPRT_ERROR Error while checking existence of the directory specified.
void IGuestSession::directoryOpen ( in wstring  path,
in wstring  filter,
in DirectoryOpenFlag[]  flags,
[retval] out IGuestDirectory  directory 
)

Opens a directory and creates a IGuestDirectory object that can be used for further operations.

Parameters:
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.
directory IGuestDirectory object containing the opened directory.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Directory to open was not found.
VBOX_E_IPRT_ERROR Error while opening the directory.
void IGuestSession::directoryQueryInfo ( in wstring  path,
[retval] out IGuestFsObjInfo  info 
)

Queries information of a directory on the guest.

Parameters:
path Directory to query information for.
info IGuestFsObjInfo object containing the queried information.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND Directory to query information for was not found.
VBOX_E_IPRT_ERROR Error querying information.
void IGuestSession::directoryRemove ( in wstring  path  ) 

Removes a guest directory if not empty.

Parameters:
path Full path of directory to remove.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
void IGuestSession::directoryRemoveRecursive ( in wstring  path,
in DirectoryRemoveRecFlag[]  flags,
[retval] out IProgress  progress 
)

Removes a guest directory recursively.

Parameters:
path Full path of directory to remove recursively.
flags Remove flags; see DirectoryRemoveRecFlag for more information.
progress Progress object to track the operation completion.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
void IGuestSession::directoryRename ( in wstring  source,
in wstring  dest,
in PathRenameFlag[]  flags 
)

Renames a directory on the guest.

Parameters:
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.
void IGuestSession::directorySetACL ( in wstring  path,
in wstring  acl 
)

Sets the ACL (Access Control List) of a guest directory.

Parameters:
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.
void IGuestSession::environmentClear (  ) 

Clears (deletes) all session environment variables.

Expected result codes:
VBOX_E_IPRT_ERROR Error while clearing the session environment variables.
void IGuestSession::environmentGet ( in wstring  name,
[retval] out wstring  value 
)

Gets the value of a session environment variable.

Parameters:
name Name of session environment variable to get the value for.
value Value of the session environment variable specified. If this variable does not exist and empty value will be returned.
Expected result codes:
VBOX_E_IPRT_ERROR Error while getting the value of the session environment variable.
void IGuestSession::environmentSet ( in wstring  name,
in wstring  value 
)

Sets a session environment variable.

Parameters:
name Name of session environment variable to set.
value Value to set the session environment variable to.
Expected result codes:
VBOX_E_IPRT_ERROR Error while setting the session environment variable.
void IGuestSession::environmentUnset ( in wstring  name  ) 

Unsets session environment variable.

Parameters:
name Name of session environment variable to unset (clear).
Expected result codes:
VBOX_E_IPRT_ERROR Error while unsetting the session environment variable.
void IGuestSession::fileCreateTemp ( in wstring  templateName,
in unsigned long  mode,
in wstring  path,
in boolean  secure,
[retval] out IGuestFile  file 
)

Creates a temporary file on 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 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.
file On success this will contain an open file object for the new temporary file.
Expected result codes:
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 file could not be created. Possible reasons include a non-existing path or an insecure path when the secure option was requested.
void IGuestSession::fileExists ( in wstring  path,
[retval] out boolean  exists 
)

Checks whether a file exists on the guest or not.

Parameters:
path File to check existence for.
exists Returns true if the file exists, false if not.
Expected result codes:
VBOX_E_IPRT_ERROR Error while checking existence of the file specified.
void IGuestSession::fileRemove ( in wstring  path  ) 

Removes a single file on the guest.

Parameters:
path Path to the file to remove.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND File to remove was not found.
VBOX_E_IPRT_ERROR Error while removing the file.
void IGuestSession::fileOpen ( in wstring  path,
in wstring  openMode,
in wstring  disposition,
in unsigned long  creationMode,
in long long  offset,
[retval] out IGuestFile  file 
)

Opens a file and creates a IGuestFile object that can be used for further operations.

Parameters:
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.
file IGuestFile object representing the opened file.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND File to open was not found.
VBOX_E_IPRT_ERROR Error while opening the file.
void IGuestSession::fileQueryInfo ( in wstring  path,
[retval] out IGuestFsObjInfo  info 
)

Queries information of a file on the guest.

Parameters:
path File to query information for.
info IGuestFsObjInfo object containing the queried information.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND File to query information for was not found.
VBOX_E_IPRT_ERROR Error querying information.
void IGuestSession::fileQuerySize ( in wstring  path,
[retval] out long long  size 
)

Queries the size of a file on the guest.

Parameters:
path File to query the size for.
size Queried file size.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUND File to rename was not found.
VBOX_E_IPRT_ERROR Error querying file size.
void IGuestSession::fileRename ( in wstring  source,
in wstring  dest,
in PathRenameFlag[]  flags 
)

Renames a file on the guest.

Parameters:
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.
void IGuestSession::fileSetACL ( in wstring  file,
in wstring  acl 
)

Sets the ACL (Access Control List) of a file on the guest.

Parameters:
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.
void IGuestSession::processCreate ( in wstring  command,
in wstring[]  arguments,
in wstring[]  environment,
in ProcessCreateFlag[]  flags,
in unsigned long  timeoutMS,
[retval] out IGuestProcess  guestProcess 
)

Executes an existing program inside the guest VM.

Parameters:
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.

Parameters:
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.
guestProcess Guest process object of the newly created process.
Expected result codes:
VBOX_E_IPRT_ERROR Could not create process.
Note:
Starting at VirtualBox 4.2 guest process execution by default is limited to serve up to 255 guest processes at a time. If all 255 guest processes are still active and running, starting a new guest process will result in an appropriate error message.

If ProcessCreateFlag_WaitForStdOut and / or respectively ProcessCreateFlag_WaitForStdErr is / are set, the guest process will not exit until all data from the specified stream(s) is / are read out.

To raise or lower the guest process execution limit, either the guest property "/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept" or VBoxService' command line by specifying "--control-procs-max-kept" needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited guest processes, a value of "0" needs to be set (not recommended).

void IGuestSession::processCreateEx ( in wstring  command,
in wstring[]  arguments,
in wstring[]  environment,
in ProcessCreateFlag[]  flags,
in unsigned long  timeoutMS,
in ProcessPriority  priority,
in long[]  affinity,
[retval] out IGuestProcess  guestProcess 
)

Executes an existing program inside the guest VM.

Extended version for also setting the process priority and affinity.

Parameters:
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.

Parameters:
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.
guestProcess Guest process object of the newly created process.
Expected result codes:
VBOX_E_IPRT_ERROR Could not create process.
Note:
Starting at VirtualBox 4.2 guest process execution by default is limited to serve up to 255 guest processes at a time. If all 255 guest processes are still active and running, starting a new guest process will result in an appropriate error message.

If ProcessCreateFlag_WaitForStdOut and / or respectively ProcessCreateFlag_WaitForStdErr is / are set, the guest process will not exit until all data from the specified stream(s) is / are read out.

To raise or lower the guest process execution limit, either the guest property "/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept" or VBoxService' command line by specifying "--control-procs-max-kept" needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited guest processes, a value of "0" needs to be set (not recommended).

void IGuestSession::processGet ( in unsigned long  pid,
[retval] out IGuestProcess  guestProcess 
)

Gets a certain guest process by its process ID (PID).

Parameters:
pid Process ID (PID) to get guest process for.
guestProcess Guest process of specified process ID (PID).
void IGuestSession::symlinkCreate ( in wstring  source,
in wstring  target,
in SymlinkType  type 
)

Creates a symbolic link on the guest.

Parameters:
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.
void IGuestSession::symlinkExists ( in wstring  symlink,
[retval] out boolean  exists 
)

Checks whether a symbolic link exists on the guest or not.

Parameters:
symlink Symbolic link to check existence for.
exists Returns true if the symbolic link exists, false if not.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
void IGuestSession::symlinkRead ( in wstring  symlink,
in SymlinkReadFlag[]  flags,
[retval] out wstring  target 
)

Reads a symbolic link on the guest.

Parameters:
symlink Full path to symbolic link to read.
flags Read flags; see SymlinkReadFlag for more information.
target Target of the symbolic link pointing to, if found.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
void IGuestSession::symlinkRemoveDirectory ( in wstring  path  ) 

Removes a symbolic link on the guest if it's a directory.

Parameters:
path Symbolic link to remove.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
void IGuestSession::symlinkRemoveFile ( in wstring  file  ) 

Removes a symbolic link on the guest if it's a file.

Parameters:
file Symbolic link to remove.
Expected result codes:
E_NOTIMPL The method is not implemented yet.

Member Data Documentation

readonly attribute wstring IGuestSession::user

Returns the user name used by this session to impersonate users on the guest.

readonly attribute wstring IGuestSession::domain

Returns the domain name used by this session to impersonate users on the guest.

readonly attribute wstring IGuestSession::name

Returns the session's friendly name.

readonly attribute unsigned long IGuestSession::id

Returns the internal session ID.

attribute unsigned long IGuestSession::timeout

Returns the session timeout (in ms).

Expected result codes:
E_NOTIMPL The method is not implemented yet.
attribute wstring [] IGuestSession::environment

Returns the current session environment.

readonly attribute IGuestProcess [] IGuestSession::processes

Returns all current guest processes.

Returns all currently opened guest directories.

readonly attribute IGuestFile [] IGuestSession::files

Returns all currently opened guest files.