1 /*

     2 * Copyright (c) 2007-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:  Interface for calendar DB operations

    15 *

    16 */

    17 

    18 

    19 #ifndef CESMRCALDBMGR_H

    20 #define CESMRCALDBMGR_H

    21 

    22 #include <e32base.h>

    23 //<cmail>

    24 #include "mesmrutilstombsext.h"

    25 //</cmail>

    26 #include <calprogresscallback.h>

    27 #include "cesmrcaldbbase.h"

    28 

    29 class MMRUtilsObserver;

    30 class CCalSession;

    31 class CCalEntry;

    32 class CESMREntryCmdIteratorAO;

    33 class CESMRGraveyardCleaner;

    34 

    35 /**

    36 * MESMRServicesCalDbMgr defines interface for calendar DB

    37 * operations.

    38 *

    39 * @lib esmrservices.lib

    40 */

    41 class MESMRCalDbMgr : public MCalProgressCallBack

    42     {

    43 public: // Constructors and destructors

    44 

    45     /**

    46     * Destructor.

    47     */

    48     virtual ~MESMRCalDbMgr() {};

    49 

    50     /**

    51      * Accessor for Agenda Model CCalEntryView owned by utility.

    52      * Returns a valid pointer if status is EAvailable or

    53      * EAvailableWithoutTombs, otherwise NULL.

    54      * @return entry view pointer, ownership not transferred

    55      */

    56     virtual CCalEntryView* NormalDbEntryView() = 0;

    57 

    58     /**

    59      * Accessor for Agenda Model CCalInstanceView owned by this utility.

    60      * Returns a valid pointer if status is EAvailable or

    61      * EAvailableWithoutTombs, otherwise NULL.

    62      * @return instance view pointer, ownership not transferred

    63      */

    64     virtual CCalInstanceView* NormalDbInstanceView() = 0;

    65 

    66     /**

    67      * Fetches entries from the Agenda Model based on time range.

    68      * In case of repeating entries the entire sequence must

    69      * be within range (but modifying entries are considered separately).

    70      * Ownership of entries is transferred to caller.

    71      * See CCalEntryView documentation for other fetch variants.

    72      * @param aCalEntryArray will contain fetched entries

    73      * @param aTimeRange criteria

    74      */

    75     virtual void FetchEntriesL(

    76             RPointerArray<CCalEntry>& aCalEntryArray,

    77             const CalCommon::TCalTimeRange& aTimeRange ) = 0;

    78 

    79     /**

    80      * Fetches entry from the Agenda Model based on Uid and recurrence id.

    81      * See CCalEntryView documentation for other fetch variants. For fetching

    82      * originating entry use TCalTime set to Time::NullTTime().

    83      * Returns NULL if no matching entry was found.

    84      * @param aUid criteria

    85      * @param aRecurrenceId criteria

    86      * @return entry, ownership is transferred to caller

    87      */

    88     virtual CCalEntry* FetchEntryL(

    89             const TDesC8& aUid,

    90             const TCalTime& aRecurrenceId ) = 0;

    91 

    92     /**

    93      * Stores the given entry in the Agenda Model. Entry is either

    94      * stored to normal calendar DB or to tombstone calendar DB depending

    95      * from input parameters.

    96      * @param aCalEntry entry to be stored.

    97      * @parma aToNormalDb ETrue  --> stored to normal DB.

    98      *                    EFalse --> stored to tombstone calendar DB.

    99      * @return KErrNone or a system wide error code.

   100      */

   101     virtual TInt StoreEntryL(

   102             CCalEntry& aCalEntry,

   103             TBool aToNormalDb = ETrue ) = 0;

   104 

   105     /**

   106      * Updates the given entry in the Agenda Model.

   107      * @param aCalEntry entry to update

   108      * @return KErrNone or a system wide error code

   109      */

   110     virtual TInt UpdateEntryL(

   111             const CCalEntry& aCalEntry ) = 0;

   112 

   113     /**

   114      * Deletes the given entry from the Agenda Model.

   115      * @param aUid Entry uid to be deleted

   116      * @return KErrNone or a system wide error code

   117      */

   118     virtual TInt DeleteEntryL(

   119             const TDesC8& aUid ) = 0;

   120 

   121     /**

   122      * Deletes the given entry from the Agenda Model.

   123      * @param aLocalUid Entry uid to be deleted

   124      * @return KErrNone or a system wide error code

   125      */

   126     virtual TInt DeleteEntryL(

   127             const TCalLocalUid& aLocalUid ) = 0;

   128 

   129     /**

   130      * Check entry: GUID, sequence number, existence in Agenda Model and

   131      * tombstone database. Same as CMRUtilsTombsExt::StoreL() but doesn't

   132      * actually store.

   133      * @param aCalEntry entry to be stored

   134      * @param aResurrectif ETrue then entry stored even if it has been

   135      * previously deleted

   136      * @param aCheckOnly

   137      * @return result code

   138      */

   139     virtual MESMRUtilsTombsExt::TESMRUtilsDbResult StoreEntryCondL(

   140             CCalEntry& aCalEntry,

   141             TBool aResurrect,

   142             TBool aCheckOnly = EFalse ) = 0;

   143 

   144     /**

   145      * Delete entry from Agenda Model if found

   146      * This method causes deletion of all entries with given GUID.

   147      * @param aUid determines entry to be deleted

   148      */

   149     virtual void DeleteEntryCondL(

   150             const TDesC8& aUid ) = 0;

   151 

   152     /**

   153      * Delete entry from Agenda Model if found.

   154      * This method causes deletion of a modifying entry, or entire

   155      * recurring event if aLocalUid corresponds to an originating entry.

   156      * @param aLocalUid determines entry to be deleted

   157      */

   158     virtual void DeleteEntryCondL(

   159             const TCalLocalUid& aLocalUid ) = 0;

   160 

   161     /**

   162      * Delete entry from Agenda Model if found.

   163      * This method causes deletion of a modifying entry, or entire

   164      * recurring event if aCalEntry is an originating entry.

   165      * @param aCalEntry entry to be deleted

   166      */

   167     virtual void DeleteEntryCondL(

   168             const CCalEntry& aCalEntry ) = 0;

   169 

   170     /**

   171      * Delete entries from Agenda Model if found.

   172      * This is asynchronous, user gets notified with

   173      * MMRUtilsObserver::HandleOperation( EDeleteEntries,... )

   174      * @param aCalTimeRange determines entries to be deleted

   175      */

   176     virtual void DeleteEntryCondL(

   177             const CalCommon::TCalTimeRange& aCalTimeRange ) = 0;

   178 

   179     /**

   180      * Fetches the calendar session associated with this

   181      * cal db manager.

   182      * @return Reference to calendar server session.

   183      */

   184     virtual CCalSession& CalSession() = 0;

   185     };

   186 

   187 /**

   188  * Manages two databases: normal Agenda db and tombstone db, and

   189  * handles command logic related to these databases. This class is

   190  * also responsible for collecting both database status information

   191  * and async command progress, and to notify aObserver.

   192  *

   193  * @lib esmrdb.lib

   194  */

   195 NONSHARABLE_CLASS(CESMRCalDbMgr) :

   196         public CBase,

   197         public MESMRCalDbMgr,

   198         public MESMRCalDbObserver

   199     {

   200 public: // Constructors and destructors

   201     /**

   202      * Symbian two-phased constructor.

   203      * @aCalSession calendar session reference

   204      * @aObserver utility observer reference

   205      */

   206     IMPORT_C static CESMRCalDbMgr* NewL(

   207             CCalSession& aCalSession,

   208             MMRUtilsObserver& aObserver );

   209 

   210     /**

   211      * Destructor.

   212      */

   213     ~CESMRCalDbMgr();

   214 

   215 protected: // From MESMRUtilsCalDbObserver

   216 

   217     void HandleCalDbStatus(

   218             const CESMRCalDbBase* aNotifier,

   219             MESMRCalDbObserver::TDbStatus aStatus );

   220 

   221 protected: // From MCalProgressCallBack

   222 

   223     void Progress(

   224             TInt aPercentageCompleted );

   225     TBool NotifyProgress();

   226     void Completed(

   227             TInt aError );

   228 

   229 protected: // From MESMRUtilsCalDbMgr

   230 

   231     CCalEntryView* NormalDbEntryView();

   232     CCalInstanceView* NormalDbInstanceView();

   233     void FetchEntriesL(

   234             RPointerArray<CCalEntry>& aCalEntryArray,

   235             const CalCommon::TCalTimeRange& aTimeRange );

   236     CCalEntry* FetchEntryL(

   237             const TDesC8& aUid,

   238             const TCalTime& aRecurrenceId );

   239     TInt StoreEntryL(

   240             CCalEntry& aCalEntry,

   241             TBool aToNormalDb = ETrue );

   242     TInt UpdateEntryL(

   243             const CCalEntry& aCalEntry );

   244     TInt DeleteEntryL(

   245             const TDesC8& aUid );

   246     TInt DeleteEntryL(

   247             const TCalLocalUid& aLocalUid );

   248     MESMRUtilsTombsExt::TESMRUtilsDbResult StoreEntryCondL(

   249             CCalEntry& aCalEntry,

   250             TBool aResurrect,

   251             TBool aCheckOnly = EFalse );

   252     MESMRUtilsTombsExt::TESMRUtilsDbResult CheckEntryCondL(

   253             const CCalEntry& aCalEntry );

   254     void DeleteEntryCondL(

   255             const TDesC8& aUid );

   256     void DeleteEntryCondL(

   257             const TCalLocalUid& aLocalUid );

   258     void DeleteEntryCondL(

   259             const CCalEntry& aCalEntry );

   260     void DeleteEntryCondL(

   261             const CalCommon::TCalTimeRange& aCalTimeRange );

   262     CCalSession& CalSession();

   263 

   264 protected: // New functions

   265     /**

   266      * Tests whether entry with same GUID and RECURRENCE-ID exists

   267      * in aDb. If yes, then aIndex will tell it's position in aCalEntryArray

   268      * which contains all entries with the same GUID.

   269      * @param aUid first identity criterion

   270      * @param aRecurrenceId second identity criterion

   271      * @param aDb database where to look

   272      * @param aCalEntryArray contains all entries with same GUID

   273      * @param aIndex tells position of entry, if method returned ETrue

   274      * @return ETrue if entry exists in aDb

   275      */

   276     TBool EntryExistsInDbL(

   277             const TDesC8& aUid,

   278             const TCalTime& aRecurrenceId,

   279             const CESMRCalDbBase& aDb,

   280             RPointerArray<CCalEntry>& aCalEntryArray,

   281             TInt& aIndex ) const;

   282     /**

   283      * Tests whether entry with same GUID and RECURRENCE-ID exists

   284      * in aDb. If yes, then aIndex will tell it's position in aCalEntryArray

   285      * which contains all entries with the same GUID.

   286      * @param aEntry, whose GUID and RECURRENCE-ID are compared

   287      * @param aDb database where to look

   288      * @param aCalEntryArray contains all entries with same GUID

   289      * @param aIndex tells position of entry, if method returned ETrue

   290      * @return ETrue if entry exists in aDb

   291      */

   292     TBool EntryExistsInDbL(

   293             const CCalEntry& aEntry,

   294             const CESMRCalDbBase& aDb,

   295             RPointerArray<CCalEntry>& aCalEntryArray,

   296             TInt& aIndex ) const;

   297 

   298     /**

   299      * Helper method for evaluating validity and status of entry

   300      * in relation to an another entry which exists in a database.

   301      * @param aEntry entry to be evaluated

   302      * @param aDbEntry corresponding entry existing in a database

   303      * @return entry evaluation result

   304      */

   305     MESMRUtilsTombsExt::TESMRUtilsDbResult EvaluateExistingEntryL(

   306             const CCalEntry& aEntry,

   307             const CCalEntry& aDbEntry ) const;

   308 

   309     /**

   310      * Helper method for evaluating validity and status of a new entry.

   311      * @aEntry entry to be evaluated

   312      * @return entry evaluation result

   313      */

   314     MESMRUtilsTombsExt::TESMRUtilsDbResult EvaluateNewEntryL(

   315             const CCalEntry& aEntry ) const;

   316 

   317     /**

   318      * Helper method which checks if given child entry would be a

   319      * valid new modifying entry, i.e. if it has a recurrence id

   320      * which matches to an existing instance.

   321      * @param aEntry entry to be evaluated

   322      * @return ETrue if valid

   323      */

   324     TBool IsValidNewModL(

   325             const CCalEntry& aEntry ) const;

   326 

   327     /**

   328      * Evaluates if corresponding originating entry exists in database.

   329      * @param aEntry

   330      * @return ETrue if originating entry exists in database

   331      */

   332     TBool OriginatingExistInDbL(

   333             const CCalEntry& aModEntry );

   334 

   335     /**

   336      * Helper method for deleting a tombstone entry.

   337      * @param aEntry entry to be deleted

   338      */

   339     void DeleteTombstoneL(

   340             const CCalEntry& aEntry );

   341 

   342 protected: // Constructors and destructors

   343 

   344     /**

   345      * C++ default constructor.

   346      * @param aCalSession calendar session reference

   347      * @param aObserver utility observer reference

   348      */

   349     CESMRCalDbMgr(

   350             CCalSession& aCalSession,

   351             MMRUtilsObserver& aObserver );

   352 

   353     /**

   354      *  Constructor, second phase.

   355      */

   356     void ConstructL();

   357 

   358 protected: // data

   359 

   360     /**

   361     * Currently ongoing asynchronous utils operation

   362     */

   363     TInt iCurrentAsyncOp;

   364 

   365     /**

   366     * Calendar session reference

   367     * Not own.

   368     */

   369     CCalSession& iCalSession;

   370 

   371     /**

   372     * Reference to cal db observer

   373     *

   374     */

   375     MMRUtilsObserver& iObserver;

   376     /**

   377     * Normal agenda database

   378     * Own.

   379     */

   380     CESMRCalDbBase* iNormalDb;

   381 

   382     /**

   383     * Handles asynchronous operation iteration

   384     * Own.

   385     */

   386     CESMREntryCmdIteratorAO* iCmdIterator;

   387     };

   388 

   389 #endif // CESMRCALDBMGR_H