/*

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

*

*/

#ifndef CCBSRECCOLLECTOR_H

#define CCBSRECCOLLECTOR_H

// INCLUDES

#include <e32base.h>

// FORWARD DECLARATIONS

class TCbsMessageCompletion;

class CCbsRecMessage;

class CCbsMessage;

class CCbsMessageFactory;

class CCbsMessageCleanupTimer;

// DATA TYPES

// Dynamic array that contains collected message pages

typedef CArrayPtrFlat<CCbsMessage> CMessageBuffer;

// CLASS DECLARATION

/**

*   This class represents a collector, which stores pages of multipaged 

*   messages. Complete messages are assembled and returned back to 

*   the caller of CollectL() method.

*  

*   CCbsRecCollector stores message pages in a number of dynamic arrays.

*   If all but one page of a message are present in collector, and

*   the remaining page is received, the pages will be assembled and

*   the corresponding message chain deleted.

*

*   The maximum number of incomplete messages stored in collector at once

*   is fixed and determined by KMaxCollectorMessages in CCbsRecCollector.cpp.

*

*   CCbsRecCollector implements a circular list to contain message.

*   Each incomplete message occupies a slot in this list. If the list already

*   contains KMaxCollectorMessages messages, the next received multipaged

*   message will delete all received pages of the oldest message in list.

*

*   On receival of a message page, the collector compares network information

*   (PLMN, LAC, CellId) of both messages to decide whether pages are of

*   the same message. In short, for pages to be of the same message

*   their network information have to meet the requirements set by the 

*   geographical scope of the already collected page.

*   See ETSI GSM 03.41 for a detailed description. 

*   

*/

class CCbsRecCollector : public CBase

    {

    public:  // Constructors and destructor

        /**

        *   Two-phased constructor.

        *

        *   @param  aFactory            Message factory instance

        *   @return                     New CCbsRecCollector instance

        */

         static CCbsRecCollector* NewL( CCbsMessageFactory& aFactory );

        /**

        *   Destructor.

        */

        virtual ~CCbsRecCollector();

    public: // New functions

        /**

        *   Called by the Receiver when a multipaged message is received.

        *   This method checks for other pages of this message to be

        *   present in the collector. If all pages are present the

        *   collector returns a pointer to completed message.

        *

        *   If some pages are still missing, function stores 

        *   the message page and returns NULL.

        *

        *   @param aMessage             Multipaged message page

        *   @return                     NULL or completed CB message

        */

        CCbsMessage* CollectL( CCbsMessage* aMessage, TInt aMessageType );

        /**

        *   Deletes all message pages contained in aArray.

        *

        *   @param aArray               Message chain.

        */

        void DeleteChainL( CMessageBuffer& aArray ) const; 

    private:    // new functions

        /**

        *   C++ default constructor.

        *

        *   @param aListener            Message factory instance

        */

        CCbsRecCollector( CCbsMessageFactory& aFactory  );

        /**

        *   By default constructor is private.

        */

        void ConstructL();

        /**

        *   Counts pages in message chain aArray and compares the result

        *   against the total number of pages in the message.

        *   @param  aArray              Message chain.

        *   @return                     ETrue, if the chain contains all pages

        *                               of the message and is ready to be 

        *                               merged.

        */

        TBool AllPagesPresent( const CMessageBuffer& aArray ) const;

        /**

        *   Merges all pages in message chain aArray and returns

        *   a pointer to the resulting assembled message. The pointer

        *   is also left on the cleanup stack.

        *

        *   @param aArray               Message chain

        *   @return                     Completed CB message

        */

        CCbsMessage* MergePagesLC( CMessageBuffer& aArray ) const;

        /**

        *   Finds and returns a message chain which already contains pages

        *   of aMessage's message. If none is found, NULL is returned.

        *

        *   @param aMessage             Message page for which a correct chain

        *                               is sought.

        *   @return                     NULL or message chain that contains

        *                               aMessage's pages.

        */

        CMessageBuffer* FindChainContainingPage( const CCbsMessage& aMessage ) const;

        /**

        *   Adds message page aMessage to the correct position in message chain

        *   aArray. Message chains are ordered in ascending page number order.

        *   Duplicate pages are not accepted.

        *

        *   Ownership of aMessage is transferred to aArray, if the given page

        *   hasn't been already collected. The given page will be deleted,

        *   if it already exists in the chain.

        *

        *   @param aMessage             Message page, which is inserted into 

        *                               the chain.

        *   @param aArray               Message chain.

        */

        void AddMessageToChainL( CCbsMessage* aMessage, 

            CMessageBuffer& aArray ) const;

        /**

        *   Checks if these pages can be merged. Returns ETrue, if merging is

        *   acceptable.

        *

        *   Decision is based network information and geographical scope of 

        *   pages. Network information consists of cell id, location area code

        *   and operator id.

        *

        *   @param aPage1               Message page.

        *   @param aPage2               Message page.

        */

        TBool CheckPageAreaInfoMatch( const CCbsMessage& aPage1, 

            const CCbsMessage& aPage2 ) const;

    private:    // prohibited functions

        // Prohibited copy constructor

        CCbsRecCollector( const CCbsRecCollector& );

        // Prohibited assignment operator

        CCbsRecCollector& operator=( const CCbsRecCollector& );

    private:    // data

        // Contains pointers to buffers, each containing a single partial

        // message with 1 or more pages. 

        CArrayPtrFlat< CMessageBuffer >* iRootNodeArray;

        // An iterator which points to a location in iRootNodeArray next used

        // to store a page of a message, which is "new" to the collector.

        // Being "new" here means that the collector doesn't contain any

        // pages of this message.

        TInt iRootNodeIterator;

        // Message factory

        CCbsMessageFactory& iFactory;

		CArrayPtrFlat< CCbsMessageCleanupTimer >*	iMessageCleanupTimerArray;

    };

#endif      // CCBSRECCOLLECTOR_H

// End of File