VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IGuestSession Interface Reference

A guest session represents one impersonated user account in the guest, so every operation will use the same credentials specified when creating the session object via IGuest::createSession. More...

Inheritance diagram for IGuestSession:

## Public Member Functions
void | close ()
| Closes this session.
void | copyFromGuest (in wstring[] sources, in wstring[] filters, in wstring[] flags, in wstring destination, [retval] out IProgress progress)
| Copies directories and/or files from guest to the host.
void | copyToGuest (in wstring[] sources, in wstring[] filters, in wstring[] flags, in wstring destination, [retval] out IProgress progress)
| Copies directories and/or files from host to the guest.
void | directoryCopy (in wstring source, in wstring destination, in DirectoryCopyFlag[] flags, [retval] out IProgress progress)
| Recursively copies a directory from one guest location to another.
void | directoryCopyFromGuest (in wstring source, in wstring destination, in DirectoryCopyFlag[] flags, [retval] out IProgress progress)
| Recursively copies a directory from the guest to the host.
void | directoryCopyToGuest (in wstring source, in wstring destination, in DirectoryCopyFlag[] flags, [retval] out IProgress progress)
| Recursively copies a directory from the host to the guest.
void | directoryCreate (in wstring path, in unsigned long mode, in DirectoryCreateFlag[] flags)
| Creates a directory in the guest.
void | directoryCreateTemp (in wstring templateName, in unsigned long mode, in wstring path, in boolean secure, [retval] out wstring directory)
| Creates a temporary directory in the guest.
void | directoryExists (in wstring path, in boolean followSymlinks, [retval] out boolean exists)
| Checks whether a directory exists in the guest or not.
void | directoryOpen (in wstring path, in wstring filter, in DirectoryOpenFlag[] flags, [retval] out IGuestDirectory directory)
| Opens a directory in the guest and creates a IGuestDirectory object that can be used for further operations.
void | directoryRemove (in wstring path)
| Removes a guest directory if empty.
void | directoryRemoveRecursive (in wstring path, in DirectoryRemoveRecFlag[] flags, [retval] out IProgress progress)
| Removes a guest directory recursively.
void | environmentScheduleSet (in wstring name, in wstring value)
| Schedules setting an environment variable when creating the next guest process.
void | environmentScheduleUnset (in wstring name)
| Schedules unsetting (removing) an environment variable when creating the next guest process.
void | environmentGetBaseVariable (in wstring name, [retval] out wstring value)
| Gets an environment variable from the session's base environment (IGuestSession::environmentBase).
void | environmentDoesBaseVariableExist (in wstring name, [retval] out boolean exists)
| Checks if the given environment variable exists in the session's base environment (IGuestSession::environmentBase).
void | fileCopy (in wstring source, in wstring destination, in FileCopyFlag[] flags, [retval] out IProgress progress)
| Copies a file from one guest location to another.
void | fileCopyFromGuest (in wstring source, in wstring destination, in FileCopyFlag[] flags, [retval] out IProgress progress)
| Copies a file from the guest to the host.
void | fileCopyToGuest (in wstring source, in wstring destination, in FileCopyFlag[] flags, [retval] out IProgress progress)
| Copies a file from the host to the guest.
void | fileCreateTemp (in wstring templateName, in unsigned long mode, in wstring path, in boolean secure, [retval] out IGuestFile file)
| Creates a temporary file in the guest.
void | fileExists (in wstring path, in boolean followSymlinks, [retval] out boolean exists)
| Checks whether a regular file exists in the guest or not.
void | fileOpen (in wstring path, in FileAccessMode accessMode, in FileOpenAction openAction, in unsigned long creationMode, [retval] out IGuestFile file)
| Opens a file and creates a IGuestFile object that can be used for further operations.
void | fileOpenEx (in wstring path, in FileAccessMode accessMode, in FileOpenAction openAction, in FileSharingMode sharingMode, in unsigned long creationMode, in FileOpenExFlag[] flags, [retval] out IGuestFile file)
| Opens a file and creates a IGuestFile object that can be used for further operations, extended version.
void | fileQuerySize (in wstring path, in boolean followSymlinks, [retval] out long long size)
| Queries the size of a regular file in the guest.
void | fsObjExists (in wstring path, in boolean followSymlinks, [retval] out boolean exists)
| Checks whether a file system object (file, directory, etc) exists in the guest or not.
void | fsObjQueryInfo (in wstring path, in boolean followSymlinks, [retval] out IGuestFsObjInfo info)
| Queries information about a file system object (file, directory, etc) in the guest.
void | fsObjRemove (in wstring path)
| Removes a file system object (file, symlink, etc) in the guest.
void | fsObjRemoveArray (in wstring[] path, [retval] out IProgress progress)
| Removes multiple file system objects (files, directories, symlinks, etc) in the guest.
void | fsObjRename (in wstring oldPath, in wstring newPath, in FsObjRenameFlag[] flags)
| Renames a file system object (file, directory, symlink, etc) in the guest.
void | fsObjMove (in wstring source, in wstring destination, in FsObjMoveFlag[] flags, [retval] out IProgress progress)
| Moves a file system object (file, directory, symlink, etc) from one guest location to another.
void | fsObjMoveArray (in wstring[] source, in wstring destination, in FsObjMoveFlag[] flags, [retval] out IProgress progress)
| Moves file system objects (files, directories, symlinks, etc) from one guest location to another.
void | fsObjCopyArray (in wstring[] source, in wstring destination, in FileCopyFlag[] flags, [retval] out IProgress progress)
| Copies file system objects (files, directories, symlinks, etc) from one guest location to another.
void | fsObjSetACL (in wstring path, in boolean followSymlinks, in wstring acl, in unsigned long mode)
| Sets the access control list (ACL) of a file system object (file, directory, etc) in the guest.
void | fsQueryFreeSpace (in wstring path, [retval] out long long freeSpace)
| Returns the free space (in bytes) of a given path.
void | fsQueryInfo (in wstring path, [retval] out IGuestFsInfo info)
| Returns file system information for a given path.
void | processCreate (in wstring executable, in wstring[] arguments, in wstring[] environmentChanges, in ProcessCreateFlag[] flags, in unsigned long timeoutMS, [retval] out IGuestProcess guestProcess)
| Creates a new process running in the guest.
void | processCreateEx (in wstring executable, in wstring[] arguments, in wstring[] environmentChanges, in ProcessCreateFlag[] flags, in unsigned long timeoutMS, in ProcessPriority priority, in long[] affinity, [retval] out IGuestProcess guestProcess)
| Creates a new process running in the guest with the extended options for setting the process priority and affinity.
void | processGet (in unsigned long pid, [retval] out IGuestProcess guestProcess)
| Gets a certain guest process by its process ID (PID).
void | symlinkCreate (in wstring symlink, in wstring target, in SymlinkType type)
| Creates a symbolic link in the guest.
void | symlinkExists (in wstring symlink, [retval] out boolean exists)
| Checks whether a symbolic link exists in the guest.
void | symlinkRead (in wstring symlink, in SymlinkReadFlag[] flags, [retval] out wstring target)
| Reads the target value of a symbolic link in the guest.
void | waitFor (in unsigned long waitFor, in unsigned long timeoutMS, [retval] out GuestSessionWaitResult reason)
| Waits for one or more events to happen.
void | waitForArray (in GuestSessionWaitForFlag[] waitFor, in unsigned long timeoutMS, [retval] out GuestSessionWaitResult reason)
| Waits for one or more events to happen.

