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 MCatalogsBase interface

    15 *

    16 */

    17 

    18 

    19 #ifndef M_CATALOGS_BASE_H

    20 #define M_CATALOGS_BASE_H

    21 

    22 #include <e32cmn.h>

    23 #include "catalogsinterfaceids.h"

    24 

    25 /**

    26  *  This interface provides functions for querying the interfaces that

    27  *  a class implements. Also, functions for reference counter are provided.

    28  *  The reference counter is used to keep track of the number of users

    29  *  of the implemented class. 

    30  *

    31  *  

    32  */

    33 class MCatalogsBase

    34     {

    35     

    36 public:

    37  

    38     /**

    39      * KInterfaceUid defines the identifier for this interface.

    40      * Child interfaces should define their own unique values for their

    41      * KInterfaceUid.

    42      *

    43      * 

    44      */

    45     enum { KInterfaceUid = ECatalogsBaseUid };

    46 

    47 

    48     /**

    49      * This function is used to test if this object contains an implementation of

    50      * the interface of the given type.

    51      *

    52      * If the object contains the interface, a pointer to it is returned, and

    53      * the reference count is increased by one. Otherwise, NULL is returned.

    54      *

    55      * @note This interface does not allow the user to delete object directly 

    56      * (destructor is protected). The destruction of this object should be done 

    57      * by calling Release-function.

    58      *

    59      * A template shorthand version is provided here, making the usage easier.

    60      * An example of using the template method:

    61      * MWantedInterface* object = 

    62      *      someObjectInheritedFromMCatalogBase->QueryInterfaceL< MWantedInterface >();

    63      *

    64      * 

    65      * @return Pointer to the object's interface, if the object implements the given

    66      *  interface, NULL otherwise. Counted, Release() must be called after use.

    67      * @see MCatalogsBase::QueryInterfaceLC

    68      */

    69     template< class T >

    70     inline T* QueryInterfaceL()

    71         {

    72         const MCatalogsBase* self = this;

    73         const TAny* interface = self->QueryInterfaceL( T::KInterfaceUid );

    74         return const_cast< T* >( static_cast< const T* >( interface ) );

    75         }

    76     

    77     /**

    78      * This is const version of QueryInterfaceL.

    79      * 

    80      */

    81     template< class T >

    82     inline const T* QueryInterfaceL() const

    83         {      

    84         return static_cast< const T* >( QueryInterfaceL( T::KInterfaceUid ) );

    85         }

    86 

    87     /**

    88      * Like QueryInterfaceL, tries to retrieve an interface of specified type

    89      * from the object. If the interface pointer is returned, it is appended

    90      * to the cleanup stack, so that a following CleanupStack::PopAndDestroy()

    91      * will call Release() on the interface pointer appropriately.

    92      *

    93      * @return Pointer to the object's interface, if the object implements

    94      * the given interface, or NULL if this object does not implement the

    95      * given interface. If NULL is returned then the object is not pushed to

    96      * the cleanupstack. 

    97      *

    98      * 

    99      * @return Pointer to the object's interface, if the object implements the given

   100      *  interface, NULL otherwise. Returned non-NULL pointer reference is counted, must

   101      *  be released with a call to CleanupStack::PopAndDestroy().

   102      * @see MCatalogsBase::QueryInterfaceL

   103      */ 

   104     template< class T >

   105     inline T* QueryInterfaceLC()

   106         {

   107         T* interface( QueryInterfaceL< T >() );

   108         if ( interface )

   109             {

   110             // Do not push NULL object into the cleanup stack.

   111             CleanupReleasePushL( *interface );        

   112             }

   113         return interface;

   114         }

   115 

   116     /**

   117      * This is const version of QueryInterfaceLC.

   118      * 

   119      */

   120     template< class T >

   121     inline const T* QueryInterfaceLC() const

   122         {

   123         const T* interface( QueryInterfaceL< const T >() );

   124         if ( interface )

   125             {

   126             // Do not push NULL object into the cleanup stack.

   127             CleanupReleasePushL( *const_cast<T*>( interface ) );        

   128             }

   129         return interface;

   130         }

   131     

   132     /**

   133      * Increments the reference counter.

   134      *

   135      * @note QueryInterfaceL() already increases the value by one

   136      *  if interface check was successfull. This function may be used

   137      *  if user knows that the interface is used in multiple places and

   138      *  Release() is called accordingly.

   139      *

   140      * 

   141      * @return New reference count value. For debug purposes only.

   142      */

   143     virtual TInt AddRef() const = 0;		

   144     

   145     /**

   146      * Releases a reference. Deletes the object if the reference count

   147      * reaches 0. 

   148      * Notice that destructor is defined as protected. So, the object of

   149      * this interface can be deleted using this function and only after 

   150      * reference count is zero.

   151      *

   152      * 

   153      * @return Reference count after release. For debug purposes only.

   154      */

   155     virtual TInt Release() const = 0;

   156     

   157     

   158 protected:

   159 

   160     /**

   161      * QueryInterfaceL

   162      *

   163      * This function is used to test if this object contains an implementation of

   164      * the interface of the given type.

   165      * If the object contains the interface, then the reference count is increased

   166      * by one.

   167      *

   168      * 

   169      * @param aInterfaceType TInt that specifies the interface that this object should implement.

   170      * @return Pointer to this object if the object implements given interface 

   171      * or NULL if this object does not implement the given interface. Counted, Release() must

   172      * be called after use.

   173      */

   174     virtual const TAny* QueryInterfaceL( TInt aInterfaceType ) const = 0;

   175     

   176 

   177     /**

   178      * The destructor of an interface is set virtual to make sure that

   179      * the destructors of derived classes are called appropriately when the

   180      * object is destroyed.

   181      *

   182      * Destructors for MCatalogsBase and all derived interfaces are defined as

   183      * protected to prevent direct use of delete on interface pointers (Release()

   184      * must be called instead of delete).

   185      *

   186      * 

   187      */

   188     virtual ~MCatalogsBase() {}

   189 

   190     };

   191 

   192 #endif // M_CATALOGS_BASE_H