/*

* 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:  Provides static information about contact lists and creates

 *                contact list adapters.

 *

*/

#ifndef CPIMCMADAPTERMANAGER_H

#define CPIMCMADAPTERMANAGER_H

//  INCLUDES

#include "mpimcontactadaptermanager.h"

#include "mpimadaptermanager.h"

#include "pimcontact.h" // field enums

#include "pimcommon.h" // basic types

#include <e32base.h>

// CONSTANTS

const TPIMField KPIMSupportedFields[] =

{

    EPIMContactPhoto,

    EPIMContactName,

    EPIMContactNickname,

    EPIMContactTel,

    EPIMContactEmail,

    EPIMContactExtDtmf,

    EPIMContactExtVoip,

    EPIMContactExtPTT,

    EPIMContactExtSWIS,

    EPIMContactExtSip,

    EPIMContactOrg,

    EPIMContactExtDepartment,

    EPIMContactTitle,

    EPIMContactExtAssistantName,

    EPIMContactExtSpouse,

    EPIMContactExtChildren,

    EPIMContactUrl,

    EPIMContactAddr,

    EPIMContactBirthday,

    EPIMContactExtAnniversary,

    EPIMContactNote,

    EPIMContactClass,

    EPIMContactExtWvUserId,

    EPIMContactUid,

    EPIMContactRevision

};

/**

 * Number of supported Contact fields by S60 platform

 */

const TInt KPIMSupportedFieldsCount = sizeof(KPIMSupportedFields)

                                      / sizeof(TPIMField);

/**

 * Maximum number of values for all standard PIM API Contact fields.

 *

 * The field constants are numbered from 100 to 118; thus they can be

 * mapped to a table starting from 0 by reducing 100 from the field

 * constant values.

 *

 * See @ref KPIMContactMaxValueMappingOffset.

 */

const TInt KPIMMaxValues[] =

{

    3, // address

    1, // birthday

    1, // class

    KPIMUnlimitedValues, // email

    0, // formatted address

    0, // formatted name

    1, // name

    1, // nickname

    KPIMUnlimitedValues, // note

    1, // org

    1, // photo

    0, // photo url

    0, // public key

    0, // public key string

    1, // revision

    KPIMUnlimitedValues, // tel

    KPIMUnlimitedValues, // title

    1, // uid

    KPIMUnlimitedValues // url

};

/**

 * Maximum number of values for all extended PIM API Contact fields.

 *

 * The field constants are numbered from 0x1005001 to 0x1005003;

 * thus they can be mapped to a table starting from 0 by reducing 0x1005001

 * from the field constant values.

 *

 * See @ref KPIMContactMaxExtValueMappingOffset.

 */

const TInt KPIMMaxExtValues[] =

{

    1, // Extended WV User ID

    KPIMUnlimitedValues, // Extended SIP

    KPIMUnlimitedValues, // Extended DTMF

    1, // Extended Department

    1, // Extended Assistant name

    1, // Extended Children

    1, // Extended Spouse

    1, // Extended Anniversary

    KPIMUnlimitedValues, // Extended VOIP

    KPIMUnlimitedValues, // Extended PTT

    KPIMUnlimitedValues // Extended SWIS

};

/**

 * Smallest Contact standard field constant.

 */

const TInt KPIMContactSmallestField = 100;

/**

 * Largest Contact standard field constant.

 */

const TInt KPIMContactLargestField = 118;

/**

 * The offset for mapping Contact standard field constant values to

 * elements in @ref KPIMMaxValues table.

 */

const TInt KPIMContactMaxValueMappingOffset = 100;

/**

 * Smallest Contact extended field constant.

 */

const TInt KPIMContactSmallestExtField = 0x1005001;

/**

 * Largest Contact extended field constant.

 */

const TInt KPIMContactLargestExtField = 0x100500B;

/**

 * The offset for mapping Contact extended field constant values to

 * elements in @ref KPIMMaxExtValues table.

 */

const TInt KPIMContactMaxExtValueMappingOffset = 0x1005001;

/**

 * Number of Contact fields in PIM API.

 */

const TInt KPIMFieldCount = sizeof(KPIMMaxValues) / sizeof(TInt)

                            + sizeof(KPIMMaxExtValues) / sizeof(TInt);

// Supported ADDR attributes

const TPIMAttribute KPIMAddrAttributes[] =

{

    EPIMContactAttrHome,

    EPIMContactAttrWork

};

const TPIMAttribute KPIMAddrAttributesCombined = (EPIMContactAttrWork

        | EPIMContactAttrHome);

