1 /*

     2 * Copyright (c) 2008 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 event occurrence matcher.

    15  *

    16 */

    17 

    18 

    19 #ifndef CPIMEVENTMATCHER_H

    20 #define CPIMEVENTMATCHER_H

    21 

    22 //  INCLUDES

    23 #include <e32base.h>

    24 #include "pimcommon.h"

    25 #include "pimevent.h"

    26 

    27 // FORWARD DECLARATIONS

    28 class CPIMEventItem;

    29 class MPIMAdapterManager;

    30 class CPIMValidator;

    31 

    32 // CLASS DECLARATION

    33 /**

    34  * Event occurrence matcher.

    35  * Used for finding events that take place on given range, possibly

    36  * checking repeating instances as well.

    37  */

    38 NONSHARABLE_CLASS(CPIMEventMatcher): public CBase

    39 {

    40 public: // Constructors and destructor

    41 

    42     /**

    43      * C++ constructor.

    44      *

    45      * @param aSearchType Search type for matching.

    46      * @param aStartDate Start date for matching.

    47      * @param aEndDate End date for matching.

    48      * @param aInitialEventOnly Determines whether repeating

    49      *        occurrences are taken into account.

    50      *

    51      * @par Notes:

    52      * @li The validity of given options can be checked with

    53      *     SaneOptions() method. The matching can be carried out

    54      *     with invalid options as well, but results will be

    55      *     crap.

    56      */

    57     CPIMEventMatcher(

    58         const TPIMEventSearchType aSearchType,

    59         const TPIMDate& aStartDate,

    60         const TPIMDate& aEndDate,

    61         TBool aInitialEventOnly);

    62 

    63     /**

    64      * Destructor.

    65      */

    66     virtual ~CPIMEventMatcher();

    67 

    68 public: // New functions

    69 

    70     /**

    71      * Checks whether the options given for matching are sane.

    72      * @li Search type is valid.

    73      * @li Start date is not greater than end date.

    74      *

    75      * This is not done during construction (e.g. within a NewL

    76      * function) because such failures are typically interpreted

    77      * as lack of resources etc.

    78      *

    79      * @return \c ETrue if the searching if valid options were

    80      *         given in construction; \c EFalse otherwise.

    81      */

    82     TBool SaneOptions();

    83 

    84     /**

    85      * Matches given item against the ranges and options set during

    86      * construction. According to them, the matching may apply to

    87      * either starting, ending or occurring events and either to

    88      * the single event instance or repeating occurrences of the

    89      * event.

    90      *

    91      * See constructor for search options.

    92      *

    93      * @param aTestedItem The item to test for matching.

    94      * @param aOccurrenceStart The start date stamp will be

    95      *        put here if the item matches. If repeating

    96      *        occurrences are taken into account, the start date

    97      *        of the repeating occurrence.

    98      *

    99      * @return \c ETrue if \a aTestedItem takes place in the set

   100      *         range according to the set options.

   101      */

   102     TBool MatchL(

   103         const CPIMEventItem& aTestedItem,

   104         TPIMDate& aOccurrenceStart) const;

   105 

   106 private: // New functions

   107 

   108     /**

   109      * Matches events starting between set range. Examines

   110      * repeating occurrences if indicated.

   111      */

   112     TBool MatchStartingL(

   113         const CPIMEventItem& aTestedEvent,

   114         TPIMDate& aOccurrenceStart) const;

   115 

   116     /**

   117      * Helper function to MatchStartingL().

   118      */

   119     TBool MatchStartingRepeatingL(

   120         const TPIMDate& aEventStart,

   121         const CPIMEventItem& aTestedEvent,

   122         TPIMDate& aOccurrenceStart) const;

   123 

   124     /**

   125      * Matches events ending between set range. Examines

   126      * repeating occurrences if indicated.

   127      */

   128     TBool MatchEndingL(

   129         const CPIMEventItem& aTestedEvent,

   130         TPIMDate& aOccurrenceStart) const;

   131 

   132     /**

   133      * Helper function to MatchEndingL().

   134      */

   135     TBool MatchEndingRepeatingL(

   136         const TPIMDate& aEventEnd,

   137         const CPIMEventItem& aTestedEvent,

   138         TPIMDate& aOccurrenceStart) const;

   139 

   140     /**

   141      * Matches events occurring (also starting and ending)

   142      * between set range. Examines repeating occurrences if

   143      * indicated.

   144      */

   145     TBool MatchOccurringL(

   146         const CPIMEventItem& aTestedEvent,

   147         TPIMDate& aOccurrenceStart) const;

   148 

   149     /**

   150      * Helper function to MatchOccurringL.

   151      */

   152     TBool MatchOccurringRepeatingL(

   153         const TPIMDate& aEventStart,

   154         const TPIMDate& aEventEnd,

   155         const CPIMEventItem& aTestedEvent,

   156         TPIMDate& aOccurrenceStart) const;

   157 

   158     /**

   159      * Helper function to MatchEndingL and MatchOccurringL.

   160      * Deduces the start and end date of given Event. If either

   161      * start or end date is missing, the other value replaces

   162      * the missing one. If neither of them are present, the

   163      * operation fails.

   164      *

   165      * @param aEvent The Event from which to extract the dates.

   166      *

   167      * @param aEventStart Event start is put here. If Event start

   168      *        is not present, Event end is put instead.

   169      *

   170      * @param aEventEnd Event end is put here. If Event end is not

   171      *        present, Event start is put instead.

   172      *

   173      * @return KErrNotFound if neither start nor end date is present;

   174      *         KErrNone otherwise.

   175      */

   176     TInt ExtractStartAndEndDateL(

   177         const CPIMEventItem& aEvent,

   178         TPIMDate& aEventStart,

   179         TPIMDate& aEventEnd) const;

   180 

   181 private: // Data

   182 

   183     const TPIMEventSearchType iSearchType;

   184     const TPIMDate iStartDate;

   185     const TPIMDate iEndDate;

   186     const TBool iInitialEventOnly;

   187 

   188 };

   189 

   190 #endif // CPIMEVENTMATCHER_H

   191 // End of File