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 cwd, 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 cwd, 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
	Gets or sets 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 wstring[]	mountPoints
	Returns all currently accessible (disk-based) mount points.
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:

{8B2B6773-8B5A-4CD2-95F8-38FAF73913E1}

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

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.

processCreate()

void IGuestSession::processCreate	(	in wstring	executable,
		in wstring[]	arguments,
		in wstring	cwd,
		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 exist 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.
cwd	Path to the directory in which to execute in the guest. The directory has to exist in the guest VM with search rights to the session user in order to succeed. If empty/null, the session user's default (typically 'home') directory is used. If not a full path, it is interpreted relative to the default directory; e.g. 'work' means '$HOME/work' (according to the guest's '$HOME'- like concept).
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.

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	cwd,
		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 exist 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.
cwd	Path to the directory in which to execute in the guest. The directory has to exist in the guest VM with search rights to the session user in order to succeed. If empty/null, the session user's default (typically 'home') directory is used. If not a full path, it is interpreted relative to the default directory; e.g. 'work' means '$HOME/work' (according to the guest's '$HOME'- like concept).
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 do 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.

Note

Deprecated and will be removed. Use IGuestSession::waitForArray instead.

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

Gets or sets 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 do 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.

mountPoints

readonly attribute wstring [] IGuestSession::mountPoints

Returns all currently accessible (disk-based) mount points.

On Windows guests, this returns the currently mapped disk drives.

Access fails with VBOX_E_NOT_SUPPORTED if the Guest Additions do not support this feature.

Expected result codes:

VBOX_E_NOT_SUPPORTED

If the Guest Additions do not support this feature.

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.