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


#ifndef CPIMEVENTMATCHER_H
#define CPIMEVENTMATCHER_H

//  INCLUDES
#include <e32base.h>
#include "pimcommon.h"
#include "pimevent.h"

// FORWARD DECLARATIONS
class CPIMEventItem;
class MPIMAdapterManager;
class CPIMValidator;

// CLASS DECLARATION
/**
 * Event occurrence matcher.
 * Used for finding events that take place on given range, possibly
 * checking repeating instances as well.
 */
NONSHARABLE_CLASS(CPIMEventMatcher): public CBase
{
public: // Constructors and destructor

    /**
     * C++ constructor.
     *
     * @param aSearchType Search type for matching.
     * @param aStartDate Start date for matching.
     * @param aEndDate End date for matching.
     * @param aInitialEventOnly Determines whether repeating
     *        occurrences are taken into account.
     *
     * @par Notes:
     * @li The validity of given options can be checked with
     *     SaneOptions() method. The matching can be carried out
     *     with invalid options as well, but results will be
     *     crap.
     */
    CPIMEventMatcher(
        const TPIMEventSearchType aSearchType,
        const TPIMDate& aStartDate,
        const TPIMDate& aEndDate,
        TBool aInitialEventOnly);

    /**
     * Destructor.
     */
    virtual ~CPIMEventMatcher();

public: // New functions

    /**
     * Checks whether the options given for matching are sane.
     * @li Search type is valid.
     * @li Start date is not greater than end date.
     *
     * This is not done during construction (e.g. within a NewL
     * function) because such failures are typically interpreted
     * as lack of resources etc.
     *
     * @return \c ETrue if the searching if valid options were
     *         given in construction; \c EFalse otherwise.
     */
    TBool SaneOptions();

    /**
     * Matches given item against the ranges and options set during
     * construction. According to them, the matching may apply to
     * either starting, ending or occurring events and either to
     * the single event instance or repeating occurrences of the
     * event.
     *
     * See constructor for search options.
     *
     * @param aTestedItem The item to test for matching.
     * @param aOccurrenceStart The start date stamp will be
     *        put here if the item matches. If repeating
     *        occurrences are taken into account, the start date
     *        of the repeating occurrence.
     *
     * @return \c ETrue if \a aTestedItem takes place in the set
     *         range according to the set options.
     */
    TBool MatchL(
        const CPIMEventItem& aTestedItem,
        TPIMDate& aOccurrenceStart) const;

private: // New functions

    /**
     * Matches events starting between set range. Examines
     * repeating occurrences if indicated.
     */
    TBool MatchStartingL(
        const CPIMEventItem& aTestedEvent,
        TPIMDate& aOccurrenceStart) const;

    /**
     * Helper function to MatchStartingL().
     */
    TBool MatchStartingRepeatingL(
        const TPIMDate& aEventStart,
        const CPIMEventItem& aTestedEvent,
        TPIMDate& aOccurrenceStart) const;

    /**
     * Matches events ending between set range. Examines
     * repeating occurrences if indicated.
     */
    TBool MatchEndingL(
        const CPIMEventItem& aTestedEvent,
        TPIMDate& aOccurrenceStart) const;

    /**
     * Helper function to MatchEndingL().
     */
    TBool MatchEndingRepeatingL(
        const TPIMDate& aEventEnd,
        const CPIMEventItem& aTestedEvent,
        TPIMDate& aOccurrenceStart) const;

    /**
     * Matches events occurring (also starting and ending)
     * between set range. Examines repeating occurrences if
     * indicated.
     */
    TBool MatchOccurringL(
        const CPIMEventItem& aTestedEvent,
        TPIMDate& aOccurrenceStart) const;

    /**
     * Helper function to MatchOccurringL.
     */
    TBool MatchOccurringRepeatingL(
        const TPIMDate& aEventStart,
        const TPIMDate& aEventEnd,
        const CPIMEventItem& aTestedEvent,
        TPIMDate& aOccurrenceStart) const;

    /**
     * Helper function to MatchEndingL and MatchOccurringL.
     * Deduces the start and end date of given Event. If either
     * start or end date is missing, the other value replaces
     * the missing one. If neither of them are present, the
     * operation fails.
     *
     * @param aEvent The Event from which to extract the dates.
     *
     * @param aEventStart Event start is put here. If Event start
     *        is not present, Event end is put instead.
     *
     * @param aEventEnd Event end is put here. If Event end is not
     *        present, Event start is put instead.
     *
     * @return KErrNotFound if neither start nor end date is present;
     *         KErrNone otherwise.
     */
    TInt ExtractStartAndEndDateL(
        const CPIMEventItem& aEvent,
        TPIMDate& aEventStart,
        TPIMDate& aEventEnd) const;

private: // Data

    const TPIMEventSearchType iSearchType;
    const TPIMDate iStartDate;
    const TPIMDate iEndDate;
    const TBool iInitialEventOnly;

};

#endif // CPIMEVENTMATCHER_H
// End of File