1 /*

     2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  An engine to collect context related metadata.

    15 *

    16 */

    17 

    18 // Statically linked dll

    19 

    20 #ifndef CCONTEXTENGINE_H

    21 #define CCONTEXTENGINE_H 

    22 

    23 #include <e32cons.h>

    24 #include <e32cmn.h>

    25 

    26 //forward declarations

    27 

    28 class CMdEObject; 

    29 class CContextEngineAO;

    30 class CContextSnapshotItem;

    31 class CMdESession;

    32 class CHarvesterData;

    33 

    34 /**

    35 * An interface for observer that wants to be informed about

    36 * context engine initialization completion and

    37 * snapshot completion.

    38 */

    39 class MContextInitializationObserver

    40     {

    41     public:

    42         /**

    43          * Pure virtual method. Intended to inform about

    44          * context engine initialization completion.

    45          *

    46          * @param aErrorCode  Error code for error occurred during initialization 

    47          */

    48         virtual void ContextInitializationStatus( TInt aErrorCode ) = 0;

    49     };

    50 

    51 /**

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

    53 */

    54 class MContextSnapshotObserver

    55     {

    56     public:

    57         /**

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

    59          *

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

    61          */

    62         virtual void ContextSnapshotStatus( CHarvesterData* aHD ) = 0;

    63     };

    64 

    65 /**

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

    67 * CContextEngineAO is used to do the actual work.

    68 * This class is implemented as a Singleton.

    69 */

    70 NONSHARABLE_CLASS( CContextEngine ) : public CBase, public MContextSnapshotObserver

    71       {

    72     public:

    73 

    74         /**

    75          * Destroys the implementation. This is virtual method

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

    77          */

    78         virtual ~CContextEngine();

    79 

    80         /**

    81          * Gets an instance to CContextEngine singleton.

    82          * A new object is created if needed.

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

    84          * asyncronously and observer is notified when ready.

    85          *

    86          * @param aObserver  an interface class for callback or NULL

    87          * @return A pointer to the context engine implementation

    88          */ 

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

    90 

    91         /**

    92          * Release an instance of this singleton.

    93          */

    94         IMPORT_C void ReleaseInstance();

    95 

    96         /**

    97          * Ignores the reference count and destroys this singleton.

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

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

   100          */

   101         IMPORT_C void Destroy();

   102 

   103         /**

   104          * Set a pointer to MdESession. The pointer is given forward to context plugins.

   105          * Session must be set in order to successfully harvest context data.

   106          *

   107          * @param aSession Session pointer to set.

   108          */

   109         IMPORT_C void SetMdeSession( CMdESession* aSession );

   110 

   111         /**

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

   113          *

   114          * @param aObserver  an interface class for callback.

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

   116          */

   117         IMPORT_C void ContextSnapshot( MContextSnapshotObserver& aObserver,

   118             CHarvesterData& aHD );

   119         

   120         /**

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

   122          *

   123          * @param aObserver  an interface class for callback.

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

   125          */

   126         IMPORT_C void ContextSnapshot( MContextSnapshotObserver& aObserver,

   127             RPointerArray<CHarvesterData>& aMetadataObjectArray );

   128         

   129         /**

   130          * Method used to clarify amount of plug-ins.

   131          *

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

   133          */

   134         IMPORT_C TInt PluginCount();

   135 

   136         /**

   137          * From MContextEngineObserver.

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

   139          * or an error has occured.

   140          *

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

   142          */

   143         void ContextSnapshotStatus( CHarvesterData* aHD );

   144 

   145     private:

   146 

   147         /**

   148          * C++ constructor - not exported;

   149          * implicitly called from GetInstance()

   150          *

   151          */

   152         CContextEngine();

   153         

   154         /**

   155          * 2nd phase construction, called by GetInstance()

   156          *

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

   158          */

   159         void ConstructL( MContextInitializationObserver* aObserver );

   160 

   161         /**

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

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

   164          * and items need a context snapshot.

   165          *

   166          * @param aItem  An item to add.

   167          */

   168         void QueueSnapshotItem( CContextSnapshotItem* aItem );

   169 

   170     private: // data

   171 

   172         /**

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

   174          */

   175         CContextEngineAO* iContextEngineAO;

   176 

   177         /**

   178          * Array of observers and related metadata objects that need

   179          * a context snapshot.

   180          * Related observer is informed about snapshot completion.

   181          */

   182         RPointerArray<CContextSnapshotItem> iSnapshotQueue;

   183         

   184         /**

   185          * In case array of objects for snapshot were passed,

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

   187          */

   188         TInt iArrayCount;

   189         

   190         /**

   191          * In case array of objects for snapshot were passed,

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

   193          */

   194         TInt iProcessedArrayCount;

   195     };

   196 

   197 

   198 /**

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

   200 */

   201 NONSHARABLE_CLASS( CContextEngineStaticData ): public CBase

   202     {

   203     friend class CContextEngine;

   204         

   205     public:

   206 

   207         CContextEngineStaticData( CContextEngine* aContextEngine ) : iContextEngine(aContextEngine)

   208             {

   209             iRefCount = 1;

   210             }

   211 

   212         virtual ~CContextEngineStaticData()

   213             {

   214             delete iContextEngine;

   215             }

   216 

   217     protected:

   218 

   219         CContextEngine* iContextEngine;

   220         TInt iRefCount;

   221     };

   222 

   223 

   224 #endif // CCONTEXTENGINE_H