/*
* 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: Handles PIM todo list <-> Agenda Model todo conversions
*
*/
#ifndef CPIMTODOLISTADAPTER_H
#define CPIMTODOLISTADAPTER_H
// INCLUDES
#include "mpimtodolistadapter.h"
#include "cpimagnlistadapter.h"
#include "pimexternalchanges.h"
// FORWARD DECLARATIONS
class MPIMToDoItem;
class CPIMAgnToDoAdapter;
// CLASS DECLARATION
/**
* PIM ToDo List Adapter class
*
* To-do list adapter creates, reads, writes and removes to-do items
* in a native database. See also \ref MPIMListAdapter class description.
*/
NONSHARABLE_CLASS(CPIMToDoListAdapter): public CPIMAgnListAdapter,
public MPIMToDoListAdapter
{
public: // Constructor and destructor
/**
* Two-phased constructor.
*/
static CPIMToDoListAdapter* NewL(java::util::FunctionServer* aFuncServer);
/**
* Destructor.
*/
~CPIMToDoListAdapter();
public: // Overloaded functions from (CPIMAgnListAdapter) 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.
*/
const CDesCArray& GetCategoriesL();
/**
* 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.
*/
RPointerArray< CPIMItemStateChange>* GetExternalItemModificationsL();
/**
* 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.
*/
void Close();
public: // Functions from MPIMToDoListAdapter
/**
* Provides access to the \ref MPIMListAdapter representation of this
* MPIMToDoListAdapter object.
*
* @return The \ref MPIMListAdapter representation of the specialized
* list adapter.
*/
MPIMListAdapter* GetPimListAdapter();
/**
* Creates a new To-Do item in the native Agenda File.
* The adapter creates a new native database entry, sets its data
* according to the data in \a aToDoItem, adds it to the Agenda File
* and sets the Item ID of \a aToDoItem. \a aToDoItem must
* contain valid data and have Item ID \ref KPIMNullItemID.
*
* @param aToDoItem The To-Do item to add to the Agenda File.
*
* @par Leaving:
* The method leaves on error. Such error always means that the list
* adapter is non-functional.
*/
void CreateToDoItemL(MPIMToDoItem& aToDoItem);
void DoCreateToDoItemL(MPIMToDoItem& aToDoItem);
/**
* Reads an existing To-Do item from the Agenda File.
* The adapter maps the Item ID in \a aToDoItem to a native Agenda Model
* entry identifier, reads the entry and sets the data of
* \a aToDoItem according to the data in the native entry.
* \a aToDoItem must have valid Item ID that corresponds to an
* existing native Agenda File entry.
*
* @param aToDoItem The To-Do item to be read from the Agenda File.
*
* @par Leaving:
* The method leaves on error. Error codes should be interpreted as
* follows:
* @li \c KErrArgument - The Item ID of \a aToDoItem is
* \ref KPIMNullItemID and thus invalid.
* @li \c KErrNotFound - No corresponding native Agenda File entry could
* be retrieved, although the Item ID of \a aToDoItem is not
* \ref KPIMNullItemID. The entry is probably removed from the
* native Agenda File.
* @li Other - The list adapter is non-functional.
*/
void ReadToDoItemL(MPIMToDoItem& aToDoItem);
void DoReadToDoItemL(MPIMToDoItem& aToDoItem);
/**
* Writes an existing To-Do item to the native Agenda File.
* The adapter maps the Item ID in \a aToDoItem to a native Agenda Model
* entry identifier, reads the entry and sets the data of the entry
* according to the data in \a aToDoItem. \a aToDoItem must have valid
* Item ID that corresponds to an existing native Agenda Model entry.
*
* @param aToDoItem The To-Do item to write to the Agenda File.
*
* @par Leaving:
* The method leaves on error. Error codes should be interpreted as
* follows:
* @li \c KErrArgument - The Item ID of \a aToDoItem is
* \ref KPIMNullItemID and thus invalid.
* @li \c KErrNotFound - No corresponding native database entry could
* be retrieved, although the Item ID of \a aToDoItem is not
* \ref KPIMNullItemID. The entry is probably removed from the
* native Agenda File.
* @li \c KErrInUse - The entry is currently in use by some other
* client. The operation may succeed later.
* @li Other - The list adapter is non-functional.
*/
void WriteToDoItemL(MPIMToDoItem& aToDoItem);
void DoWriteToDoItemL(MPIMToDoItem& aToDoItem);
/**
* Removes an existing To-Do from the native Agenda File.
* The adapter maps \a aItemID to a native Agenda Model entry and removes
* it.
*
* @param aItemID Item ID of the item to be removed.
*
* @par Leaving:
* @li \c KErrArgument - \a aItemID is \ref KPIMNullItemID and thus
* invalid.
* @li \c KErrNotFound - No native Agenda Model entry could be retrieved
* by \a aItemID. The entry is probably already removed.
* @li \c KErrInUse - The entry is currently in use by some other
* client. The operation may succeed later.
* @li Other - The list adapter is non-functional.
*/
void RemoveToDoItemL(TPIMItemID aItemID);
void DoRemoveToDoItemL(TPIMItemID aItemID);
protected:
/**
* C++ default constructor.
*/
CPIMToDoListAdapter(java::util::FunctionServer* aFuncServer);
/**
* By default Symbian 2nd phase constructor is private.
*/
void ConstructL();
private: // Member data
CDesCArrayFlat* iToDoCategoryArray;
CPIMAgnToDoAdapter* iAgnToDoAdapter;
};
#endif // CPIMTODOLISTADAPTER_H
// End of File