/*

* 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 the License "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: 

* Evaluator mix-in classes implementation

*

*/

/**

 @file 

 @released

 @internalComponent 

*/

#ifndef AUTHSERVER_EVALUATOR_H

#define AUTHSERVER_EVALUATOR_H

#include "authexpression_impl.h"

namespace AuthServer {

class MEvaluatorPluginInterface

/**

	CEvaluator uses this interface to invoke a plugin,

	which can be specified by type or ID.

	@see CEvaluator

 */

	{

public:

	/**

		Invoke the specified plugin and record the identity

		which was returned.

		@param	aPluginId		Plugin to use.

		@param	aIdentityId		On successful completion this

								object is set to the returned

								identity.

		@param	aType			The type of plugin represented 

								by this instance.						

		@param	aStatus			On completion (successful or

								otherwise) this object is

								completed with the error code.

	 */

	virtual void Evaluate(TPluginId aPluginId, TIdentityId& aIdentityId, 

						  CAuthExpressionImpl::TType aType, TRequestStatus& aStatus) = 0;

	/**

	    Cancel the plugin currently being invoked.

	 **/

	virtual void CancelEvaluate() = 0;

	/**

		Invoke a plugin of the requested type and record

		the identity which was returned.

		@param	aPluginType		Type of plugin to use.  The

								implementation maps this to a

								single, specific plugin.

		@param	aIdentityId		On successful completion this

								object is set to the returned

								identity.

		@param	aType			The type of plugin represented 

								by this instance.						

		@param	aStatus			On completion (successful or

								otherwise) this object is

								completed with the error code.

	 */

	virtual void Evaluate(TAuthPluginType aPluginType, TIdentityId& aIdentityId, 

						  CAuthExpressionImpl::TType aType, TRequestStatus& aStatus) = 0;

	};

class MEvaluatorClientInterface

/**

	CEvaluator uses this interface to notify the server

	when an evaluation has finished, successfully or otherwise.

	The server implements this interface to notify

	the client that the authentication request has

	completed.

 */

	{

public:

	/**

		This function is called by the evaluator when it

		has successfully parsed and evaluated an expression.

		In this context, successful means there were no

		errors in running the plugins, or otherwise in

		evaluating the expression, such as OOM.  It does

		not mean that a specific user was identified -

		aIdentity can still be CIdentity::KUnknown.

		@param	aIdentityId		Identified user.  This can

								be CIdentity::KUnknown.

		@see EvaluationFailed

	 */

	virtual void EvaluationSucceeded(TIdentityId aIdentityId) = 0;

	/**

		This function is called by the evaluator when

		it has failed to evaluate an expression.  Reasons

		for failure include failing to run a plugin;

		the user cancelling a plugin; OOM; and others.

		Failure in this sense does not means the expression

		was evaluated but no specific user was identified.

		That case is handled by EvaluationSucceeded.

		@param	aReason		Symbian OS error code.

		@see EvaluationSucceeded

	 */

	virtual void EvaluationFailed(TInt aReason) = 0;

	};

class CEvaluator : public CActive

/**

	Expression evaluator.  This asynchronously

	evaluates the supplied expression by calling

	the referenced plugins.

 */

	{

public:

	static CEvaluator* NewL(MEvaluatorPluginInterface* aPluginInterface, MEvaluatorClientInterface* aClientInterface);

	virtual ~CEvaluator();

	void Evaluate(const CAuthExpressionImpl* aExpr);

private:

	CEvaluator(MEvaluatorPluginInterface* aPluginInterface, MEvaluatorClientInterface* aClientInterface);

	void ConstructL();

	void EvaluatedNode(TIdentityId aIdentity);

	void EvaluateCompound(const CAuthExpressionImpl* aParent);

	void ReplaceComplexIdentity(TIdentityId aIdentity);

	// complete client request

	void NotifyClientSucceeded(TIdentityId aIdentity);

	void NotifyClientFailed(TInt aReason);

	// manipulate RPN stack

	TBool PushIdentity(TIdentityId aIdentity);

	TIdentityId PopIdentity();

	TIdentityId& LastIdentity();

	void ResetRpnStack();

	// implement CActive

	virtual void RunL();

	virtual void DoCancel();

#ifdef _DEBUG

	enum TPanic

		{

		EENRpnStackNonZero = 0x10,

		EECRpnStackTooLow = 0x20, EECBadParentType, EECRpnStackNotOneAtRoot, EECBadRightParent,

		EBusy = 0x30,

		};

	static void Panic(TPanic aPanic);

	TInt RpnDepth() const;

#endif

private:

	/** The evaluator uses this to invoke plugins. */

	MEvaluatorPluginInterface*const iPluginInterface;

	/**

		The evaluator uses this to notify the server

		when an evaluation has completed, successfully

		or otherwise.

	 */

	MEvaluatorClientInterface*const iClientInterface;

	/** Constant value defined for short name readability only. */

	static const CAuthExpressionImpl::TType KAnd;

	/** Constant value defined for short name readability only. */

	static const CAuthExpressionImpl::TType KOr;

	/** The expression which is currently being evaluated. */

	const CAuthExpressionImpl* iCurrentNode;

	/** The plugin sets this value to the returned identity. */

	TIdentityId iIdentity;

	/**

		Granularity of RPN stack.  This value should be large

		to parse a reasonable expression without having to

		reallocate, and without wasting too much memory.

	 */

	static const TInt KRPNGranularity;

	/**

		Intermediate results.  (A CArrayFixFlat is used here

		instead of an RArray because, although it uses more

		memory, it can be resized when items are popped.)

	 */

	CArrayFixFlat<TIdentityId>* iRpnStack;

	};

}	// namespace AuthServer

#endif	// #ifndef AUTHSERVER_EVALUATOR_H