/*

* Copyright (c) 2006-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:  An engine to collect context related metadata.

*

*/

// Statically linked dll

#ifndef CCONTEXTENGINE_H

#define CCONTEXTENGINE_H 

#include <e32cons.h>

#include <e32cmn.h>

//forward declarations

class CMdEObject; 

class CContextEngineAO;

class CContextSnapshotItem;

class CMdESession;

class CHarvesterData;

/**

* An interface for observer that wants to be informed about

* context engine initialization completion and

* snapshot completion.

*/

class MContextInitializationObserver

    {

    public:

        /**

         * Pure virtual method. Intended to inform about

         * context engine initialization completion.

         *

         * @param aErrorCode  Error code for error occurred during initialization 

         */

        virtual void ContextInitializationStatus( TInt aErrorCode ) = 0;

    };

/**

* An interface for observers that want to be informed about context snapshot completion.

*/

class MContextSnapshotObserver

    {

    public:

        /**

         * Pure virtual method. Intended to inform about context snapshot taking completion.

         *

         * @param aErrorCode  Error code for error occurred while taking the snapshot.

         */

        virtual void ContextSnapshotStatus( CHarvesterData* aHD ) = 0;

    };

/**

* An engine to collect context metadata with available context plugins.

* CContextEngineAO is used to do the actual work.

* This class is implemented as a Singleton.

*/

NONSHARABLE_CLASS( CContextEngine ) : public CBase, public MContextSnapshotObserver

      {

    public:

        /**

         * Destroys the implementation. This is virtual method

         * and this class is not intended for derivation, so not exported.

         */

        virtual ~CContextEngine();

        /**

         * Gets an instance to CContextEngine singleton.

         * A new object is created if needed.

         * If an observer object to notify is given, context plugins are initialized

         * asyncronously and observer is notified when ready.

         *

         * @param aObserver  an interface class for callback or NULL

         * @return A pointer to the context engine implementation

         */ 

        IMPORT_C static CContextEngine* GetInstanceL( MContextInitializationObserver* aObserver = NULL );

        /**

         * Release an instance of this singleton.

         */

        IMPORT_C void ReleaseInstance();

        /**

         * Ignores the reference count and destroys this singleton.

         * THINK BEFORE USING! Should be used only instead of reference counting

         * if clients are not calling ReleaseInstance() (which they should).

         */

        IMPORT_C void Destroy();

        /**

         * 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.

         */

        IMPORT_C void SetMdeSession( CMdESession* aSession );

        /**

         * Context snapshot. This takes the snapshot using plug-ins.

         *

         * @param aObserver  an interface class for callback.

         * @param aMetadataObject  MdE object the snapshot is taken to.

         */

        IMPORT_C void ContextSnapshot( MContextSnapshotObserver& aObserver,

            CHarvesterData& aHD );

        /**

         * Context snapshot. This takes the snapshot using plug-ins.

         *

         * @param aObserver  an interface class for callback.

         * @param aMetadataObjectArray  An array of MdE objects the snapshot is taken to.

         */

        IMPORT_C void ContextSnapshot( MContextSnapshotObserver& aObserver,

            RPointerArray<CHarvesterData>& aMetadataObjectArray );

        /**

         * Method used to clarify amount of plug-ins.

         *

         * @return Amount of plug-ins. Intended for test purposes only.

         */

        IMPORT_C TInt PluginCount();

        /**

         * From MContextEngineObserver.

         * Method is called by CContextEngineAO when a context snapshot is finished

         * or an error has occured.

         *

         * @param aErrorCode  Error code for error occurred during snapshot.

         */

        void ContextSnapshotStatus( CHarvesterData* aHD );

    private:

        /**

         * C++ constructor - not exported;

         * implicitly called from GetInstance()

         *

         */

        CContextEngine();

        /**

         * 2nd phase construction, called by GetInstance()

         *

         * @param aObserver object/callback to notify when initialization is ready.

         */

        void ConstructL( MContextInitializationObserver* aObserver );

        /**

         * Add a new observer and metadata items to a queue.

         * These observers need to be informed when a snapshot is ready

         * and items need a context snapshot.

         *

         * @param aItem  An item to add.

         */

        void QueueSnapshotItem( CContextSnapshotItem* aItem );

    private: // data

        /**

         * This active object is used to handle queued snapshot requests.

         */

        CContextEngineAO* iContextEngineAO;

        /**

         * Array of observers and related metadata objects that need

         * a context snapshot.

         * Related observer is informed about snapshot completion.

         */

        RPointerArray<CContextSnapshotItem> iSnapshotQueue;

        /**

         * In case array of objects for snapshot were passed,

         * variable to store the amount of items to be processed.

         */

        TInt iArrayCount;

        /**

         * In case array of objects for snapshot were passed,

         * variable to store the amount of items that have been processed.

         */

        TInt iProcessedArrayCount;

    };

/**

* A helper class to store this singleton's static data.

*/

NONSHARABLE_CLASS( CContextEngineStaticData ): public CBase

    {

    friend class CContextEngine;

    public:

        CContextEngineStaticData( CContextEngine* aContextEngine ) : iContextEngine(aContextEngine)

            {

            iRefCount = 1;

            }

        virtual ~CContextEngineStaticData()

            {

            delete iContextEngine;

            }

    protected:

        CContextEngine* iContextEngine;

        TInt iRefCount;

    };

#endif // CCONTEXTENGINE_H