Index: /trunk/src/VBox/Main/idl/VirtualBox.xidl
===================================================================
--- /trunk/src/VBox/Main/idl/VirtualBox.xidl	(revision 55582)
+++ /trunk/src/VBox/Main/idl/VirtualBox.xidl	(revision 55583)
@@ -4080,5 +4080,5 @@
     <attribute name="guestAddress" type="long" readonly="yes">
       <desc>
-        Address of device on the guest.
+        Address of device in the guest.
       </desc>
     </attribute>
@@ -9910,5 +9910,5 @@
       <desc>A guest user has locked its account. This might
         include running a password-protected screensaver
-        on the guest.
+        in the guest.
         <note>This property is not implemented yet!</note>
       </desc>
@@ -9933,5 +9933,5 @@
         The event will be triggered if a guest user is not active for
         at least 5 seconds. This threshold can be adjusted by either altering
-        VBoxService's command line on the guest to
+        VBoxService's command line in the guest to
         <pre>--vminfo-user-idle-threshold &lt;ms&gt;</pre>
         , or by setting the per-VM guest property
@@ -10108,5 +10108,5 @@
       <desc>
         The waiting operation timed out. Also use if the guest process has
-        timed out on the guest side (kill attempted).
+        timed out in the guest side (kill attempted).
       </desc>
     </const>
@@ -10787,15 +10787,17 @@
     >
     <desc>
-      A guest session represents one impersonated user account on the guest, so
+      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 <link to="IGuest::createSession"/>.
 
       There can be a maximum of 32 sessions at once per VM, whereas session 0
-      is reserved for the root session. 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 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 to="IGuestSession::fileOpen"/> or
+      is reserved for the root session.
+<!-- r=bird: Is the root session part of the maximum of 32?? Not really clear. -->
+      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 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 to="IGuestSession::fileOpen"/> or
       <link to="IGuestSession::directoryOpen"/> for example).
 
@@ -10803,20 +10805,20 @@
       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 to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>.
-      To override (or unset) certain environment variables already set by the
-      guest session, one can specify a per-process environment block when using
-      one of the both above mentioned process creation calls.
+      A set of environment variables changes is associated with each session.
+      These are applied to the standard environment of the impersonated guest
+      user when creating a new guest process.  For additional flexibility the
+      <link to="IGuestSession::processCreate"/> and
+      <link to="IGuestSession::processCreateEx"/> methods allows you to specify
+      individual environment changes for each process you create.
     </desc>
 
     <attribute name="user" type="wstring" readonly="yes">
       <desc>Returns the user name used by this session to impersonate
-        users on the guest.
+        users in the guest.
       </desc>
     </attribute>
     <attribute name="domain" type="wstring" readonly="yes">
       <desc>Returns the domain name used by this session to impersonate
-        users on the guest.
+        users in the guest.
       </desc>
     </attribute>
@@ -10829,4 +10831,5 @@
     <attribute name="timeout" type="unsigned long">
       <desc>
+<!-- r=bird: Using 'Returns' for writable attributes is misleading. -->
         Returns the session timeout (in ms).
         <result name="E_NOTIMPL">
@@ -10843,6 +10846,11 @@
     </attribute>
     <attribute name="environment" type="wstring" safearray="yes">
-      <desc>
-        Returns the current session environment.
+      <!-- r=bird: Would probably be a great idea to rename this attribute as
+                   it is misleading and will cause worse confusion if we ever
+                   expose the default environment for session (which arguably
+                   would be useful in many ways).   -->
+      <desc>
+        The set of environment changes.  They are in putenv format, i.e.
+        "NAME=VALUE" for setting and "NAME" for unsetting.
       </desc>
     </attribute>
@@ -10873,5 +10881,5 @@
         processes which are not referenced by clients anymore will be
         closed. Guest processes which fall into this category and still
-        are running on the guest will be terminated automatically.
+        are running in the guest will be terminated automatically.
       </desc>
     </method>
@@ -10886,5 +10894,5 @@
       </desc>
       <param name="source" type="wstring" dir="in">
-        <desc>Source file on the guest to copy to the host.</desc>
+        <desc>Source file in the guest to copy to the host.</desc>
       </param>
       <param name="dest" type="wstring" dir="in">
@@ -10911,5 +10919,5 @@
       </param>
       <param name="dest" type="wstring" dir="in">
-        <desc>Destination file name on the guest.</desc>
+        <desc>Destination file name in the guest.</desc>
       </param>
       <param name="flags" type="CopyFileFlag" dir="in" safearray="yes">
@@ -10923,5 +10931,5 @@
     <method name="directoryCreate">
       <desc>
