// Copyright (c) 1997-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:

// This file contains the definition of the class CTransition

// This file comment is for DOxygen only and is ignored by EDoc.

// 

//

/**

 @test

*/

#if defined (_MSC_VER) && (_MSC_VER >= 1000)

#pragma once

#endif

#ifndef _INC_TRANSITION_3A23BFC30021_INCLUDED

#define _INC_TRANSITION_3A23BFC30021_INCLUDED

#include <e32base.h>

#include <ecom/test_bed/testutilities.h>

#include <ecom/test_bed/stateaccessor.h>

#include <ecom/test_bed/transitionobserver.h>

class CDataLogger;

/**

	@internalAll

	Comments : Provide the base class definition for a Unit Test's specific data.  This class

	is CBase derived so that test developers can derive from this class and add owned member 

	data if they wish.

 */

class CUnitTestContext : public CBase

	{

public:

/**

	@fn				CUnitTestContext(CDataLogger& aDataLogger, 

										MStateAccessor& aAccessor,

										MTransitionObserver& aObserver)

	Intended Usage	: Default constructor.

	@since			7.0

	@param			aDataLogger The output logging object.

	@param			aObserver The observer of this UnitTest's Transitions.

	@param			aAccessor WhiteBox state access to the class under test.

	@pre 			None.

	@post			CUnitTestContext is fully constructed, and initialized.

*/

	CUnitTestContext(CDataLogger&			aDataLogger, 

					MStateAccessor&			aAccessor,

					MTransitionObserver&	aObserver);

/**

	@fn				CDataLogger& DataLogger() const

	Intended Usage	:	Provides access to the CDataLogger

	@since			7.0

	@return			A reference to a CDataLogger

	@pre 			Object is fully constructed

 */

	CDataLogger& DataLogger() const;

/**

	@fn				MTransitionObserver& TransitionObserver() const

	Intended Usage	:	Provides access to the MTransitionObserver

	@since			7.0

	@return			A reference to an MTransitionObserver

	@pre 			Object is fully constructed

 */

	MTransitionObserver& TransitionObserver() const;

/**

	@fn				MStateAccessor& StateAccessor() const

	Intended Usage	:	Provides access to the MStateAccessor

	@since			7.0

	@return			A reference to an MStateAccessor

	@pre 			Object is fully constructed

 */

	MStateAccessor& StateAccessor() const;

protected:

	/** The output logging object. */

	CDataLogger&			iDataLogger;

	/** The observer of this UnitTest's Transitions. */

	MTransitionObserver&	iObserver;

	/** WhiteBox state access to the class under test. */

	MStateAccessor&			iStateAccessor;

	};

/**

	@internalAll

	@enum TTestBedAsyncState

	Dependencies : None

	Comments : Represents the possible states of an asynchronous transition when 

	ValidatePostConditions is called. EAsyncCalled means the async request has been made but

	not satisfied, EAsyncCompleted is when the request has been satisfied.

 */

enum TTestBedAsyncState {EAsyncCalled, EAsyncCompleted};

/**

	@internalAll

	Comments : Placeholder for the functions which validate the state of a transition

	before and after its execution.

 */

class TTransitionValidator

	{

public:

/**

	@fn				TTransitionValidator(CUnitTestContext& aUTContext)

	Intended Usage	:	Standard constructor

	@since			7.0

	@param			aUTContext The context within which this transition is executing

 */

	TTransitionValidator(CUnitTestContext& aUTContext);

/**

	@fn				~TTransitionValidator()

	Intended Usage	: Standard Destructor.

	Error Condition	: None.	

	@since			7.0

*/

	virtual ~TTransitionValidator();

/**

	@fn				virtual TBool ValidatePreConditions()

	Intended Usage	:	Overridden in the derived transition to check the transition pre

	conditions.

	@since			7.0

	@return			TBool ETrue if the Preconditions were valid, EFalse if not.

	@pre 			This CTransition is fully constructed

	@post			Returns the validity of the preconditions

 */

	virtual TBool ValidatePreConditions();

/**

	@fn				virtual TBool ValidatePostConditions(TTestBedAsyncState aAsyncState)

	Intended Usage	:	Overridden in the derived transition to check the transition post

	conditions.

	When overriding, if the transition calls an asynchronous function ValidatePostConditions

	will be called twice. Firstly, after the asynchronous function has been called and, 

	secondly, after the asynchronous request has completed.  The parameter aAsyncState can

	be used to distinguish between these two cases.

	@since			7.0

	@param			aAsyncState EAsyncCalled if the async function has been just been called,

	EAsyncCompleted if the function has completed.

	@return			TBool ETrue if the Postconditions were valid, EFalse if not.

	@pre 			This CTransition is fully constructed

	@post			Unspecified

 */

	virtual TBool ValidatePostConditions(TTestBedAsyncState aAsyncState);

protected:

/** The context that this transition will be executing in */

	CUnitTestContext& iUTContext;

	};

