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
sourcesPaths 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.
filtersArray of source filters. This uses the DOS/NT style wildcard characters '?' and '*'.
flagsArray 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
destinationWhere to put the sources on the host. Host path style.
progressProgress 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
sourcesPaths 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.
filtersArray of source filters. This uses the DOS/NT style wildcard characters '?' and '*'.
flagsArray 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
destinationWhere to put the sources on the guest. Guest path style.
progressProgress 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
sourceThe path to the directory to copy (in the guest). Guest path style.
destinationThe path to the target directory (in the guest). Unless the DirectoryCopyFlag_CopyIntoExisting flag is given, the directory shall not already exist. Guest path style.
flagsZero or more DirectoryCopyFlag values.
progressProgress object to track the operation to completion.
Expected result codes:
E_NOTIMPLNot 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
sourcePath to the directory on the guest side that should be copied to the host. Guest path style.
destinationWhere to put the directory on the host. Unless the DirectoryCopyFlag_CopyIntoExisting flag is given, the directory shall not already exist. Host path style.
flagsZero or more DirectoryCopyFlag values.
progressProgress 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
sourcePath to the directory on the host side that should be copied to the guest. Host path style.
destinationWhere to put the file in the guest. Unless the DirectoryCopyFlag_CopyIntoExisting flag is given, the directory shall not already exist. Guest style path.
flagsZero or more DirectoryCopyFlag values.
progressProgress 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
pathPath to the directory directory to be created. Guest path style.
modeThe 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.
flagsZero or more DirectoryCreateFlag flags.
Expected result codes:
VBOX_E_IPRT_ERRORError 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
templateNameTemplate 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.
modeThe 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
pathThe path to the directory in which the temporary directory should be created. Guest path style.
secureWhether 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.
directoryOn success this will contain the full path to the created directory. Guest path style.
Expected result codes:
VBOX_E_NOT_SUPPORTEDThe operation is not possible as requested on this particular guest type.
E_INVALIDARGInvalid argument. This includes an incorrectly formatted template, or a non-absolute path.
VBOX_E_IPRT_ERRORThe 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
pathPath to the directory to check if exists. Guest path style.
followSymlinksIf 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).
existsReturns true if the directory exists, false if not, or is not a directory.
Expected result codes:
VBOX_E_IPRT_ERRORError 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
pathPath to the directory to open. Guest path style.
filterOptional directory listing filter to apply. This uses the DOS/NT style wildcard characters '?' and '*'.
flagsZero or more DirectoryOpenFlag flags.
directoryIGuestDirectory object containing the opened directory.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUNDDirectory to open was not found.
VBOX_E_IPRT_ERRORError while opening the directory.
VBOX_E_MAXIMUM_REACHEDThe 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
pathPath 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
pathPath of the directory that is to be removed recursively. Guest path style.
flagsZero or more DirectoryRemoveRecFlag flags.
progressProgress 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
nameName of the environment variable to set. This cannot be empty nor can it contain any equal signs.
valueValue 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
nameName 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
nameName of the environment variable to get.This cannot be empty nor can it contain any equal signs.
valueThe 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_SUPPORTEDIf the Guest Additions does not support the session base environment feature. Support for this was introduced with protocol version XXXX.
VBOX_E_INVALID_OBJECT_STATEIf 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
nameName of the environment variable to look for. This cannot be empty nor can it contain any equal signs.
existsTRUE if the variable exists, FALSE if not.
Expected result codes:
VBOX_E_NOT_SUPPORTEDIf the Guest Additions does not support the session base environment feature. Support for this was introduced with protocol version XXXX.
VBOX_E_INVALID_OBJECT_STATEIf 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
sourceThe path to the file to copy (in the guest). Guest path style.
destinationThe path to the target file (in the guest). This cannot be a directory. Guest path style.
flagsZero or more FileCopyFlag values.
progressProgress object to track the operation to completion.
Expected result codes:
E_NOTIMPLNot 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
sourcePath to the file on the guest side that should be copied to the host. Guest path style.
destinationWhere to put the file on the host (file, not directory). Host path style.
flagsZero or more FileCopyFlag values.
progressProgress object to track the operation to completion.
Expected result codes:
VBOX_E_IPRT_ERRORError 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
sourcePath to the file on the host side that should be copied to the guest. Host path style.
destinationWhere to put the file in the guest (file, not directory). Guest style path.
flagsZero or more FileCopyFlag values.
progressProgress object to track the operation to completion.
Expected result codes:
VBOX_E_IPRT_ERRORError 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
templateNameTemplate 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.
modeThe 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
pathThe path to the directory in which the temporary file should be created.
secureWhether 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.
fileOn success this will contain an open file object for the new temporary file.
Expected result codes:
VBOX_E_NOT_SUPPORTEDThe operation is not possible as requested on this particular guest OS.
E_INVALIDARGInvalid argument. This includes an incorrectly formatted template, or a non-absolute path.
VBOX_E_IPRT_ERRORThe 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
pathPath to the alleged regular file. Guest path style.
followSymlinksIf 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).
existsReturns 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_ERRORError 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
pathPath to file to open. Guest path style.
accessModeThe file access mode (read, write and/or append). See FileAccessMode for details.
openActionWhat action to take depending on whether the file exists or not. See FileOpenAction for details.
creationModeThe 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.
fileIGuestFile object representing the opened file.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUNDFile to open was not found.
VBOX_E_IPRT_ERRORError while opening the file.
VBOX_E_MAXIMUM_REACHEDThe 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
pathPath to file to open. Guest path style.
accessModeThe file access mode (read, write and/or append). See FileAccessMode for details.
openActionWhat action to take depending on whether the file exists or not. See FileOpenAction for details.
sharingModeThe 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.
creationModeThe 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.
flagsZero or more FileOpenExFlag values.
fileIGuestFile object representing the opened file.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUNDFile to open was not found.
VBOX_E_IPRT_ERRORError 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
pathPath to the file which size is requested. Guest path style.
followSymlinksIt 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).
sizeQueried file size.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUNDFile to was not found.
VBOX_E_IPRT_ERRORError 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
pathPath to the file system object to check the existance of. Guest path style.
followSymlinksIf 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.
existsReturns true if the file exists, false if not.
Expected result codes:
VBOX_E_IPRT_ERRORError 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
pathPath to the file system object to gather information about. Guest path style.
followSymlinksInformation about symbolic links is returned if false. Otherwise, symbolic links are followed and the returned information concerns itself with the symlink target if true.
infoIGuestFsObjInfo object containing the information.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUNDThe file system object was not found.
VBOX_E_IPRT_ERRORError 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
pathPath to the file system object to remove. Guest style path.
Expected result codes:
E_NOTIMPLThe method has not been implemented yet.
VBOX_E_OBJECT_NOT_FOUNDThe file system object was not found.
VBOX_E_IPRT_ERRORFor 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
pathArray of paths to the file system objects to remove. Guest style path.
progressProgress object to track the operation to completion.
Expected result codes:
E_NOTIMPLThe 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
oldPathThe current path to the object. Guest path style.
newPathThe new path to the object. Guest path style.
flagsZero or more FsObjRenameFlag values.
Expected result codes:
VBOX_E_OBJECT_NOT_FOUNDThe file system object was not found.
VBOX_E_IPRT_ERRORFor 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
sourcePath to the file to move. Guest path style.
destinationWhere to move the file to (file, not directory). Guest path style.
flagsZero or more FsObjMoveFlag values.
progressProgress object to track the operation to completion.
Expected result codes:
E_NOTIMPLNot 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
sourceArray of paths to the file system objects to move. Guest style path.
destinationWhere to move the file system objects to (directory). Guest path style.
flagsZero or more FsObjMoveFlag values.
progressProgress object to track the operation to completion.
Expected result codes:
E_NOTIMPLNot 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
sourceArray of paths to the file system objects to copy. Guest style path.
destinationWhere to copy the file system objects to (directory). Guest path style.
flagsZero or more FileCopyFlag values.
progressProgress object to track the operation to completion.
Expected result codes:
E_NOTIMPLNot 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
pathFull path of the file system object which ACL to set.
followSymlinksIf 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.
aclThe ACL specification string. To-be-defined.
modeUNIX-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_NOTIMPLThe 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
pathFull path to return the free space for.
freeSpaceFree space (in bytes).
Expected result codes:
E_NOTIMPLThe 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
pathFull path to return file system information for.
infoIGuestFsInfo object containing the information.
Expected result codes:
E_NOTIMPLThe 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
executableFull 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]).
argumentsArray of arguments passed to the new process.
environmentChangesSet 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
flagsProcess creation flags; see ProcessCreateFlag for more information.
timeoutMSTimeout (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.
guestProcessGuest process object of the newly created process.
Expected result codes:
VBOX_E_IPRT_ERRORError creating guest process.
VBOX_E_MAXIMUM_REACHEDThe 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
executableFull 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]).
argumentsArray of arguments passed to the new process.
environmentChangesSet 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
flagsProcess creation flags, see ProcessCreateFlag for detailed description of available flags.
timeoutMSTimeout (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.
priorityProcess priority to use for execution, see ProcessPriority for available priority levels.
affinityProcessor affinity to set for the new process. This is a list of guest CPU numbers the process is allowed to run on.
guestProcessGuest 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
pidProcess ID (PID) to get guest process for.
guestProcessGuest 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
symlinkPath to the symbolic link that should be created. Guest path style.
targetThe path to the symbolic link target. If not an absolute, this will be relative to the symlink location at access time. Guest path style.
typeThe symbolic link type (mainly for Windows). See SymlinkType for more information.
Expected result codes:
E_NOTIMPLThe 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
symlinkPath to the alleged symbolic link. Guest path style.
existsReturns 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_NOTIMPLThe 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
symlinkPath to the symbolic link to read.
flagsZero or more SymlinkReadFlag values.
targetTarget value of the symbolic link. Guest path style.
Expected result codes:
E_NOTIMPLThe 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
waitForSpecifies what to wait for; see GuestSessionWaitForFlag for more information.
timeoutMSTimeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
reasonThe 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
waitForSpecifies what to wait for; see GuestSessionWaitForFlag for more information.
timeoutMSTimeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
reasonThe 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_NOTIMPLThis 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_NOTIMPLThis 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.