-        Create a directory on the guest.
+        Create a directory in the guest.
 
         <result name="VBOX_E_IPRT_ERROR">
@@ -10942,5 +10950,5 @@
     <method name="directoryCreateTemp">
       <desc>
-        Create a temporary directory on the guest.
+        Create a temporary directory in the guest.
 
         <result name="VBOX_E_NOT_SUPPORTED">
@@ -10987,5 +10995,5 @@
     <method name="directoryExists">
       <desc>
-        Checks whether a directory exists on the guest or not.
+        Checks whether a directory exists in the guest or not.
 
         <result name="VBOX_E_IPRT_ERROR">
@@ -11029,5 +11037,5 @@
     <method name="directoryQueryInfo">
       <desc>
-        Queries information of a directory on the guest.
+        Queries information about a directory in the guest.
 
         <result name="VBOX_E_OBJECT_NOT_FOUND">
@@ -11073,5 +11081,5 @@
     <method name="directoryRename">
       <desc>
-        Renames a directory on the guest.
+        Renames a directory in the guest.
       </desc>
       <param name="source" type="wstring" dir="in">
@@ -11102,4 +11110,5 @@
     </method>
 
+<!-- r=bird: Remove this it duplicates the 'environment' attribute. -->
     <method name="environmentClear">
       <desc>
@@ -11107,4 +11116,5 @@
 
         <result name="VBOX_E_IPRT_ERROR">
+<!-- r=bird: No, it won't return this result, because you're just doing .clear() on a vector. -->
           Error while clearing the session environment variables.
         </result>
@@ -11113,8 +11123,13 @@
 
     <method name="environmentGet">
-      <desc>
-        Gets the value of a session environment variable.
+<!-- r=bird: Remove this because the interface isn't suitable for returning
+'unset' or empty values, and it can easily be misunderstood.  Besides there is
+hardly a usecase for it as long as it just works on environment changes and
+there is the 'environment' attribute. -->
+      <desc>
+        Gets the value of an environment variable scheduled to be set.
 
         <result name="VBOX_E_IPRT_ERROR">
+<!-- r=bird: Would never return this, only invalid input or out of memory. -->
           Error while getting the value of the session environment variable.
         </result>
@@ -11125,6 +11140,10 @@
       <param name="value" type="wstring" dir="return">
         <desc>
-          Value of the session environment variable specified. If this variable
-          does not exist and empty value will be returned.
+          Value of the session environment variable specified.  If this variable
+          does not exist an empty value will be returned.
+          <note>
+            An empty value will also be return for a variable with an value or
+            a unset-variable entry.
+          </note>
         </desc>
       </param>
@@ -11133,12 +11152,10 @@
     <method name="environmentSet">
       <desc>
-        Sets a session environment variable.
-
-        <result name="VBOX_E_IPRT_ERROR">
-          Error while setting the session environment variable.
-        </result>
+        Schedules setting an environment variable when creating the next guest
+        process.  This affects the <link to="environment"/> attribute.
       </desc>
       <param name="name" type="wstring" dir="in">
-        <desc>Name of session environment variable to set.</desc>
+        <desc>Name of the environment variable to set.  This cannot be empty
+          nor can it contain any equal signs.</desc>
       </param>
       <param name="value" type="wstring" dir="in">
@@ -11149,12 +11166,11 @@
     <method name="environmentUnset">
       <desc>
-        Unsets a session environment variable.
-
-        <result name="VBOX_E_IPRT_ERROR">
-          Error while unsetting the session environment variable.
-        </result>
+        Schedules unsetting (removing) an environment variable when creating
+        the next guest process.  This affects the <link to="environment"/>
+        attribute.
       </desc>
       <param name="name" type="wstring" dir="in">
-        <desc>Name of session environment variable to unset (clear).</desc>
+        <desc>Name of the environment variable to unset.  This cannot be empty
+          nor can it contain any equal signs.</desc>
       </param>
     </method>
@@ -11162,5 +11178,5 @@
     <method name="fileCreateTemp">
       <desc>
-        Creates a temporary file on the guest.
+        Creates a temporary file in the guest.
 
         <result name="VBOX_E_NOT_SUPPORTED">
@@ -11209,5 +11225,5 @@
     <method name="fileExists">
       <desc>
-        Checks whether a file exists on the guest or not.
+        Checks whether a file exists in the guest or not.
 
         <result name="VBOX_E_IPRT_ERROR">
@@ -11225,5 +11241,5 @@
     <method name="fileRemove">
       <desc>
-        Removes a single file on the guest.
+        Removes a single file in the guest.
 
         <result name="VBOX_E_OBJECT_NOT_FOUND">
@@ -11331,5 +11347,5 @@
       </param>
       <param name="sharingMode" type="wstring" dir="in">