/**

	@internalAll

	@struct TTransitionInfo

	Dependencies : None

	Comments : Structure for storing the current transition id and iteration number

 */

struct TTransitionInfo

	{

	TTransitionInfo(const TDesC& aTransitionId, 

					CDataLogger& aDataLogger);

/** Descriptor containing the transition identifier */

	const TDesC&		iTransitionId;

/** The iteration that this transition is currently on */

	TInt				iIteration;

/** The Data Logger that this transition is currently using */

	const CDataLogger&	iDataLogger;

	};

const TInt KFirstTransitionIteration = 1;

/**

	@internalAll

	Comments : Base class from which test developers 

				can derive their own transitions for both

				synchronous and asynchronous methods on

				the test class.

				The default behaviour is to log its activity,

				and claim that the pre and post conditions are true.

				The TransitMethodL implementation does nothing.

				To	write a complete test class method transition

				override:

				1. The c'tor, (To obtain the test class reference, 

				(or pointer reference for a NewL transit), 

				and any parameters for the TransitMethodL).

				2. SetStartStateL() to set the test class state,

				Using the TStateAccessor provided in the c'tor.

				3. ValidatePreConditions() to test the test class state 

				is valid.

				4. TransitMethodL() to define the transition behaviour,

				calling the method to test with the appropriate parameters.

				5. ValidatePostConditions(), to check the end state is valid.

				The simplest case of implementation is to derive an empty 

				class, that relies entirely upon the default behaviour,

				and implement the remaining methods as appropriate.

				(See the the EXAMPLE implementation.)

 */