## Public Attributes
readonly attribute wstring | user
| Returns the user name used by this session to impersonate users in the guest.
readonly attribute wstring | domain
| Returns the domain name used by this session to impersonate users in 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).
readonly attribute unsigned long | protocolVersion
| Returns the protocol version which is used by this session to communicate with the guest.
readonly attribute GuestSessionStatus | status
| Returns the current session status.
attribute wstring[] | environmentChanges
| The set of scheduled environment changes to the base environment of the session.
readonly attribute wstring[] | environmentBase
| The base environment of the session.
readonly attribute IGuestProcess[] | processes
| Returns all current guest processes.
readonly attribute PathStyle | pathStyle
| The style of paths used by the guest.
attribute wstring | currentDirectory
| Gets or sets the current directory of the session.
readonly attribute wstring | userHome
| Returns the user's home / profile directory.
readonly attribute wstring | userDocuments
| Returns the user's documents directory.
readonly attribute IGuestDirectory[] | directories
| Returns all currently opened guest directories.
readonly attribute IGuestFile[] | files
| Returns all currently opened guest files.
readonly attribute IEventSource | eventSource
| Event source for guest session events.

## Detailed Description

A guest session represents one impersonated user account in 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, whereas session 0 always is reserved for the root session (the root session is part of that limit).

This root session is controlling all other guest sessions and also is responsible for actions which require system level privileges.

Each guest session keeps track of the guest directories and files that it opened as well as guest processes it has created. To work on guest files or directories a guest session offers methods to open or create such objects (see IGuestSession::fileOpen or IGuestSession::directoryOpen for instance). Similarly, there a methods for creating guest processes.

There can be up to 2048 objects (guest processes, files and directories) a time per guest session. Exceeding the limit will result in an error (see the corresponding functions for more).

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

Closing a session via IGuestSession::close will try to close all the mentioned objects above unless these objects are still used by a client.

