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

    15  *

    16 */

    17 

    18 

    19 #ifndef CPIMTODOLISTADAPTER_H

    20 #define CPIMTODOLISTADAPTER_H

    21 

    22 // INCLUDES

    23 #include "mpimtodolistadapter.h"

    24 #include "cpimagnlistadapter.h"

    25 #include "pimexternalchanges.h"

    26 

    27 // FORWARD DECLARATIONS

    28 class MPIMToDoItem;

    29 class CPIMAgnToDoAdapter;

    30 

    31 // CLASS DECLARATION

    32 

    33 /**

    34  * PIM ToDo List Adapter class

    35  *

    36  *  To-do list adapter creates, reads, writes and removes to-do items

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

    38  */

    39 NONSHARABLE_CLASS(CPIMToDoListAdapter): public CPIMAgnListAdapter,

    40         public MPIMToDoListAdapter

    41 {

    42 public: // Constructor and destructor

    43 

    44     /**

    45      * Two-phased constructor.

    46      */

    47     static CPIMToDoListAdapter* NewL(java::util::FunctionServer* aFuncServer);

    48 

    49     /**

    50      * Destructor.

    51      */

    52     ~CPIMToDoListAdapter();

    53 

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

    55 

    56     /**

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

    58      *

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

    60      *         meant to be modified.

    61      *

    62      * @par Leaving:

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

    64      * adapter is non-functional.

    65      */

    66     const CDesCArray& GetCategoriesL();

    67 

    68     /**

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

    70      * native database. See \ref IsItemsExternallyModified method.

    71      *

    72      * If GetExternalItemModificationsL has never been called, all

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

    74      *

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

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

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

    78      *     modifications and NULL will be returned.

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

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

    81      *     addition, removal and modification of the database

    82      *     entries.

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

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

    85      *     refreshed. All current entries in the database are

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

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

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

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

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

    91      *     must be explicitly refreshed.

    92      *

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

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

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

    96      *

    97      * @par Leaving:

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

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

   100      * leaved once, it must always leave.

   101      */

   102     RPointerArray< CPIMItemStateChange>* GetExternalItemModificationsL();

   103 

   104     /**

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

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

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

   108      */

   109     void Close();

   110 

   111 public: // Functions from MPIMToDoListAdapter

   112 

   113     /**

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

   115      * MPIMToDoListAdapter object.

   116      *

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

   118      *         list adapter.

   119      */

   120     MPIMListAdapter* GetPimListAdapter();

   121 

   122     /**

   123      * Creates a new To-Do item in the native Agenda File.

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

   125      * according to the data in \a aToDoItem, adds it to the Agenda File

   126      * and sets the Item ID of \a aToDoItem. \a aToDoItem must

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

   128      *

   129      * @param aToDoItem The To-Do item to add to the Agenda File.

   130      *

   131      * @par Leaving:

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

   133      * adapter is non-functional.

   134      */

   135     void CreateToDoItemL(MPIMToDoItem& aToDoItem);

   136 

   137     void CPIMToDoListAdapter::DoCreateToDoItemL(

   138         MPIMToDoItem& aToDoItem);

   139 

   140     /**

   141      * Reads an existing To-Do item from the Agenda File.

   142      * The adapter maps the Item ID in \a aToDoItem to a native Agenda Model

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

   144      * \a aToDoItem according to the data in the native entry.

   145      * \a aToDoItem must have valid Item ID that corresponds to an

   146      * existing native Agenda File entry.

   147      *

   148      * @param aToDoItem The To-Do item to be read from the Agenda File.

   149      *

   150      * @par Leaving:

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

   152      * follows:

   153      * @li \c KErrArgument - The Item ID of \a aToDoItem is

   154      *        \ref KPIMNullItemID and thus invalid.

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

   156      *        be retrieved, although the Item ID of \a aToDoItem is not

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

   158      *        native Agenda File.

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

   160      */

   161     void ReadToDoItemL(MPIMToDoItem& aToDoItem);

   162 

   163     void CPIMToDoListAdapter::DoReadToDoItemL(

   164         MPIMToDoItem& aToDoItem);

   165 

   166     /**

   167      * Writes an existing To-Do item to the native Agenda File.

   168      * The adapter maps the Item ID in \a aToDoItem to a native Agenda Model

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

   170      * according to the data in \a aToDoItem. \a aToDoItem must have valid

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

   172      *

   173      * @param aToDoItem The To-Do item to write to the Agenda File.

   174      *

   175      * @par Leaving:

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

   177      * follows:

   178      * @li \c KErrArgument - The Item ID of \a aToDoItem is

   179      *        \ref KPIMNullItemID and thus invalid.

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

   181      *        be retrieved, although the Item ID of \a aToDoItem is not

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

   183      *        native Agenda File.

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

   185      *        client. The operation may succeed later.

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

   187      */

   188     void WriteToDoItemL(MPIMToDoItem& aToDoItem);

   189 

   190     void CPIMToDoListAdapter::DoWriteToDoItemL(

   191         MPIMToDoItem& aToDoItem);

   192 

   193     /**

   194      * Removes an existing To-Do from the native Agenda File.

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

   196      * it.

   197      *

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

   199      *

   200      * @par Leaving:

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

   202      *        invalid.

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

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

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

   206      *        client. The operation may succeed later.

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

   208      */

   209     void RemoveToDoItemL(TPIMItemID aItemID);

   210 

   211     void CPIMToDoListAdapter::DoRemoveToDoItemL(

   212         TPIMItemID aItemID);

   213 

   214 protected:

   215 

   216     /**

   217      * C++ default constructor.

   218      */

   219     CPIMToDoListAdapter(java::util::FunctionServer* aFuncServer);

   220 

   221     /**

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

   223      */

   224     void ConstructL();

   225 

   226 private: // Member data

   227 

   228     CDesCArrayFlat* iToDoCategoryArray;

   229     CPIMAgnToDoAdapter* iAgnToDoAdapter;

   230 };

   231 

   232 #endif // CPIMTODOLISTADAPTER_H

   233 // End of File