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.

readonly attribute IGuestDirectory [] IGuestSession::directories

Returns all currently opened guest directories.

readonly attribute IGuestFile [] IGuestSession::files

Returns all currently opened guest files.