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:  Implementation for calendar database accessor

    15 *

    16 */

    17 

    18 

    19 #ifndef CESMRCALDBBASE_H

    20 #define CESMRCALDBBASE_H

    21 

    22 #include <e32base.h>

    23 #include <calprogresscallback.h>

    24 #include <calcommon.h>

    25 

    26 class CESMRCalDbBase;

    27 class CCalEntryView;

    28 class CCalInstanceView;

    29 class CCalEntry;

    30 class CCalInstance;

    31 class CCalSession;

    32 

    33 /**

    34 * Observer interface for handling calendar database status.

    35 *

    36 * @lib esmrdb.lib

    37 */

    38 class MESMRCalDbObserver

    39     {

    40 public: // Data types

    41     /**

    42      * Enumeration for database status.

    43      */

    44     enum TDbStatus

    45         {

    46         EUninitialized       = 0x0000, // nothing done yet

    47         EReseting            = 0x0002, // db reset ongoing

    48         EInitEntryView       = 0x0004, // init entry view

    49         EInitInstanceView    = 0x0008, // init instance view

    50         EFinishedOk          = 0x0010, // init succeeded

    51         EFinishedError       = 0x0020  // init failed

    52         };

    53 

    54 public: // Interface

    55     /**

    56      * Callback method for handling database status.

    57      * @param aNotifier for identifying the notifying database

    58      * @param aStatus new current status of the database

    59      */

    60     virtual void HandleCalDbStatus(

    61             const CESMRCalDbBase* aNotifier,

    62             TDbStatus aStatus ) = 0;

    63 

    64     };

    65 

    66 /**

    67 * Base class representing a calendar database.

    68 *

    69 * @lib esmrdb.lib

    70 */

    71 class CESMRCalDbBase : public CBase,

    72                        public MCalProgressCallBack

    73     {

    74 public: // Constructors and destructors

    75     /**

    76     * Destructor.

    77     */

    78     ~CESMRCalDbBase();

    79 

    80     /**

    81      * Entry view accessor. Ownership not transferred.

    82      * @return entry view, may be NULL

    83      */

    84     const CCalEntryView* EntryView() const;

    85 

    86     /**

    87      * Instance view accessor. Ownership not transferred.

    88      * @return instance view, may be NULL

    89      */

    90     const CCalInstanceView* InstanceView() const;

    91 

    92     /**

    93      * Session accessor. Ownership not transferred.

    94      * @return session, may be NULL

    95      */

    96     const CCalSession* Session() const;

    97 

    98     /**

    99      * Entry view accessor. Ownership not transferred.

   100      * @return entry view, may be NULL

   101      */

   102     CCalEntryView* EntryView();

   103 

   104     /**

   105      * Instance view accessor. Ownership not transferred.

   106      * @return instance view, may be NULL

   107      */

   108     CCalInstanceView* InstanceView();

   109 

   110     /**

   111      * Session accessor. Ownership not transferred.

   112      * @return session, may be NULL

   113      */

   114     CCalSession* Session();

   115 

   116     /**

   117      * Database status getter.

   118      * @return current database status

   119      */

   120     MESMRCalDbObserver::TDbStatus DbStatus();

   121 

   122     /**

   123      * CCalEntryView lacks fetch with time range. This method provides such

   124      * functionality. In case of repeating entries the entire sequence must

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

   126      * If database doesn't have both instance and entry view then this

   127      * method leaves with KErrNotSupported.

   128      * @param aCalEntryArray fetched entries, caller owns array items

   129      * @param aCalTimeRange time range

   130      * @param aFetchFullCopy copy type of calendar entry

   131      */

   132     void FetchWithRangeL(

   133             RPointerArray<CCalEntry>& aCalEntryArray,

   134             const CalCommon::TCalTimeRange& aCalTimeRange,

   135             TBool aFetchFullCopy = ETrue );

   136 

   137     /**

   138      * Reset database, causes asynchronous db initialization

   139      * which is notified through MMRUtilsCalDbObserver interface.

   140      * Calling this method requires that there are no external

   141      * open references for the session.

   142      * The default implementation leaves with KErrNotSupported.

   143      */

   144     virtual void ResetDbL();

   145 

   146     /**

   147      * Tests whether given entry fits completely within given time range.

   148      * @param aEntry entry to test

   149      * @param aCalTimeRange criterion

   150      * @return ETrue if fits, EFalse if exceeds from either end

   151      */

   152     static TBool IsCompletelyWithinRangeL(

   153             const CCalEntry& aEntry,

   154             const CalCommon::TCalTimeRange& aCalTimeRange );

   155 

   156     /**

   157      * Wrapper which traps leaving CompareL(), and in leave situation

   158      * returns that objects are equal since that is a safer interpretation

   159      * and avoids duplicates in database.

   160      * In real life CompareL() is not expected to ever leave.

   161      * @param aFirst entry

   162      * @param aSecond entry

   163      * @return zero if the objects are equal, a negative value if aFirst is

   164      *         less than aSecond and a positive value otherwise

   165      */

   166     static TInt Compare(

   167             const CCalEntry& aFirst,

   168             const CCalEntry& aSecond );

   169 

   170     /**

   171      * Helper which allows ordering entries in an array. That is implemented

   172      * by evaluating GUID and RECURRENCE-ID of the two entries.

   173      * @param aFirst entry

   174      * @param aSecond entry

   175      * @return zero if the objects are equal, a negative value if aFirst is

   176      *         less than aSecond and a positive value otherwise

   177      */

   178     static TInt CompareL(

   179             const CCalEntry& aFirst,

   180             const CCalEntry& aSecond );

   181 

   182 protected: // From MCalProgressCallBack

   183     void Progress(

   184             TInt aPercentageCompleted );

   185     TBool NotifyProgress();

   186 

   187 protected: // Constructors and destructors

   188    /**

   189     * C++ default constructor.

   190     * @param aDbObserver database observer reference

   191     * @param aCmdObserver asynchronous command observer reference

   192     */

   193     CESMRCalDbBase(

   194             MESMRCalDbObserver& aDbObserver,

   195             MCalProgressCallBack& aCmdObserver );

   196 

   197 protected: // data

   198     /**

   199     * Current database status

   200     * Own.

   201     */

   202     MESMRCalDbObserver::TDbStatus iDbStatus;

   203     /**

   204     * Used for notifying about database status

   205     * Not own.

   206     */

   207     MESMRCalDbObserver& iDbObserver;

   208     /**

   209     * This callback is used for notifying about asynchronous

   210     * command progress, Note: currently not used for anything!

   211     * Not own.

   212     */

   213     MCalProgressCallBack& iCmdObserver;

   214 

   215     /**

   216     * Calender DB view. Managed by the subclass

   217     * Own.

   218     */

   219     CCalEntryView* iCalEntryView;

   220 

   221     /**

   222     * Caledar DB instance view. Managed by the subclass

   223     * Own.

   224     */

   225     CCalInstanceView* iCalInstanceView;

   226     /**

   227     * Calendar DB session. Managed by the subclass

   228     * Own.

   229     */

   230     CCalSession* iCalSession;

   231     };

   232 

   233 #endif // CESMRCALDBBASE_H