A set of environment variables changes is associated with each session (IGuestSession::environmentChanges). These are applied to the base environment of the impersonated guest user when creating a new guest process. For additional flexibility the IGuestSession::processCreate and IGuestSession::processCreateEx methods allows you to specify individual environment changes for each process you create. With newer guest addition versions, the base environment is also made available via IGuestSession::environmentBase. (One reason for why we record changes to a base environment instead of working directly on an environment block is that we need to be compatible with older Guest Additions. Another reason is that this way it is always possible to undo all the changes you've scheduled.)

Interface ID:
  `{234F0627-866D-48C2-91A5-4C9D50F04928}`

## Member Function Documentation

## ◆ close()

void IGuestSession::close | ( |  | ) |

Closes this session.

All opened guest directories, files and processes which are not referenced by clients anymore will be closed. Guest processes which fall into this category and still are running in the guest will be terminated automatically.

## ◆ copyFromGuest()

void IGuestSession::copyFromGuest | ( | in wstring[] | sources,
|  | in wstring[] | filters,
|  | in wstring[] | flags,
|  | in wstring | destination,
|  | [retval] out IProgress | progress
| ) |  |

Copies directories and/or files from guest to the host.

This function requires several parallel arrays to be supplied, one set for each source.

Parameters

  sources | Paths to directories and/or files on the guest side that should be copied to the host. If the path ends with a path delimiter, only the directory's content is being copied. Guest path style.
  filters | Array of source filters. This uses the DOS/NT style wildcard characters '?' and '*'.
  flags | Array of comma-separated list of source flags.

The following flags are available:

`CopyIntoExisting`
  Allow copying into an existing destination directory.
`NoReplace`
  Do not replace any existing destination files on the destination.
`FollowLinks`
  Follows (and handles) (symbolic) links.
`Update`
  Only copy when the source file is newer than the destination file or when the destination file is missing.

Parameters

  destination | Where to put the sources on the host. Host path style.
  progress | Progress object to track the operation to completion.

## ◆ copyToGuest()

void IGuestSession::copyToGuest | ( | in wstring[] | sources,
|  | in wstring[] | filters,
|  | in wstring[] | flags,
|  | in wstring | destination,
|  | [retval] out IProgress | progress
| ) |  |

Copies directories and/or files from host to the guest.

This function requires several parallel arrays to be supplied, one set for each source.

Parameters

  sources | Paths to directories and/or files on the host side that should be copied to the guest. If the path ends with a path delimiter, only the directory's content is being copied. Host path style.
  filters | Array of source filters. This uses the DOS/NT style wildcard characters '?' and '*'.
  flags | Array of comma-separated list of source flags.

The following flags are available:

`CopyIntoExisting`
  Allow copying into an existing destination directory.
`NoReplace`
  Do not replace any existing destination files on the destination.
`FollowLinks`
  Follows (and handles) (symbolic) links.
`Update`
  Only copy when the source file is newer than the destination file or when the destination file is missing.

Parameters

  destination | Where to put the sources on the guest. Guest path style.
  progress | Progress object to track the operation to completion.

## ◆ directoryCopy()

void IGuestSession::directoryCopy | ( | in wstring | source,
|  | in wstring | destination,
|  | in DirectoryCopyFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Recursively copies a directory from one guest location to another.

Parameters

  source | The path to the directory to copy (in the guest). Guest path style.
  destination | The path to the target directory (in the guest). Unless the DirectoryCopyFlag_CopyIntoExisting flag is given, the directory shall not already exist. Guest path style.
  flags | Zero or more DirectoryCopyFlag values.
  progress | Progress object to track the operation to completion.

Expected result codes:

  E_NOTIMPL | Not yet implemented.

## ◆ directoryCopyFromGuest()

void IGuestSession::directoryCopyFromGuest | ( | in wstring | source,
|  | in wstring | destination,
|  | in DirectoryCopyFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Recursively copies a directory from the guest to the host.

Parameters

  source | Path to the directory on the guest side that should be copied to the host. Guest path style.
  destination | Where to put the directory on the host. Unless the DirectoryCopyFlag_CopyIntoExisting flag is given, the directory shall not already exist. Host path style.
  flags | Zero or more DirectoryCopyFlag values.
  progress | Progress object to track the operation to completion.

## ◆ directoryCopyToGuest()

void IGuestSession::directoryCopyToGuest | ( | in wstring | source,
|  | in wstring | destination,
|  | in DirectoryCopyFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Recursively copies a directory from the host to the guest.

Parameters

  source | Path to the directory on the host side that should be copied to the guest. Host path style.
  destination | Where to put the file in the guest. Unless the DirectoryCopyFlag_CopyIntoExisting flag is given, the directory shall not already exist. Guest style path.
  flags | Zero or more DirectoryCopyFlag values.
  progress | Progress object to track the operation to completion.

## ◆ directoryCreate()

void IGuestSession::directoryCreate | ( | in wstring | path,
|  | in unsigned long | mode,
|  | in DirectoryCreateFlag[] | flags
| ) |  |

Creates a directory in the guest.

Parameters

  path | Path to the directory directory to be created. Guest path style.
  mode | The UNIX-style access mode mask to create the directory with. Whether/how all three access groups and associated access rights are realized is guest OS dependent. The API does the best it can on each OS.
  flags | Zero or more DirectoryCreateFlag flags.

Expected result codes:

  VBOX_E_IPRT_ERROR | Error while creating the directory.

## ◆ directoryCreateTemp()

void IGuestSession::directoryCreateTemp | ( | in wstring | templateName,
|  | in unsigned long | mode,
|  | in wstring | path,
|  | in boolean | secure,
|  | [retval] out wstring | directory
| ) |  |

Creates a temporary directory in 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 UNIX-style access mode mask to create the directory with. Whether/how all three access groups and associated access rights are realized is guest OS dependent. The API does the best it can on each OS.

This parameter is ignored if the secure parameter is set to `true`.

Parameters

  path | The path to the directory in which the temporary directory should be created. Guest path style.
  secure | Whether to fail if the directory can not be securely created. Currently this means that another unprivileged user cannot manipulate the path specified or remove the temporary directory after it has been created. Also causes the mode specified to be ignored. May not be supported on all guest types.
  directory | On success this will contain the full path to the created directory. Guest path style.

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.

Note
  It is strongly recommended to use 0700.

## ◆ directoryExists()

void IGuestSession::directoryExists | ( | in wstring | path,
|  | in boolean | followSymlinks,
|  | [retval] out boolean | exists
| ) |  |

Checks whether a directory exists in the guest or not.

Parameters

  path | Path to the directory to check if exists. Guest path style.
  followSymlinks | If `true`, symbolic links in the final component will be followed and the existance of the symlink target made the question for this method. If `false`, a symbolic link in the final component will make the method return `false` (because a symlink isn't a directory).
  exists | Returns `true` if the directory exists, `false` if not, or is not a directory.

Expected result codes:

  VBOX_E_IPRT_ERROR | Error while checking existence of the directory specified.

## ◆ directoryOpen()

void IGuestSession::directoryOpen | ( | in wstring | path,
|  | in wstring | filter,
|  | in DirectoryOpenFlag[] | flags,
|  | [retval] out IGuestDirectory | directory
| ) |  |

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

Parameters

  path | Path to the directory to open. Guest path style.
  filter | Optional directory listing filter to apply. This uses the DOS/NT style wildcard characters '?' and '*'.
  flags | Zero or more DirectoryOpenFlag flags.
  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.
  VBOX_E_MAXIMUM_REACHED | The maximum of concurrent guest directories has been reached.

Note
  This method follows symbolic links by default at the moment, this may change in the future.
  One idiosyncrasy of the current implementation is that you will NOT get VBOX_E_OBJECT_NOT_FOUND returned here if the directory doesn't exist. Instead the read function will fail with VBOX_E_IPRT_ERROR. This will be fixed soon.

## ◆ directoryRemove()

void IGuestSession::directoryRemove | ( | in wstring | path | ) |

Removes a guest directory if empty.

Parameters

  path | Path to the directory that should be removed. Guest path style.

Note
  Symbolic links in the final component will not be followed, instead an not-a-directory error is reported.

## ◆ directoryRemoveRecursive()

void IGuestSession::directoryRemoveRecursive | ( | in wstring | path,
|  | in DirectoryRemoveRecFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Removes a guest directory recursively.

Parameters

  path | Path of the directory that is to be removed recursively. Guest path style.
  flags | Zero or more DirectoryRemoveRecFlag flags.
  progress | Progress object to track the operation completion. This is not implemented yet and therefore this method call will block until deletion is completed.

Note
  WARNING!! THE FLAGS ARE NOT CURRENTLY IMPLEMENTED. THE IMPLEMENTATION WORKS AS IF FLAGS WAS SET TO DirectoryRemoveRecFlag_ContentAndDir.
  If the final path component is a symbolic link, this method will fail as it can only be applied to directories.
  WARNING! SPECIFYING DirectoryRemoveRecFlag_ContentAndDir IS MANDATORY AT THE MOMENT!!

## ◆ environmentScheduleSet()

void IGuestSession::environmentScheduleSet | ( | in wstring | name,
|  | in wstring | value
| ) |  |

Schedules setting an environment variable when creating the next guest process.

This affects the IGuestSession::environmentChanges attribute.

Parameters

  name | Name of the environment variable to set. This cannot be empty nor can it contain any equal signs.
  value | Value to set the session environment variable to.

## ◆ environmentScheduleUnset()

void IGuestSession::environmentScheduleUnset | ( | in wstring | name | ) |

Schedules unsetting (removing) an environment variable when creating the next guest process.

This affects the IGuestSession::environmentChanges attribute.

Parameters

  name | Name of the environment variable to unset. This cannot be empty nor can it contain any equal signs.

## ◆ environmentGetBaseVariable()

void IGuestSession::environmentGetBaseVariable | ( | in wstring | name,
|  | [retval] out wstring | value
| ) |  |

Gets an environment variable from the session's base environment (IGuestSession::environmentBase).

Parameters

  name | Name of the environment variable to get.This cannot be empty nor can it contain any equal signs.
  value | The value of the variable. Empty if not found. To deal with variables that may have empty values, use IGuestSession::environmentDoesBaseVariableExist.

Expected result codes:

  VBOX_E_NOT_SUPPORTED | If the Guest Additions does not support the session base environment feature. Support for this was introduced with protocol version XXXX.
  VBOX_E_INVALID_OBJECT_STATE | If the Guest Additions has yet to report the session base environment.

## ◆ environmentDoesBaseVariableExist()

void IGuestSession::environmentDoesBaseVariableExist | ( | in wstring | name,
|  | [retval] out boolean | exists
| ) |  |

Checks if the given environment variable exists in the session's base environment (IGuestSession::environmentBase).

Parameters

  name | Name of the environment variable to look for. This cannot be empty nor can it contain any equal signs.
  exists | TRUE if the variable exists, FALSE if not.

Expected result codes:

  VBOX_E_NOT_SUPPORTED | If the Guest Additions does not support the session base environment feature. Support for this was introduced with protocol version XXXX.
  VBOX_E_INVALID_OBJECT_STATE | If the Guest Additions has yet to report the session base environment.

## ◆ fileCopy()

void IGuestSession::fileCopy | ( | in wstring | source,
|  | in wstring | destination,
|  | in FileCopyFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Copies a file from one guest location to another.

Parameters

  source | The path to the file to copy (in the guest). Guest path style.
  destination | The path to the target file (in the guest). This cannot be a directory. Guest path style.
  flags | Zero or more FileCopyFlag values.
  progress | Progress object to track the operation to completion.

Expected result codes:

  E_NOTIMPL | Not yet implemented.

Note
  Will overwrite the destination file unless FileCopyFlag_NoReplace is specified.

## ◆ fileCopyFromGuest()

void IGuestSession::fileCopyFromGuest | ( | in wstring | source,
|  | in wstring | destination,
|  | in FileCopyFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Copies a file from the guest to the host.

Parameters

  source | Path to the file on the guest side that should be copied to the host. Guest path style.
  destination | Where to put the file on the host (file, not directory). Host path style.
  flags | Zero or more FileCopyFlag values.
  progress | Progress object to track the operation to completion.

Expected result codes:

  VBOX_E_IPRT_ERROR | Error starting the copy operation.

Note
  Will overwrite the destination file unless FileCopyFlag_NoReplace is specified.

## ◆ fileCopyToGuest()

void IGuestSession::fileCopyToGuest | ( | in wstring | source,
|  | in wstring | destination,
|  | in FileCopyFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Copies a file from the host to the guest.

Parameters

  source | Path to the file on the host side that should be copied to the guest. Host path style.
  destination | Where to put the file in the guest (file, not directory). Guest style path.
  flags | Zero or more FileCopyFlag values.
  progress | Progress object to track the operation to completion.

Expected result codes:

  VBOX_E_IPRT_ERROR | Error starting the copy operation.

Note
  Will overwrite the destination file unless FileCopyFlag_NoReplace is specified.

## ◆ fileCreateTemp()

void IGuestSession::fileCreateTemp | ( | in wstring | templateName,
|  | in unsigned long | mode,
|  | in wstring | path,
|  | in boolean | secure,
|  | [retval] out IGuestFile | file
| ) |  |

Creates a temporary file in 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 UNIX-style access mode mask to create the file with. Whether/how all three access groups and associated access rights are realized is guest OS dependent. The API does the best it can on each OS.

This parameter is ignore if the secure parameter is set to `true`.

Parameters

  path | The path to the directory in which the temporary file should be created.
  secure | Whether to fail if the file can not be securely created. Currently this means that another unprivileged user cannot manipulate the path specified or remove the temporary file after it has been created. Also causes the mode specified to be ignored. May not be supported on all guest types.
  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 OS.
  E_INVALIDARG | Invalid argument. This includes an incorrectly formatted template, or a non-absolute path.
  VBOX_E_IPRT_ERROR | The temporary file could not be created. Possible reasons include a non-existing path or an insecure path when the secure option was requested.

Note
  It is strongly recommended to use 0600.

## ◆ fileExists()

void IGuestSession::fileExists | ( | in wstring | path,
|  | in boolean | followSymlinks,
|  | [retval] out boolean | exists
| ) |  |

Checks whether a regular file exists in the guest or not.

Parameters

  path | Path to the alleged regular file. Guest path style.
  followSymlinks | If `true`, symbolic links in the final component will be followed and the existance of the symlink target made the question for this method. If `false`, a symbolic link in the final component will make the method return `false` (because a symlink isn't a regular file).
  exists | Returns `true` if the file exists, `false` if not. `false` is also return if this path does not point to a file object.

Expected result codes:

  VBOX_E_IPRT_ERROR | Error while checking existence of the file specified.

## ◆ fileOpen()

void IGuestSession::fileOpen | ( | in wstring | path,
|  | in FileAccessMode | accessMode,
|  | in FileOpenAction | openAction,
|  | in unsigned long | creationMode,
|  | [retval] out IGuestFile | file
| ) |  |

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

Parameters

  path | Path to file to open. Guest path style.
  accessMode | The file access mode (read, write and/or append). See FileAccessMode for details.
  openAction | What action to take depending on whether the file exists or not. See FileOpenAction for details.
  creationMode | The UNIX-style access mode mask to create the file with if openAction requested the file to be created (otherwise ignored). Whether/how all three access groups and associated access rights are realized is guest OS dependent. The API does the best it can on each OS.
  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.
  VBOX_E_MAXIMUM_REACHED | The maximum of concurrent guest files has been reached.

## ◆ fileOpenEx()

void IGuestSession::fileOpenEx | ( | in wstring | path,
|  | in FileAccessMode | accessMode,
|  | in FileOpenAction | openAction,
|  | in FileSharingMode | sharingMode,
|  | in unsigned long | creationMode,
|  | in FileOpenExFlag[] | flags,
|  | [retval] out IGuestFile | file
| ) |  |

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

Parameters

  path | Path to file to open. Guest path style.
  accessMode | The file access mode (read, write and/or append). See FileAccessMode for details.
  openAction | What action to take depending on whether the file exists or not. See FileOpenAction for details.
  sharingMode | The file sharing mode in the guest. This parameter is currently ignore for all guest OSes. It will in the future be implemented for Windows, OS/2 and maybe Solaris guests only, the others will ignore it. Use FileSharingMode_All.
  creationMode | The UNIX-style access mode mask to create the file with if openAction requested the file to be created (otherwise ignored). Whether/how all three access groups and associated access rights are realized is guest OS dependent. The API does the best it can on each OS.
  flags | Zero or more FileOpenExFlag values.
  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.

## ◆ fileQuerySize()

void IGuestSession::fileQuerySize | ( | in wstring | path,
|  | in boolean | followSymlinks,
|  | [retval] out long long | size
| ) |  |

Queries the size of a regular file in the guest.

Parameters

  path | Path to the file which size is requested. Guest path style.
  followSymlinks | It `true`, symbolic links in the final path component will be followed to their target, and the size of the target is returned. If `false`, symbolic links in the final path component will make the method call fail (symblink is not a regular file).
  size | Queried file size.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | File to was not found.
  VBOX_E_IPRT_ERROR | Error querying file size.

## ◆ fsObjExists()

void IGuestSession::fsObjExists | ( | in wstring | path,
|  | in boolean | followSymlinks,
|  | [retval] out boolean | exists
| ) |  |

Checks whether a file system object (file, directory, etc) exists in the guest or not.

Parameters

  path | Path to the file system object to check the existance of. Guest path style.
  followSymlinks | If `true`, symbolic links in the final component will be followed and the method will instead check if the target exists. If `false`, symbolic links in the final component will satisfy the method and it will return `true` in exists.
  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.

## ◆ fsObjQueryInfo()

void IGuestSession::fsObjQueryInfo | ( | in wstring | path,
|  | in boolean | followSymlinks,
|  | [retval] out IGuestFsObjInfo | info
| ) |  |

Queries information about a file system object (file, directory, etc) in the guest.

Parameters

  path | Path to the file system object to gather information about. Guest path style.
  followSymlinks | Information about symbolic links is returned if `false`. Otherwise, symbolic links are followed and the returned information concerns itself with the symlink target if `true`.
  info | IGuestFsObjInfo object containing the information.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | The file system object was not found.
  VBOX_E_IPRT_ERROR | Error while querying information.

## ◆ fsObjRemove()

void IGuestSession::fsObjRemove | ( | in wstring | path | ) |

Removes a file system object (file, symlink, etc) in the guest.

Will not work on directories, use IGuestSession::directoryRemove to remove directories.

Parameters

  path | Path to the file system object to remove. Guest style path.

Expected result codes:

  E_NOTIMPL | The method has not been implemented yet.
  VBOX_E_OBJECT_NOT_FOUND | The file system object was not found.
  VBOX_E_IPRT_ERROR | For most other errors. We know this is unhelpful, will fix shortly...

Note
  This method will remove symbolic links in the final path component, not follow them.

## ◆ fsObjRemoveArray()

void IGuestSession::fsObjRemoveArray | ( | in wstring[] | path,
|  | [retval] out IProgress | progress
| ) |  |

Removes multiple file system objects (files, directories, symlinks, etc) in the guest.

Use with caution.

Parameters

  path | Array of paths to the file system objects to remove. Guest style path.
  progress | Progress object to track the operation to completion.

Expected result codes:

  E_NOTIMPL | The method has not been implemented yet.

Note
  This method is not implemented yet and will return E_NOTIMPL.
  This method will remove symbolic links in the final path component, not follow them.

## ◆ fsObjRename()

void IGuestSession::fsObjRename | ( | in wstring | oldPath,
|  | in wstring | newPath,
|  | in FsObjRenameFlag[] | flags
| ) |  |

Renames a file system object (file, directory, symlink, etc) in the guest.

Parameters

  oldPath | The current path to the object. Guest path style.
  newPath | The new path to the object. Guest path style.
  flags | Zero or more FsObjRenameFlag values.

Expected result codes:

  VBOX_E_OBJECT_NOT_FOUND | The file system object was not found.
  VBOX_E_IPRT_ERROR | For most other errors. We know this is unhelpful, will fix shortly...

## ◆ fsObjMove()

void IGuestSession::fsObjMove | ( | in wstring | source,
|  | in wstring | destination,
|  | in FsObjMoveFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Moves a file system object (file, directory, symlink, etc) from one guest location to another.

This differs from IGuestSession::fsObjRename in that it can move accross file system boundraries. In that case it will perform a copy and then delete the original. For directories, this can take a while and is subject to races.

Parameters

  source | Path to the file to move. Guest path style.
  destination | Where to move the file to (file, not directory). Guest path style.
  flags | Zero or more FsObjMoveFlag values.
  progress | Progress object to track the operation to completion.

Expected result codes:

  E_NOTIMPL | Not yet implemented.

## ◆ fsObjMoveArray()

void IGuestSession::fsObjMoveArray | ( | in wstring[] | source,
|  | in wstring | destination,
|  | in FsObjMoveFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Moves file system objects (files, directories, symlinks, etc) from one guest location to another.

Parameters

  source | Array of paths to the file system objects to move. Guest style path.
  destination | Where to move the file system objects to (directory). Guest path style.
  flags | Zero or more FsObjMoveFlag values.
  progress | Progress object to track the operation to completion.

Expected result codes:

  E_NOTIMPL | Not yet implemented.

## ◆ fsObjCopyArray()

void IGuestSession::fsObjCopyArray | ( | in wstring[] | source,
|  | in wstring | destination,
|  | in FileCopyFlag[] | flags,
|  | [retval] out IProgress | progress
| ) |  |

Copies file system objects (files, directories, symlinks, etc) from one guest location to another.

Parameters

  source | Array of paths to the file system objects to copy. Guest style path.
  destination | Where to copy the file system objects to (directory). Guest path style.
  flags | Zero or more FileCopyFlag values.
  progress | Progress object to track the operation to completion.

Expected result codes:

  E_NOTIMPL | Not yet implemented.

## ◆ fsObjSetACL()

void IGuestSession::fsObjSetACL | ( | in wstring | path,
|  | in boolean | followSymlinks,
|  | in wstring | acl,
|  | in unsigned long | mode
| ) |  |

Sets the access control list (ACL) of a file system object (file, directory, etc) in the guest.

Parameters

  path | Full path of the file system object which ACL to set.
  followSymlinks | If `true` symbolic links in the final component will be followed, otherwise, if `false`, the method will work directly on a symbolic link in the final component.
  acl | The ACL specification string. To-be-defined.
  mode | UNIX-style mode mask to use if acl is empty. As mention in IGuestSession::directoryCreate this is realized on a best effort basis and the exact behavior depends on the Guest OS.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ fsQueryFreeSpace()

void IGuestSession::fsQueryFreeSpace | ( | in wstring | path,
|  | [retval] out long long | freeSpace
| ) |  |

Returns the free space (in bytes) of a given path.

Parameters

  path | Full path to return the free space for.
  freeSpace | Free space (in bytes).

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ fsQueryInfo()

void IGuestSession::fsQueryInfo | ( | in wstring | path,
|  | [retval] out IGuestFsInfo | info
| ) |  |

Returns file system information for a given path.

Parameters

  path | Full path to return file system information for.
  info | IGuestFsInfo object containing the information.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ processCreate()

void IGuestSession::processCreate | ( | in wstring | executable,
|  | in wstring[] | arguments,
|  | in wstring[] | environmentChanges,
|  | in ProcessCreateFlag[] | flags,
|  | in unsigned long | timeoutMS,
|  | [retval] out IGuestProcess | guestProcess
| ) |  |

Creates a new process running in the guest.

The new process will be started asynchronously, meaning on return of this function it is not be guaranteed that the guest process is in a started state. To wait for successful startup, use the IProcess::waitFor call.

Parameters

  executable | Full path to the file to execute in the guest. The file has to exists in the guest VM with executable right to the session user in order to succeed. If empty/null, the first entry in the arguments array will be used instead (i.e. argv[0]).
  arguments | Array of arguments passed to the new process.
  environmentChanges | Set of environment changes to complement IGuestSession::environmentChanges. Takes precedence over the session ones. The changes are in putenv format, i.e. "VAR=VALUE" for setting and "VAR" for unsetting.

The changes are applied to the base environment of the impersonated guest user (IGuestSession::environmentBase) when creating the process. (This is done on the guest side of things in order to be compatible with older Guest Additions. That is one of the motivations for not passing in the whole environment here.)

Parameters

  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.
  guestProcess | Guest process object of the newly created process.

Expected result codes:

  VBOX_E_IPRT_ERROR | Error creating guest process.
  VBOX_E_MAXIMUM_REACHED | The maximum of concurrent guest processes has been reached.

Note
  Starting at VirtualBox 4.2 guest process execution by is default limited to serve up to 255 guest processes at a time. If all 255 guest processes are active and running, creating a new guest process will result in an error.

If ProcessCreateFlag_WaitForStdOut and/or ProcessCreateFlag_WaitForStdErr are set, the guest process will not enter the terminated state until all data from the specified streams have been read read.

Note
  Starting with VirtualBox 5.0 this array starts with argument 0 instead of argument 1 as in previous versions. Whether the zeroth argument can be passed to the guest depends on the VBoxService version running there. If you depend on this, check that the IGuestSession::protocolVersion is 3 or higher.

## ◆ processCreateEx()

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

Creates a new process running in the guest with the extended options for setting the process priority and affinity.

See IGuestSession::processCreate for more information.

Parameters

  executable | Full path to the file to execute in the guest. The file has to exists in the guest VM with executable right to the session user in order to succeed. If empty/null, the first entry in the arguments array will be used instead (i.e. argv[0]).
  arguments | Array of arguments passed to the new process.
  environmentChanges | Set of environment changes to complement IGuestSession::environmentChanges. Takes precedence over the session ones. The changes are in putenv format, i.e. "VAR=VALUE" for setting and "VAR" for unsetting.

The changes are applied to the base environment of the impersonated guest user (IGuestSession::environmentBase) when creating the process. (This is done on the guest side of things in order to be compatible with older Guest Additions. That is one of the motivations for not passing in the whole environment here.)

Parameters

  flags | Process creation flags, see ProcessCreateFlag for detailed description of available flags.
  timeoutMS | Timeout (in ms) for limiting the guest process' running time. Pass 0 for an infinite timeout. On timeout the guest process will be killed and its status will be put to an appropriate value. See ProcessStatus for more information.
  priority | Process priority to use for execution, see ProcessPriority for available priority levels.
  affinity | Processor affinity to set for the new process. This is a list of guest CPU numbers the process is allowed to run on.
  guestProcess | Guest process object of the newly created process.

Note
  Starting with VirtualBox 5.0 this array starts with argument 0 instead of argument 1 as in previous versions. Whether the zeroth argument can be passed to the guest depends on the VBoxService version running there. If you depend on this, check that the IGuestSession::protocolVersion is 3 or higher.
  This is silently ignored if not supported by Guest Additions.
  This is silently ignored if the guest does not support setting the affinity of processes, or if the Guest Additions does not implemet this feature.

## ◆ processGet()

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

## ◆ symlinkCreate()

void IGuestSession::symlinkCreate | ( | in wstring | symlink,
|  | in wstring | target,
|  | in SymlinkType | type
| ) |  |

Creates a symbolic link in the guest.

Parameters

  symlink | Path to the symbolic link that should be created. Guest path style.
  target | The path to the symbolic link target. If not an absolute, this will be relative to the symlink location at access time. Guest path style.
  type | The symbolic link type (mainly for Windows). See SymlinkType for more information.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ symlinkExists()

void IGuestSession::symlinkExists | ( | in wstring | symlink,
|  | [retval] out boolean | exists
| ) |  |

Checks whether a symbolic link exists in the guest.

Parameters

  symlink | Path to the alleged symbolic link. Guest path style.
  exists | Returns `true` if the symbolic link exists. Returns `false` if it does not exist, if the file system object identified by the path is not a symbolic link, or if the object type is inaccessible to the user, or if the symlink argument is empty.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ symlinkRead()

void IGuestSession::symlinkRead | ( | in wstring | symlink,
|  | in SymlinkReadFlag[] | flags,
|  | [retval] out wstring | target
| ) |  |

Reads the target value of a symbolic link in the guest.

Parameters

  symlink | Path to the symbolic link to read.
  flags | Zero or more SymlinkReadFlag values.
  target | Target value of the symbolic link. Guest path style.

Expected result codes:

  E_NOTIMPL | The method is not implemented yet.

## ◆ waitFor()

void IGuestSession::waitFor | ( | in unsigned long | waitFor,
|  | in unsigned long | timeoutMS,
|  | [retval] out GuestSessionWaitResult | reason
| ) |  |

Waits for one or more events to happen.

Parameters

  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.
  reason | The overall wait result; see GuestSessionWaitResult for more information.

## ◆ waitForArray()

void IGuestSession::waitForArray | ( | in GuestSessionWaitForFlag[] | waitFor,
|  | in unsigned long | timeoutMS,
|  | [retval] out GuestSessionWaitResult | reason
| ) |  |

Waits for one or more events to happen.

Scriptable version of waitFor.

Parameters

  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.
  reason | The overall wait result; see GuestSessionWaitResult for more information.

## Member Data Documentation

## ◆ user

readonly attribute wstring IGuestSession::user

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

## ◆ domain

readonly attribute wstring IGuestSession::domain

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

## ◆ name

readonly attribute wstring IGuestSession::name

Returns the session's friendly name.

## ◆ id

readonly attribute unsigned long IGuestSession::id

Returns the internal session ID.

## ◆ timeout

attribute unsigned long IGuestSession::timeout

Returns the session timeout (in ms).

Expected result codes:

  E_NOTIMPL | This attribute is not implemented yet.

## ◆ protocolVersion

readonly attribute unsigned long IGuestSession::protocolVersion

Returns the protocol version which is used by this session to communicate with the guest.

## ◆ status

readonly attribute GuestSessionStatus IGuestSession::status

Returns the current session status.

## ◆ environmentChanges

attribute wstring [] IGuestSession::environmentChanges

The set of scheduled environment changes to the base environment of the session.

They are in putenv format, i.e. "VAR=VALUE" for setting and "VAR" for unsetting. One entry per variable (change). The changes are applied when creating new guest processes.

This is writable, so to undo all the scheduled changes, assign it an empty array.

## ◆ environmentBase

readonly attribute wstring [] IGuestSession::environmentBase

The base environment of the session.

They are on the "VAR=VALUE" form, one array entry per variable.

Access fails with VBOX_E_NOT_SUPPORTED if the Guest Additions does not support the session base environment feature. Support for this was introduced with protocol version XXXX.

Access fails with VBOX_E_INVALID_OBJECT_STATE if the Guest Additions has yet to report the session base environment.

## ◆ processes

readonly attribute IGuestProcess [] IGuestSession::processes

Returns all current guest processes.

## ◆ pathStyle

readonly attribute PathStyle IGuestSession::pathStyle

The style of paths used by the guest.

Handy for giving the right kind of path specifications to IGuestSession::fileOpen and similar methods.

## ◆ currentDirectory

attribute wstring IGuestSession::currentDirectory

Gets or sets the current directory of the session.

Guest path style.

Expected result codes:

  E_NOTIMPL | This attribute is not implemented yet.

## ◆ userHome

readonly attribute wstring IGuestSession::userHome

Returns the user's home / profile directory.

Guest path style.

## ◆ userDocuments

readonly attribute wstring IGuestSession::userDocuments

Returns the user's documents directory.

Guest path style.

## ◆ directories

readonly attribute IGuestDirectory [] IGuestSession::directories

Returns all currently opened guest directories.

## ◆ files

readonly attribute IGuestFile [] IGuestSession::files

Returns all currently opened guest files.

## ◆ eventSource

readonly attribute IEventSource IGuestSession::eventSource

Event source for guest session events.