/*
* 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 __CIMPSSAPKEYVALUEPAIR_H
#define __CIMPSSAPKEYVALUEPAIR_H

//  INCLUDES
#include <e32base.h>
#include <s32strm.h>

// CLASS DECLARATION
/**
 * Key - value container.
 * Can be derived to expand services.
 *
 * @since 3.0
 **/
NONSHARABLE_CLASS( CIMPSSAPKeyValuePair ): public CBase
    {
public:  // Enumerations

    /**
     * Data type enumeration.
     * List supported value data types.
     * @since 3.0
     **/
    enum TValueType
        {
        EValueTypeNone = 0,
        EValueTypeInt,
        EValueTypeDesC8,
        EValueTypeDesC16
        };


public:  // Constructors and destructor

    /**
     * Non leaving two phased constructor.
     *
     * If object allocation fails, returns NULL.
     *
     * @since 3.0
     * @param aKey The key.
     */
    static CIMPSSAPKeyValuePair* New( const TDesC& aKey );

    /**
     * Two phased constructor initializing object state
     * from the stream.
     *
     * @since 3.0
     * @param aStream The stream to read object state.
     */
    static CIMPSSAPKeyValuePair* NewLC( RReadStream& aStream );

    /**
     * Two phased constructor initializing object state
     * from given flat descriptor.
     *
     * @since 3.0
     * @param aKeyValuePairFlat The flat representation of key-value pair
     */

    static CIMPSSAPKeyValuePair* NewLC( const TDesC& aKeyValuePairFlat );

    /**
     * Destructor.
     */
    virtual ~CIMPSSAPKeyValuePair();



protected:  // Constructor

    /**
     * C++ default constructor.
     */
    CIMPSSAPKeyValuePair();


    /**
     * 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.
     *
     * Overloaded to support integer type and
     * narrow and wide descriptors.
     *
     * @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( TInt aValue );
    TInt SetValue( const TDesC8& aValue );
    TInt SetValue( const TDesC16& aValue );


    /**
     * Data getters.
     *
     * Overloaded to support integer type and
     * narrow and wide descriptors.
     *
     * @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( TInt& aValue ) const;
    TInt GetValue( TPtrC8& aValue ) const;
    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();


public:  // Streaming support


    /**
     * Externalises the value pair to given stream.
     *
     * @since 3.0
     * @param aStream stream to write to.
     */
    void ExternalizeL( RWriteStream& aStream ) const;


    /**
     * Approximates the value pair data size.
     *
     * @since 3.0
     * @return The value pair data size.
     */
    TInt DataSize() const;

    /**
     * Approximates the value pair data size
     * in decimal textual representation
     *
     * @since 3.0
     * @return The value pair data size.
     */
    TInt DataSizeDec() const;

    /**
    * Checks if the data fits in the flat
    * descriptor
    *
    * @since 3.0
    * @return ETrue if data is too big.
    */

    TBool IsDataTooBig() 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      // __CIMPSSAPKEYVALUEPAIR_H


//  End of File