VirtualBox

Changeset 35674 in vbox for trunk


Ignore:
Timestamp:
Jan 24, 2011 1:23:38 PM (14 years ago)
Author:
vboxsync
Message:

Comments, added misc. assertions.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Additions/common/VBoxService/VBoxServiceControlExec.cpp

    r35526 r35674  
    55
    66/*
    7  * Copyright (C) 2010 Oracle Corporation
     7 * Copyright (C) 2011 Oracle Corporation
    88 *
    99 * This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    319319
    320320/**
    321  * TODO
     321 * Execution loop which (usually) runs in a dedicated per-started-process thread and
     322 * handles all pipe input/output and signalling stuff.
    322323 *
    323324 * @return  IPRT status code.
    324  * @param   pThread
    325  * @param   hProcess
    326  * @param   cMillies
    327  * @param   hPollSet
    328  * @param   hStdInW
    329  * @param   hStdOutR
    330  * @param   hStdErrR
     325 * @param   pThread                     The process' thread handle.
     326 * @param   hProcess                    The actual process handle.
     327 * @param   cMsTimeout                  Time limit (in ms) of the process' life time.
     328 * @param   hPollSet                    The poll set to use.
     329 * @param   hStdInW                     Handle to the process' stdin write end.
     330 * @param   hStdOutR                    Handle to the process' stdout read end.
     331 * @param   hStdErrR                    Handle to the process' stderr read end.
    331332 */
    332333static int VBoxServiceControlExecProcLoop(PVBOXSERVICECTRLTHREAD pThread,
    … …  
    728729
    729730/**
    730  * TODO
     731 * Reads out data from a specififed pipe buffer.
    731732 *
    732733 * @return  IPRT status code.
    733  * @param   pBuf
    734  * @param   pbBuffer
    735  * @param   cbBuffer
    736  * @param   pcbToRead
     734 * @param   pBuf                        Pointer to pipe buffer to read the data from.
     735 * @param   pbBuffer                    Pointer to buffer to store the read out data.
     736 * @param   cbBuffer                    Size (in bytes) of the buffer where to store the data.
     737 * @param   pcbToRead                   Pointer to desired amount (in bytes) of data to read,
     738 *                                      will reflect the actual amount read on return.
    737739 */
    738740int VBoxServiceControlExecReadPipeBufferContent(PVBOXSERVICECTRLEXECPIPEBUF pBuf,
    739741                                                uint8_t *pbBuffer, uint32_t cbBuffer, uint32_t *pcbToRead)
    740742{
    741     AssertPtr(pBuf);
    742     AssertPtr(pcbToRead);
     743    AssertPtrReturn(pBuf, VERR_INVALID_PARAMETER);
     744    AssertPtrReturn(pbBuffer, VERR_INVALID_PARAMETER);
     745    AssertReturn(cbBuffer, VERR_INVALID_PARAMETER);
     746    AssertPtrReturn(pcbToRead, VERR_INVALID_PARAMETER);
    743747
    744748    int rc = RTCritSectEnter(&pBuf->CritSect);
    … …  
    769773
    770774/**
    771  * TODO
     775 * Writes data into a specififed pipe buffer.
    772776 *
    773777 * @return  IPRT status code.
    774  * @param   pBuf
    775  * @param   pbData
    776  * @param   cbData
    777  * @param   fPendingClose
    778  * @param   pcbWritten
     778 * @param   pBuf                        Pointer to pipe buffer to write data into.
     779 * @param   pbData                      Pointer to byte data to write.
     780 * @param   cbData                      Data size (in bytes) to write.
     781 * @param   fPendingClose               Needs the pipe (buffer) to be closed next time we have the chance to?
     782 * @param   pcbWritten                  Pointer to where the amount of written bytes get stored. Optional.
    779783 */
    780784int VBoxServiceControlExecWritePipeBuffer(PVBOXSERVICECTRLEXECPIPEBUF pBuf,
    … …  
    783787{
    784788    AssertPtrReturn(pBuf, VERR_INVALID_PARAMETER);
    785     AssertPtrReturn(pcbWritten, VERR_INVALID_PARAMETER);
     789    AssertPtrReturn(pbData, VERR_INVALID_PARAMETER);
    786790
    787791    int rc;
    … …  
    846850            if (RT_SUCCESS(rc))
    847851            {
    848                 /* Report back written bytes. */
    849                 *pcbWritten = cbData;
     852                /* Report back written bytes (if wanted). */
     853                if (pcbWritten)
     854                    *pcbWritten = cbData;
    850855
    851856                /*
    852                  * Was this the final read/write to do on this buffer? The close it
     857                 * Was this the final read/write to do on this buffer? Then close it
    853858                 * next time we have the chance to.
    854859                 */
    … …  
    885890 *
    886891 * @return  IPRT status code.
    887  * @param   pThread
    888  * @param   u32ContextID
    889  * @param   pszCmd
    890  * @param   uFlags
    891  * @param   pszArgs
    892  * @param   uNumArgs
    893  * @param   pszEnv
    894  * @param   cbEnv
    895  * @param   uNumEnvVars
    896  * @param   pszUser
    897  * @param   pszPassword
    898  * @param   uTimeLimitMS
     892 * @param   pThread                     The thread's handle to allocate the data for.
     893 * @param   u32ContextID                The context ID bound to this request / command.
     894 * @param   pszCmd                      Full qualified path of process to start (without arguments).
     895 * @param   uFlags                      Process execution flags.
     896 * @param   pszArgs                     String of arguments to pass to the process to start.
     897 * @param   uNumArgs                    Number of arguments specified in pszArgs.
     898 * @param   pszEnv                      String of environment variables ("FOO=BAR") to pass to the process
     899 *                                      to start.
     900 * @param   cbEnv                       Size (in bytes) of environment variables.
     901 * @param   uNumEnvVars                 Number of environment variables specified in pszEnv.
     902 * @param   pszUser                     User name (account) to start the process under.
     903 * @param   pszPassword                 Password of specified user name (account).
     904 * @param   uTimeLimitMS                Time limit (in ms) of the process' life time.
    899905 */
    900906static int VBoxServiceControlExecAllocateThreadData(PVBOXSERVICECTRLTHREAD pThread,
    … …  
    10281034
    10291035
    1030 /** @todo Maybe we want to have an own IPRT function for that! */
     1036/**
     1037 * Expands a file name / path to its real content. This only works on Windows
     1038 * for now (e.g. translating "%TEMP%\foo.exe" to "C:\Windows\Temp" when starting
     1039 * with system / administrative rights).
     1040 *
     1041 * @return  IPRT status code.
     1042 * @param   pszPath                     Path to resolve.
     1043 * @param   pszExpanded                 Pointer to string to store the resolved path in.
     1044 * @param   cbExpanded                  Size (in bytes) of string to store the resolved path.
     1045 */
    10311046static int VBoxServiceControlExecMakeFullPath(const char *pszPath, char *pszExpanded, size_t cbExpanded)
    10321047{
    … …  
    10401055#endif
    10411056#ifdef DEBUG
    1042         VBoxServiceVerbose(3, "ControlExec: VBoxServiceControlExecMakeFullPath: %s -> %s\n",
    1043                            pszPath, pszExpanded);
     1057    VBoxServiceVerbose(3, "ControlExec: VBoxServiceControlExecMakeFullPath: %s -> %s\n",
     1058                       pszPath, pszExpanded);
    10441059#endif
    10451060    return rc;
    … …  
    10471062
    10481063
     1064/**
     1065 * Resolves the full path of a specified executable name. This function also
     1066 * resolves internal VBoxService tools to its appropriate executable path + name.
     1067 *
     1068 * @return  IPRT status code.
     1069 * @param   pszFileName                 File name to resovle.
     1070 * @param   pszResolved                 Pointer to a string where the resolved file name will be stored.
     1071 * @param   cbResolved                  Size (in bytes) of resolved file name string.
     1072 */
    10491073static int VBoxServiceControlExecResolveExecutable(const char *pszFileName, char *pszResolved, size_t cbResolved)
    10501074{
    … …  
    11451169
    11461170/**
    1147  * TODO
     1171 * Helper function to create/start a process on the guest.
    11481172 *
    11491173 * @return  IPRT status code.
    1150  * @param   pszExec
    1151  * @param   papszArgs
    1152  * @param   hEnv
    1153  * @param   fFlags
    1154  * @param   phStdIn
    1155  * @param   phStdOut
    1156  * @param   phStdErr
    1157  * @param   pszAsUser
    1158  * @param   pszPassword
    1159  * @param   phProcess
     1174 * @param   pszExec                     Full qualified path of process to start (without arguments).
     1175 * @param   papszArgs                   Pointer to array of command line arguments.
     1176 * @param   hEnv                        Handle to environment block to use.
     1177 * @param   fFlags                      Process execution flags.
     1178 * @param   phStdIn                     Handle for the process' stdin pipe.
     1179 * @param   phStdOut                    Handle for the process' stdout pipe.
     1180 * @param   phStdErr                    Handle for the process' stderr pipe.
     1181 * @param   pszAsUser                   User name (account) to start the process under.
     1182 * @param   pszPassword                 Password of the specified user.
     1183 * @param   phProcess                   Pointer which will receive the process handle after
     1184 *                                      successful process start.
    11601185 */
    11611186static int VBoxServiceControlExecCreateProcess(const char *pszExec, const char * const *papszArgs, RTENV hEnv, uint32_t fFlags,
    … …  
    11631188                                               const char *pszPassword, PRTPROCESS phProcess)
    11641189{
     1190    AssertPtrReturn(pszExec, VERR_INVALID_PARAMETER);
     1191    AssertPtrReturn(papszArgs, VERR_INVALID_PARAMETER);
     1192    AssertPtrReturn(phProcess, VERR_INVALID_PARAMETER);
     1193
    11651194    int  rc = VINF_SUCCESS;
    11661195#ifdef RT_OS_WINDOWS
    … …  
    14441473
    14451474/**
    1446  * TODO
    1447  *
    1448  * @return  int
    1449  * @param   uContextID
    1450  * @param   pszCmd
    1451  * @param   uFlags
    1452  * @param   pszArgs
    1453  * @param   uNumArgs
    1454  * @param   pszEnv
    1455  * @param   cbEnv
    1456  * @param   uNumEnvVars
    1457  * @param   pszUser
    1458  * @param   pszPassword
    1459  * @param   uTimeLimitMS
     1475 * Executes (starts) a process on the guest. This causes a new thread to be created
     1476 * so that this function will not block the overall program execution.
     1477 *
     1478 * @return  IPRT status code.
     1479 * @param   uContextID                  Context ID to associate the process to start with.
     1480 * @param   pszCmd                      Full qualified path of process to start (without arguments).
     1481 * @param   uFlags                      Process execution flags.
     1482 * @param   pszArgs                     String of arguments to pass to the process to start.
     1483 * @param   uNumArgs                    Number of arguments specified in pszArgs.
     1484 * @param   pszEnv                      String of environment variables ("FOO=BAR") to pass to the process
     1485 *                                      to start.
     1486 * @param   cbEnv                       Size (in bytes) of environment variables.
     1487 * @param   uNumEnvVars                 Number of environment variables specified in pszEnv.
     1488 * @param   pszUser                     User name (account) to start the process under.
     1489 * @param   pszPassword                 Password of specified user name (account).
     1490 * @param   uTimeLimitMS                Time limit (in ms) of the process' life time.
    14601491 */
    14611492int VBoxServiceControlExecProcess(uint32_t uContextID, const char *pszCmd, uint32_t uFlags,
    … …  
    15171548
    15181549/**
    1519  * TODO
    1520  *
    1521  * @return  IPRT status code.
    1522  * @param   u32ClientId
    1523  * @param   uNumParms
     1550 * Handles starting processes on the guest.
     1551 *
     1552 * @returns IPRT status code.
     1553 * @param   u32ClientId                 The HGCM client session ID.
     1554 * @param   uNumParms                   The number of parameters the host is offering.
    15241555 */
    15251556int VBoxServiceControlExecHandleCmdStartProcess(uint32_t u32ClientId, uint32_t uNumParms)
    … …  
    15821613
    15831614/**
    1584  * Handles input for the started process by copying the received data into its
     1615 * Handles input for a started process by copying the received data into its
    15851616 * stdin pipe.
    15861617 *
    15871618 * @returns IPRT status code.
    1588  * @param   u32ClientId     idClient    The HGCM client session ID.
    1589  * @param   uNumParms       cParms      The number of parameters the host is
    1590  *                                      offering.
     1619 * @param   u32ClientId                 The HGCM client session ID.
     1620 * @param   uNumParms                   The number of parameters the host is offering.
     1621 * @param   cMaxBufSize                 The maximum buffer size for retrieving the input data.
    15911622 */
    15921623int VBoxServiceControlExecHandleCmdSetInput(uint32_t u32ClientId, uint32_t uNumParms, size_t cbMaxBufSize)
    … …  
    16131644    else if (cbSize >  cbMaxBufSize)
    16141645    {
    1615         VBoxServiceError("ControlExec: Input size is invalid! cbSize=%u\n", cbSize);
     1646        VBoxServiceError("ControlExec: Maximum input buffer size is too small! cbSize=%u, cbMaxBufSize=%u\n",
     1647                         cbSize, cbMaxBufSize);
    16161648        rc = VERR_INVALID_PARAMETER;
    16171649    }
    … …  
    16911723
    16921724/**
    1693  *
     1725 * Handles the guest control output command.
    16941726 *
    16951727 * @return  IPRT status code.
    1696  * @param   u32ClientId
    1697  * @param   uNumParms
     1728 * @param   u32ClientId     idClient    The HGCM client session ID.
     1729 * @param   uNumParms       cParms      The number of parameters the host is
     1730 *                                      offering.
    16981731 */
    16991732int VBoxServiceControlExecHandleCmdGetOutput(uint32_t u32ClientId, uint32_t uNumParms)
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette