/*

* Copyright (c) 2004 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:  Key - value container.

*

*/

#ifndef __CVIMPSTSETTINGSKEYVALUEPAIR_H

#define __CVIMPSTSETTINGSKEYVALUEPAIR_H

//  INCLUDES

#include <e32base.h>

#include <s32strm.h>

// CLASS DECLARATION

/**

 * Key - value container.

 * Can be derived to expand services.

 *

 * @since 3.0

 **/

NONSHARABLE_CLASS( CVIMPSTSettingsKeyValuePair ): public CBase

    {

    public:  // Enumerations

        /**

         * Data type enumeration.

         * List supported value data types.

         * @since 3.0

         **/

        enum TValueType

            {

            EValueTypeNone = 0,            

            EValueTypeDesC16

            };

    public:  // Constructors and destructor

        /**

         * Non leaving two phased constructor.

         *

         * If object allocation fails, returns NULL.

         *

         * @since 3.0

         * @param aKey The key.

         */

        static CVIMPSTSettingsKeyValuePair* New( const TDesC& aKey );

        /**

         * Two phased constructor initializing object state

         * from given flat descriptor.

         *

         * @since 3.0

         * @param aKeyValuePairFlat The flat representation of key-value pair

         */

		static CVIMPSTSettingsKeyValuePair* NewLC( const TDesC& aKeyValuePairFlat );

        /**

         * Destructor.

         */

        virtual ~CVIMPSTSettingsKeyValuePair();

    protected:  // Constructor

        /**

         * C++ default constructor.

         */

        CVIMPSTSettingsKeyValuePair();

        /**

         * Symbian OS constructor.

         * Initializes object state from given stream.

         *

         * @since 3.0

         * @param aStream The stream to read object state.

         */

        void ConstructL( RReadStream& aStream );

    public:  //Data access

        /**

         * Key accessor.

         *

         * Gets the key associated with key-value object.

         * Virtual to allow derived classes to expand behaviour.

         *

         * @since 3.0

         * @return The key.

         */

        virtual const TDesC& Key() const;

        /**

         * Data setters.

         *

         *

         * @since 3.0

         * @param aValue The value to assign for key-value object.

         * @return Error code. One of following:

         * KErrNone: Value assigned/updated succesfully.

         * KErrGeneral: Different data type already assigned.

         * KErrNoMemory: No memory to allocate the new value.

         * Original value remains if assigning new value fails.

         */

        TInt SetValue( const TDesC16& aValue );

        /**

         * Data getters.

         *

         *

         * @since 3.0

         * @param aValue The value to get.

         * @return Error code. One of following:

         * KErrNone: Value read succesfully.

         * KErrNotFound: No value yet assigned.

         * KErrGeneral: Different data type assigned.

         * Given aValue isn't changed if reading fails.

         */    

        TInt GetValue( TPtrC16& aValue ) const;

		/**

         * Key-Value pair flat representation

         *

         * Creates flat representation of the key-value pair

         * and pushes it in cleanup stack.

         * Ownership is transferred to calling method.

         *

         * @since 3.0

         * @return The flat representation of key-value pair

         */

		HBufC* KeyValuePairFlatLC();

		/**

		 * Checks if the data fits in the flat

		 * descriptor

		 *

		 * @since 3.0

		 * @return ETrue if data is too big.

		 */

		TBool IsDataTooBig() const;

		/**

		 * Approximates the value pair data size

		 * in decimal textual representation

		 *

		 * @since 3.0

		 * @return The value pair data size.

		 */

		TInt DataSizeDec() const;

    private:    // Help functions

        /**

         * Resets the value pair data.

         * @since 3.0

         */

        void Reset();

        /**

         * Parses value pair data from flat descriptor.

         * @param aKeyValuePairFlat flat descriptor to parse

         * @since 3.0

         */

        void ParseFlatKeyValuePairL( const TDesC& aKeyValuePairFlat );

    private:    // Data

        HBufC16*        iKey;           //OWN: The key.

        TValueType      iValueType;     //OWN: The value type.

        union                           //OWN: The value. Value type is determined from iValueType.

            {

            TInt        iInt;

            HBufC8*     iBuf8;

            HBufC16*    iBuf16;

            };

    };

#endif      // __CVIMPSTSETTINGSKEYVALUEPAIR_H

//  End of File