const TInt KPIMAddrAttributeCount = sizeof(KPIMAddrAttributes)

                                    / sizeof(TPIMAttribute);

// Supported EMAIL attributes

const TPIMAttribute KPIMEmailAttributes[] =

{

    EPIMContactAttrHome,

    EPIMContactAttrWork,

    EPIMContactAttrPreferred

};

const TPIMAttribute KPIMEmailAttributesCombined = (EPIMContactAttrHome

        | EPIMContactAttrWork | EPIMContactAttrPreferred);

const TInt KPIMEmailAttributeCount = sizeof(KPIMEmailAttributes)

                                     / sizeof(TPIMAttribute);

// Supported TEL attributes

const TPIMAttribute KPIMTelAttributes[] =

{

    EPIMContactAttrHome,

    EPIMContactAttrWork,

    EPIMContactAttrMobile,

    EPIMContactAttrAuto,

    EPIMContactAttrExtVideoCall,

    EPIMContactAttrFax,

    EPIMContactAttrPager,

    EPIMContactAttrPreferred,

    EPIMContactAttrSms,

    EPIMContactAttrAsst,

    EPIMContactAttrOther // We "support" this but it is silently discarded

};

const TPIMAttribute KPIMTelAttributesCombined = (EPIMContactAttrHome

        | EPIMContactAttrWork | EPIMContactAttrMobile | EPIMContactAttrAuto

        | EPIMContactAttrExtVideoCall | EPIMContactAttrFax

        | EPIMContactAttrPager | EPIMContactAttrPreferred | EPIMContactAttrSms

        | EPIMContactAttrAsst | EPIMContactAttrOther);

const TInt KPIMTelAttributeCount = sizeof(KPIMTelAttributes)

                                   / sizeof(TPIMAttribute);

// Note: These are only the supported elements

const TPIMArrayElement KPIMNameElements[] =

{

    EPIMContactNamePrefix,

    EPIMContactNameGiven,

    EPIMContactExtGivenNameReading,

    EPIMContactNameOther,

    EPIMContactNameFamily,

    EPIMContactExtFamilyNameReading,

    EPIMContactNameSuffix

};

const TInt KPIMNameElementCount = sizeof(KPIMNameElements)

                                  / sizeof(TPIMArrayElement);

const TInt KPIMNameArraySize = EPIMContactNameNumElements;

// Note: All elements are currently supported

const TInt KPIMAddrElementCount = EPIMContactAddrNumElements;

const TPIMArrayElement KPIMAddrElements[KPIMAddrElementCount] =

{

    EPIMContactAddrPoBox,

    EPIMContactAddrExtra,

    EPIMContactAddrStreet,

    EPIMContactAddrPostalCode,

    EPIMContactAddrLocality,

    EPIMContactAddrRegion,

    EPIMContactAddrCountry

};

// Supported VOIP attributes

const TPIMAttribute KPIMVoipAttributes[] =

{

    EPIMContactAttrHome,

    EPIMContactAttrWork,

    EPIMContactAttrPreferred

};

const TInt KPIMVoipAttributeCount = sizeof(KPIMVoipAttributes)

                                    / sizeof(TPIMAttribute);

// FORWARD DECLARATIONS

class MPIMItem;

// CLASS DECLARATION

/**

 * This class provides access to the PIM Contacts Model list

 */

NONSHARABLE_CLASS(CPIMCMAdapterManager): public CBase,

        public MPIMContactAdapterManager,

        public MPIMAdapterManager

