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


#ifndef CONTEXTENGINEAO_H
#define CONTEXTENGINEAO_H

// system include
#include <e32base.h>

// user include
#include "contextplugin.h"
#include "mpropertyobserver.h"

// forward declarations
class CContextSnapshotItem;
class MContextInitializationObserver;
class MContextSnapshotObserver;
class CMdESession;
class CPropertyWatcher;

/**
* This class implements an active object for collecting context metadata
* asyncronously from the context plugins.
*/
NONSHARABLE_CLASS( CContextEngineAO ) : public CActive, 
									    public MContextPluginObserver,
										public MKeyObserver
  	{
public:

	/**
	 * State for context engine (=this active object).
	 * Possible states: Ready for snapshot, initializing plugins or taking a snapshot.
	 */
	enum TContextEngineState { EReady = 0, EInitialization, ESnapshot };

	/**
	 * Creates and constructs a new instance of CContextEngineAO.
	 *
	 * @return A pointer to the new instance.
	 */
	static CContextEngineAO* NewL( MContextInitializationObserver* aInitObserver,
		MContextSnapshotObserver* aSnapshotObserver );

	/**
	 * Destructor.
	 */
	virtual ~CContextEngineAO();

public:
	/**
	 * Set a pointer to MdESession. The pointer is given forward to context plugins.
	 * Session must be set in order to successfully harvest context data.
	 *
	 * @param aSession Session pointer to set.
	 */
	void SetMdeSession( CMdESession* aSession );

	/**
	 * Start taking a context snapshot (for multiple objects).
	 *
	 * @param aItem  Observer to inform about snapshot completion
	 *               and MdE objects the snapshot is taken to.
	 */
	void StartSnapshot( CContextSnapshotItem* aItem );

	/**
	 * Method used to clarify how many plug-ins are loaded.
	 *
	 * @return Amount of plug-ins loaded.
	 */
	TInt PluginCount();

public:   // from base class CActive

	/**
	 * From CActive.
	 * Every call takes a context snapshot from one plug-in.
	 */
	void RunL();

	/**
	 * From CActive.
	 * Handles a leave occurring in the request completion event handler RunL().
	 *
	 * @param aError  An error code.
	 * @return An error code.
	 */
	TInt RunError( TInt aError );

	/**
	 * From CActive.
	 * Cancels ????.
	 */
	void DoCancel();

public:   // from MContextPluginObserver

	/**
	 * From MContextPluginObserver.
	 * This is derived from MContextPluginObserver and it is called
	 * by each plug-in when they have initialized.
	 * Error code for the first encountered error is returned as a parameter.
	 *
	 * @param aErrorCode  Error code for the first error occurred during initialization.
	 */
	void PluginInitializationStatus( TInt aErrorCode );
	
	/**
	 * From MContextPluginObserver.
	 * This is derived from MContextPluginObserver and it is called
	 * by each plug-in when they have taken the context snapshot.
	 * Error code for the first encountered error is returned as a parameter.
	 *
	 * @param aErrorCode  Error code for the first error occurred while taking the snapshot.
	 */
	void PluginSnapshotStatus( CHarvesterData* aHD );
        
public: // From MKeyObserver.   	

	/**
	 * Method NotifyKeyL from MKeyObserver get notifications when
	 * property key has changed.
	 */
	void NotifyKeyL( 
			const TInt aKeyValue,
			const TUid aPropertyCategory,
			const TUint aKey );     

private:

	/**
	 * Default constructor, implicitly called by NewL().
	 */
	CContextEngineAO( MContextInitializationObserver* aInitObserver,
		MContextSnapshotObserver* aSnapshotObserver );

	/**
	 * 2nd phase construction, called by NewL().
	 */
	void ConstructL();

	/**
	 * Load context plugins.
	 */
	void LoadPluginsL();

	/**
	 * Initialize this object. Thus load and initialize context plugins.
	 */
	void InitializeL();

	/**
	  * Called when
	  * Backup&Restore is backing up or restoring.
	  */
	 void BackupRestoreStart();

	 /**
	  * Called when
	  * Backup&Restore has finished backup or restore.
	  */
	 void BackupRestoreReady();

	/**
	 * Method HandleBackupRestoreKeyActionL.
	 * If user make full restore sets restore flag on.
	 */
	void HandleBackupRestoreKeyAction( const TUint aKeyValue );
    
private: // data

	/**
	 * This observer is used to inform the client application about
	 * finishing plug-in initializations.
	 */
	MContextInitializationObserver* iInitializationObserver;
	
	/**
	 * This observer is used to inform Context Engine about
	 * finishing a context snapshot.
	 */
	MContextSnapshotObserver* iContextSnapshotObserver;

	/**
	 * Plug-in array contains the plug-ins.
	 */
	RPointerArray<CContextPlugin> iPlugins;

	/**
	 * Number of plug-ins currently not being initialized yet.
	 */
	TInt iUninitializedPluginsCount;
	
	/**
	 * Number of HDs currently not completed the snapshot yet.
	 */
	TInt iPluginSnapshotsLacking;
	
	/**
	 * Item to which we are currently doing a snapshot for.
	 */
	CContextSnapshotItem* iItem;
	
	/**
	 * State of this active object.
	 */
	TContextEngineState iState;
	
	/** First error code encountered in initialization is cached here and returned later. */
	TInt iInitializationError;
	
	/** First error code encountered in snapshot is cached here and returned later. */
	TInt iSnapshotError;
	
	/**
	  * iMdESession - MDE session.
	  */
	CMdESession* iMdESession;

	/**
	 * iPropertyWatcher - constains observed key's, owned by this class.
	 */
	CPropertyWatcher* iPropertyWatcher;
	
    /**
     * iPropertyWatcher - used to check if only one plugin has not finished work.
     */
    TBool iLastPlugin;
    };

#endif // CONTEXTENGINEAO_H