/*

* 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 CCbsDbImpTopicMessages class.

*    

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

*

*/

#ifndef CCBSDBIMPTOPICMESSAGES_H

#define CCBSDBIMPTOPICMESSAGES_H

// INCLUDES

#include <e32std.h>

#include <s32file.h>

#include "CbsCommon.h"

// FORWARD DECLARATIONS

class CCbsDbImp;

class CCbsDbImpTopicList;

class CCbsRecEtel;

//  CLASS DECLARATION 

/**

*   CCbsDbImpTopicMessages represents CB messages stored in persistent memory.

*   CBS server has two files to accommodate messages: one for unsaved 

*   and one for saved messages. "Topic messages"-stream contains information

*   on whether a message is saved or not, and what is message's stream id.

*   CCbsDbImpTopicMessages determines the correct data file depending on

*   message's save status.

*

*   Changes are written to stores immediately after operations. Message cache

*   iMessageList contains header information of all messages in a single topic

*   at once. A call to LoadCacheL() is thus made prior to any operation to

*   make sure that the appropriate topic is being used.

*/

class CCbsDbImpTopicMessages : public CBase

    {

    public:        // New functions

        /**

        *   Creates an instance of the class.

        *

        *   @param  aTopicList          Topic list database manager

        *   @param  aFs                 File server session

        *   @return                     Pointer to the created instance

        */

        static CCbsDbImpTopicMessages* NewL( CCbsDbImpTopicList& aTopicList,

            RFs& aFs );

        /**

        *   Destructor.

        */

        ~CCbsDbImpTopicMessages();

    public:

        /**

        *   Invalidates the cache.

        */

        void InvalidateCache();

        /**

        *   Invalidates the cache if the cache contains messages of the topic.

        *

        *   @param aNumber              Number of the topic that is 

        *                               invalidated.

        */

        void InvalidateCacheIfTopic( const TCbsDbTopicNumber& aNumber );

        /**

        *   Creates a default topic messages stream.

        *

        *   @param  aStore              Store to which the stream is created.

        *   @return                     Stream identifier to the created stream

        */

        static TStreamId CreateDefaultTopicMessagesStreamL( 

            CStreamStore& aStore );

        /**

        *   Delete all topics messages.

        *

        *   @param  aSavedStore         Store which contains saved messages.

        *   @param  aUnsavedStore       Store which contains unsaved messages.

        *   @param  aIn                 Stream for topic messages.

        */

        static void DeleteAllTopicMessagesL( CStreamStore& aSavedStore, 

            CStreamStore& aUnsavedStore, RReadStream& aIn );

        /**

        *   Determines whether or not there are any locked messages in 

        *   the topic.

        *

        *   @param  aNumber             Number of the topic.

        *   @return                     Boolean value indicating if there are 

        *                               locked messages in topic.

        */

        TBool IsLockedMessagesInTopic( const TCbsDbTopicNumber& aNumber ) 

            const;

        /**

        *   Determines whether there is at least one locked message.

        *

        *   @return                     ETrue, if there's at least one locked

        *                               message.

        */

        TBool IsLockedMessages() const;

        /**

        *   Returns the total amount of messages the topic contains.

        *

        *   @param aNumber              Number of the topic.

        *   @param aCount               Returns: number of messages in given

        *                               topic

        */

        void GetMessageCountL( const TCbsDbTopicNumber& aNumber, 

            TInt& aCount );

        /**

        *   Returns message information.

        *

        *   @param aNumber              Number of the topic.

        *   @param aIndex               Index to the message in topic.

        *   @param aMessage             Returns: message information.

        */

        void GetMessageL( const TCbsDbTopicNumber& aNumber, 

            TInt aIndex, TCbsDbMessage& aMessage );

        /**

        *   Finds the message for given handle and returns it.

        *

        *   @param aHandle              Handle to the message.

        *   @param aMessage             Returns: message information.

        */

        void FindMessageByHandleL( const TCbsDbMessageHandle& aHandle, 

            TCbsDbMessage& aMessage );

        /**

        *   Finds the message by message key.

        *

        *   @param  aNumber             Number of the topic.

        *   @param  aKey                Message key to be looked for.

        *   @return                     Handle to the message, or KErrNotFound if no 

        *                               such message was found.

        */

        TInt FindMessageByKeyL( TCbsDbTopicNumber aNumber, 

            TCbsDbMessageKey aKey,

            TCbsDbMessage& aMessage );

        /**

        *   Stores the contents of the message to the buffer aContents. 

        *   If aContents is too small to contain the whole message

        *   body, the message body is truncated.

        *

        *   @param aHandle              Handle to the message.

        *   @param aContents            Returns: message body

        *   @param aSize                Number of bytes to read

        */

        void GetMessageContentsL( const TCbsDbMessageHandle& aHandle, 

            TPtr& aContents, TUint aSize );

        /**

        *   Deletes a message from the topic.

        *

        *   @param aHandle      Handle to the message to be deleted.

        *   @param  aReceiver   Receiver.

        */

        void DeleteMessageL( const TCbsDbMessageHandle& aHandle,

            const CCbsRecEtel& aReceiver );

        /**

        *   Creates a new message to the topic.

        *

        *   FFS critical level check is made prior to operation.

        *

        *   @param aNumber              Number of the topic to which 

        *                               the message is to be added.

        *   @param aMessage             Contains the message information 

        *                               (i.e., header, not body).

        *   @param aContents            The contents of the message.

        */

        void AddMessageL( const TCbsDbTopicNumber& aNumber, 

            TCbsDbMessage& aMessage, const TPtrC& aContents );

        /**

        *   Saves the message.

        *

        *   FFS critical level check is made prior to the operation.

        *

        *   @param aHandle      Handle to the message to be saved.

        *   @param  aReceiver   Receiver.

        */

        void SaveMessageL( const TCbsDbMessageHandle& aHandle,

            const CCbsRecEtel& aReceiver );

        /**

        *   Sets the message as read.

        *

        *   @param aHandle      Handle to the message to be set read.

        *   @param  aReceiver   Receiver.

        */

        void ReadMessageL( const TCbsDbMessageHandle& aHandle,

            const CCbsRecEtel& aReceiver );

        /**

        *   Updates handles of messages in the topic with the number given in

        *   aOldTopicNumber to match new topic number.

        *

        *   @param  aOldTopicNumber     Number of topic to be changed

        *   @param  aNewTopicNumber     Change handles to match this number

        */

        void UpdateHandlesOfTopicMessagesL(

            const TCbsDbTopicNumber& aOldTopicNumber, 

            const TCbsDbTopicNumber& aNewTopicNumber );

        /**

        *   Unlocks one message and then locks another message.

        *

        *   Message that is locked can not be removed. Topic that 

        *   contains a locked message can not be removed.

        *

        *   Note that locking status is not persistent in the sense that 

        *   when the power is switched off and turned on, no messages 

        *   are automatically locked.

        *

        *   @param aUnlock       Handle to the message to be unlocked.

        *   @param aLock         Handle to the message to be locked.

        */

        void LockMessageL( const TCbsDbMessageHandle& aUnlock, 

            const TCbsDbMessageHandle& aLock );

        /**

        *   Retrieves handles of messages that precede and succeed the message

        *   with handle aCurrentMsg.

        */

        void GetNextAndPrevMsgHandleL(

            const TCbsDbMessageHandle& aCurrentMsg,

            TCbsDbMessageHandle& aNextMsg, 

            TCbsDbMessageHandle& aPrevMsg, 

            TInt& aPosition);

        /**

        *   Finds message position by message handle.

        *

        *   The method leaves in case the message is not found.

        *

        *   @param  aHandle             Handle to the message to be looked for.

        *   @return                     The position of the message.

        */

        TInt FindMessagePositionByHandleL( 

            const TCbsDbMessageHandle& aMessage );        

    private:

        // The structure that represents the topic messages cache item.

        struct TCbsDbImpTopicMessagesCacheItem

            {   

            // The stream identifier for the message information.

            TStreamId iId;

            // Whether this message is saved or not

            TBool iIsSaved;

            // Indicates whether iMessage and iContentsId are valid.

            TBool iIsMessage;

            // Message header - valid only if iIsMessage is true.

            TCbsDbMessage iMessage;

            // Stream identifier for message body-valid if iIsMessage is ETrue

            TStreamId iContentsId;

            };

        typedef CArrayFixFlat< TCbsDbImpTopicMessagesCacheItem > 

            TCbsDbImpTopicMessagesCache;

        /**

        *   Constructor.

        *

        *   @param aTopicList           Topic list database object

        *   @param aFs                  File server session

        */

        CCbsDbImpTopicMessages( CCbsDbImpTopicList& aTopicList, RFs& aFs );

        /**

        *   Finalizes the construction.

        */

        void ConstructL();

        /**

        *   Adds a message.

        *

        *   @param aMessage             Contains the message information.

        *   @param aContents            Contains the message contents.

        */

        void DoAddMessageL( TCbsDbMessage& aMessage, const TDesC& aContents );

        /**

        *   Deletes a message.

        *

        *   @param aPosition            Position in the internal array where 

        *                               the message is.

        */

        void DoDeleteMessageL( TInt aPosition );

        /**

        *   Updates message information.

        *

        *   @param aId                  Stream id to which the information is

        *                               written.

        *   @param aMessage             Contains the message information.

        *   @param aContentsId          Contains the contents id.

        */

        void DoUpdateMessageL( const TStreamId& aId, 

            const TCbsDbMessage& aMessage, const TStreamId& aContentsId ) const;

        /**

        *   Sets the message read.

        *

        *   @param  aId                 Stream id to which the information is 

        *                               written.

        *   @param  aMessage            Contains the message information.

        *   @param  aContentsId         Stream idenfitier to the contents.

        */

        void DoReadMessageL( const TStreamId& aId, const TCbsDbMessage& aMessage, 

            const TStreamId& aContentsId );

        /**

        *   Deletes messages that are not supposed to be in the topic.

        *

        *   Because of message locking it is possible that there are more 

        *   received messages than there should be. This method tries to 

        *   delete this kind of message.

        */

        void DoDeleteL();

        /**

        *   Loads the cache, if it is not already loaded with this topic 

        *   information.

        *

        *   The method does not load any message information to the cache 

        *   - only what is really necessary.

        *

        *   @param aNumber              Number of the topic to be loaded 

        *                               to the cache.

        */

        void LoadCacheL( const TCbsDbTopicNumber& aNumber );

        /**

        *   Loads the message header to the cache.

        *

        *   Note that it is assumed that the index is in proper range! 

        *   And the cache is already loaded!

        *

        *   @param aIndex               The index to the message in cache.

        *   @param aMessage             Returns: message information.

        */

        void LoadMessageL( TInt aIndex, TCbsDbMessage& aMessage );

        /**

        *   Loads message contents (as much as it fits).

        *

        *   Save status of message is required because saved and unsaved

        *   messages are stored on separate files.

        *

        *   @param aContentsId          Stream identifier to the content.

        *   @param aContents            Returns: message body.

        *   @param aIsSaved             ETrue, if the message is saved.

		*	@param aSize				Size of the message.

        */

        void LoadMessageContentsL( const TStreamId& aContentsId, TPtr& aContents, 

            TBool aIsSaved, TUint aSize ) const;

        /**

        *   Generates a new message handle.

        *

        *   @param  aNumber             Number of the topic which will contain 

        *                               the message.

        *   @return                     Returns the new message handle.

        */

        TCbsDbMessageHandle GenerateNewMessageHandle( 

            const TCbsDbTopicNumber& aNumber );

        /**

        *   Checks that if there are too many received messages in 

        *   the internal cache, then they will be deleted if they

        *   are not locked.

        *

        *   @return                     Boolean value indicating if some 

        *                               changes was made.

        */

        TBool DeleteReceivedIfNecessaryL();

        /**

        *   Deletes message by its position in the internal cache.

        *

        *   Note that after the call the internal cache won't contain 

        *   the item.

        *

        *   @param aPosition            The position to the message.

        */

        void DeleteMessageByPositionL( TInt index );

        /**

        *   Determines whether or not the message is locked.

        *

        *   @param  aHandle             The handle to the message.

        *   @return                     Boolean value indicating if 

        *                               the message is locked.

        */

        TBool IsMessageLocked( const TCbsDbMessageHandle& aHandle ) const;

        /**

        *   Deletes from the locked messages.

        *

        *   @param aHandle              Message to be unlocked.

        */

        void DeleteFromLocked( const TCbsDbMessageHandle& aHandle );

        /**

        *   Adds a handle to the locked messages.

        *

        *   @param aHandle              Message to be locked.

        */

        void InsertToLockedL( const TCbsDbMessageHandle& aHandle );

        /**

        *   Updates topic messages stream from the internal cache.

        *

        *   @param aDeleting            Whether the call is due to a deletion.

        */

        void UpdateTopicMessagesStreamL( TBool aDeleting );

        /**

        *   Writes topic messages stream from the internal cache.

        *

        *   @param aOut                 Stream to which data is written.

        */

        void WriteTopicMessagesStreamL( RWriteStream& aOut );

        /**

        *   Saves the message.

        *

        *   @param aMessage             The message to be saved.

        *   @param aItem                The cache item to the previous instance of the

        *                               message.

        *   @param aContentPtr          The contents of the message.

        *   @param aPosition            The position of the message in the cache.

        */

        void DoSaveMessageL( 

            TCbsDbMessage& aMessage,

            const TCbsDbImpTopicMessagesCacheItem& aItem,

            const TDesC& aContentPtr,

            TInt aPosition );

        /**

        *   Reverts any not commited file operation in data files,

        *   reloads cache and then leaves with aReason.

        *

        *   @param  aReason             Leave code

        */

        void RevertFileOperationL( TInt aReason );

        /**

        *   Creates a new message content stream.

        *

        *   @param aStore               Store to which the stream is created.

        *   @param aContents            Message content.

        */

        static TStreamId CreateMessageContentsStreamL( CStreamStore& aStore,

            const TDesC& aContents );

        /**

        *   Creates a new message stream.

        *

        *   @param aStore               Store to which the stream is created.

        *   @param aMessage             Message information.

        *   @param aContents            Stream identifier to the contents.

        */

        static TStreamId CreateMessageStreamL( CStreamStore& aStore, 

            TCbsDbMessage& aMessage, const TStreamId& aContents );

        /**

        *   Reads all cache items for a topic.

        *

        *   @param aStore               Reference to the store.

        *   @param aId                  Stream id to the topic messages stream.

        *   @param aCache               Empty cache where it is supposed that 

        *                               these messages are put.

        *   @param aSpace               Contain the amount of space for 

        *                               messages.

        */

        static void ReadTopicMessagesCacheItemsL( const CStreamStore& aStore, 

            const TStreamId& aId, 

            TCbsDbImpTopicMessagesCache& aCache, 

            TInt& aSpace );

        /**

        *   Reads necessary message information from the store.

        *

        *   @param aStore               Store that contains the information.

        *   @param aId                  Stream identifier to the message 

        *                               stream.

        *   @param aMessage             Contain message information.

        *   @param aContentsId          Contain the stream identifier to 

        *                               the contents.

        */

        static void ReadMessageInformationL( 

            const CStreamStore& aStore, 

            const TStreamId& aId, 

            TCbsDbMessage& aMessage, 

            TStreamId& aContentsId );

        /**

        *   Writes message information to the store.

        *

        *   @param aOut                 Stream to which data is written.