{

public: // Constructors and a destructor

    /**

     * Two-phased constructor.

     *

     * @param aListName List name.

     */

    static CPIMCMAdapterManager* NewL(const TDesC& aListName);

    /**

     * destructor

     */

    ~CPIMCMAdapterManager();

public: // MPIMAdapterManager

    const TDesC& ListNameL();

    /**

     * Provides number of maximum categories supported by the list adapter.

     * @return Number of maximum supported categories .

     */

    TInt MaxCategories();

    /**

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

     */

    TBool IsSupportedField(TPIMField aField);

    /**

     * Provides all fields supported by the list adapter.

     *

     * @return An array containing all supported fields.

     *

     * @par Leaving:

     * The method leaves on error. Such error always means that the adapter

     * is non-functional.

     */

    const CArrayFix<TPIMField>& GetSupportedFieldsL();

    /**

     * Checks whether a specific attribute is supported by the list adapter.

     * @param aAttribute The attribute to be checked.

     * @return ETrue if the given attribute is supported, EFalse otherwise.

     */

    TBool IsSupportedAttribute(TPIMField aField,

                               TPIMAttribute aAttribute);

    /**

     * Provides all attributes supported by the list adapter.

     *

     * @return An array containing all supported attributes.

     *

     * @par Leaving:

     * The method leaves on error. Such error always means that the adapter

     * is non-functional.

     */

    const CArrayFix<TPIMAttribute>& GetSupportedAttributesL(

        TPIMField aField);

    /**

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

     */

    TPIMAttribute GetSupportedAttributesCombinedL(

        TPIMField aField);

    /**

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

     */

    TPIMAttribute GetAllSupportedAttributesCombined();

    /**

     * Checks whether a specific array element is supported by the list adapter.

     * @param aArrayElement The array element to be checked.

     * @return ETrue if the given array element is supported, EFalse otherwise.

     */

    TBool IsSupportedArrayElement(TPIMField aStringArrayField,

                                  TPIMArrayElement aArrayElement);

    /**

     * Provides all array elements supported by the list adapter.

     *

     * @return An array containing all supported array elements.

     *

     * @par Leaving:

     * The method leaves on error. Such error always means that the adapter

     * is non-functional.

     */

    const CArrayFix<TPIMArrayElement>& GetSupportedArrayElementsL(

        TPIMField aStringArrayField);

    /**

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

     */

    TInt MaxValues(TPIMField aField);

    /**

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

     */

    TInt StringArraySizeL(TPIMField aStringArrayField);

    /**

     * Provides pointer to a function which implements an algorithm that

     * determines the order of two items.

     *

     * @return Item comparison function.

     */

    TPIMItemComparisonFunc ItemOrder();

public: // MPIMContactAdapterManager

    /**

     * Provides access to the \ref MPIMAdapterManager representation of

     * this object.

     *

     * @return The \ref MPIMAdapterManager representation of this object.

     */

    MPIMAdapterManager* GetAdapterManager();

public: // new methods

    /**

     * Compares two MPIMItemData objects.

     * Used for determining

     * their ordering in an item enumeration.

     *

     * @param aFirst first object to compare

     * @param aSecond second object to compare

     * @return

     * @li < 0, if aFirst becomes \b before aSecond

     * @li 0, if the objects are equal in the ordering

     * @li > 0, if aFirst becomes \b after aSecond

     */

    static TInt ItemComparisonFunc(const MPIMItem& aFirst,

                                   const MPIMItem& aSecond);

    /**

     * Compares two MPIMItemData objects.

     * Used for determining

     * their ordering in an item enumeration.

     *

     * @param aFirst first object to compare

     * @param aSecond second object to compare

     * @return

     * @li < 0, if aFirst becomes \b before aSecond

     * @li 0, if the objects are equal in the ordering

     * @li > 0, if aFirst becomes \b after aSecond

     */

    static TInt ItemComparisonFuncL(const MPIMItem& aFirst,

                                    const MPIMItem& aSecond);

protected: // New methods

    /**

     * Provides data type of a specific field.

     * @param aField The field to be evaluated.

     * @return Field type.

     */

    TPIMFieldDataType GetFieldDataTypeL(TPIMField aField);

protected:

    /**

     * C++ default constructor.

     */

    CPIMCMAdapterManager();

    /**

     * Symbian 2nd phase constructor

     */

    void ConstructL(const TDesC& aListName);

private: // private methods

    TBool IsSupportedAttributeL(TPIMField aField,

                                TPIMAttribute aAttribute);

    TBool IsSupportedArrayElementL(TPIMField aArrayField,

                                   TPIMArrayElement aElement);

private: // members

    /** List name, owned. The name does not change after initialization. */

    TDesC* iListName;

    // List of supported fields by this adapter, owned.

    CArrayFixFlat<TPIMField>* iSupportedFields;

    // List of attributes for those fields which support no attributes,

    // owned.

    CArrayFixFlat<TPIMAttribute>* iNoAttributes;

    // List of attributes for address and url fields, owned.

    CArrayFixFlat<TPIMAttribute>* iAddrAttributes;

    // List of attributes for the email field, owned.

    CArrayFixFlat<TPIMAttribute>* iEmailAttributes;

    // List of attributes for the tel field, owned.

    CArrayFixFlat<TPIMAttribute>* iTelAttributes;

    // List of supported name array elements, owned.

    CArrayFixFlat<TPIMArrayElement>* iNameElements;

    // List of supported address array elements, owned.

    CArrayFixFlat<TPIMArrayElement>* iAddrElements;

    // List of attributes for the voip field, woned.

    CArrayFixFlat<TPIMAttribute>* iVoipAttributes;

};

#endif // CPIMCMADAPTERMANAGER_H

// End of File