/*

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

*    

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

*                Topic collection keeps a record of topic identities received from

*                the network. Topic identity includes a topic name and a topic number. 

*                These can be accessed but not modified.

*

*/

#ifndef     CCBSDBIMPTOPICCOLLECTION_H   

#define     CCBSDBIMPTOPICCOLLECTION_H   

//  INCLUDES

#include <e32base.h>

#include <e32std.h>

#include <s32stor.h>

#include <f32file.h>

#include <s32file.h>

#include "MCbsDbTopicCollectionObserver.H"

//  CLASS DECLARATION 

class CCbsDbImp;

/**

*   This class defines the interface for handling topic collections.

*

*   User's Guide for accessing stored topic identities:

*   GetTopicIdentityCount(TInt&)

*       Retrieves the number of topic identities currently stored in the 

*       topic collection.

*   GetTopicIdentityL(TInt&, TCbsDbTopicIdentity&)

*       Retrieves a single topic identity identified with an index.

*

*   User's Guide for observing the topic collection.

*   AddObserverL(MCbsDbTopicCollectionObserver*)

*       Registers an observer which is notified of changes in the topic

*       collection.

*   RemoveObserverL(MCbsDbTopicCollectionObserver*)

*       Unregisters an observer.

*

*   User's Guide for modifying the topic collection:

*   Clear()

*       Clears the current topic collection. This is called by the index

*       message parsing routine when it's about to parse a root index

*       message. Topic identities contained in subsequent child subindex 

*       messages, if any, are then simply added with AddTopicIdentityL()

*   AddTopicIdentityL(TCbsDbTopicIdentity&)

*       Adds a topic identity into the topic collection's buffer.

*   Apply()

*       Writes the topic identity buffer into persistent storage.

*       Clears the buffer.

*   

*/

class CCbsDbImpTopicCollection : public CBase

    {

    public:     // New functions.

        /**

        *   Creates a new instance of the class.

        *       

        *   @return                     A pointer to the created 

        *                               CCbsDbImpTopicCollection instance.

        */

        static CCbsDbImpTopicCollection* NewL();

        /**

        *   Destructor. 

        */

        ~CCbsDbImpTopicCollection();

    public: 

        /**

        *   Returns the total amount of topic identities 

        *   the collection contans.

        *

        *   @param aCount               The method stores the topic identity

        *                               count to this variable.

        */

        void GetTopicIdentityCount( TInt& aCount ) const;

        /**

        *   Stores a topic identity (index is aIndex in the list) to aIdentity.

        *   The method leaves if the parameter aIndex is invalid.

        *

        *   Exceptions:

        *   KErrNotFound                The requested topic identity was not 

        *                               found.

        *

        *   @param aIndex               Used to index identities.

        *   @param aIdentity            The method stores a topic identity to 

        *                               the parameter.

        */

        void GetTopicIdentityL( 

            TInt& aIndex, 

            TCbsDbTopicIdentity& aIdentity ) const;

        /**

        *   Adds a topic collection observer. 

        *

        *   Panics if aObserver is null.

        *

        *   Exceptions:

        *   KErrNoMemory                OOM

        *

        *   @param aObserver            Pointer to the new observer to be added

        */

        void AddObserverL( MCbsDbTopicCollectionObserver* aObserver );

        /**

        *   Removes a topic collection observer. 

        *

        *   Panics if aObserver is null or aObserver is not registered

        *   as an observer.

        *

        *   @param aObserver            Pointer to the observer to be removed

        */

        void RemoveObserver( const MCbsDbTopicCollectionObserver* aObserver );

        /**

        *   Clears the topic collection builder's buffered topic list.

        *   This does not have any effect on identities stored in 

        *   the database.

        *

        *   This method should be called prior to parsing a root index

        *   message. Any topic identities extracted from subindex messages

        *   should be appended into collection with AddTopicIdentityL()

        *   without any call to Clear().

        */

        void Clear();

        /**

        *   Stores topic identities which were added to the topic 

        *   collection with AddTopicIdentityL() after previous call to 

        *   Apply().

        *

        */

        void Apply();

        /**

        *   Adds a new topic identity to the buffered collection.

        *   A topic identity contains topic name and number. If the

        *   topic exists already, nothing is done.

        *   

        *   This method will return KErrAlreadyExists, if there is already 

        *   another topic identity that has the same number.

        *

        *   Exceptions:

        *   KErrNoMemory                OOM

        *   KErrArgument                Topic number of the given identity is

        *                               out of valid range.

        *

        *   @param  aIdentity           Topic identity to be added.

        */

        void AddTopicIdentityL( const TCbsDbTopicIdentity& aIdentity );

    private:

        /**

        *   Constructor. 

        *

        */

        CCbsDbImpTopicCollection();

        /**

        *   Finalizes the construction.

        *

        */

        void ConstructL();

        /**

        *   Notifies topic collection observers about changed topic 

        *   collection.

        */       

        void NotifyObservers();

    private:

        // Own: Contains the observers.

        CArrayFixFlat< MCbsDbTopicCollectionObserver* >* iObservers;

        // Own: Contains buffered topic identities.

        CArrayFix< TCbsDbTopicIdentity >* iIdentities;

    };

#endif      //  CCBSDBIMPTOPICCOLLECTION_H   

// End of File