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