--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mds_plat/context_engine_plugin_api/inc/contextengine.h Mon Jan 18 20:34:07 2010 +0200
@@ -0,0 +1,224 @@
+/*
+* 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