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

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

Public Member Functions

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

Public Attributes

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

Detailed Description

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

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

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

  Every guest session has its own environment variable block which gets
  automatically applied when starting a new guest process via
  @link IGuestSession::processCreate IGuestSession::processCreate@endlink<b></b> or @link IGuestSession::processCreateEx IGuestSession::processCreateEx@endlink<b></b>.
  To override (or unset) certain environment variables already set by the
  guest session, one can specify a per-process environment block when using
  one of the both above mentioned process creation calls.
Interface ID:
{57EB82A8-822B-42C1-9D1C-5C54BC3D3250}

Member Function Documentation

void IGuestSession::close ( )

Closes this session.

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

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

Copies a file from guest to the host.

Parameters
sourceSource file on the guest to copy to the host.
destDestination file name on the host.
flagsCopy flags; see CopyFileFlag for more information.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error starting the copy operation.

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

Copies a file from host to the guest.

Parameters
sourceSource file on the host to copy to the guest.
destDestination file name on the guest.
flagsCopy flags; see CopyFileFlag for more information.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error starting the copy operation.

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

Create a directory on the guest.

Parameters
pathFull path of directory to create.
modeFile creation mode.
flagsCreation flags; see DirectoryCreateFlag for more information.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error while creating the directory.

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

Create a temporary directory on the guest.

Parameters
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 mode of the directory to create. Use 0700 unless there are reasons not to. This parameter is ignored if "secure" is specified.
pathThe absolute path to create the temporary directory in.
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 name of the directory created with full path.
Expected result codes:
VBOX_E_NOT_SUPPORTED The operation is not possible as requested on this particular guest type.
E_INVALIDARG Invalid argument. This includes an incorrectly formatted template, or a non-absolute path.
VBOX_E_IPRT_ERROR The temporary directory could not be created. Possible reasons include a non-existing path or an insecure path when the secure option was requested.
void IGuestSession::directoryExists ( in wstring  path,
[retval] out boolean  exists 
)

Checks whether a directory exists on the guest or not.

Parameters
pathDirectory to check existence for.
existsReturns true if the directory exists, false if not.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error while checking existence of the directory specified.

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

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

Parameters
pathFull path to file to open.
filterOpen filter to apply. This can include wildcards like ? and *.
flagsOpen flags; see DirectoryOpenFlag for more information.
directoryIGuestDirectory object containing the opened directory.
  @par Expected result codes:
<table>

VBOX_E_OBJECT_NOT_FOUND

Directory to open was not found.

VBOX_E_IPRT_ERROR

Error while opening the directory.

void IGuestSession::directoryQueryInfo ( in wstring  path,
[retval] out IGuestFsObjInfo  info 
)

Queries information of a directory on the guest.

Parameters
pathDirectory to query information for.
infoIGuestFsObjInfo object containing the queried information.
  @par Expected result codes:
<table>

VBOX_E_OBJECT_NOT_FOUND

Directory to query information for was not found.

VBOX_E_IPRT_ERROR

Error querying information.

void IGuestSession::directoryRemove ( in wstring  path)

Removes a guest directory if not empty.

Parameters
pathFull path of directory to remove.
  @par Expected result codes:
<table><tr>

E_NOTIMPL

The method is not implemented yet.

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

Removes a guest directory recursively.

Parameters
pathFull path of directory to remove recursively.
flagsRemove flags; see DirectoryRemoveRecFlag for more information.
progressProgress object to track the operation completion.
  @par Expected result codes:
<table><tr>

E_NOTIMPL

The method is not implemented yet.

void IGuestSession::directoryRename ( in wstring  source,
in wstring  dest,
in PathRenameFlag[]  flags 
)

Renames a directory on the guest.

Parameters
sourceSource directory to rename.
destDestination directory to rename the source to.
flagsRename flags; see PathRenameFlag for more information.
  @par Expected result codes:
<table><tr>

E_NOTIMPL

The method is not implemented yet.

void IGuestSession::directorySetACL ( in wstring  path,
in wstring  acl 
)

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

Parameters
pathFull path of directory to set the ACL for.
aclActual ACL string to set. Must comply with the guest OS.
  @par Expected result codes:
<table><tr>

E_NOTIMPL

The method is not implemented yet.

void IGuestSession::environmentClear ( )

Clears (deletes) all session environment variables.

  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error while clearing the session environment variables.

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

Gets the value of a session environment variable.

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

Sets a session environment variable.

Parameters
nameName of session environment variable to set.
valueValue to set the session environment variable to.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error while setting the session environment variable.

void IGuestSession::environmentUnset ( in wstring  name)

Unsets session environment variable.

Parameters
nameName of session environment variable to unset (clear).
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error while unsetting the session environment variable.

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

Creates a temporary file on the guest.

Parameters
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 mode of the file to create. Use 0700 unless there are reasons not to. This parameter is ignored if "secure" is specified.
pathThe absolute path to create the temporary file in.
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_SUPPORTED The operation is not possible as requested on this particular guest type.
E_INVALIDARG Invalid argument. This includes an incorrectly formatted template, or a non-absolute path.
VBOX_E_IPRT_ERROR The temporary file could not be created. Possible reasons include a non-existing path or an insecure path when the secure option was requested.
void IGuestSession::fileExists ( in wstring  path,
[retval] out boolean  exists 
)

Checks whether a file exists on the guest or not.

Parameters
pathFile to check existence for.
existsReturns true if the file exists, false if not.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Error while checking existence of the file specified.

void IGuestSession::fileRemove ( in wstring  path)

Removes a single file on the guest.

Parameters
pathPath to the file to remove.
  @par Expected result codes:
