/*

* Copyright (c) 2006 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:   Contains CCatalogsInterfacebase class

*

*/

#ifndef CATALOGS_INTERFACE_BASE_H

#define CATALOGS_INTERFACE_BASE_H

#include <e32base.h>

#include <e32cmn.h>

#include "catalogsbase.h"

#include "catalogsinterfaceids.h"

class CCatalogsInterfaceIdentifier;

/**

 * This class contains list of the interface objects that this class object 

 * contains or implements. Also, reference counters are provided so that

 * the user may check if some of the interfaces are used.

 *

 * @note Two kind of counter informations are provided here. 

 * One is for the top parent reference counter. 

 * Another is class object specific (My-functions).

 * The top parent counter contains the sum of all the reference counts of 

 * its children and their children, etc.. 

 * My-reference counter functions give the child reference 

 * counts for that specific class object and its children, and their children,

 * etc.. 

 * Notice also that when the My-reference counter info is asked for a parent, 

 * the parent specific information contains also the total count of references

 * including child reference information. This should be adequate because some

 * classes may implement multiple interfaces and thus have the same counter 

 * for them.

 */

class CCatalogsInterfaceBase: public CBase,

                              public virtual MCatalogsBase

    {

public:

    /**

     * Destructor

     *

     * @note Only deletes the register list info elements that are owned 

     * by this class. But, does not delete the actual interface elements.

     * So, the destructor of the child of this class has to delete

     * separately the objects that it owns.

     */

    virtual ~CCatalogsInterfaceBase();

    /**

     * Sets the new parent for this class object.

     *

     * If the given parent is same as this,

     * then nothing is done. 

     * The reference counters of the new parent 

     * are increased according to the counters of this object.

     *

     * @note This function can be called only to the class object that

     * is top parent itself at the moment. If this function is called

     * to the class object that is not a top parent, then function leaves

     * with KErrArgument. The reason for this is that only top parent knows

     * all the registered interfaces and only that parent may update these

     * interfaces to the new top parent. Also, notice that aParent does not

     * need to be a top parent, because it will forward the interfaces

     * to its own top parent.

     *

     * @note If the given parent contains interfaces that this class object

     * contains, then interfaces pointers of the parent will be replaced

     * be the interfaces of this class object. 

     *

     * @param aParent The new parent of this class object.

     * If NULL is given then this class object does not have a parent.

     * Ownership is not transferred.

     * @exception Leaves with KErrArgument if this class object is not

     * a top parent when this function is called.

     */

    void SetParentL( CCatalogsInterfaceBase* aParent );

    /**

     * This function is used to remove this class object from the ownership of its

     * parents. This function only affects the reference counters of the parents.

     * The parent of this object is set to NULL by this function. In other words this

     * class object will be a top parent itself after this function has finished.

     *

     * @note WARNING! Use this function with great care. This function only

     * releases parents' reference counts that have been reserved by this class object and its

     * children. Interfaces are not released. If this class object will be deleted

     * before its parent, the parent may contain obsolete interface references if

     * they are not separately removed from the top parents interface list. Use of those

     * obsolete references will most likely crash the program.

     *

     * @note Even if the total reference count of this object is zero after removing it from the parent, 

     * this object will not be deleted in this function. So, the user has to call delete for this object 

     * separately if the object should be deleted in that situation.

     */

    void RemoveFromParent(); 

    /**

     * Adds the given interface object into the interface register list. 

     * If the interface already exists in the list, the old interface 

     * object is removed and replaced by the new object.

     *

     * @param aInterface Interface infromation that is inserted to the

     * interface register list. The list is used to check if the object

     * implements an interface that is requested by using QueryInterface

     * functions. Ownership is transferred.

     */

    void AddInterfaceL( CCatalogsInterfaceIdentifier* aInterface );

    /**

     * Finds the interface from the interface register list

     * according to the given interface id and removes

     * the interface.

     *

     * @param aId Interface identifier that is used to remove the

     * registered interface from the interface list.

     */

    void RemoveInterface( TInt aId );

    /**

     * @note This information is gotten from the top parent

     * (if the parent is different object that this class object).

     *

     * @return The total number of references to the object

     * This contains the internal and external counts.

     */

    TInt TotalRefCount() const;

    /**

     * @note This updates the information contained in the parent(s)

     * (if the parent is different object that this class object).

     *

     * @return The number of internal references to the object

     * after the addition.

     * Internal reference counts are meant to be used when the

     * counter info is want to be hidden from the API user.

     */

    TInt InternalAddRef();

    /**

     * @note This updates the information contained in the parent(s)

     * (if the parent is different object that this class object)

     * in addition to the counter information contained for this

     * class object.

     *

     * @return The number of internal references to the object

     * after the release.

     * Internal reference counts are meant to be used when the

     * counter info is want to be hidden from the API user.

     */

    TInt InternalRelease();

    /**

     * @note This gives the information contained in the top parent

     * (if the parent is different object that this class object).

     *

     * @return The number of internal references to the object.

     * Internal reference counts are meant to be used when the

     * counter info is want to be hidden from the API user.

     */

    TInt InternalRefCount() const;

    /**

     * @note This information is this class object specific.

     * (does not forward the request to the top parent).

     *

     * @return The total number of references to the object

     * This contains the internal and external counts.

     */

    TInt MyTotalRefCount() const;

    /**

     * @note This information is this class object specific

     * (does not forward the request to the top parent).

     *

     * @return The number of API references to the object.

     */

    TInt MyRefCount() const;

    /**

     * @note This information is this class object specific

     * (does not forward the request to the top parent).

     *

     * @return The number of internal references to the object.

     * Internal reference counts are meant to be used when the

     * counter info is want to be hidden from the API user.

     */

    TInt MyInternalRefCount() const;

public: // MCatalogsBase

    /**

     * @see MCatalogsBase::AddRef

     */

    virtual TInt AddRef() const;

    /**

     * @see MCatalogsBase::Release

     */

    virtual TInt Release() const;

    /**

     * @see MCatalogsBase::RefCount

     */

    virtual TInt RefCount() const;

protected: // MCatalogsBase

    /**

     * @see MCatalogsBase::QueryInterfaceL

     */

    virtual const TAny* QueryInterfaceL( TInt aInterfaceType ) const;

protected:

    /**

     * Constructor

     *

     * Because this class is meant to be a parent instead

     * of an object class itself. The constructor is protected.

     * So, the objects should be created from the child classes.

     *

     * @param aParent If NULL this object does not have parent.

     * Ownership is not transferred.

     */

    CCatalogsInterfaceBase( CCatalogsInterfaceBase* aParent );

private:

    // Prevent

    CCatalogsInterfaceBase( const CCatalogsInterfaceBase& aObject );

    CCatalogsInterfaceBase& operator =( const CCatalogsInterfaceBase& aObject );

private: // data

    // If NULL then this class object does not have parent.

    // Notice that the parent here does not necessarily mean same as the

    // owner of the class. The parent means the object that contains

    // the registered interfaces and reference counts of all the objects

    // that have set the parent as their parent.

    CCatalogsInterfaceBase* iParent;

    // This counter knows how many times the interfaces of this class

    // has been queried from ui.

    // Notice, that the total counter is set to zero when an object is created.

    // When Release is called, the object will be deleted if the ref count

    // is zero or less.

    mutable TInt iRefCount;

    TInt iInternalRefCount;

    // This list will contain pointers to the interfaces

    // that are identified by interface uid.

    // QueryInterface-functions check the right pointers

    // from this list.

    RPointerArray<CCatalogsInterfaceIdentifier> iInterfaces;     

    };

#endif // CATALOGS_INTERFACE_BASE_H