diff -r 000000000000 -r ba25891c3a9e ncdengine/engine/inc/catalogsinterfacebase.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ncdengine/engine/inc/catalogsinterfacebase.h Thu Dec 17 08:51:10 2009 +0200 @@ -0,0 +1,287 @@ +/* +* 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 +#include + +#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 iInterfaces; + + }; + +#endif // CATALOGS_INTERFACE_BASE_H