/*
* 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:  Adapter manager interface, describes adapter properties.
 *
*/


#ifndef MPIMADAPTERMANAGER_H
#define MPIMADAPTERMANAGER_H

//  INCLUDES
#include <e32def.h>
#include <e32std.h>
#include <bamdesca.h>
#include "pimcommon.h"

//  FORWARD DECLARATIONS
class MPIMItemData;

// CLASS DECLARATION

/**
 *  Defines the operations common to all adapter managers and provides
 *  the characteristics of a single list.
 *
 *  List characteristics include
 *  list name, supported fields and attributes and limits of the
 *  list. The underlying native database cannot be changed through
 *  MPIMAdapterManager class.
 */
class MPIMAdapterManager
{
public:
    // Constructors and destructor

    /**
     * Destructor.
     */
    virtual ~MPIMAdapterManager()
    {
    }

public:
    // New functions

    /**
     * Provides the name of this list.
     */
    virtual const TDesC& ListNameL() = 0;

    /**
     * Provides number of maximum categories supported by the list adapter.
     * @return Number of maximum supported categories. 0 if not supported,
     *         -1 if unlimited.
     */
    virtual TInt MaxCategories() = 0;

    /**
     * Checks whether a specific field is supported by the list adapter.
     * @param aField The field to be checked.
     * @return ETrue if the given field is supported, EFalse otherwise.
     */
    virtual TBool IsSupportedField(TPIMField aField) = 0;

    /**
     * Provides all fields supported by the list adapter.
     *
     * @return An array containing all supported fields. The order of the
     *         fields must be the same as in the native side application
     *         UI.
     *
     * @par Leaving:
     * The method leaves on error. Such error always means that the adapter
     * is non-functional.
     */
    virtual const CArrayFix<TPIMField>& GetSupportedFieldsL() = 0;

    /**
     * Checks whether a specific attribute is supported by the list adapter.
     *
     * @param aField The field to which the attribute might be associated.
     * @param aAttribute The attribute to be checked.
     *
     * @return ETrue if the given attribute is supported, EFalse otherwise,
     *         also on unsupported \a aField.
     */
    virtual TBool IsSupportedAttribute(TPIMField aField,
                                       TPIMAttribute aAttribute) = 0;

    /**
     * Provides attributes supported for a field.
     *
     * @param aField The field to which the attributes are associated with.
     *
     * @return An array containing attributes supported for the \a aField.
     *         The order of attributes must reflect the order of field and
     *         attribute combinations in the native application UI.
     *
     * @par Leaving:
     * The method leaves on error. Error codes should be interpreted as
     * follows:
     * @li \c KErrArgument - \a aField is not valid.
     * @li Other - Array could not be created.
     */
    virtual const CArrayFix<TPIMAttribute>& GetSupportedAttributesL(
        TPIMField aField) = 0;

    /**
     * Provides attributes supported for a field, combined into single
     * integer value.
     *
     * @param aField The field to which the attributes are associated with.
     *
     * @return An integer holding the combination of all attributes
     *         supported for \a aField.
     *
     * @par Leaving.
     * The method leaves on error. Error codes should be interpreted as
     * follows:
     * @li \c KErrArgument - \a aField is not valid.
     */
    virtual TPIMAttribute
    GetSupportedAttributesCombinedL(TPIMField aField) = 0;

    /**
     * Provides all attributes supported for all fields, combined into
     * single integer value.
     *
     * @return An integer holding the combination of all attributes
     *         supported for all fields.
     */
    virtual TPIMAttribute GetAllSupportedAttributesCombined() = 0;

    /**
     * Checks whether a specific array element is supported by the
     * list adapter.
     *
     * @param aStringArrayField The field to which the array
     *        element belongs to.
     * @param aArrayElement The array element to be checked.
     *
     * @return ETrue if the given array element is supported,
     *         EFalse otherwise.
     */
    virtual TBool IsSupportedArrayElement(TPIMField aStringArrayField,
                                          TPIMArrayElement aArrayElement) = 0;

    /**
     * Provides supported array elements for a specific field.
     *
     * @param aStringArrayField A string array field.
     *
     * @return An array containing supported array elements for the field.
     *
     * @par Leaving:
     * The method leaves on error. Error codes should be interpreted as
     * follows:
     * @li \c KErrArgument - \a aField is not valid.
     * @li Other - Array could not be created.
     */
    virtual const CArrayFix<TPIMArrayElement>& GetSupportedArrayElementsL(
        TPIMField aStringArrayField) = 0;

    /**
     * Provides the number of maximum values supported for a specific field.
     *
     * @param aField The field to be evaluated.
     *
     * @return Number of values supported for the field. -1 for unlimited,
     *         0 if not supported.
     */
    virtual TInt MaxValues(TPIMField aField) = 0;

    /**
     * Provides the array size of a specific string array field.
     * The values in a string array field are arrays themselves.
     * StringArraySize method returns the number of elements in every value
     * of the field.
     *
     * @param aStringArrayField The string array field to be evaluated.
     * @return Number of elements in a single string array value.
     *
     * @par Leaving:
     * The method leaves with \c KErrArgument if \a aStringArrayField
     * is not a string array field or is not supported.
     */
    virtual TInt StringArraySizeL(TPIMField aStringArrayField) = 0;

    /**
     * Provides pointer to a function which implements an algorithm that
     * determines the order of two items.
     *
     * @return Item comparison function.
     */
    virtual TPIMItemComparisonFunc ItemOrder() = 0;

protected:
    // Non-public operations

    // Allow derivation with protected default constructor.
    MPIMAdapterManager()
    {
    }

private:
    // Prohibited operations

    // Prohibit copy constructor.
    MPIMAdapterManager(const MPIMAdapterManager&)
    {
    }

    // Prohibit assigment operator.
    MPIMAdapterManager& operator=(const MPIMAdapterManager&)
    {
        return *this;
    }

};

#endif // MPIMADAPTERMANAGER_H
// End of File