Index: trunk/src/VBox/Additions/common/VBoxService/VBoxServiceControlExec.cpp
===================================================================
--- trunk/src/VBox/Additions/common/VBoxService/VBoxServiceControlExec.cpp	(revision 35673)
+++ trunk/src/VBox/Additions/common/VBoxService/VBoxServiceControlExec.cpp	(revision 35674)
@@ -5,5 +5,5 @@
 
 /*
- * Copyright (C) 2010 Oracle Corporation
+ * Copyright (C) 2011 Oracle Corporation
  *
  * This file is part of VirtualBox Open Source Edition (OSE), as
@@ -319,14 +319,15 @@
 
 /**
- * TODO
+ * Execution loop which (usually) runs in a dedicated per-started-process thread and
+ * handles all pipe input/output and signalling stuff.
  *
  * @return  IPRT status code.
- * @param   pThread
- * @param   hProcess
- * @param   cMillies
- * @param   hPollSet
- * @param   hStdInW
- * @param   hStdOutR
- * @param   hStdErrR
+ * @param   pThread                     The process' thread handle.
+ * @param   hProcess                    The actual process handle.
+ * @param   cMsTimeout                  Time limit (in ms) of the process' life time.
+ * @param   hPollSet                    The poll set to use.
+ * @param   hStdInW                     Handle to the process' stdin write end.
+ * @param   hStdOutR                    Handle to the process' stdout read end.
+ * @param   hStdErrR                    Handle to the process' stderr read end.
  */
 static int VBoxServiceControlExecProcLoop(PVBOXSERVICECTRLTHREAD pThread,
@@ -728,17 +729,20 @@
 
 /**
- * TODO
+ * Reads out data from a specififed pipe buffer.
  *
  * @return  IPRT status code.
- * @param   pBuf
- * @param   pbBuffer
- * @param   cbBuffer
- * @param   pcbToRead
+ * @param   pBuf                        Pointer to pipe buffer to read the data from.
+ * @param   pbBuffer                    Pointer to buffer to store the read out data.
+ * @param   cbBuffer                    Size (in bytes) of the buffer where to store the data.
+ * @param   pcbToRead                   Pointer to desired amount (in bytes) of data to read,
+ *                                      will reflect the actual amount read on return.
  */
 int VBoxServiceControlExecReadPipeBufferContent(PVBOXSERVICECTRLEXECPIPEBUF pBuf,
                                                 uint8_t *pbBuffer, uint32_t cbBuffer, uint32_t *pcbToRead)
 {
-    AssertPtr(pBuf);
-    AssertPtr(pcbToRead);
+    AssertPtrReturn(pBuf, VERR_INVALID_PARAMETER);
+    AssertPtrReturn(pbBuffer, VERR_INVALID_PARAMETER);
+    AssertReturn(cbBuffer, VERR_INVALID_PARAMETER);
+    AssertPtrReturn(pcbToRead, VERR_INVALID_PARAMETER);
 
     int rc = RTCritSectEnter(&pBuf->CritSect);
@@ -769,12 +773,12 @@
 
 /**
- * TODO
+ * Writes data into a specififed pipe buffer.
  *
  * @return  IPRT status code.
- * @param   pBuf
- * @param   pbData
- * @param   cbData
- * @param   fPendingClose
- * @param   pcbWritten
+ * @param   pBuf                        Pointer to pipe buffer to write data into.
+ * @param   pbData                      Pointer to byte data to write.
+ * @param   cbData                      Data size (in bytes) to write.
+ * @param   fPendingClose               Needs the pipe (buffer) to be closed next time we have the chance to?
+ * @param   pcbWritten                  Pointer to where the amount of written bytes get stored. Optional.
  */
 int VBoxServiceControlExecWritePipeBuffer(PVBOXSERVICECTRLEXECPIPEBUF pBuf,
@@ -783,5 +787,5 @@
 {
     AssertPtrReturn(pBuf, VERR_INVALID_PARAMETER);
-    AssertPtrReturn(pcbWritten, VERR_INVALID_PARAMETER);
+    AssertPtrReturn(pbData, VERR_INVALID_PARAMETER);
 
     int rc;
@@ -846,9 +850,10 @@
             if (RT_SUCCESS(rc))
             {
-                /* Report back written bytes. */
-                *pcbWritten = cbData;
+                /* Report back written bytes (if wanted). */
+                if (pcbWritten)
+                    *pcbWritten = cbData;
 
                 /*
-                 * Was this the final read/write to do on this buffer? The close it
+                 * Was this the final read/write to do on this buffer? Then close it
                  * next time we have the chance to.
                  */
@@ -885,16 +890,17 @@
  *
  * @return  IPRT status code.
- * @param   pThread
- * @param   u32ContextID
- * @param   pszCmd
- * @param   uFlags
- * @param   pszArgs
- * @param   uNumArgs
- * @param   pszEnv
- * @param   cbEnv
- * @param   uNumEnvVars
- * @param   pszUser
- * @param   pszPassword
- * @param   uTimeLimitMS
+ * @param   pThread                     The thread's handle to allocate the data for.
+ * @param   u32ContextID                The context ID bound to this request / command.
+ * @param   pszCmd                      Full qualified path of process to start (without arguments).
+ * @param   uFlags                      Process execution flags.
+ * @param   pszArgs                     String of arguments to pass to the process to start.
+ * @param   uNumArgs                    Number of arguments specified in pszArgs.
+ * @param   pszEnv                      String of environment variables ("FOO=BAR") to pass to the process
+ *                                      to start.
+ * @param   cbEnv                       Size (in bytes) of environment variables.
+ * @param   uNumEnvVars                 Number of environment variables specified in pszEnv.
+ * @param   pszUser                     User name (account) to start the process under.
+ * @param   pszPassword                 Password of specified user name (account).
+ * @param   uTimeLimitMS                Time limit (in ms) of the process' life time.
  */
 static int VBoxServiceControlExecAllocateThreadData(PVBOXSERVICECTRLTHREAD pThread,
@@ -1028,5 +1034,14 @@
 
 
-/** @todo Maybe we want to have an own IPRT function for that! */
+/**
+ * Expands a file name / path to its real content. This only works on Windows
+ * for now (e.g. translating "%TEMP%\foo.exe" to "C:\Windows\Temp" when starting
+ * with system / administrative rights).
+ *
+ * @return  IPRT status code.
+ * @param   pszPath                     Path to resolve.
+ * @param   pszExpanded                 Pointer to string to store the resolved path in.
+ * @param   cbExpanded                  Size (in bytes) of string to store the resolved path.
+ */
 static int VBoxServiceControlExecMakeFullPath(const char *pszPath, char *pszExpanded, size_t cbExpanded)
 {
@@ -1040,6 +1055,6 @@
 #endif
 #ifdef DEBUG
-        VBoxServiceVerbose(3, "ControlExec: VBoxServiceControlExecMakeFullPath: %s -> %s\n",
-                           pszPath, pszExpanded);
+    VBoxServiceVerbose(3, "ControlExec: VBoxServiceControlExecMakeFullPath: %s -> %s\n",
+                       pszPath, pszExpanded);
 #endif
     return rc;
@@ -1047,4 +1062,13 @@
 
 
+/**
+ * Resolves the full path of a specified executable name. This function also
+ * resolves internal VBoxService tools to its appropriate executable path + name.
+ *
+ * @return  IPRT status code.
+ * @param   pszFileName                 File name to resovle.
+ * @param   pszResolved                 Pointer to a string where the resolved file name will be stored.
+ * @param   cbResolved                  Size (in bytes) of resolved file name string.
+ */
 static int VBoxServiceControlExecResolveExecutable(const char *pszFileName, char *pszResolved, size_t cbResolved)
 {
@@ -1145,17 +1169,18 @@
 
 /**
- * TODO
+ * Helper function to create/start a process on the guest.
  *
  * @return  IPRT status code.
- * @param   pszExec
- * @param   papszArgs
- * @param   hEnv
- * @param   fFlags
- * @param   phStdIn
- * @param   phStdOut
- * @param   phStdErr
- * @param   pszAsUser
- * @param   pszPassword
- * @param   phProcess
+ * @param   pszExec                     Full qualified path of process to start (without arguments).
+ * @param   papszArgs                   Pointer to array of command line arguments.
+ * @param   hEnv                        Handle to environment block to use.
+ * @param   fFlags                      Process execution flags.
+ * @param   phStdIn                     Handle for the process' stdin pipe.
+ * @param   phStdOut                    Handle for the process' stdout pipe.
+ * @param   phStdErr                    Handle for the process' stderr pipe.
+ * @param   pszAsUser                   User name (account) to start the process under.
+ * @param   pszPassword                 Password of the specified user.
+ * @param   phProcess                   Pointer which will receive the process handle after
+ *                                      successful process start.
  */
 static int VBoxServiceControlExecCreateProcess(const char *pszExec, const char * const *papszArgs, RTENV hEnv, uint32_t fFlags,
@@ -1163,4 +1188,8 @@
                                                const char *pszPassword, PRTPROCESS phProcess)
 {
+    AssertPtrReturn(pszExec, VERR_INVALID_PARAMETER);
+    AssertPtrReturn(papszArgs, VERR_INVALID_PARAMETER);
+    AssertPtrReturn(phProcess, VERR_INVALID_PARAMETER);
+
     int  rc = VINF_SUCCESS;
 #ifdef RT_OS_WINDOWS
@@ -1444,18 +1473,20 @@
 
 /**
- * TODO
- *
- * @return  int
- * @param   uContextID
- * @param   pszCmd
- * @param   uFlags
- * @param   pszArgs
- * @param   uNumArgs
- * @param   pszEnv
- * @param   cbEnv
- * @param   uNumEnvVars
- * @param   pszUser
- * @param   pszPassword
- * @param   uTimeLimitMS
+ * Executes (starts) a process on the guest. This causes a new thread to be created
+ * so that this function will not block the overall program execution.
+ *
+ * @return  IPRT status code.
+ * @param   uContextID                  Context ID to associate the process to start with.
+ * @param   pszCmd                      Full qualified path of process to start (without arguments).
+ * @param   uFlags                      Process execution flags.
+ * @param   pszArgs                     String of arguments to pass to the process to start.
+ * @param   uNumArgs                    Number of arguments specified in pszArgs.
+ * @param   pszEnv                      String of environment variables ("FOO=BAR") to pass to the process
+ *                                      to start.
+ * @param   cbEnv                       Size (in bytes) of environment variables.
+ * @param   uNumEnvVars                 Number of environment variables specified in pszEnv.
+ * @param   pszUser                     User name (account) to start the process under.
+ * @param   pszPassword                 Password of specified user name (account).
+ * @param   uTimeLimitMS                Time limit (in ms) of the process' life time.
  */
 int VBoxServiceControlExecProcess(uint32_t uContextID, const char *pszCmd, uint32_t uFlags,
@@ -1517,9 +1548,9 @@
 
 /**
- * TODO
- *
- * @return  IPRT status code.
- * @param   u32ClientId
- * @param   uNumParms
+ * Handles starting processes on the guest.
+ *
+ * @returns IPRT status code.
+ * @param   u32ClientId                 The HGCM client session ID.
+ * @param   uNumParms                   The number of parameters the host is offering.
  */
 int VBoxServiceControlExecHandleCmdStartProcess(uint32_t u32ClientId, uint32_t uNumParms)
@@ -1582,11 +1613,11 @@
 
 /**
- * Handles input for the started process by copying the received data into its
+ * Handles input for a started process by copying the received data into its
  * stdin pipe.
  *
  * @returns IPRT status code.
- * @param   u32ClientId     idClient    The HGCM client session ID.
- * @param   uNumParms       cParms      The number of parameters the host is
- *                                      offering.
+ * @param   u32ClientId                 The HGCM client session ID.
+ * @param   uNumParms                   The number of parameters the host is offering.
+ * @param   cMaxBufSize                 The maximum buffer size for retrieving the input data.
  */
 int VBoxServiceControlExecHandleCmdSetInput(uint32_t u32ClientId, uint32_t uNumParms, size_t cbMaxBufSize)
@@ -1613,5 +1644,6 @@
     else if (cbSize >  cbMaxBufSize)
     {
-        VBoxServiceError("ControlExec: Input size is invalid! cbSize=%u\n", cbSize);
+        VBoxServiceError("ControlExec: Maximum input buffer size is too small! cbSize=%u, cbMaxBufSize=%u\n",
+                         cbSize, cbMaxBufSize);
         rc = VERR_INVALID_PARAMETER;
     }
@@ -1691,9 +1723,10 @@
 
 /**
- *
+ * Handles the guest control output command.
  *
  * @return  IPRT status code.
- * @param   u32ClientId
- * @param   uNumParms
+ * @param   u32ClientId     idClient    The HGCM client session ID.
+ * @param   uNumParms       cParms      The number of parameters the host is
+ *                                      offering.
  */
 int VBoxServiceControlExecHandleCmdGetOutput(uint32_t u32ClientId, uint32_t uNumParms)
