1 /*

     2 * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  

    15 * procexec.h

    16 * Process execution class which can be used to execute a process and

    17 * optionally record all the processes output.

    18 *

    19 */

    20 

    21 

    22 #ifndef __CAPROCESS_H__

    23 #define __CAPROCESS_H__

    24 

    25 /////////////////////////////////////////////////////////////////////////////////////////////

    26 //

    27 // System Includes

    28 //

    29 /////////////////////////////////////////////////////////////////////////////////////////////

    30 #include <string>

    31 using namespace std;

    32 

    33 /////////////////////////////////////////////////////////////////////////////////////////////

    34 //

    35 // Definitions

    36 //

    37 /////////////////////////////////////////////////////////////////////////////////////////////

    38 typedef enum { 

    39   CAE_NONE,

    40   CAE_INVALID_STATE,

    41   CAE_FAILED_TO_CREATE_PIPE,

    42   CAE_FORK_FAILED,

    43   CAE_FAILED_TO_SET_NONBLOCKING,

    44   CAE_SIGNAL_FAILED,

    45   CAE_TIMEOUT,

    46   CAE_WAITPID_FAILED,

    47   CAE_SELECT_FAILED,

    48   CAE_READ_FAILED,

    49 } TCAProcessError;

    50 

    51 /////////////////////////////////////////////////////////////////////////////////////////////

    52 //

    53 // Types

    54 //

    55 /////////////////////////////////////////////////////////////////////////////////////////////

    56 typedef enum {

    57   PS_INVALID,

    58   PS_INIT,

    59   PS_STARTED,

    60   PS_STOPPED,

    61   PS_ABANDONNED

    62 } TProcessStatus;

    63 

    64 typedef enum {

    65   // If process is in PS_INIT or PS_STARTED state then the value is invalid

    66   ER_INVALID,

    67 

    68   // If process is in PS_STOPPED state then it must be one of the 

    69   ER_UNKNOWN,

    70   ER_EXITED,

    71   ER_SIGNALLED,

    72 

    73   // If process is PS_ABANDONED state then it must be one of the following. Processes 

    74   // are abandonned if something goes wrong that we can't recover from.

    75   ER_SIGNALFAILED,

    76   ER_STOPFAILED,

    77   ER_WAITPIDFAILED

    78 } TProcessExitReason;

    79 

    80 

    81 /////////////////////////////////////////////////////////////////////////////////////////////

    82 //

    83 // CAProcess definition

    84 //

    85 /////////////////////////////////////////////////////////////////////////////////////////////

    86 class CAProcess

    87 {

    88  public:

    89 

    90   CAProcess();

    91   ~CAProcess();

    92   

    93   // This function will run the process and wait for it to finish. It is intended as a single call 

    94   // function.  Use the other functions for more control of the process. Do not mix the two.

    95   // Result:

    96   //          CAE_FORK_FAILED / CAE_FAILED_TO_CREATE_PIPE / CAE_FAILED_TO_SET_NON_BLOCKING - PS_INIT

    97   TCAProcessError Execute( const char *aCommand, int *aErrorCode, int aTimeoutInMilliseconds = -1, 

    98 			   string *aStandardOutput = NULL, string *aStandardError = NULL );

    99 

   100   // The basic process control functions

   101   TCAProcessError StartProcess( const char *aCommand, int *aErrorCode, bool aRecordStdOut = true, 

   102 				bool aRecordStdErr = true, bool aMakeNewProcessGroup = false );

   103   TCAProcessError RequestStop( int aSignal );

   104   TCAProcessError GetProcessStatus( TProcessStatus *aProcessStatus );

   105   TCAProcessError WaitForProcessToTerminate( int aMaxWait );

   106 

   107   // Poll for new output on either stdout or stdin. If there is no new data then the method will

   108   // wait up to aMaxWait seconds for new data to show up. The Get- methods will return all data

   109   // received since the last call. This data will then be removed from the object's buffers.

   110   TCAProcessError PollProcessForNewOutput( int aMaxWait, int *aStandardOutputRead, int *aStandardErrorRead );

   111   int GetRecordedStandardOutput( string *aStdout, int *aReadError );

   112   int GetRecordedStandardError( string *aStdout, int *aReadError );

   113 

   114   // Accessor methods

   115   string GetCommandString();

   116   TCAProcessError GetExitReason( TProcessExitReason *aExitReason );

   117   TCAProcessError GetExitCode( int *aExitCode );

   118   

   119  private:

   120   // help methods

   121   TCAProcessError CreatePipes( int *aErrorCode );  

   122   void ClosePipes();

   123   void ClosePipePair( int *aPipes );

   124   void ClosePipeDesc( int *aPipeDescriptor );

   125   TProcessExitReason GetExitReasonFromStatus( int aStatus, int *aExitCode );

   126   TCAProcessError ReadOutput( int *aFileDes, string *aBuffer, bool aStoreFlag, int *aReadError );

   127   TCAProcessError InternalPollProcessForNewOutput( int aMaxWait, int *aStandardOutputRead, int *aStandardErrorRead );

   128 

   129   // state variables

   130   TProcessStatus iProcessStatus;

   131 

   132   // information variables

   133   string *iCommand;

   134   int  iPID;

   135   bool iRecordStdOut;

   136   bool iRecordStdErr;

   137   TProcessExitReason iProcessExitReason;

   138   int iProcessExitCode;

   139   int iReadStdoutError;

   140   int iReadStderrError;

   141 

   142   // File descriptors for process output

   143   int iStdInPipe[2];

   144   int iStdOutPipe[2];

   145   int iStdErrPipe[2];

   146 

   147   // Current output of the process.

   148   string iRecordedStdOut;

   149   string iRecordedStdErr;

   150 };

   151 

   152 #endif