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

    15  *                contact list adapters.

    16  *

    17 */

    18 

    19 

    20 #ifndef CPIMCMADAPTERMANAGER_H

    21 #define CPIMCMADAPTERMANAGER_H

    22 

    23 //  INCLUDES

    24 #include "mpimcontactadaptermanager.h"

    25 #include "mpimadaptermanager.h"

    26 #include "pimcontact.h" // field enums

    27 #include "pimcommon.h" // basic types

    28 #include <e32base.h>

    29 

    30 // CONSTANTS

    31 

    32 

    33 const TPIMField KPIMSupportedFields[] =

    34 {

    35     EPIMContactPhoto,

    36     EPIMContactName,

    37     EPIMContactNickname,

    38     EPIMContactTel,

    39     EPIMContactEmail,

    40     EPIMContactExtDtmf,

    41     EPIMContactExtVoip,

    42     EPIMContactExtPTT,

    43     EPIMContactExtSWIS,

    44     EPIMContactExtSip,

    45     EPIMContactOrg,

    46     EPIMContactExtDepartment,

    47     EPIMContactTitle,

    48     EPIMContactExtAssistantName,

    49     EPIMContactExtSpouse,

    50     EPIMContactExtChildren,

    51     EPIMContactUrl,

    52     EPIMContactAddr,

    53     EPIMContactBirthday,

    54     EPIMContactExtAnniversary,

    55     EPIMContactNote,

    56     EPIMContactClass,

    57     EPIMContactExtWvUserId,

    58     EPIMContactUid,

    59     EPIMContactRevision

    60 };

    61 

    62 /**

    63  * Number of supported Contact fields by S60 platform

    64  */

    65 const TInt KPIMSupportedFieldsCount = sizeof(KPIMSupportedFields)

    66                                       / sizeof(TPIMField);

    67 

    68 /**

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

    70  *

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

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

    73  * constant values.

    74  *

    75  * See @ref KPIMContactMaxValueMappingOffset.

    76  */

    77 const TInt KPIMMaxValues[] =

    78 {

    79     3, // address

    80     1, // birthday

    81     1, // class

    82     KPIMUnlimitedValues, // email

    83     0, // formatted address

    84     0, // formatted name

    85     1, // name

    86     1, // nickname

    87     KPIMUnlimitedValues, // note

    88     1, // org

    89     1, // photo

    90     0, // photo url

    91     0, // public key

    92     0, // public key string

    93     1, // revision

    94     KPIMUnlimitedValues, // tel

    95     KPIMUnlimitedValues, // title

    96     1, // uid

    97     KPIMUnlimitedValues // url

    98 };

    99 

   100 /**

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

   102  *

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

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

   105  * from the field constant values.

   106  *

   107  * See @ref KPIMContactMaxExtValueMappingOffset.

   108  */

   109 const TInt KPIMMaxExtValues[] =

   110 {

   111     1, // Extended WV User ID

   112     KPIMUnlimitedValues, // Extended SIP

   113     KPIMUnlimitedValues, // Extended DTMF

   114     1, // Extended Department

   115     1, // Extended Assistant name

   116     1, // Extended Children

   117     1, // Extended Spouse

   118     1, // Extended Anniversary

   119     KPIMUnlimitedValues, // Extended VOIP

   120     KPIMUnlimitedValues, // Extended PTT

   121     KPIMUnlimitedValues // Extended SWIS

   122 };

   123 

   124 /**

   125  * Smallest Contact standard field constant.

   126  */

   127 const TInt KPIMContactSmallestField = 100;

   128 

   129 /**

   130  * Largest Contact standard field constant.

   131  */

   132 const TInt KPIMContactLargestField = 118;

   133 

   134 /**

   135  * The offset for mapping Contact standard field constant values to

   136  * elements in @ref KPIMMaxValues table.

   137  */

   138 const TInt KPIMContactMaxValueMappingOffset = 100;

   139 

   140 /**

   141  * Smallest Contact extended field constant.

   142  */

   143 const TInt KPIMContactSmallestExtField = 0x1005001;

   144 

   145 /**

   146  * Largest Contact extended field constant.

   147  */

   148 const TInt KPIMContactLargestExtField = 0x100500B;

   149 /**

   150  * The offset for mapping Contact extended field constant values to

   151  * elements in @ref KPIMMaxExtValues table.

   152  */

   153 const TInt KPIMContactMaxExtValueMappingOffset = 0x1005001;

   154 

   155 /**

   156  * Number of Contact fields in PIM API.

   157  */

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

   159                             + sizeof(KPIMMaxExtValues) / sizeof(TInt);

   160 

   161 // Supported ADDR attributes

   162 const TPIMAttribute KPIMAddrAttributes[] =

   163 {

   164     EPIMContactAttrHome,

   165     EPIMContactAttrWork

   166 };

   167 

   168 const TPIMAttribute KPIMAddrAttributesCombined = (EPIMContactAttrWork

   169         | EPIMContactAttrHome);

   170 

   171 const TInt KPIMAddrAttributeCount = sizeof(KPIMAddrAttributes)

   172                                     / sizeof(TPIMAttribute);

   173 

   174 // Supported EMAIL attributes

   175 const TPIMAttribute KPIMEmailAttributes[] =

   176 {

   177     EPIMContactAttrHome,

   178     EPIMContactAttrWork,

   179     EPIMContactAttrPreferred

   180 };

   181 

   182 const TPIMAttribute KPIMEmailAttributesCombined = (EPIMContactAttrHome

   183         | EPIMContactAttrWork | EPIMContactAttrPreferred);

   184 

   185 const TInt KPIMEmailAttributeCount = sizeof(KPIMEmailAttributes)

   186                                      / sizeof(TPIMAttribute);

   187 

   188 // Supported TEL attributes

   189 const TPIMAttribute KPIMTelAttributes[] =

   190 {

   191     EPIMContactAttrHome,

   192     EPIMContactAttrWork,

   193     EPIMContactAttrMobile,

   194     EPIMContactAttrAuto,

   195     EPIMContactAttrExtVideoCall,

   196     EPIMContactAttrFax,

   197     EPIMContactAttrPager,

   198     EPIMContactAttrPreferred,

   199     EPIMContactAttrSms,

   200     EPIMContactAttrAsst,

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

   202 };

   203 

   204 const TPIMAttribute KPIMTelAttributesCombined = (EPIMContactAttrHome

   205         | EPIMContactAttrWork | EPIMContactAttrMobile | EPIMContactAttrAuto

   206         | EPIMContactAttrExtVideoCall | EPIMContactAttrFax

   207         | EPIMContactAttrPager | EPIMContactAttrPreferred | EPIMContactAttrSms

   208         | EPIMContactAttrAsst | EPIMContactAttrOther);

   209 

   210 const TInt KPIMTelAttributeCount = sizeof(KPIMTelAttributes)

   211                                    / sizeof(TPIMAttribute);

   212 

   213 // Note: These are only the supported elements

   214 const TPIMArrayElement KPIMNameElements[] =

   215 {

   216     EPIMContactNamePrefix,

   217     EPIMContactNameGiven,

   218     EPIMContactExtGivenNameReading,

   219     EPIMContactNameOther,

   220     EPIMContactNameFamily,

   221     EPIMContactExtFamilyNameReading,

   222     EPIMContactNameSuffix

   223 };

   224 

   225 const TInt KPIMNameElementCount = sizeof(KPIMNameElements)

   226                                   / sizeof(TPIMArrayElement);

   227 

   228 const TInt KPIMNameArraySize = EPIMContactNameNumElements;

   229 

   230 // Note: All elements are currently supported

   231 const TInt KPIMAddrElementCount = EPIMContactAddrNumElements;

   232 

   233 const TPIMArrayElement KPIMAddrElements[KPIMAddrElementCount] =

   234 {

   235     EPIMContactAddrPoBox,

   236     EPIMContactAddrExtra,

   237     EPIMContactAddrStreet,

   238     EPIMContactAddrPostalCode,

   239     EPIMContactAddrLocality,

   240     EPIMContactAddrRegion,

   241     EPIMContactAddrCountry

   242 };

   243 

   244 // Supported VOIP attributes

   245 const TPIMAttribute KPIMVoipAttributes[] =

   246 {

   247     EPIMContactAttrHome,

   248     EPIMContactAttrWork,

   249     EPIMContactAttrPreferred

   250 };

   251 

   252 const TInt KPIMVoipAttributeCount = sizeof(KPIMVoipAttributes)

   253                                     / sizeof(TPIMAttribute);

   254 

   255 // FORWARD DECLARATIONS

   256 class MPIMItem;

   257 

   258 // CLASS DECLARATION

   259 

   260 /**

   261  * This class provides access to the PIM Contacts Model list

   262  */

   263 

   264 NONSHARABLE_CLASS(CPIMCMAdapterManager): public CBase,

   265         public MPIMContactAdapterManager,

   266         public MPIMAdapterManager

   267 {

   268 public: // Constructors and a destructor

   269 

   270     /**

   271      * Two-phased constructor.

   272      *

   273      * @param aListName List name.

   274      */

   275     static CPIMCMAdapterManager* NewL(const TDesC& aListName);

   276 

   277     /**

   278      * destructor

   279      */

   280     ~CPIMCMAdapterManager();

   281 

   282 public: // MPIMAdapterManager

   283 

   284     const TDesC& ListNameL();

   285 

   286     /**

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

   288      * @return Number of maximum supported categories .

   289      */

   290     TInt MaxCategories();

   291 

   292     /**

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

   294      * @param aField The field to be checked.

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

   296      */

   297     TBool IsSupportedField(TPIMField aField);

   298 

   299     /**

   300      * Provides all fields supported by the list adapter.

   301      *

   302      * @return An array containing all supported fields.

   303      *

   304      * @par Leaving:

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

   306      * is non-functional.

   307      */

   308     const CArrayFix<TPIMField>& GetSupportedFieldsL();

   309 

   310     /**

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

   312      * @param aAttribute The attribute to be checked.

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

   314      */

   315     TBool IsSupportedAttribute(TPIMField aField,

   316                                TPIMAttribute aAttribute);

   317 

   318     /**

   319      * Provides all attributes supported by the list adapter.

   320      *

   321      * @return An array containing all supported attributes.

   322      *

   323      * @par Leaving:

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

   325      * is non-functional.

   326      */

   327     const CArrayFix<TPIMAttribute>& GetSupportedAttributesL(

   328         TPIMField aField);

   329 

   330     /**

   331      * Provides attributes supported for a field, combined into single

   332      * integer value.

   333      *

   334      * @param aField The field to which the attributes are associated with.

   335      *

   336      * @return An integer holding the combination of all attributes

   337      *         supported for \a aField.

   338      *

   339      * @par Leaving.

   340      * The method leaves on error. Error codes should be interpreted as

   341      * follows:

   342      * @li \c KErrArgument - \a aField is not valid.

   343      */

   344     TPIMAttribute GetSupportedAttributesCombinedL(

   345         TPIMField aField);

   346 

   347     /**

   348      * Provides all attributes supported for all fields, combined into

   349      * single integer value.

   350      *

   351      * @return An integer holding the combination of all attributes

   352      *         supported for all fields.

   353      */

   354     TPIMAttribute GetAllSupportedAttributesCombined();

   355 

   356     /**

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

   358      * @param aArrayElement The array element to be checked.

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

   360      */

   361     TBool IsSupportedArrayElement(TPIMField aStringArrayField,

   362                                   TPIMArrayElement aArrayElement);

   363 

   364     /**

   365      * Provides all array elements supported by the list adapter.

   366      *

   367      * @return An array containing all supported array elements.

   368      *

   369      * @par Leaving:

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

   371      * is non-functional.

   372      */

   373     const CArrayFix<TPIMArrayElement>& GetSupportedArrayElementsL(

   374         TPIMField aStringArrayField);

   375 

   376     /**

   377      * Provides the number of maximum values supported for a specific field.

   378      * @param aField The field to be evaluated.

   379      * @return Number of values supported for the field.

   380      */

   381     TInt MaxValues(TPIMField aField);

   382 

   383     /**

   384      * Provides the array size of a specific string array field.

   385      * The values in a string array field are arrays themselves.

   386      * StringArraySize method returns the number of elements in every value

   387      * of the field.

   388      *

   389      * @param aStringArrayField The string array field to be evaluated.

   390      * @return Number of elements in a single string array value.

   391      *

   392      * @par Leaving:

   393      * The method leaves with \c KErrArgument if \a aStringArrayField

   394      * is not a string array field.

   395      */

   396     TInt StringArraySizeL(TPIMField aStringArrayField);

   397 

   398     /**

   399      * Provides pointer to a function which implements an algorithm that

   400      * determines the order of two items.

   401      *

   402      * @return Item comparison function.

   403      */

   404     TPIMItemComparisonFunc ItemOrder();

   405 

   406 public: // MPIMContactAdapterManager

   407 

   408     /**

   409      * Provides access to the \ref MPIMAdapterManager representation of

   410      * this object.

   411      *

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

   413      */

   414     MPIMAdapterManager* GetAdapterManager();

   415 

   416 public: // new methods

   417 

   418     /**

   419      * Compares two MPIMItemData objects.

   420      * Used for determining

   421      * their ordering in an item enumeration.

   422      *

   423      * @param aFirst first object to compare

   424      * @param aSecond second object to compare

   425      * @return

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

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

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

   429      */

   430     static TInt ItemComparisonFunc(const MPIMItem& aFirst,

   431                                    const MPIMItem& aSecond);

   432 

   433     /**

   434      * Compares two MPIMItemData objects.

   435      * Used for determining

   436      * their ordering in an item enumeration.

   437      *

   438      * @param aFirst first object to compare

   439      * @param aSecond second object to compare

   440      * @return

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

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

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

   444      */

   445     static TInt ItemComparisonFuncL(const MPIMItem& aFirst,

   446                                     const MPIMItem& aSecond);

   447 

   448 protected: // New methods

   449 

   450     /**

   451      * Provides data type of a specific field.

   452      * @param aField The field to be evaluated.

   453      * @return Field type.

   454      */

   455     TPIMFieldDataType GetFieldDataTypeL(TPIMField aField);

   456 

   457 protected:

   458     /**

   459      * C++ default constructor.

   460      */

   461     CPIMCMAdapterManager();

   462 

   463     /**

   464      * Symbian 2nd phase constructor

   465      */

   466     void ConstructL(const TDesC& aListName);

   467 

   468 private: // private methods

   469     TBool IsSupportedAttributeL(TPIMField aField,

   470                                 TPIMAttribute aAttribute);

   471     TBool IsSupportedArrayElementL(TPIMField aArrayField,

   472                                    TPIMArrayElement aElement);

   473 

   474 private: // members

   475 

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

   477     TDesC* iListName;

   478 

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

   480     CArrayFixFlat<TPIMField>* iSupportedFields;

   481 

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

   483     // owned.

   484     CArrayFixFlat<TPIMAttribute>* iNoAttributes;

   485 

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

   487     CArrayFixFlat<TPIMAttribute>* iAddrAttributes;

   488 

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

   490     CArrayFixFlat<TPIMAttribute>* iEmailAttributes;

   491 

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

   493     CArrayFixFlat<TPIMAttribute>* iTelAttributes;

   494 

   495     // List of supported name array elements, owned.

   496     CArrayFixFlat<TPIMArrayElement>* iNameElements;

   497 

   498     // List of supported address array elements, owned.

   499     CArrayFixFlat<TPIMArrayElement>* iAddrElements;

   500 

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

   502     CArrayFixFlat<TPIMAttribute>* iVoipAttributes;

   503 

   504 };

   505 

   506 #endif // CPIMCMADAPTERMANAGER_H

   507 // End of File