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:  Handles PIM contact list <-> Contacts Model conversions

    15  *

    16 */

    17 

    18 

    19 #ifndef CPIMCONTACTLISTADAPTER_H

    20 #define CPIMCONTACTLISTADAPTER_H

    21 

    22 // INTERNAL INCLUDES

    23 #include "mpimcontactlistadapter.h"

    24 #include "mpimlistadapter.h"

    25 #include "pimexternalchanges.h"

    26 

    27 // EXTERNAL INCLUDES

    28 #include <cntdef.h>         // TContactItemId

    29 #include <cntdbobs.h>       // MContactDbObserver

    30 #include <e32base.h>

    31 #include <badesca.h>

    32 

    33 // FORWARD DECLARATIONS

    34 class CPIMContactCategoryManager;

    35 class CPIMContactItemAdapter;

    36 class CContactDatabase;

    37 class CContactChangeNotifier;

    38 class CContactItemViewDef;

    39 class CContactGroup;

    40 class CCntFilter;

    41 

    42 // CLASS DECLARATION

    43 

    44 /**

    45  * Contact List Adapter

    46  * Manages Contact Items and Categories in Contacts Model.

    47  */

    48 NONSHARABLE_CLASS(CPIMContactListAdapter): public CBase,

    49         public MContactDbObserver,

    50         //public MContactViewObserver,

    51         public MPIMListAdapter,

    52         public MPIMContactListAdapter

    53 {

    54 public: // Constructor and destructor

    55 

    56     /**

    57      * Two-phased constructor.

    58      */

    59     static CPIMContactListAdapter* NewL(java::util::FunctionServer* aFuncServer);

    60 

    61     /**

    62      * Destructor.

    63      */

    64     ~CPIMContactListAdapter();

    65 

    66 public: // MContactDbObserver

    67 

    68     /**

    69      * Tests the contact database observer event type and handles it

    70      *

    71      * @param aEvent Provides information about the change event.

    72      */

    73     void HandleDatabaseEventL(TContactDbObserverEvent aEvent);

    74 

    75 

    76 public: // MPIMListAdapter

    77 

    78 

    79     /**

    80      * Provides all categories currently existing in the native database.

    81      *

    82      * @return Array of categories. The contents of the array are not

    83      *         meant to be modified. The contents of the array may change

    84      *         whenever any category related method is called.

    85      *

    86      * @par Leaving:

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

    88      * adapter is non-functional.

    89      */

    90     const CDesCArray& GetCategoriesL();

    91 

    92     /**

    93      * Adds a new category to the native database. If the category already

    94      * exists, nothing is done and the method returns successfully.

    95      *

    96      * @param aNewCategory The name of the category to be added.

    97      *

    98      * @par Leaving:

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

   100      * follows:

   101      * @li \c KErrArgument - \a aNewCategory is invalid.

   102      * @li Other - The list adapter is non-functional.

   103      */

   104     void AddCategoryL(const TDesC& aNewCategory);

   105 

   106     /**

   107      * Deletes an existing category. If there is no such category, nothing

   108      * is done and the method returns successfully.

   109      *

   110      * @param aCategory The category to be deleted.

   111      *

   112      * @par Leaving:

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

   114      * follows:

   115      * @li \c KErrNotFound - \a aCategory is invalid.

   116      * @li Other - The list adapter is non-functional.

   117      */

   118     void DeleteCategoryL(const TDesC& aCategory);

   119 

   120     /**

   121      * Renames an existing category. Entries in the old category are moved

   122      * to the new category.

   123      *

   124      * @param aOldCategory The old category name.

   125      * @param aNewCategory The new category name.

   126      *

   127      * @par Leaving:

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

   129      * follows:

   130      * @li \c KErrArgument - \a aNewCategory is invalid.

   131      * @li \c KErrNotFound - \a aOldCategory does not exist.

   132      * @li Other - The list adapter is non-functional.

   133      */

   134     void RenameCategoryL(const TDesC& aOldCategory, const TDesC& aNewCategory);

   135 

   136     /**

   137      * Checks whether there have been external changes to the categories in

   138      * the native database after last call to

   139      * \ref GetExternalCategoryModifications or list adapter creation.

   140      *

   141      * @return ETrue if there are any external changes, EFalse otherwise.

   142      */

   143     TBool IsCategoriesExternallyModified();

   144 

   145     /**

   146      * Provides the external changes to the categories in the native

   147      * database. See \ref IsCategoriesExternallyModified method.

   148      *

   149      * @return An array of category state change objects. The \b ownership

   150      *         of the array is transferred to the caller. Note that the

   151      *         array elements contain heap-allocated data.

   152      *

   153      * @par Leaving:

   154      * The method leaves with \c KErrCorrupt if updating the list of

   155      * external modifications has failed at some point. If the method has

   156      * leaved once, it must always leave.

   157      */

   158     RPointerArray<CPIMCategoryStateChange>*

   159     GetExternalCategoryModificationsL();

   160 

   161     /**

   162      * Checks whether there have been external changes to the items

   163      * (or entries) in the native database after last call to

   164      * GetExternalItemModificationsL() or list adapter creation.

   165      *

   166      * If GetExternalItemModificationsL() has never been called, all

   167      * entries in the native database are considered to be new.

   168      *

   169      * See GetExternalItemModificationsL().

   170      *

   171      * @return \c EExternalChangesNone if there are no changes;

   172      *         \c EExternalChangesMinor if there are changes that

   173      *         can be classified to new, removed or modified;

   174      */

   175     MPIMListAdapter::TExternalItemChangeClass IsItemsExternallyModified();

   176 

   177     /**

   178      * Provides the external changes to the items (or entries) in the

   179      * native database. See \ref IsItemsExternallyModified method.

   180      *

   181      * @return An array of item state change objects. The \b ownership

   182      *         of the array is transferred to the caller.

   183      *

   184      * @par Leaving:

   185      * The method leaves with \c KErrCorrupt if updating the list of

   186      * external modifications has failed at some point. If the method has

   187      * leaved once, it must always leave.

   188      */

   189     RPointerArray< CPIMItemStateChange>* GetExternalItemModificationsL();

   190 

   191     /**

   192      * Used to inform the list adapter that the list has been closed. The

   193      * list adapter may then release all resources it has reserved.

   194      * No method of the list adapter can be invoked after call to Close.

   195      */

   196     void Close();

   197 

   198     void CPIMContactListAdapter::DoClose();

   199 

   200 public: // MPIMContactListAdapter

   201 

   202     /**

   203      * Provides access to the \ref MPIMListAdapter representation of this

   204      * MPIMContactListAdapter object.

   205      *

   206      * @return The \ref MPIMListAdapter representation of the specialized

   207      *         list adapter.

   208      */

   209     MPIMListAdapter* GetPimListAdapter();

   210 

   211     /**

   212      * Creates a new contact item (entry) in the native database.

   213      * The adapter creates a new native database entry, sets its data

   214      * according to the data in \a aContactItem, adds it to the database

   215      * and sets the Item ID of \a aContactItem. \a aContactItem must

   216      * contain valid data and have Item ID \ref KPIMNullItemID.

   217      *

   218      * @param aContactItem The contact item to add to the database.

   219      *

   220      * @par Leaving:

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

   222      * adapter is non-functional.

   223      */

   224     void CreateContactItemL(MPIMContactItem& aContactItem);

   225 

   226     void CPIMContactListAdapter::DoCreateContactItemL(

   227         MPIMContactItem& aContactItem);

   228 

   229     /**

   230      * Reads an existing contact item from the native database.

   231      * The adapter maps the Item ID in \a aContactItem to a native database

   232      * entry identifier, reads the entry and sets the data of

   233      * \a aContactItem according to the data in the native entry.

   234      * \a aContactItem must have valid Item ID that corresponds to an

   235      * existing native database entry.

   236      *

   237      * @param aContactItem The contact item to be read from the database.

   238      *

   239      * @par Leaving:

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

   241      * follows:

   242      * @li \c KErrArgument - The Item ID of \a aContactItem is

   243      *        \ref KPIMNullItemID and thus invalid.

   244      * @li \c KErrNotFound - No corresponding native database entry could

   245      *        be retrieved, although the Item ID of \a aContactItem is not

   246      *        \ref KPIMNullItemID. The entry is probably removed from the

   247      *        native database.

   248      * @li Other - The list adapter is non-functional.

   249      */

   250     void ReadContactItemL(MPIMContactItem& aContactItem);

   251 

   252     void CPIMContactListAdapter::DoCallReadContactItemL(

   253         MPIMContactItem& aContactItem);

   254 

   255     /**

   256      * Reads an existing contact item from the native database

   257      * This version reads only minimal contact item data and should be used

   258      * when listing contacts through the API. Contacts Model view definition

   259      * is used to read items with this function

   260      *

   261      * @param aContactItem The contat item to be read from the database

   262      *

   263      * @par Leaving:

   264      * The methods leaves on error. Error codes should be interpreted as

   265      * follows:

   266      * @li \c KErrArgument - The Item ID of \a aContactItem is

   267      *        \ref KPIMNullItemID and thus invalid.

   268      * @li \c KErrNotFound - No corresponding native database entry could

   269      *        be retrieved, although the Item ID of \a aContactItem is not

   270      *        \ref KPIMNullItemID. The entry is probably removed from the

   271      *        native database.

   272      * @li Other - The list adapter is non-functional.

   273      */

   274     void ReadMinimalContactItemL(

   275         MPIMContactItem& aContactItem);

   276 

   277     void CPIMContactListAdapter::DoCallReadMinimalContactItemL(

   278         MPIMContactItem& aContactItem);

   279 

   280     /**

   281      * Reads an existing contact item from the native database

   282      * This version reads only minimal contact item data and should be used

   283      * when listing contacts through the API. This version takes a matching

   284      * item as a parameter which defines which fields are to be retrieved

   285      * from the native database. The fields include minimal fields also,

   286      * currently name array elements.

   287      *

   288      * @param aContactItem The contact item to be read from the database

   289      * @param aMatchingContactitem A contact which gives information which

   290      *        fields are to be retrieved from the native database

   291      *

   292      * @par Leaving:

   293      * The methods leaves on error. Error codes should be interpreted as

   294      * follows:

   295      * @li \c KErrArgument - The Item ID of \a aContactItem is

   296      *        \ref KPIMNullItemID and thus invalid.

   297      * @li \c KErrNotFound - No corresponding native database entry could

   298      *        be retrieved, although the Item ID of \a aContactItem is not

   299      *        \ref KPIMNullItemID. The entry is probably removed from the

   300      *        native database.

   301      * @li Other - The list adapter is non-functional.

   302      */

   303     void ReadMinimalContactItemL(

   304         MPIMContactItem& aContactItem,

   305         const MPIMContactItem& aMatchingContactItem);

   306 

   307     /**

   308      * Reads one field from the contact database and adds it to the

   309      * item. New view definition is used to filter the database

   310      *

   311      * @param aContactItem The contact item where the data is added

   312      * @param aContactField The contact fields which is to be read

   313      *        from the database

   314      */

   315     void ReadContactFieldL(MPIMContactItem& aContactItem,

   316                            TPIMContactField aContactField);

   317 

   318     void CPIMContactListAdapter::DoReadContactFieldL(

   319         MPIMContactItem& aContactItem,

   320         TPIMContactField aContactField);

   321 

   322     /**

   323      * Writes an existing contact item to the native database.

   324      * The adapter maps the Item ID in \a aContactItem to a native database

   325      * entry identifier, reads the entry and sets the data of the entry

   326      * according to the data in \a aContactItem. \a aContactItem must have

   327      * valid Item ID that corresponds to an existing native database entry.

   328      *

   329      * @param aContactItem The contact item to write to the database.

   330      *

   331      * @par Leaving:

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

   333      * follows:

   334      * @li \c KErrArgument - The Item ID of \a aContactItem is

   335      *        \ref KPIMNullItemID and thus invalid.

   336      * @li \c KErrNotFound - No corresponding native database entry could

   337      *        be retrieved, although the Item ID of \a aContactItem is not

   338      *        \ref KPIMNullItemID. The entry is probably removed from the

   339      *        native database.

   340      * @li \c KErrInUse - The entry is currently in use by some other

   341      *        client. The operation may succeed later.

   342      * @li Other - The list adapter is non-functional.

   343      */

   344     void WriteContactItemL(MPIMContactItem& aContactItem);

   345 

   346     void CPIMContactListAdapter::DoWriteContactItemL(

   347         MPIMContactItem& aContactItem);

   348 

   349     /**

   350      * Removes an existing contact from the native database.

   351      * The adapter maps \a aItemID to a native database entry and removes

   352      * it.

   353      *

   354      * @param aItemID Item ID of the item to be removed.

   355      *

   356      * @par Leaving:

   357      * @li \c KErrArgument - \a aItemID is \ref KPIMNullItemID and thus

   358      *        invalid.

   359      * @li \c KErrNotFound - No native database entry could be retrieved

   360      *        by \a aItemID. The entry is probably already removed.

   361      * @li \c KErrInUse - The entry is currently in use by some other

   362      *        client. The operation may succeed later.

   363      * @li Other - The list adapter is non-functional.

   364      */

   365     void RemoveContactItemL(TPIMItemID aItemID);

   366 

   367 private:

   368 

   369     /**

   370      * C++ default constructor.

   371      */

   372     CPIMContactListAdapter(java::util::FunctionServer* aFuncServer);

   373 

   374     /**

   375      * Symbian 2nd phase constructor.

   376      */

   377     void ConstructL();

   378 

   379     /**

   380      * Adds an entry to external category change list.

   381      * Also causes the category cache to be flushed.

   382      *

   383      * @param aId Id of the changed category

   384      * @param aType type of the change

   385      */

   386     void ExternalGroupChangeL(TContactItemId aId,

   387                               TPIMExternalChangeType aType);

   388 

   389     /**

   390      * Adds an entry to external item change list.

   391      *

   392      * @param aId Id of the changed item

   393      * @param aType type of the change

   394      */

   395     void ExternalItemChangeL(TContactItemId aId,

   396                              TPIMExternalChangeType aType);

   397 

   398     /**

   399      * Filters all contact items from the database to the item changes list.

   400      */

   401     void FilterAllContactsL();

   402 

   403     /**

   404      * Initialized minimal view definition to include

   405      * requested fields when item is loaded from the native database

   406      */

   407     void InitializeMinimalViewDefinitionL();

   408 

   409     /**

   410      * Reads a contact item from the contacts database using specified

   411      * item view definition. The item must be associated with a list

   412      * (i.e it has to have an item id which is not zero)

   413      *

   414      * @param aContactItem PIM Contact item to which the data is read

   415      * @param aContactItemViewDef View definition which is used for

   416      *        reading the contact item from the database

   417      */

   418     void CPIMContactListAdapter::DoReadContactItemL(

   419         MPIMContactItem& aContactItem,

   420         const CContactItemViewDef& aContactItemViewDef);

   421 

   422     void IsDatabaseReadyL();

   423 

   424     void DoRemoveContactItemL(TPIMItemID aItemID);

   425 

   426 private: // Data

   427 

   428     // Contacts Model database used for storing contact data, owned.

   429     CContactDatabase* iDatabase;

   430 

   431     // Notifies ContactListAdapter about changes in the database, owned.

   432     CContactChangeNotifier* iNotifier;

   433 

   434     // Handles categories, owned.

   435     CPIMContactCategoryManager* iCategoryManager;

   436 

   437     // Converts between PIM items <--> Contacts Model items, owned.

   438     CPIMContactItemAdapter* iItemAdapter;

   439 

   440     // View Definitions. Owned

   441     CContactItemViewDef* iMinimalFieldsViewDef;

   442 

   443     // Active scheduler wait for waiting remote view initialization

   444     // This class can be used as a data member, see definition of

   445     // CActiveSchedulerWait

   446     CActiveSchedulerWait iWait;

   447 

   448     // Array of unqueried category changes in the database, owned.

   449     // When the ownership is given away, this pointer is chaned to NULL.

   450     RPointerArray<CPIMCategoryStateChange>* iCategoryChanges;

   451 

   452     // Array of unqueried item changes in the database, owned.

   453     // When the ownership is given away, this pointer is chaned to NULL.

   454     RPointerArray< CPIMItemStateChange>* iItemChanges;

   455 

   456     // Have item changes been queried or not

   457     TBool iFirstItemChanges;

   458 

   459     java::util::FunctionServer* iFuncServer;

   460 

   461 };

   462 

   463 #endif // CPIMCONTACTLISTADAPTER_H

   464 // End of File