<table>

VBOX_E_OBJECT_NOT_FOUND

File to remove was not found.

VBOX_E_IPRT_ERROR

Error while removing the file.

void IGuestSession::fileOpen ( in wstring  path,
in wstring  openMode,
in wstring  disposition,
in unsigned long  creationMode,
in long long  offset,
[retval] out IGuestFile  file 
)

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

Parameters
pathFull path to file to open.
openModeThe file open mode.
dispositionThe file disposition.
creationModeThe file creation mode.
offsetThe initial read/write offset.
fileIGuestFile object representing the opened file.
  @par Expected result codes:
<table>

VBOX_E_OBJECT_NOT_FOUND

File to open was not found.

VBOX_E_IPRT_ERROR

Error while opening the file.

void IGuestSession::fileQueryInfo ( in wstring  path,
[retval] out IGuestFsObjInfo  info 
)

Queries information of a file on the guest.

Parameters
pathFile to query information for.
infoIGuestFsObjInfo object containing the queried information.
  @par Expected result codes:
<table>

VBOX_E_OBJECT_NOT_FOUND

File to query information for was not found.

VBOX_E_IPRT_ERROR

Error querying information.

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

Queries the size of a file on the guest.

Parameters
pathFile to query the size for.
sizeQueried file size.
  @par Expected result codes:
<table>

VBOX_E_OBJECT_NOT_FOUND

File to rename was not found.

VBOX_E_IPRT_ERROR

Error querying file size.

void IGuestSession::fileRename ( in wstring  source,
in wstring  dest,
in PathRenameFlag[]  flags 
)

Renames a file on the guest.

Parameters
sourceSource file to rename.
destDestination file to rename the source to.
flagsRename flags; see PathRenameFlag for more information.
  @par Expected result codes:
<table><tr>

E_NOTIMPL

The method is not implemented yet.

void IGuestSession::fileSetACL ( in wstring  file,
in wstring  acl 
)

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

Parameters
fileFull path of file to set the ACL for.
aclActual ACL string to set. Must comply with the guest OS.
  @par Expected result codes:
<table><tr>

E_NOTIMPL

The method is not implemented yet.

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

Executes an existing program inside the guest VM.

Parameters
commandFull path name of the command to execute on the guest; the commands has to exists in the guest VM in order to be executed.
argumentsArray of arguments passed to the execution command.
environmentEnvironment variables that can be set while the command is being executed, in form of "NAME=VALUE"; one pair per entry. To unset a variable just set its name ("NAME") without a value.

This parameter can be used to override environment variables set by the guest session, which will be applied to the newly started process in any case.

Parameters
flagsProcess creation flags; see ProcessCreateFlag for more information.
timeoutMSTimeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
guestProcessGuest process object of the newly created process.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Could not create process.

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

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

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

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

Executes an existing program inside the guest VM.

Extended version for also setting the process priority and affinity.

Parameters
commandFull path name of the command to execute on the guest; the commands has to exists in the guest VM in order to be executed.
argumentsArray of arguments passed to the execution command.
environmentEnvironment variables that can be set while the command is being executed, in form of "NAME=VALUE"; one pair per entry. To unset a variable just set its name ("NAME") without a value.

This parameter can be used to override environment variables set by the guest session, which will be applied to the newly started process in any case.

Parameters
flagsProcess creation flags; see ProcessCreateFlag for more information.
timeoutMSTimeout (in ms) to wait for the operation to complete. Pass 0 for an infinite timeout.
priorityProcess priority to use for execution; see see ProcessPriority for more information.
affinityProcess affinity to use for execution. This parameter is not implemented yet.
guestProcessGuest process object of the newly created process.
  @par Expected result codes:
<table><tr>

VBOX_E_IPRT_ERROR

Could not create process.

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

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

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

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

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

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

Creates a symbolic link on the guest.

Parameters
sourceThe name of the symbolic link.
targetThe path to the symbolic link target.
typeThe symbolic link type; see SymlinkReadFlag for more information.
Expected result codes:
E_NOTIMPL The method is not implemented yet.
void IGuestSession::symlinkExists ( in wstring  symlink,
[retval] out boolean  exists 
)

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

Parameters
symlinkSymbolic link to check existence for.
existsReturns true if the symbolic link exists, false if not.
  @par Expected result codes:
<table><tr>

E_NOTIMPL

The method is not implemented yet.

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

Reads a symbolic link on the guest.

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

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

Parameters
pathSymbolic link to remove.
  @par Expected result codes:
<table><tr>

E_NOTIMPL

The method is not implemented yet.

void IGuestSession::symlinkRemoveFile ( in wstring  file)

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

Parameters
fileSymbolic link to remove.
  @par Expected result codes:
<table><tr>

E_NOTIMPL

The method is not implemented yet.

Member Data Documentation

readonly attribute wstring IGuestSession::user

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

readonly attribute wstring IGuestSession::domain

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

readonly attribute wstring IGuestSession::name

Returns the session's friendly name.

readonly attribute unsigned long IGuestSession::id

Returns the internal session ID.

attribute unsigned long IGuestSession::timeout

Returns the session timeout (in ms).

  @par Expected result codes:
<table><tr>

E_NOTIMPL

The method is not implemented yet.

attribute wstring [] IGuestSession::environment

Returns the current session environment.

readonly attribute IGuestProcess [] IGuestSession::processes

Returns all current guest processes.

readonly attribute IGuestDirectory [] IGuestSession::directories

Returns all currently opened guest directories.

readonly attribute IGuestFile [] IGuestSession::files

Returns all currently opened guest files.