class CTransition : public CActive

	{

public:

/**

	@fn				 IMPORT_C ~CTransition()

	Intended Usage	: Standardized virtual destruction method

	@since			7.0

	@pre 			The CTransition exists

	@post			The object has been destroyed

 */

	IMPORT_C ~CTransition();

/**

	@fn				virtual void SetStartStateL()

	Intended Usage	:	Sets the state of the test object to that specified

	Error Condition	:	

	@since			7.0

	@pre 			The CTransition is instantiated

	@post			The CTransition is in the state specified

 */

	IMPORT_C virtual void SetStartStateL();

/**

	@fn				IMPORT_C const TDesC& TransitionId() const

	Intended Usage	:	Returns the transition identifier

	Error Condition	:	

	@since			7.0

	@return			const TDesC& The identifier of this transition

	@pre 			The CTransition has been instantiated

 */

	IMPORT_C const TDesC& TransitionId() const;

/**

	@fn				IMPORT_C const TTransitionInfo& TransitionInfo() const

	Intended Usage	:	Get information on this transition.  Return struct contains the 

	transition ID, the current iteration and the logging mechanism used by this transition

	Error Condition	:	

	@since			7.0

	@return			const TTransitionInfo Information on the current transition

	@pre 			This CTransition is initialized

 */

	IMPORT_C const TTransitionInfo& TransitionInfo() const;

/**

	@fn				virtual void RunTransition(TRequestStatus* aUnitTestStatus)

	Intended Usage	:	Indicates that this transition should be run as soon as possible.

	This function calls ValidatePreConditions to ensure the object is in the appropriate start state 

	and then sets the transition active causing its RunL function to be called.

	Error Condition	:	

	@since			7.0

	@param			aUnitTestStatus Status word of the calling CUnitTest

	@pre 			The test object is in an appropriate state for this transition

	@post			The test object is in the end state of this transition

 */

	IMPORT_C virtual void RunTransition(TRequestStatus* aUnitTestStatus);

/**

	@fn				IMPORT_C void RepeatOnce()

	Intended Usage	:	Flag this transition to be repeated

	@since			7.0

	@pre 			None

	@post			The iRepeatThis flag is set to true.

 */

	IMPORT_C void RepeatOnce();

/**

	@fn				IMPORT_C TBool IsBlockingTransition() const

	Intended Usage	:	A blocking transition is one which does not run until all 

					outstanding asynchronous transitions have completed.  This function returns

					whether this is a blocking transition.

					This function does not need to be used by test developers as it is taken 

					care of in the transition and unittest base classes.  Blocking transitions

					can be added using AddBlockingTransitionL() in CUnitTest::ConstructL().

	@since			7.0

	@return			TBool Flag indicating whether this is a blocking transition or not.

	@pre 			None

 */

	IMPORT_C TBool IsBlockingTransition() const;

/**

	@fn				IMPORT_C void SetBlockingTransition(TBool aBlocking)

	Intended Usage	:	A blocking transition is one which does not run until all 

					outstanding asynchronous transitions have completed.

					This function does not need to be used by test developers as it is taken 

					care of in the transition and unittest base classes.  Blocking transitions

					can be added using AddBlockingTransitionL() in CUnitTest::ConstructL().

	@since			7.0

	@param			aBlocking Pass ETrue to set this as a blocking transition

	@pre 			This object is fully constructed

	@post			The blocking status of this CTransition is set

 */

	IMPORT_C void SetBlockingTransition(TBool aBlocking);

/**

	@fn				GetErrorCode() const

	Intended Usage	:	Returns the error code last recorded by the transition.

	@since			7.0

	@return			The error code that was last recorded during the transition execution.

	@pre 			This object is fully constructed.

 */

	IMPORT_C TInt GetErrorCode() const;

protected:

/**

	@fn				 CTransition(const TDesC&			aTransactionId, 

								CUnitTestContext&		aUTContext,

								TTransitionValidator&	aValidator)

	Intended Usage	: Default Constructor

	@param			aTransitionId The identifier of this transition

	@param			aUTContext The context within which this transition should run

	@param			aValidator Provides Pre & Post condition validation

	@since			7.0

	@pre 			None

	@post			First phase of two phase construction is complete

 */

	IMPORT_C CTransition(const TDesC&					aTransitionId, 

							   CUnitTestContext&		aUTContext,

							   TTransitionValidator&	aValidator);

/**

	@fn				virtual void DoCancel()

	Intended Usage	:	Standard Active Object method for cancelling the current request

	Error Condition	:	

	@since			7.0

	@pre 			None

	@post			Any outstanding requests are cancelled

 */

	IMPORT_C virtual void DoCancel();

/**

	@fn				RunL()

	Intended Usage	:	Implementation of CActive pure virtual method.  For each transition execution 

	RunL is performed twice.

	The first time it calls TransitMethodL() which is the developer defined function which executes the 

	test method.  It then immediately sets itself active and attempts to complete.  If TransitMethodL() 

	called a synchronous function then iStatus will not be KRequestPending and the RunL will be called as

	soon as it is scheduled.  If TransitMethodL() calls an asyncronous function then it will pass iStatus to the function and RunL

	will be called when the asynchronous function completes.

	Whichever method is used the second call of RunL() will complete the request of the CUnitTest which 

	called this transition by setting its status word.  If it has been requested that this transition is

	repeated then the status word will be set to KTestBedRepeatTest.

	Error Condition	:	

	@since			7.0

	@pre 			RunTransition() ensures the preconditions for this function

	@post			After 1st run - test method has been called

					After 2nd run - Unittest has been completed.

 */

	IMPORT_C virtual void RunL();

/**

	@fn				TransitMethodL()

	Intended Usage	:	Calls the method on the class being tested.  If the call is to 

	an asynchronous service provider you must set iStatus to KRequestPending as usual

	Error Condition	:	

	@since			7.0

	@pre 			Preconditions for this transition have been validated

	@post			The test method has been executed

 */

	IMPORT_C virtual void TransitMethodL() = 0;

/**

	@fn				RunError(TInt anErrorCode)

	Intended Usage	:	Called by the active scheduler if RunL leaves

	@since			7.0

	@param			anErrorCode The error code which RunL left with

	@return			KErrNone because if a CTransition::RunL leaves then we simply log

					the event and inform the CUnitTest.

	@pre 			This function is only called by the active scheduler if RunL leaves.

	@post			The owning CUnitTest has been informed that this CTransition left

 */

	IMPORT_C virtual TInt RunError(TInt aErrorCode);

/**

	@fn				PostTransitionCleanup()

	Intended Usage	:	Called from the RunL immediately after TransitMethodL() executes

	@since			7.0

	@pre 			Must be called from RunL only after TransitMethodL() has completed.

	@post			Default behaviour is to do nothing. 

					See the derived classes for additional functionality.

 */

	IMPORT_C virtual void PostTransitionCleanup();

protected:

/** The transition identifier*/

	const TDesC&		iTransitionId;

/** The context in which this transition is running (logging, state accessor & observer) */

	CUnitTestContext&	iUTContext;

/** Used for checking the state of the test object - provides pre and post condition 

	validation functions */

	TTransitionValidator& iValidator;

/** Indicates that this transition should be re-run after the current run */

	TBool					iRepeatThis;

/** The iStatus of the UnitTest which owns me so that I can complete it */

	TRequestStatus*			iUnitTestStatus;

/** Indicates that the transition has executed and can be completed */

	TBool					iTransitionFinished;

/** indicates the code that the RunL left with when completing with a KErrTestBedLeft */

	TInt iLeaveError;

/** Indicates that this transition should not execute until all previous async transitions

	have finished */

	TBool					iBlockingTransition;

/** Indicates that this transition is an asynchronous transition*/

	TBool					iAsyncTransition;

/** Information on this transition including its ID, its iteration number and the data logger

	it is currently using */

	TTransitionInfo			iTransitionInfo;

/** A friend for self-test operation */

	friend class TTransition_StateAccessor;

	};

#include <ecom/test_bed/transition.inl>

#endif