1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Contains CCatalogsInterfacebase class

    15 *

    16 */

    17 

    18 

    19 #ifndef CATALOGS_INTERFACE_BASE_H

    20 #define CATALOGS_INTERFACE_BASE_H

    21 

    22 

    23 #include <e32base.h>

    24 #include <e32cmn.h>

    25 

    26 #include "catalogsbase.h"

    27 #include "catalogsinterfaceids.h"

    28 

    29 

    30 class CCatalogsInterfaceIdentifier;

    31 

    32 

    33 /**

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

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

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

    37  *

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

    39  * One is for the top parent reference counter. 

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

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

    42  * its children and their children, etc.. 

    43  * My-reference counter functions give the child reference 

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

    45  * etc.. 

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

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

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

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

    50  * for them.

    51  */

    52 class CCatalogsInterfaceBase: public CBase,

    53                               public virtual MCatalogsBase

    54     {

    55 public:

    56 

    57     /**

    58      * Destructor

    59      *

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

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

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

    63      * separately the objects that it owns.

    64      */

    65     virtual ~CCatalogsInterfaceBase();

    66 

    67 

    68     /**

    69      * Sets the new parent for this class object.

    70      *

    71      * If the given parent is same as this,

    72      * then nothing is done. 

    73      

    74      * The reference counters of the new parent 

    75      * are increased according to the counters of this object.

    76      *

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

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

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

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

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

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

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

    84      * to its own top parent.

    85      *

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

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

    88      * be the interfaces of this class object. 

    89      *

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

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

    92      * Ownership is not transferred.

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

    94      * a top parent when this function is called.

    95      */

    96     void SetParentL( CCatalogsInterfaceBase* aParent );

    97 

    98     /**

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

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

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

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

   103      *

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

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

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

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

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

   109      * obsolete references will most likely crash the program.

   110      *

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

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

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

   114      */

   115     void RemoveFromParent(); 

   116      

   117     /**

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

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

   120      * object is removed and replaced by the new object.

   121      *

   122      * @param aInterface Interface infromation that is inserted to the

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

   124      * implements an interface that is requested by using QueryInterface

   125      * functions. Ownership is transferred.

   126      */

   127     void AddInterfaceL( CCatalogsInterfaceIdentifier* aInterface );

   128     

   129     /**

   130      * Finds the interface from the interface register list

   131      * according to the given interface id and removes

   132      * the interface.

   133      *

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

   135      * registered interface from the interface list.

   136      */

   137     void RemoveInterface( TInt aId );

   138 

   139 

   140     /**

   141      * @note This information is gotten from the top parent

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

   143      *

   144      * @return The total number of references to the object

   145      * This contains the internal and external counts.

   146      */

   147     TInt TotalRefCount() const;

   148 

   149     

   150     /**

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

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

   153      *

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

   155      * after the addition.

   156      * Internal reference counts are meant to be used when the

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

   158      */

   159     TInt InternalAddRef();

   160 

   161     /**

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

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

   164      * in addition to the counter information contained for this

   165      * class object.

   166      *

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

   168      * after the release.

   169      * Internal reference counts are meant to be used when the

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

   171      */

   172     TInt InternalRelease();

   173 

   174     /**

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

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

   177      *

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

   179      * Internal reference counts are meant to be used when the

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

   181      */

   182     TInt InternalRefCount() const;

   183 

   184 

   185     /**

   186      * @note This information is this class object specific.

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

   188      *

   189      * @return The total number of references to the object

   190      * This contains the internal and external counts.

   191      */

   192     TInt MyTotalRefCount() const;

   193         

   194     /**

   195      * @note This information is this class object specific

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

   197      *

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

   199      */

   200     TInt MyRefCount() const;

   201 

   202     /**

   203      * @note This information is this class object specific

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

   205      *

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

   207      * Internal reference counts are meant to be used when the

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

   209      */

   210     TInt MyInternalRefCount() const;

   211 

   212 

   213 public: // MCatalogsBase

   214 

   215     /**

   216      * @see MCatalogsBase::AddRef

   217      */

   218     virtual TInt AddRef() const;

   219     

   220     

   221     /**

   222      * @see MCatalogsBase::Release

   223      */

   224     virtual TInt Release() const;

   225     

   226     

   227     /**

   228      * @see MCatalogsBase::RefCount

   229      */

   230     virtual TInt RefCount() const;

   231 

   232 

   233 protected: // MCatalogsBase

   234 

   235     /**

   236      * @see MCatalogsBase::QueryInterfaceL

   237      */

   238     virtual const TAny* QueryInterfaceL( TInt aInterfaceType ) const;

   239 

   240 

   241 protected:

   242 

   243     /**

   244      * Constructor

   245      *

   246      * Because this class is meant to be a parent instead

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

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

   249      *

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

   251      * Ownership is not transferred.

   252      */

   253     CCatalogsInterfaceBase( CCatalogsInterfaceBase* aParent );

   254  

   255 

   256 private:

   257     // Prevent

   258     CCatalogsInterfaceBase( const CCatalogsInterfaceBase& aObject );

   259     CCatalogsInterfaceBase& operator =( const CCatalogsInterfaceBase& aObject );

   260 

   261 

   262 private: // data

   263 

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

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

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

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

   268     // that have set the parent as their parent.

   269     CCatalogsInterfaceBase* iParent;

   270     

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

   272     // has been queried from ui.

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

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

   275     // is zero or less.

   276     mutable TInt iRefCount;

   277     TInt iInternalRefCount;

   278     

   279     // This list will contain pointers to the interfaces

   280     // that are identified by interface uid.

   281     // QueryInterface-functions check the right pointers

   282     // from this list.

   283     RPointerArray<CCatalogsInterfaceIdentifier> iInterfaces;     

   284 

   285     };

   286 

   287 #endif // CATALOGS_INTERFACE_BASE_H