// Copyright (c) 2005-2009 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:
// ss_rmetaextensioncontainer.h
// 

/**
@file
@prototype 
@publishedPartner 
*/

#ifndef SYMBIAN_SS_RMETAEXTENSIONCONTAINER
#define SYMBIAN_SS_RMETAEXTENSIONCONTAINER

#include <e32cmn.h>
#include <elements/metadata.h>


#ifdef MEC_UNITTEST
class TMetaExtensionContainerSpy;
#endif

namespace ESock
{

class CMetaExtensionContainerImplBase;
class CMetaExtensionContainer;
class CMetaExtensionContainerArray;
class TMetaExtensionContainerMetaType;


enum TMecPanic
    {
    ENoImplementation = 1,      // No implementation opened for the RMEC instance
    EInvalidSelfReference = 2,  // Trying to open an RMEC using itself as the source RMEC 
    EAlreadyOpen = 3,           // Trying to open a reference against a new RMEC without closing this one
    EUsingEmptyContainer = 4,   // An explicit attempt was made to open an RMEC which was created with no extensions (wasteful - RMECs should always hold something of value)
    EIllegalState = 5, 			// Should never happen. Indicates bad logic or bad code.
    };

/**
Represents a read only meta extension container.

@prototype
@publishedPartner
*/
class RMetaExtensionContainerC
	{
#ifdef MEC_UNITTEST
	friend class ::TMetaExtensionContainerSpy;
#endif
	friend class ESock::TMetaExtensionContainerMetaType;

public:
    /**
    Default c'tor. 
    */
    IMPORT_C RMetaExtensionContainerC();
    
    /**
    D'tor
    */
    IMPORT_C ~RMetaExtensionContainerC();

    /**
    Opens a reference against a specific container. This RMetaExtensionContainerC must not be open already.
    @param aSource Container to open this instance against. A reference will be automatically added to the source container.
    */
    IMPORT_C void Open(const RMetaExtensionContainerC& aSource);
    
    /**
	Releases a reference to the underlying container implementation
	*/
	IMPORT_C void Close();

	/**
	Finds the extension specified within the container
	@param aTypeId The STypeId of the meta extension to find
	@return A pointer to the meta extension or NULL if it wasn't found
	*/
	IMPORT_C const Meta::SMetaData* FindExtension(const Meta::STypeId& aTypeId) const;

	/**
	Finds the extension specified within the container
	@param aTypeId The STypeId of the meta extension to find
	@return A reference to the meta extension
	@exception Leaves with KErrNotFound if the meta extension was not present in the container
	*/
	IMPORT_C const Meta::SMetaData& FindExtensionL(const Meta::STypeId& aTypeId) const;
	
protected:
    /**
    Opens an additional reference to the underlying container implementation.
    */
    IMPORT_C void Open();

    /**
	Returns a pointer to the container implementation being represented by this interface
	@internalTechnology
	*/
	inline CMetaExtensionContainerImplBase* Container() const;

	/**
	Sets the initial container implementation to be represented by this interface
	@internalTechnology
	*/
	inline void SetContainer(CMetaExtensionContainerImplBase* aContainer);
        
private:
	// A pointer to the container implementation
	mutable CMetaExtensionContainerImplBase* iContainerImpl;
	};


/**
Represents an appendable meta extension container.
@prototype
@publishedPartner
*/
class RMetaExtensionContainer : public RMetaExtensionContainerC
	{
#ifdef MEC_UNITTEST
    friend class ::TMetaExtensionContainerSpy;
#endif

public:
    /**
    Default c'tor
    */
    IMPORT_C RMetaExtensionContainer();
    
    /**
    If the container is already open a reference is added to the container.
    If the container is not open a new appendable root meta extension container will be created and a reference added.
    */
    IMPORT_C void Open();

    /**
    A new appendable meta extension container will be created using the supplied container as the base container to build on.
	The container must not already be open.
	@param aBaseContainer Container to use as the base meta extension container. A reference will be automatically added to this.
	*/
	IMPORT_C void Open(const RMetaExtensionContainerC& aBaseContainer);
	
    /**
    Releases a reference to the underlying container implementation
    */
    IMPORT_C void Close();
    
	/**
	Finds the extension specified within the container
	@param aTypeId The STypeId of the meta extension to find
	@return A pointer to the meta extension or NULL if it wasn't found
	*/
	IMPORT_C const Meta::SMetaData* FindExtension(const Meta::STypeId& aTypeId) const;

	/**
	Finds the extension specified within the container
	@param aTypeId The STypeId of the meta extension to find
	@return A reference to the meta extension
	@exception Leaves with KErrNotFound if the meta extension was not present in the container
	*/
	IMPORT_C const Meta::SMetaData& FindExtensionL(const Meta::STypeId& aTypeId) const;
	
	/**
	Adds a meta extension to the container, which will take ownership on success.
	@param aExtension The meta extension to add
	@return KErrAlreadyExists If a meta extension of the same type is in the container
			KErrNone If the meta extension was added successfully
			Other system-wide error codes
	*/
	IMPORT_C TInt AppendExtension(const Meta::SMetaData* aExtension);

	/**
	Adds a meta extension to the container, which will take ownership on success.
	@param aExtension The meta extension to add
	@exception Leaves with KErrAlreadyExists If a meta extension of the same type is in the container,
			or other system-wide error codes
	*/
	IMPORT_C void AppendExtensionL(const Meta::SMetaData* aExtension);

	/**
	Appends a container to the list of container implementations.
	@aBaseContainer Appends an existing container. Extensions in aBaseContainer container will override
	any extensions of the same type already present in the container this method is called on.
	@exception Leaves with KErrNone on success, 
			KErrAlreadyExists if the container is already present, 
			or any other system-wide error code.
	*/
	IMPORT_C void AppendContainerL(const RMetaExtensionContainerC& aBaseContainer);

private:
	/**
	@return Returns an implementation of an appendable extension container instance or
	NULL if one isn't available at present
	*/
	CMetaExtensionContainer* AppendableExtensionContainer() const;
	
	/**
	@return Returns an implementation of an appendable container array instance or
	NULL if one isn't available at present
	*/
	CMetaExtensionContainerArray* AppendableContainerArray() const;

	/**
    Creates a new container implementations
    @exception Any system wide error code
    */
    void CreateExtensionContainerL();

	/**
    Creates a new container implementations
    @exception Any system wide error code
    */
    void CreateContainerArrayL();

private:
    TBool iIsLazyCreationDone:1; // Used for lazy creation of the container impl.
	TBool iIsOpen:1;
    mutable CMetaExtensionContainer* iCurrentExtensionContainer;	// Not owned
	};



/**
@internalTechnology
*/
CMetaExtensionContainerImplBase* RMetaExtensionContainerC::Container() const
	{
	return iContainerImpl;
    }


/**
@internalTechnology
*/
inline void RMetaExtensionContainerC::SetContainer(CMetaExtensionContainerImplBase* aContainer)
	{
	ASSERT(aContainer);		 // Don't allow setting it to NULL
	iContainerImpl = aContainer;
	}



} // namespace ESock

#endif
// SYMBIAN_SS_RMETAEXTENSIONCONTAINER