/*

* 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 item matcher.

 *

*/

#ifndef CPIMITEMMATCHER_H

#define CPIMITEMMATCHER_H

//  INCLUDES

#include <e32base.h>

#include "pimcommon.h"

// FORWARD DECLARATIONS

class CPIMItem;

class MPIMAdapterManager;

class CPIMValidator;

// CLASS DECLARATION

/**

 * Class for matching an item against multiple items for a match

 * defined in the PIM API PIMList.items( aMatchingItem ) method.

 * See MatchL() method.

 */

NONSHARABLE_CLASS(CPIMItemMatcher): public CBase

{

public: // Constructors and destructor

    //@{

    /**

     * Constructors.

     * \c NewLC() version leaves the created object in the

     * cleanup stack.

     *

     * @param aValidator A validator by which the field types are

     *        determined and the validity of

     *        the attributes in \a aMatchingItem is checked.

     * @param aAdapterManager An adapter manager by which support

     *        for the attributes in \a aMatchingItem are checked.

     * @param aMatchingItem The item against which the matching

     *        is done in subsequent matching operations.

     *        Some of the item data may be cached to

     *        optimize execution speed.

     *

     * @return New instance of CPIMItemMatcher.

     */

    static CPIMItemMatcher* NewLC(

        const CPIMValidator& aValidator,

        MPIMAdapterManager& aAdapterManager,

        const CPIMItem& aMatchingItem);

    //@}

    /**

     * Destructor.

     */

    virtual ~CPIMItemMatcher();

public: // New functions

    /**

     * Determines whether tested item matches the matching item

     * which was during construction.

     * @li Boolean, Date, Int and Binary fields are tested for

     *     exact match.

     * @li String fields are tested for collated substring match.

     * @li String Arry elements are tested for collated

     *     substring match. Null elements are ignored.

     *

     *

     * @param aTestedItem the item which is compared against

     *        \a aMatchingItem.

     *

     * @return \c ETrue if all values (and associated attributes)

     *         of all fields of the matching item are present

     *         in the \a aTestedItem; \c EFalse otherwise.

     *

     * @par Leaving:

     * Some of the leave codes indicate that the tested item did

     * not match the matching item. However, if the matching item

     * originates from this list (as required in the PIM API),

     * we should not come to such a situation.

     * @li \c KErrArgument - A matching field is invalid for

     *     given PIM type (no match).

     * @li \c KErrNotSupported - A matching field is not supported

     *     for given PIM list (no match).

     */

    TBool MatchL(const CPIMItem& aTestedItem);

private: // New functions

    /**

     * Match all values of given field in given item.

     *

     * @return \c ETrue if all values (and their attributes) of

     *         \a aMatchingField of the matching item are present

     *         in \a aTestedItem; \c EFalse otherwise.

     */

    TBool MatchAllMatchingValuesL(

        TPIMField aMatchingField,

        const CPIMItem& aTestedItem);

    /**

     * Match a value of matching item in given item.

     *

     * @return \c ETrue if some of the values in the

     *         \a aMatchingField of \a aTestedItem matches the

     *         value of \a aMatchingField indicated by

     *         \a aMatchingValueIndex in the

     *         matching item; \c EFalse otherwise.

     */

    TBool FindAnyTestedValueL(

        TPIMField aMatchingField,

        TInt aMatchingValueIndex,

        const CPIMItem& aTestedItem);

    /**

     * Matches a value of any type and its attributes to a given

     * value and attributes of the matching item.

     *

     * @return \c ETrue if the value and attributes of

     *         \a aMatchingField indicated by

     *         \a aTestedValueIndex in \a aTestedItem matches

     *         the value and attributes indicated by

     *         \a aMatchingValueIndex of

     *         \a aMatchingField in the matching item; \c EFalse

     *         otherwise.

     *

     * @par Notes:

     * @li The attributes associated with the value in the

     *     matching item must be a subset of the attributes

     *     associated with the value in the tested item.

     * @li The requirements for matching value may vary according

     *     to the type of the field.

     */

    TBool MatchValueAndAttributesL(

        TPIMField aMatchingField,

        TInt aMatchingValueIndex,

        const CPIMItem& aTestedItem,

        TInt aTestedValueIndex);

    /**

     * Matches the attributes associated with a value in the

     * tested item to the attributes with a value in the matching

     * item.

     *

     * @return \c ETrue if the attributes associated with the

     *         value in \a aMatchingValueIndex of

     *         \a aMatchingField of the matching item are a

     *         complete subset of the attributes associated with

     *         the value in \a aTestedValueindex of

     *         \a aMatchingField of \a aTestedItem; \c EFalse

     *         otherwise.

     */

    TBool MatchAttributesL(

        TPIMField aMatchingField,

        TInt aMatchingValueIndex,

        const CPIMItem& aTestedItem,

        TInt aTestedValueIndex);

    /**

     * Matches a boolean value (without attributes) in the given

     * item against the value in the matching item. The values

     * must match exactly.

     */

    TBool MatchBooleanL(

        TPIMField aMatchingField,

        TInt aMatchingValueIndex,

        const CPIMItem& aTestedItem,

        TInt aTestedValueIndex);

    /**

     * Matches a date value (without attributes) in the given

     * item against the value in the matching item. The values

     * must match exactly.

     */

    TBool MatchDateL(

        TPIMField aMatchingField,

        TInt aMatchingValueIndex,

        const CPIMItem& aTestedItem,

        TInt aTestedValueIndex);

    /**

     * Matches an int value (without attributes) in the given

     * item against the value in the matching item. The values

     * must match exactly.

     */

    TBool MatchIntL(

        TPIMField aMatchingField,

        TInt aMatchingValueIndex,

        const CPIMItem& aTestedItem,

        TInt aTestedValueIndex);

    /**

     * Matches a binary value (without attributes) in the given

     * item against the value in the matching item. The values

     * must match exactly.

     */

    TBool MatchBinaryL(

        TPIMField aMatchingField,

        TInt aMatchingValueIndex,

        const CPIMItem& aTestedItem,

        TInt aTestedValueIndex);

    /**

     * Matches a string value (without attributes) in the given

     * item against the value in the matching item. The value

     * in the given item must be a substring of the value in the

     * matching item, case-insensitive.

     */

    TBool MatchStringL(

        TPIMField aMatchingField,

        TInt aMatchingValueIndex,

        const CPIMItem& aTestedItem,

        TInt aTestedValueIndex);

    /**

     * Matches a string array value (without attributes) in the

     * given item against the value in the matching item. The

     * elements of the array in the given item must be substrings

     * of the elements in the array in the matching item,

     * case-insensitive. Empty elements in the matching item value

     * are ignored.

     */

    TBool MatchStringArrayL(

        TPIMField aMatchingField,

        TInt aMatchingValueIndex,

        const CPIMItem& aTestedItem,

        TInt aTestedValueIndex);

private: // Constructors

    /**

     * Constructor.

     */

    CPIMItemMatcher(

        const CPIMValidator& aValidator,

        MPIMAdapterManager& aAdapterManager,

        const CPIMItem& aMatchingItem);

    /**

     * Symbian 2nd phase constructor.

     */

    void ConstructL();

private: // Data

    const CPIMValidator& iValidator;

    MPIMAdapterManager& iAdapterManager;

    const CPIMItem& iMatchingItem;

    /** Cached matching fields, owned. */

    CArrayFix< TPIMField>* iMatchingFields;

};

#endif // CPIMITEMMATCHER_H

// End of File