/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  

* procexec.h

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

* optionally record all the processes output.

*

*/

#ifndef __CAPROCESS_H__

#define __CAPROCESS_H__

/////////////////////////////////////////////////////////////////////////////////////////////

//

// System Includes

//

/////////////////////////////////////////////////////////////////////////////////////////////

#include <string>

using namespace std;

/////////////////////////////////////////////////////////////////////////////////////////////

//

// Definitions

//

/////////////////////////////////////////////////////////////////////////////////////////////

typedef enum { 

  CAE_NONE,

  CAE_INVALID_STATE,

  CAE_FAILED_TO_CREATE_PIPE,

  CAE_FORK_FAILED,

  CAE_FAILED_TO_SET_NONBLOCKING,

  CAE_SIGNAL_FAILED,

  CAE_TIMEOUT,

  CAE_WAITPID_FAILED,

  CAE_SELECT_FAILED,

  CAE_READ_FAILED,

} TCAProcessError;

/////////////////////////////////////////////////////////////////////////////////////////////

//

// Types

//

/////////////////////////////////////////////////////////////////////////////////////////////

typedef enum {

  PS_INVALID,

  PS_INIT,

  PS_STARTED,

  PS_STOPPED,

  PS_ABANDONNED

} TProcessStatus;

typedef enum {

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

  ER_INVALID,

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

  ER_UNKNOWN,

  ER_EXITED,

  ER_SIGNALLED,

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

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

  ER_SIGNALFAILED,

  ER_STOPFAILED,

  ER_WAITPIDFAILED

} TProcessExitReason;

/////////////////////////////////////////////////////////////////////////////////////////////

//

// CAProcess definition

//

/////////////////////////////////////////////////////////////////////////////////////////////

class CAProcess

{

 public:

  CAProcess();

  ~CAProcess();

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

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

  // Result:

  //          CAE_FORK_FAILED / CAE_FAILED_TO_CREATE_PIPE / CAE_FAILED_TO_SET_NON_BLOCKING - PS_INIT

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

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

  // The basic process control functions

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

				bool aRecordStdErr = true, bool aMakeNewProcessGroup = false );

  TCAProcessError RequestStop( int aSignal );

  TCAProcessError GetProcessStatus( TProcessStatus *aProcessStatus );

  TCAProcessError WaitForProcessToTerminate( int aMaxWait );

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

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

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

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

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

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

  // Accessor methods

  string GetCommandString();

  TCAProcessError GetExitReason( TProcessExitReason *aExitReason );

  TCAProcessError GetExitCode( int *aExitCode );

 private:

  // help methods

  TCAProcessError CreatePipes( int *aErrorCode );  

  void ClosePipes();

  void ClosePipePair( int *aPipes );

  void ClosePipeDesc( int *aPipeDescriptor );

  TProcessExitReason GetExitReasonFromStatus( int aStatus, int *aExitCode );

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

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

  // state variables

  TProcessStatus iProcessStatus;

  // information variables

  string *iCommand;

  int  iPID;

  bool iRecordStdOut;

  bool iRecordStdErr;

  TProcessExitReason iProcessExitReason;

  int iProcessExitCode;

  int iReadStdoutError;

  int iReadStderrError;

  // File descriptors for process output

  int iStdInPipe[2];

  int iStdOutPipe[2];

  int iStdErrPipe[2];

  // Current output of the process.

  string iRecordedStdOut;

  string iRecordedStdErr;

};

#endif