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


#ifndef M_CATALOGS_BASE_H
#define M_CATALOGS_BASE_H

#include <e32cmn.h>
#include "catalogsinterfaceids.h"

/**
 *  This interface provides functions for querying the interfaces that
 *  a class implements. Also, functions for reference counter are provided.
 *  The reference counter is used to keep track of the number of users
 *  of the implemented class. 
 *
 *  
 */
class MCatalogsBase
    {
    
public:
 
    /**
     * KInterfaceUid defines the identifier for this interface.
     * Child interfaces should define their own unique values for their
     * KInterfaceUid.
     *
     * 
     */
    enum { KInterfaceUid = ECatalogsBaseUid };


    /**
     * This function is used to test if this object contains an implementation of
     * the interface of the given type.
     *
     * If the object contains the interface, a pointer to it is returned, and
     * the reference count is increased by one. Otherwise, NULL is returned.
     *
     * @note This interface does not allow the user to delete object directly 
     * (destructor is protected). The destruction of this object should be done 
     * by calling Release-function.
     *
     * A template shorthand version is provided here, making the usage easier.
     * An example of using the template method:
     * MWantedInterface* object = 
     *      someObjectInheritedFromMCatalogBase->QueryInterfaceL< MWantedInterface >();
     *
     * 
     * @return Pointer to the object's interface, if the object implements the given
     *  interface, NULL otherwise. Counted, Release() must be called after use.
     * @see MCatalogsBase::QueryInterfaceLC
     */
    template< class T >
    inline T* QueryInterfaceL()
        {
        const MCatalogsBase* self = this;
        const TAny* interface = self->QueryInterfaceL( T::KInterfaceUid );
        return const_cast< T* >( static_cast< const T* >( interface ) );
        }
    
    /**
     * This is const version of QueryInterfaceL.
     * 
     */
    template< class T >
    inline const T* QueryInterfaceL() const
        {      
        return static_cast< const T* >( QueryInterfaceL( T::KInterfaceUid ) );
        }

    /**
     * Like QueryInterfaceL, tries to retrieve an interface of specified type
     * from the object. If the interface pointer is returned, it is appended
     * to the cleanup stack, so that a following CleanupStack::PopAndDestroy()
     * will call Release() on the interface pointer appropriately.
     *
     * @return Pointer to the object's interface, if the object implements
     * the given interface, or NULL if this object does not implement the
     * given interface. If NULL is returned then the object is not pushed to
     * the cleanupstack. 
     *
     * 
     * @return Pointer to the object's interface, if the object implements the given
     *  interface, NULL otherwise. Returned non-NULL pointer reference is counted, must
     *  be released with a call to CleanupStack::PopAndDestroy().
     * @see MCatalogsBase::QueryInterfaceL
     */ 
    template< class T >
    inline T* QueryInterfaceLC()
        {
        T* interface( QueryInterfaceL< T >() );
        if ( interface )
            {
            // Do not push NULL object into the cleanup stack.
            CleanupReleasePushL( *interface );        
            }
        return interface;
        }

    /**
     * This is const version of QueryInterfaceLC.
     * 
     */
    template< class T >
    inline const T* QueryInterfaceLC() const
        {
        const T* interface( QueryInterfaceL< const T >() );
        if ( interface )
            {
            // Do not push NULL object into the cleanup stack.
            CleanupReleasePushL( *const_cast<T*>( interface ) );        
            }
        return interface;
        }
    
    /**
     * Increments the reference counter.
     *
     * @note QueryInterfaceL() already increases the value by one
     *  if interface check was successfull. This function may be used
     *  if user knows that the interface is used in multiple places and
     *  Release() is called accordingly.
     *
     * 
     * @return New reference count value. For debug purposes only.
     */
    virtual TInt AddRef() const = 0;		
    
    /**
     * Releases a reference. Deletes the object if the reference count
     * reaches 0. 
     * Notice that destructor is defined as protected. So, the object of
     * this interface can be deleted using this function and only after 
     * reference count is zero.
     *
     * 
     * @return Reference count after release. For debug purposes only.
     */
    virtual TInt Release() const = 0;
    
    
protected:

    /**
     * QueryInterfaceL
     *
     * This function is used to test if this object contains an implementation of
     * the interface of the given type.
     * If the object contains the interface, then the reference count is increased
     * by one.
     *
     * 
     * @param aInterfaceType TInt that specifies the interface that this object should implement.
     * @return Pointer to this object if the object implements given interface 
     * or NULL if this object does not implement the given interface. Counted, Release() must
     * be called after use.
     */
    virtual const TAny* QueryInterfaceL( TInt aInterfaceType ) const = 0;
    

    /**
     * The destructor of an interface is set virtual to make sure that
     * the destructors of derived classes are called appropriately when the
     * object is destroyed.
     *
     * Destructors for MCatalogsBase and all derived interfaces are defined as
     * protected to prevent direct use of delete on interface pointers (Release()
     * must be called instead of delete).
     *
     * 
     */
    virtual ~MCatalogsBase() {}

    };

#endif // M_CATALOGS_BASE_H