/*

* 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:  Base class for the event and todo list adapters

 *

*/

#ifndef CPIMAGNLISTADAPTER_H

#define CPIMAGNLISTADAPTER_H

// INCLUDES

#include <e32base.h>

#include <calprogresscallback.h>

#include <calchangecallback.h>

#include <calentry.h>

#include <caltime.h>

#include <badesca.h>

#include "mpimlistadapter.h"

#include "pimexternalchanges.h"

// FORWARD DECLARATIONS

class CCalSession;

class CCalEntryView;

class CPIMToDoListAdapter;

class CPIMEventListAdapter;

class CPIMAgnServerWait;

// CLASS DECLARATION

/**

 * PIM Agenda List Adapter class, the base for Event and ToDo List Adapters

 */

NONSHARABLE_CLASS(CPIMAgnListAdapter): public CBase,

        public MPIMListAdapter,

        public MCalChangeCallBack

{

public: // destructor

    /**

     * Destructor.

     */

    virtual ~CPIMAgnListAdapter();

public: // Functions from MPIMListAdapter

    /**

     * Provides all categories currently existing in the native database.

     *

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

     *         meant to be modified.

     *

     * @par Leaving:

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

     * adapter is non-functional.

     */

    virtual const CDesCArray& GetCategoriesL() = 0;

    /**

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

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

     *

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

     *

     * @par Leaving:

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

     * follows:

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

     * @li \c KErrNotSupported - The operation is not supported.

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

     */

    void AddCategoryL(const TDesC& aNewCategory);

    /**

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

     * is done and the method returns successfully.

     *

     * @param aCategory The category to be deleted.

     *

     * @par Leaving:

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

     * follows:

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

     * @li \c KErrNotSupported - The operation is not supported.

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

     */

    void DeleteCategoryL(const TDesC& aCategory);

    /**

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

     * to the new category.

     *

     * @param aOldCategory The old category name.

     * @param aNewCategory The new category name.

     *

     * @par Leaving:

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

     * follows:

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

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

     * @li \c KErrNotSupported - The operation is not supported.

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

     */

    void RenameCategoryL(const TDesC& aOldCategory,

                         const TDesC& aNewCategory);

    /**

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

     * the native database after last call to

     * \ref GetExternalCategoryModifications or list adapter creation.

     *

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

     */

    TBool IsCategoriesExternallyModified();

    /**

     * Provides the external changes to the categories in the native

     * database. See \ref IsCategoriesExternallyModified method.

     *

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

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

     *         changes are present, \c NULL is returned.

     *

     * @par Leaving:

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

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

     * leaved once, it must always leave.

     */

    RPointerArray<CPIMCategoryStateChange>*

    GetExternalCategoryModificationsL();

    /**

     * Checks whether there have been external changes to the items

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

     * GetExternalItemModificationsL() or list adapter creation.

     *

     * If GetExternalItemModificationsL() has never been called, all

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

     *

     * See GetExternalItemModificationsL().

     *

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

     *         \c EExternalChangesMinor if there are changes that

     *         can be classified to new, removed or modified;

     *         \c EExternalChangesMajor if there are changes that

     *         force all items to be refreshed.

     */

    MPIMListAdapter::TExternalItemChangeClass IsItemsExternallyModified();

    /**

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

     * native database. See \ref IsItemsExternallyModified method.

     *

     * If GetExternalItemModificationsL has never been called, all

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

     *

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

     * depends of the status provided by IsItemsExternallyModified():

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

     *     modifications and NULL will be returned.

     * @li \c EExternalChangesMinor means that the changes are

     *     applied over the existing set of items, reflecting the

     *     addition, removal and modification of the database

     *     entries.

     * @li \c EExternalChangesMajor means that the changes cannot

     *     be classified and the whole set of items must be

     *     refreshed. All current entries in the database are

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

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

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

     *     and which of the existing items have been removed.

     *     If any existing items are reused, their data content

     *     must be explicitly refreshed.

     *

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

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

     *         changes are present, \c NULL is returned.

     *

     * @par Leaving:

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

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

     * leaved once, it must always leave.

     */

    virtual RPointerArray< CPIMItemStateChange>*

    GetExternalItemModificationsL() = 0;

    /**

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

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

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

     */

    virtual void Close() = 0;

public: // From MCalChangeCallBack

    void CalChangeNotification(

        MCalChangeCallBack::TChangeEntryType aChangeEntryType);

protected:

    /**

     * Fetches external item modifications from the native Agenda Model.

     *

     * @param aEntryType The Agenda Model entry types that are to be checked

     *

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

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

     *         changes are present, \c NULL is returned.

     *

     * @par Leaving:

     * This method may leave.

     */

    RPointerArray< CPIMItemStateChange>*

    GetExternalItemModificationsByEntryTypeL(

        CCalEntry::TType aEntryType);

    /**

     * Fetches a CAgnEntry from the native Agenda Model.

     *

     * @param aItemId The Agenda Model unique id of the entry to be fetched

     * @param aEntryType The Agenda Model entry type to be fetched

     *

     * @return A CAgnEntry according to framework item.

     * The \b ownership of the entry is transferred to the caller.

     *

     * @par Leaving:

     * This method may leave.

     */

    CCalEntry* FetchNativeEntryL(

        TPIMItemID aItemId,

        CCalEntry::TType aEntryType);

    /**

     * Closes the file which is open in the current agenda server session,

     * and also deletes both the Agenda Model and Agenda Server

     */

    void CloseAgendaSession();

    /**

     * Leaves with KErrNotReady if session is closed.

     */

    void EnsureOpenSessionL();

protected: // Constructors

    /**

     * C++ default constructor.

     * Allow derivation with protected default constructor.

     */

    CPIMAgnListAdapter(java::util::FunctionServer* aFuncServer);

    /**

     * By default Symbian 2nd phase constructor is private.

     *

     * @param aEntryType Entry type for change callbacks (ToDo/Event/all).

     */

    void DoClose();

protected: // Member data

    /** Session to calendar server. Owned. */

    CCalSession* iCalSession;

    /** Entry-based view to the database. Owned. */

    CCalEntryView* iCalEntryView;

    /** Agenda server operation synchronizer. Owned. */

    CPIMAgnServerWait* iServerWait;

    /** Item change array. May be NULL. Owned. */

    RPointerArray< CPIMItemStateChange>* iItemChangeArray;

    /** Indicates whether changes have been read since they have last

     * occurred */

    TBool iChangesRead;

    java::util::FunctionServer* iFuncServer;

};

#endif // CPIMAGNLISTADAPTER_H

// End of File