-        <desc>The file sharing mode on the guest. This parameter
+        <desc>The file sharing mode in the guest. This parameter
           is not implemented yet. Pass an empty string here.</desc>
       </param>
@@ -11348,5 +11364,5 @@
     <method name="fileQueryInfo">
       <desc>
-        Queries information of a file on the guest.
+        Queries information about a file in the guest.
 
         <result name="VBOX_E_OBJECT_NOT_FOUND">
@@ -11367,5 +11383,5 @@
     <method name="fileQuerySize">
       <desc>
-        Queries the size of a file on the guest.
+        Queries the size of a file in the guest.
 
         <result name="VBOX_E_OBJECT_NOT_FOUND">
@@ -11386,5 +11402,5 @@
     <method name="fileRename">
       <desc>
-        Renames a file on the guest.
+        Renames a file in the guest.
       </desc>
       <param name="source" type="wstring" dir="in">
@@ -11401,5 +11417,5 @@
     <method name="fileSetACL">
       <desc>
-        Sets the ACL (Access Control List) of a file on the guest.
+        Sets the ACL (Access Control List) of a file in the guest.
 
         <result name="E_NOTIMPL">
@@ -11417,18 +11433,18 @@
     <method name="processCreate">
       <desc>
-        Creates a new process running on the guest. The new process will be
+        Creates a new process running in the guest. The new process will be
         started asynchronously, meaning on return of this function it is not
-        guaranteed that the guest process is in a started state. To wait for
+        be guaranteed that the guest process is in a started state. To wait for
         successful startup, use the <link to="IProcess::waitFor"/> call.
 
         <note>
-          Starting at VirtualBox 4.2 guest process execution by default is limited
+          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 still active and running, creating a new guest process will result in an
-          appropriate error message.
+          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 exit until all data from the specified
-          streams are read out.
+          are set, the guest process will not enter the terminated state until
+          all data from the specified streams have been read read.
         </note>
 
@@ -11439,8 +11455,8 @@
       <param name="executable" type="wstring" dir="in">
         <desc>
-          Full path name of the file to execute on the guest.  The file has to
+          Full path to the file to execute in the guest.  The file has to
           exists in the guest VM with executable right to the session user in
-          order to be executed. If empty/null, the first entry in the
-          @a arguments array will be used in stead (i.e. argv[0]).
+          order to succeed.  If empty/null, the first entry in the
+          @a arguments array will be used instead (i.e. argv[0]).
         </desc>
       </param>
@@ -11451,5 +11467,6 @@
             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.
+            version running there.  If you depend on this, check that the
+            <link to="IGuestSession::protocolVersion"/> is 3 or higher.
           </note>
         </desc>
@@ -11457,10 +11474,11 @@
       <param name="environment" type="wstring" dir="in" safearray="yes">
         <desc>
-          Environment variables to set or unset for the guest process,
-          relative to the environment of the guest session.
-
-          The variables are in the traditional "NAME=VALUE" form with one pair
-          per array entry.  To unset a variable just leave out the equal sign
-          and the value ("NAME").
+          Set of environment changes to complement
+          <link to="IGuestSession::environment"/>.  Takes precedence over
+          the session ones.  The changes are in putenv format, i.e.
+          "NAME=VALUE" for setting and "NAME" for unsetting.
+
+          The changes are applied to the standard environment of the
+          impersonated guest user when creating the process.
         </desc>
       </param>
@@ -11486,6 +11504,6 @@
     <method name="processCreateEx">
       <desc>
-        Creates a new process running on the guest. Extended version for
-        also setting the process priority and affinity.
+        Creates a new process running in the guest with the extended options
+        for setting the process priority and affinity.
 
         See <link to="IGuestSession::processCreate"/> for more information.
@@ -11493,8 +11511,8 @@
       <param name="executable" type="wstring" dir="in">
         <desc>
-          Full path name of the file to execute on the guest.  The file has to
+          Full path to the file to execute in the guest.  The file has to
           exists in the guest VM with executable right to the session user in
-          order to be executed.  If empty/null, the first entry in the
-          @a arguments array will be used in stead (i.e. argv[0]).
+          order to succeed.  If empty/null, the first entry in the
+          @a arguments array will be used instead (i.e. argv[0]).
         </desc>
       </param>
@@ -11505,5 +11523,6 @@
             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.
+            version running there.  If you depend on this, check that the
+            <link to="IGuestSession::protocolVersion"/> is 3 or higher.
           </note>
         </desc>
@@ -11511,16 +11530,17 @@
       <param name="environment" type="wstring" dir="in" safearray="yes">
         <desc>
