/** 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 DECLARATIONSclass 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. * @param aMessage Contains the message information to be * written. * @param aContentsId Stream identifier to the contents. */ static void WriteMessageInformationL( RWriteStream& aOut, const TCbsDbMessage& aMessage, const TStreamId& aContentsId ); /** * Updates the soft notification (dialog) when unread message * count changes. * * @param aHandle Handle to the message to be set as read * @param aReceiver Receiver. */ void UpdateSoftNotificationL( const TCbsDbMessageHandle& aHandle, const CCbsRecEtel& aReceiver ); private: // Topic list manager. CCbsDbImpTopicList& iTopicList; // Indicates whether the cache is valid or not. TBool iCacheValid; // If cache is valid, then it contains the topic handle of the // cached topic. TCbsDbTopicNumber iCachedTopicNumber; // If cache is valid, then it tells how many messages the stream // can hold. TInt iSpaceForMessages; // Own: If cache is valid, it contains some information of the // topic messages for fast access. TCbsDbImpTopicMessagesCache* iMessageList; // Own: handles of the locked messages. CArrayFixFlat< TCbsDbMessageHandle >* iLockedMessages; // Reference to a file server session of CCbsDbImp RFs& iFs; };#endif // CCBSDBIMPTOPICMESSAGES_H // End of File