--- /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 <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