/*

* Copyright (c) 2006-2008 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:   Definition of ncdattributes interface and

*                implementation class.

*

*/

#ifndef C_NCDATTRIBUTES_H

#define C_NCDATTRIBUTES_H

#include <e32base.h>

#include "ncdpanics.h"

class RWriteStream;

class RReadStream;

/**

 * Simple attribute container

 *

 * Used for setting, getting, storing and loading simple

 * attributes. Currently supports 16-bit descriptors and TInt32

 */

class CNcdAttributes : public CBase

    {

public:

    /**

     * Types of supported attributes

     */

    enum TAttributeType 

        {

        /**

         * Attribute type is not set

         */

        EAttributeTypeUndefined = 0,

        /**

         * Attribute is TInt32

         */

        EAttributeTypeInt32,

        /**

         * Attribute is a 16-bit descriptor

         */

        EAttributeTypeString16

        };

public:

    /**

     * @param aUpperLimit Upper attribute limit is NOT included in the range. Must be >= 0 and > aLowerLimit

     *

     */

    IMPORT_C static CNcdAttributes* NewL( TInt aUpperLimit, TInt aLowerLimit = 0 );

    /**

     * @note If given upperlimit differs from the one read from the stream then

     * the attribute range is adjusted for the given limit.

     * @leave KErrArgument if aLowerLimit differs from the lower limit read from the stream

     */

    IMPORT_C static CNcdAttributes* NewL( 

        RReadStream& aStream,

        TInt aUpperLimit, 

        TInt aLowerLimit = 0 );

    /**

     * Copy constructor

     */

    IMPORT_C static CNcdAttributes* NewL( const CNcdAttributes& aAttributes );

    /**

     * Destructor

     */

    IMPORT_C virtual ~CNcdAttributes();

public:

    /**

     * Lower limit getter

     */

    IMPORT_C TInt RangeLowerLimit() const;

    /**

     * Upper limit getter

     */

    IMPORT_C TInt RangeUpperLimit() const;

    /**

     * TInt32 attribute setter

     *

     * @param aAttribute Attribute

     * @param aValue Value     

     * @panic ENcdPanicIndexOutOfRange if aAttribute is not 

     * RangeLowerLimit() <= aAttribute < RangeUpperLimit()

     * @panic ENcdPanicInvalidArgument if the attribute type is not 

     * EAttributeTypeInt32 or EAttributeTypeUndefined

     */

    IMPORT_C void SetAttributeL( TInt aAttribute, TInt32 aValue );

    /**

     * 16-bit descriptor attribute setter

     *

     * @param aAttribute Attribute

     * @param aValue Value

     * @leave KErrNoMemory if memory runs out

     * @panic ENcdPanicIndexOutOfRange if aAttribute is not 

     * RangeLowerLimit() <= aAttribute < RangeUpperLimit()

     * @panic ENcdPanicInvalidArgument if the attribute type is not 

     * EAttributeTypeString16 or EAttributeTypeUndefined

     */

    IMPORT_C void SetAttributeL( TInt aAttribute, const TDesC& aValue );

    /**

     * 16-bit descriptor attribute getter

     *

     * @param aAttribute Attribute

     * @return Value of the attribute

     * @panic ENcdPanicIndexOutOfRange if aAttribute is not 

     * RangeLowerLimit() <= aAttribute < RangeUpperLimit()

     * @panic ENcdPanicInvalidArgument if the attribute type is not 

     * EAttributeTypeString16

     */

    IMPORT_C const TDesC& AttributeString16( TInt aAttribute ) const;

    /**

     * TInt32 attribute getter

     *

     * @param aAttribute Attribute

     * @return Value of the attribute

     * @panic ENcdPanicIndexOutOfRange if aAttribute is not 

     * RangeLowerLimit() <= aAttribute < RangeUpperLimit()

     * @panic ENcdPanicInvalidArgument if the attribute type is not 

     * EAttributeTypeInt32

     */

    IMPORT_C TInt32 AttributeInt32( TInt aAttribute ) const;

    /**

     * Attribute type getter

     * 

     * @param aAttribute

     * @return Attribute type

     * @panic ENcdPanicIndexOutOfRange if aAttribute is not 

     * RangeLowerLimit() <= aAttribute < RangeUpperLimit()

     */

    IMPORT_C TAttributeType AttributeType( TInt aAttribute ) const;

public:

    IMPORT_C void ExternalizeL( RWriteStream& aStream ) const;

    IMPORT_C void InternalizeL( RReadStream& aStream );

protected:

    // Union that contains all possible attribute types

    union TAttributeUnion 

        {

        HBufC* iString16;

        TInt32 iInt32;

        };

    // Attribute 

    struct TAttribute

        {

        TAttributeType iType;

        TAttributeUnion iAttribute;

        TAttribute() : iType( EAttributeTypeUndefined )

            {            

            iAttribute.iString16 = NULL;

            }            

        };

protected:

    CNcdAttributes( TInt aUpperLimit, TInt aLowerLimit );

    void ConstructL();

    void ConstructL( const CNcdAttributes& aAttributes );

    // Deletes all attributes, array size is reduced to 0

    void ClearAttributes();

    // Deletes all attributes and resets the array to have

    // room for the attribute range, array size == ArraySize()

    void ResetAttributesL();

    // Size needed for containing the attribute range

    TInt ArraySize() const;

    // Attribute externalization and internalization

    void ExternalizeAttributeL( 

        const TAttribute& aAttribute, RWriteStream& aStream ) const;

    TAttribute InternalizeAttributeL( RReadStream& aStream ) const;

    // Deletes attribute's internals

    void DeleteAttribute( TAttribute& aAttribute );

    // Copies attribute's internals and returns the copy

    TAttribute CopyAttributeL( const TAttribute& aAttribute ) const;

    // Indexing methods

    const TAttribute& Attribute( TInt aAttribute ) const;    

    TAttribute& Attribute( TInt aAttribute );

private:

    CNcdAttributes( const CNcdAttributes& );

    CNcdAttributes& operator=( const CNcdAttributes& );

private:

    TInt iLowerLimit;

    TInt iUpperLimit;

    // Attribute array

    RArray<TAttribute> iAttributes;

    };

#endif // M_NCDATTRIBUTES_H