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 event list <-> Agenda Model conversions

    15  *

    16 */

    17 

    18 

    19 #ifndef CPIMEVENTLISTADAPTER_H

    20 #define CPIMEVENTLISTADAPTER_H

    21 

    22 // INCLUDES

    23 #include "mpimeventlistadapter.h"

    24 #include "cpimagnlistadapter.h"

    25 #include "pimexternalchanges.h"

    26 

    27 // FORWARD DECLARATIONS

    28 class MPIMEventItem;

    29 class CPIMAgnEventAdapter;

    30 

    31 // CLASS DECLARATION

    32 

    33 /**

    34  * PIM Event List Adapter class

    35  *

    36  *  Event list adapter creates, reads, writes and removes event items

    37  *  in a native database. See also \ref MPIMListAdapter class description.

    38  */

    39 NONSHARABLE_CLASS(CPIMEventListAdapter): public CPIMAgnListAdapter,

    40         public MPIMEventListAdapter

    41 {

    42 public: // constructor and destructor

    43 

    44     /**

    45      * Two-phased constructor.

    46      */

    47     static CPIMEventListAdapter* NewL(

    48         CCalEntry::TType aEntryType,

    49         CPIMAgnEventAdapter* aEventAdapter,

    50         java::util::FunctionServer* aFuncServer);

    51 

    52     /**

    53      * Destructor.

    54      */

    55     virtual ~CPIMEventListAdapter();

    56 

    57 public: // Overloaded functions from (CPIMAgnListAdapter) MPIMListAdapter

    58 

    59     /**

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

    61      *

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

    63      *         meant to be modified.

    64      *

    65      * @par Leaving:

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

    67      * adapter is non-functional.

    68      */

    69     const CDesCArray& GetCategoriesL();

    70 

    71     /**

    72      * Provides the external changes to the items (entries) in the

    73      * native database. See \ref IsItemsExternallyModified method.

    74      *

    75      * If GetExternalItemModificationsL has never been called, all

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

    77      *

    78      * \b Important: The interpretation of the returned data set

    79      * depends of the status provided by IsItemsExternallyModified():

    80      * @li \c EExternalChangesNone always means that there are no

    81      *     modifications and NULL will be returned.

    82      * @li \c EExternalChangesMinor means that the changes are

    83      *     applied over the existing set of items, reflecting the

    84      *     addition, removal and modification of the database

    85      *     entries.

    86      * @li \c EExternalChangesMajor means that the changes cannot

    87      *     be classified and the whole set of items must be

    88      *     refreshed. All current entries in the database are

    89      *     returned as new entries and it is up to the caller to

    90      *     discard the existing set of items and create new set of

    91      *     items or to deduce which of the given entries are new

    92      *     and which of the existing items have been removed.

    93      *     If any existing items are reused, their data content

    94      *     must be explicitly refreshed.

    95      *

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

    97      *         of the array is transferred to the caller. If no

    98      *         changes are present, \c NULL is returned.

    99      *

   100      * @par Leaving:

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

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

   103      * leaved once, it must always leave.

   104      */

   105     RPointerArray< CPIMItemStateChange>* GetExternalItemModificationsL();

   106 

   107     /**

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

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

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

   111      */

   112     void Close();

   113 

   114 public: // Functions from MPIMToDoListAdapter

   115 

   116     /**

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

   118      * MPIMEventListAdapter object.

   119      *

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

   121      *         list adapter.

   122      */

   123     MPIMListAdapter* GetPimListAdapter();

   124 

   125     /**

   126      * Creates a new event item in the native Agenda File.

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

   128      * according to the data in \a aEventItem, adds it to the Agenda File

   129      * and sets the Item ID of \a aEventItem. \a aEventItem must

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

   131      *

   132      * @param aEventItem The event item to add to the Agenda File.

   133      *

   134      * @par Leaving:

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

   136      * adapter is non-functional.

   137      */

   138     void CreateEventItemL(MPIMEventItem& aEventItem);

   139 

   140     void CPIMEventListAdapter::DoCreateEventItemL(

   141         MPIMEventItem& aEventItem);

   142 

   143     /**

   144      * Reads an existing event item from the Agenda File.

   145      * The adapter maps the Item ID in \a aEventItem to a native Agenda Model

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

   147      * \a aEventItem according to the data in the native entry.

   148      * \a aEventItem must have valid Item ID that corresponds to an

   149      * existing native Agenda File entry.

   150      *

   151      * @param aEventItem The event item to be read from the Agenda File.

   152      *

   153      * @par Leaving:

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

   155      * follows:

   156      * @li \c KErrArgument - The Item ID of \a aEventItem is

   157      *        \ref KPIMNullItemID and thus invalid.

   158      * @li \c KErrNotFound - No corresponding native Agenda File entry could

   159      *        be retrieved, although the Item ID of \a aEventItem is not

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

   161      *        native Agenda File.

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

   163      */

   164     void ReadEventItemL(MPIMEventItem& aEventItem);

   165 

   166     void CPIMEventListAdapter::DoReadEventItemL(

   167         MPIMEventItem& aEventItem);

   168 

   169     /**

   170      * Writes an existing event item to the native Agenda File.

   171      * The adapter maps the Item ID in \a aEventItem to a native Agenda Model

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

   173      * according to the data in \a aEventItem. \a aEventItem must have

   174      * valid Item ID that corresponds to an existing native Agenda Model entry.

   175      *

   176      * @param aEventItem The event item to write to the Agenda File.

   177      *

   178      * @par Leaving:

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

   180      * follows:

   181      * @li \c KErrArgument - The Item ID of \a aEventItem is

   182      *        \ref KPIMNullItemID and thus invalid.

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

   184      *        be retrieved, although the Item ID of \a aEventItem is not

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

   186      *        native Agenda File.

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

   188      *        client. The operation may succeed later.

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

   190      */

   191     void WriteEventItemL(MPIMEventItem& aEventItem);

   192 

   193     void CPIMEventListAdapter::DoWriteEventItemL(

   194         MPIMEventItem& aEventItem);

   195 

   196     /**

   197      * Removes an existing event from the native Agenda File.

   198      * The adapter maps \a aItemID to a native Agenda Model entry and removes

   199      * it.

   200      *

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

   202      *

   203      * @par Leaving:

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

   205      *        invalid.

   206      * @li \c KErrNotFound - No native Agenda Model entry could be retrieved

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

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

   209      *        client. The operation may succeed later.

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

   211      */

   212     void RemoveEventItemL(TPIMItemID aItemID);

   213 

   214     void CPIMEventListAdapter::DoRemoveEventItemL(

   215         TPIMItemID aItemID);

   216 

   217 protected:

   218 

   219     /**

   220      * C++ default constructor.

   221      */

   222     CPIMEventListAdapter(java::util::FunctionServer* aFuncServer);

   223 

   224     /**

   225      * By default Symbian 2nd phase constructor is private.

   226      */

   227     void ConstructL(

   228         CCalEntry::TType aEntryType,

   229         CPIMAgnEventAdapter* aEventAdapter);

   230 

   231 private: // Member data

   232 

   233     CPIMAgnEventAdapter* iAgnAdapter;

   234     CDesCArrayFlat* iEventCategoryArray;

   235     CCalEntry::TType iEntryType;

   236 

   237 };

   238 

   239 #endif // CPIMEVENTLISTADAPTER_H

   240 // End of File