/*

* Copyright (c) 2003 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:  This file contains the header file of the CCbsDmImpTopicList class

*    

*                This class represents the topic list stored in the database.

*

*/

#ifndef     CCBSDBIMPTOPICLIST_H

#define     CCBSDBIMPTOPICLIST_H

// INCLUDES

#include <f32file.h>

#ifndef __SECURE_BACKUP__

#include <babackup.h>

#endif

#include "CbsCommon.h"

#include "CCbsDbImp.H"

// FORWARD DECLARATIONS

//class CCbsDbImp;

class CCbsDbImpTopicMessages;

class MCbsDbTopicListObserver;

class CFileStore;

//  CLASS DECLARATION 

/**

*   CCbsDbImpTopicList is the database topic list manager.

*   

*/

class CCbsDbImpTopicList : public CBase

#ifndef __SECURE_BACKUP__

, public MBackupObserver

#endif

    {

    #ifndef __SECURE_BACKUP__

    public: // MBackupObserver

        /**

        *   Closes or reopens the settings file if requested by a backup.

        *

        *   @param aFileName                The name of the file to close.

        *   @param aFlags                   The action to be performed.

        *

        */

        void ChangeFileLockL( const TDesC& aFileName, TFileLockFlags aFlags );

    #else

    public:

        /**

        *   Closes or reopens the settings file if requested by a backup.

        *

        *   @param aRequest                 Current request        

        *

        */

        void ChangeFileLockL( const TCbsBackupRequest& aRequest );

    #endif

    private: 

        /**

        *   Check if the server has a file lock. Leaves with

        *   KErrLocked if not.

        */

        void CheckFileLockL() const;

    public:     // New functions

        /**

        *   Creates an instance of the class.

        *

        *   @param aFs                      Open file server session.

        *   @param aTopicsFile              Name of the file containing topics.

        *   @param aUnsavedMessagesFile     Name of the file containing unsaved

        *                                   messages.

        *   @param aDatabase                Reference to database object

        *   @return                         Pointer to the created instance.

        */

        static CCbsDbImpTopicList* NewL( RFs& aFs, 

            const TDesC& aTopicsFile, 

            const TDesC& aUnsavedMessagesFile,

            CCbsDbImp& aDatabase );

        /**

        *   Destructor.

        */

        ~CCbsDbImpTopicList();

    public:

        /**

        *   Creates a new topic list

		*

        *	@param	aTopicListName		Name of the new topic list

		*	@param	aTopicListIndex		Returns: Index number of the new list

        */

        void CreateNewTopicListL( const TDesC& aTopicListName );

		/**

        *	Deletes old read messages. The clean up interval is set

		*	by the user.

		*

        */

        void CleanupReadMessagesL();        

        /**

        *   Sets the topic messages manager.

        *

        *   Note that this function does not transfer ownership

        *   of aMessages.

        *

        *   @param aMessages            Pointer to the topic messages 

        *                               manager.

        */

        void SetTopicMessages( CCbsDbImpTopicMessages* aMessages );

        /**

        *   Returns pointer to the current store which contains topics

        *   of the server (i.e., Topics-file) and saved messages. 

        *   Leaves with KErrLocked if the store is locked by backup.

        *

        *   @return                     Pointer to topics store.

        */

        CFileStore* TopicStoreL() const;

        /**

        *   Returns a pointer to the name of the file, which contains unsaved

        *   messages of the server.

        *

        *   @return                     Reference to the file name.

        */

        const TDesC& TopicFilename() const;

        /**

        *   Returns a pointer to the store, which contains unsaved

        *   messages of the server.

        *

        *   @return                     Pointer to unsaved messages store.

        */

        CFileStore* UnsavedMessagesStore() const;

        /**

        *   Returns a pointer to the name of the file, which contains unsaved

        *   messages of the server (Unsaved Messages-file, "cbs4.dat").

        *

        *   @return                     Reference to the file name.

        */

        const TDesC& UnsavedMessagesFilename() const;

        /**

        *   Returns the topic messages stream id by topic handle.

        *

        *   @param  aNumber             Topic number

        *   @param  aId                 Returns: the stream id to the topic

        *                               messages stream.

        */

        void GetTopicMessagesIdL( TCbsDbTopicNumber aNumber,

            TStreamId& aId ) const;

        /**

        *   Updates the topic messages stream id by topic handle. The new 

        *   identifier is expected not to be a null id.

        *

        *   Note that the method will not commit changes to the store. 

        *   It also changes the internal state and thus if the method leaves, 

        *   it is good to reload the whole root stream.

        *

        *   The method will delete the old topic messages stream.

        *

        *   @param aNumber              Topic number

        *   @param aNewId               New stream id.

        */

        void UpdateTopicMessagesIdL( TCbsDbTopicNumber aNumber, 

            const TStreamId& aNewId );

        /**

        *   Generates a message handle.

        *

        *   Note that it must be checked that the message handle is unique 

        *   in that topic.

        *

        *   @param  aNumber             Topic number

        *   @param  aRandom             Number generated in some way.

        *   @return                     New message handle.

        */

        TCbsDbMessageHandle GenerateMessageHandle( 

            const TCbsDbTopicNumber aNumber, TUint16 aRandom ) const;

        /**

        *   Informs that a new message has been received in a topic.

        *

        *   @param  aMessageHandle      Handle of the received message.

        */

        void InformNewMessageReceivedL(

            const TCbsDbMessageHandle& aMessageHandle  );

        /**

        *   Informs that a message has been set as saved.

        *

        *   @param  aMessageHandle      Handle of the saved message.

        */

        void InformMessageSavedL( const TCbsDbMessageHandle& aMessageHandle );

        /**

        *   Informs that an unread message has been read.

        *

        *   @param  aMessageHandle      Handle of the read message.

        */

        void InformUnreadMessageReadL( 

            const TCbsDbMessageHandle& aMessageHandle );

        /**

        *   Informs that a message has been deleted.

        *

        *   @param  aMessageHandle      Handle of the deleted message.

        *   @param  aPermanent          ETrue, if the message was permanent.

        *   @param  aRead               ETrue, if the message was read.

        */

        void InformMessageDeletedL( 

            const TCbsDbMessageHandle& aMessageHandle, 

            TBool aPermanent, TBool aRead );

        /**

        *   Extracts topic handle from message handle.

        *

        *   Note that the method does not check that the message exists.

        *

        *   @param  aHandle             Handle to a message.

        *   @return                     Returns the number of the topic to 

        *                               which the message belongs.

        */

        TCbsDbTopicNumber ExtractTopicNumber( 

            const TCbsDbMessageHandle& aHandle ) const;

        /**

        *   Initialises the whole topic list. 

        */

        void InitializeListL( const TBool aFileOpenFailed );

        /**

        *   Returns the total amount of saved messages.

        *

        *   @return                     Number of saved messages.

        */

        TInt TotalSavedMessages() const;

        /**

        *   Returns the amount of topics the list contains.

        *

        *   @param  aCount              Returns: number of topics in topic list

        */

        void GetTopicCount( TInt& aCount ) const;

        /**

        *   Returns a topic by index.

        *

        *   Return values:

        *   KErrNone                    Parameter aTopic contains the requested

        *                               topic.

        *   KErrArgument                Index out of bounds.

        *

        *   Leaves if file read fails.

        *

        *   @param  aIndex              Index to the topic.

        *   @param  aTopic              Returns: topic information.

        */

        void GetTopicL( TInt aIndex, TCbsDbTopic& aTopic );

        /**

        *   Returns a topic by topic number.

        *

        *   Leaves with KErrNotFound, if a topic with the given number

        *   is not found.

        *

        *   @param    aNumber           Number of the topic.

        *   @param    aTopic            Returns: topic information.

        */

        void FindTopicByNumberL( TCbsDbTopicNumber aNumber, 

            TCbsDbTopic& aTopic );

        /**

        *   Reads the name of the index topic from resource.

        *

        *   @return     Name of the index topic

        */

        HBufC* ReadIndexTopicNameLC();

        /**

        *   Adds a new topic to the list.

        *

        *   @param    aTopic            Topic information.

        *   @param    aDetected         Was the topic detected automatically

        */

        void AddTopicL( TCbsDbTopic& aTopic, const TBool aDetected );

        /**

        *   Updates the topic name and number.

        *

        *   @param    aOldNumber        Old number of the topic.

        *   @param    aNewNumber        New number of the topic.

        *   @param    aName             New name of the topic.

        */

        void UpdateTopicNameAndNumberL( 

            TCbsDbTopicNumber aOldNumber, 

            TCbsDbTopicNumber aNewNumber, 

            const TCbsDbTopicName& aName );

        /**

        *   Updates the topic subscription status.

        *

        *   @param    aNumber           Topic number

        *   @param    aStatus           New subscription status.

        */

        void UpdateTopicSubscriptionStatusL( 

            TCbsDbTopicNumber aNumber, 

            TBool aStatus );

        /**

        *   Updates the topic hotmark status.

        *

        *   @param    aNumber           Topic number

        *   @param    aStatus           New hotmark status.

        */

        void UpdateTopicHotmarkStatusL( 

            TCbsDbTopicNumber aNumber, 

            TBool aStatus );

        /**

        *   Deletes an existing topic and all its messages.

        *

        *   @param    aNumber           Number of the topic to be deleted.

        */

        void DeleteTopicL( TCbsDbTopicNumber aNumber );

        /**

        *   Gets the total amount of unread messages.

        *

        *   @param  aCount              Returns: number of unread topics. 

        */

        void GetUnreadMessageCount( TInt& aCount ) const;

        /**

        *   Returns the handle to the latest hotmarked message. 

        *   

        *   The method leaves if there is no such message.

        *

        *   @param  aMessage            Returns: Handle to a message that has         

        *                               been  received under a hotmarked topic

        */

        void GetHotmarkedMessageHandleL( TCbsDbMessageHandle& aMessage );

        /**

        *   Adds a topic list observer. 

        *   

        *   After an observer is added to the topic list, it will be notified 

        *   whenever an event occurs.

        *

        *   @param  aObserver           New observer for the list.

        */

        void AddObserverL( MCbsDbTopicListObserver* aObserver );

        /**

        *   Removes a topic list observer. 

        *   

        *   If aObserver is not in the list, the method will panic.

        *

        *   @param  aObserver           Pointer to the observer to be removed.

        */

        void RemoveObserver( const MCbsDbTopicListObserver* aObserver );

        /**

        *   Adds numbers of subscribed topics to the given array.

        *

        *   @param aSubscriptions       Dynamic array into which the topic

        *                               numbers are inserted.

        */

        void AppendSubscribedTopicsL( CArrayFixFlat< TUint16 >& aSubscriptions )

            const;

        /**

        *   Reverts all changes made to three datafiles handled by this

        *   class.

        */

        void RevertFilesL();

        /**

        *   Commits all changes made to three datafiles handled by this

        *   class.

        */

        void CommitFilesL();

        /**

        *   Returns the number of the topic that was added last

        *   to the database by topic detection feature.

        *

        *   Result code KErrNotFound indicates that no topic has ever

        *   been added to the database.

        *

        *   @param aNumber              Returns: topic number

        *   @return                     Result code

        */

        TInt GetLatestTopicNumber( TCbsTopicNumber& aNumber ) const;

        /**

        *   Finds the index of the topic matching the given topic number

        *   in the topic list.

        *

        *   @param aNumber              Topic number

        *   @return                     Index to the position of topic in 

        *                               the topic list.

        */

        TInt TopicIndexInList( TCbsDbTopicNumber aNumber ) const;

        /**

        *   Returns the number of unread messages in hotmarked topics.

        */

        TInt UnreadHotmarkedMessageCount() const;

        /**

        *   Retrieves numbers of topics that precede and succeed the topic

        *   with number aCurrentTopic.

        *

        *   @param  aCurrentTopic   Topic number of current topic

        *   @param  aNextTopic      Topic number of next topic

        *   @param  aPrevTopic      Topic number of previous topic

        *   @param  aPosition       Position of topic in the topic list

        */

        void GetNextAndPrevTopicNumberL( const TCbsTopicNumber& aCurrentTopic,

            TCbsTopicNumber& aNextTopic, TCbsTopicNumber& aPrevTopic,

            TInt& aPosition );

        /**

        *   Notifies each observer that a new message has arrived to a topic.

        *

        *   @param    aHandle                    Handle to the topic.

        */

        void NotifyNewMessageArrivedL( const TCbsDbMessageHandle& aHandle );

        /**

        *   Notifies each observer that a topic has been modified.

        *

        *   @param    aNumber                    Topic number

        */

        void NotifyTopicModifiedL( TCbsDbTopicNumber aNumber );

        /**

        *   Loads the topic stream to the memory.

        *

        */

        void LoadDefaultTopicStreamL();

    private:                

        /**

        *   Constructor.

        *

        *   @param aFs                  Open file server session.

        *   @param aDatabase            Reference to database object

        */

        CCbsDbImpTopicList( RFs& aFs, CCbsDbImp& aDatabase );

        /**

        *   Returns the total amount of topics the list contains.

        *

        *   @return                     The total amount of topics in the list.

        */

        TInt TopicCount() const;

		/**

        *   Returns the total amount of topic lists.

        *

        *   @return                     The total amount of topic lists.

        */

        TInt TopicListCount() const;

        /**    

        *   Finalizes the construction.

        *

        *   @param aTopicFile           File name of the topic file

        *   @param aUnsavedMessagesFile File name of the unsaved messages file.

        */

        void ConstructL( const TDesC& aTopicsFile, 

            const TDesC& aUnsavedMessagesFile );

        /**

        *   Loads the root stream to the memory.

        *

        *   Root stream contains stream ids for each topic list and the total

        *   count of topic lists.        

        */

        void LoadRootStreamL();

        /**

        *   Reloads the root stream to the memory.

        */

        void ReloadRootStreamL();

		/**

        *   Reads all information on topic list found with stream ID.        

        *

        *   @param aId                  Stream id to the topic information

        *   @param aTopicList           Returns: topic list information

        */

		void ReadTopicListInformationL(const TStreamId& aId, 

			TCbsDbImpTopicList& aTopicList ) const;

        /**

        *   Reads all information on topic found in stream aId

        *   into aTopic.

        *

        *   This function is called when details of a topic are needed.

        *

        *   @param aId                  Stream id to the topic information

        *   @param aTopic               Returns: topic information.