-          Environment variables to set or unset for the guest process,
-          relative to the environment of the guest session.
-
-          The variables are in the traditional "NAME=VALUE" form with one pair
-          per array entry.  To unset a variable just leave out the equal sign
-          and the value ("NAME").
+          Set of environment changes to complement
+          <link to="IGuestSession::environment"/>.  Takes precedence over
+          the session ones.  The changes are in putenv format, i.e.
+          "NAME=VALUE" for setting and "NAME" for unsetting.
+
+          The changes are applied to the standard environment of the
+          impersonated guest user when creating the process.
         </desc>
       </param>
       <param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes">
         <desc>
-          Process creation flags;
-          see <link to="ProcessCreateFlag"/> for more information.
+          Process creation flags, see <link to="ProcessCreateFlag"/> for
+          detailed description of available flags.
         </desc>
       </param>
@@ -11535,11 +11555,18 @@
       <param name="priority" type="ProcessPriority" dir="in">
         <desc>
-          Process priority to use for execution;
-          see see <link to="ProcessPriority"/> for more information.</desc>
+          Process priority to use for execution, see <link to="ProcessPriority"/>
+          for available priority levels.
+          <note>This is silently ignored if not supported by guest additions.</note>
+        </desc>
       </param>
       <param name="affinity" type="long" dir="in" safearray="yes">
         <desc>
-          Process affinity to use for execution. This parameter
-          is not implemented yet.
+          Processor affinity to set for the new process.  This is a list of
+          guest CPU numbers the process is allowed to run on.
+          <note>
+            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.
+          </note>
         </desc>
       </param>
@@ -11563,5 +11590,5 @@
     <method name="symlinkCreate">
       <desc>
-        Creates a symbolic link on the guest.
+        Creates a symbolic link in the guest.
 
         <result name="E_NOTIMPL">
@@ -11585,5 +11612,5 @@
     <method name="symlinkExists">
       <desc>
-        Checks whether a symbolic link exists on the guest or not.
+        Checks whether a symbolic link exists in the guest.
 
         <result name="E_NOTIMPL">
@@ -11601,5 +11628,5 @@
     <method name="symlinkRead">
       <desc>
-        Reads a symbolic link on the guest.
+        Reads a symbolic link in the guest.
 
         <result name="E_NOTIMPL">
@@ -11624,5 +11651,5 @@
     <method name="symlinkRemoveDirectory">
       <desc>
-        Removes a symbolic link on the guest if it's a directory.
+        Removes a symbolic link in the guest if it's a directory.
 
         <result name="E_NOTIMPL">
@@ -11637,5 +11664,5 @@
     <method name="symlinkRemoveFile">
       <desc>
-        Removes a symbolic link on the guest if it's a file.
+        Removes a symbolic link in the guest if it's a file.
 
         <result name="E_NOTIMPL">
@@ -11714,6 +11741,12 @@
     </attribute>
     <attribute name="environment" type="wstring" readonly="yes" safearray="yes">
-      <desc>
-        The environment block this process is using during execution.
+      <!-- r=bird: Would probably be a great idea to rename this attribute as
+                   it is misleading and will cause worse confusion if we ever
+                   expose the initial environment for processes.  -->
+      <desc>
+        The set of environment changes appled to the default environment when
+        starting the process.  The format is putenv style, i.e. "NAME=VALUE"
+        for variables that should be set and "NAME" for values that should be
+        unset (removed).  See also <link to="IGuestSession::environment"/>.
       </desc>
     </attribute>
@@ -11895,5 +11928,5 @@
     <desc>
       Implementation of the <link to="IProcess" /> object
-      for processes on the guest.
+      for processes the host has started in the guest.
     </desc>
   </interface>
@@ -11948,5 +11981,5 @@
     <desc>
       Implementation of the <link to="IDirectory" /> object
-      for directories on the guest.
+      for directories in the guest.
     </desc>
   </interface>
@@ -12163,5 +12196,5 @@
     <desc>
       Implementation of the <link to="IFile" /> object
-      for files on the guest.
+      for files in the guest.
     </desc>
   </interface>
@@ -12494,9 +12527,9 @@
         call.
 
-        A guest session represents one impersonated user account on the guest, so
+        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 <link to="IGuest::createSession"/>. Anonymous
         sessions, that is, sessions without specifying a valid
-        user account on the guest are not allowed due to security reasons.
+        user account in the guest are not allowed due to security reasons.
 
         There can be a maximum of 32 sessions at once per VM. Each session keeps
@@ -12606,5 +12639,5 @@
           Optional command line arguments to use for the Guest Additions
           installer. Useful for retrofitting features which weren't installed
-          before on the guest.
+          before in the guest.
         </desc>
       </param>