/*
* Copyright (c) 2003-2005 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:     A generic parameter class.
*
*/





#ifndef AIW_GENERIC_PARAM_H
#define AIW_GENERIC_PARAM_H

// INCLUDES
#include <e32base.h>
#include "aiwgenericparam.hrh"
#include "aiwvariant.h"

/**
 * AIW generic parameter id. This data type should always be used when dealing 
 * with AIW generic parameters. UIDs can be used as AIW generic parameter IDs. 
 * However, values from 0 to 131071 are reserved.
 * @see TAiwGenericParam 
 * @see TGenericParamIdValue
 */ 
typedef TInt TGenericParamId;

// CLASS DECLARATION

/**
* Generic parameter class for passing data between applications.
* A generic parameter is a pair of semantic ID and
* variant value. The semantic ID tells the purpose of the parameter,
* for example a file name, URL or phone number. The variant value contains
* the data format and actual value. This class does not implement any
* consistency checks between the semantic ID and value's data format.
* So one semantic ID can be expressed as alternative data formats.
*
* @lib ServiceHandler.lib
* @since Series 60 2.6
* @see TAiwVariant
* @see CAiwGenericParamList
*/
class TAiwGenericParam
    {
    public:  // Constructors and destructor
        /**
        * Constructs a generic parameter.
        */
        inline TAiwGenericParam();
        
        /**
        * Constructs a generic parameter.
        *
        * @param aSemanticId The semantic ID of the parameter, one of TGenericParamId values.
        */        
        inline TAiwGenericParam(TGenericParamId aSemanticId);
        
        /**
        * Constructs a generic parameter.
        *
        * @param aSemanticId The semantic ID of the parameter, one of TGenericParamId values.
        * @param aValue The parameter value.
        */        
        inline TAiwGenericParam(TGenericParamId aSemanticId, const TAiwVariant& aValue);

    public:  // Interface
        /**
        * Sets the semantic ID. Possibly set previous ID is overwritten.
        *
        * @param aSemanticId The semantic ID of the parameter.
        */
        inline void SetSemanticId(TGenericParamId aSemanticId);

        /**
        * Returns the semantic ID of this parameter.
        *
        * @return The semantic ID.
        */
        inline TGenericParamId SemanticId() const;

        /**
        * Returns the value of this parameter.
        *
        * @return The value of the parameter.        
        */
        inline TAiwVariant& Value();

        /**
        * Returns the const value of this parameter.
        *
        * @return The const value of the parameter.        
        */
        inline const TAiwVariant& Value() const;

        /**
        * Resets the semantic ID and the value of this parameter.
        */
        inline void Reset();

    private:  // Interface for friend classes
        void Destroy();
        void CopyLC(const TAiwGenericParam& aParam);
        static void CleanupDestroy(TAny* aObj);
        operator TCleanupItem();
        void InternalizeL(RReadStream& aStream);
        void ExternalizeL(RWriteStream& aStream) const;
        TInt Size() const; 

    private:  // Data
        /// Own: semantic ID of this parameter
        TGenericParamId iSemanticId;
        /// Own: value of this parameter
        TAiwVariant iValue;
        /// Reserved member
        TAny* iReserved;

    private:  // friend declarations
        friend class CAiwGenericParamList;
    };


// FUNCTIONS

/**
* Returns ETrue if two generic params are equal.
*
* @param aLhs Left hand side.
* @param aRhs Right hand side.
* @return ETrue if equal, EFalse otherwise.
*/ 
IMPORT_C TBool operator==(const TAiwGenericParam& aLhs, const TAiwGenericParam& aRhs);

/**
* Returns ETrue if two generic params are not equal.
*
* @param aLhs Left hand side.
* @param aRhs Right hand side.
* @return ETrue if not equal, EFalse otherwise.
*/
inline TBool operator!=(const TAiwGenericParam& aLhs, const TAiwGenericParam& aRhs);
        

/**
 * Generic parameter list.
 * A list containing TAiwGenericParam objects. Used for passing parameters 
 * between consumers and providers.
 *
 * @lib ServiceHandler.lib
 * @since Series 60 2.6
 */
NONSHARABLE_CLASS(CAiwGenericParamList): public CBase
    {
    public:   // Constructors and destructor
        /**
        * Creates an instance of this class.
        *
        * @return A pointer to the new instance.
        */
        IMPORT_C static CAiwGenericParamList* NewL();
        
        /**
        * Creates an instance of this class.
        *
        * @param aReadStream A stream to initialize this parameter list from.
        * @return A pointer to the new instance.
        */        
        IMPORT_C static CAiwGenericParamList* NewL(RReadStream& aReadStream);

        /**
        * Creates an instance of this class. Leaves the created instance on the
        * cleanup stack.
        *
        * @return A pointer to the new instance.
        */
        IMPORT_C static CAiwGenericParamList* NewLC();
        
        /**
        * Creates an instance of this class. Leaves the created instance on the
        * cleanup stack.
        *
        * @param aReadStream A stream to initialize this parameter list from.
        * @return A pointer to the new instance.
        */        
        IMPORT_C static CAiwGenericParamList* NewLC(RReadStream& aReadStream);

        /**
        * Destructor.
        */
        virtual ~CAiwGenericParamList();
        
    public:  // Interface
        /**
        * Returns the number of parameters in the list. 
        *
        * @return The number of parameters in the list. 
        */
        IMPORT_C TInt Count() const;
        
        /**
        * Returns the number of the parameters in the list by semantic id and datatype.
        *
        * @param aSemanticId The semantic ID of the parameter.
        * @param aDataType The type id of data. Default is any type.
        * @return The number of parameters in the list by semantic id and datatype.
        */
        IMPORT_C TInt Count(TGenericParamId aSemanticId, 
                TVariantTypeId aDataType = EVariantTypeAny) const;  
            
        /**
        * Returns a parameter from this list.
        *
        * @param aIndex Index of the parameter.
        * @return The parameter at the aIndex position.
        * @pre aIndex>=0 && aIndex<Count()
        */
        IMPORT_C const TAiwGenericParam& operator[](TInt aIndex) const;

        /**
        * Appends a parameter to this list.
        *
        * @param aParam The parameter to append to this list. This object takes
        *               an own copy of the data in aParam.
        */
        IMPORT_C void AppendL(const TAiwGenericParam& aParam);

        /**
        * Copies the given list and appends it to end of this list.
        *
        * @since Series 60 2.8        
        * @param aList A list to be copied and appended.
        */
        IMPORT_C void AppendL(const CAiwGenericParamList& aList);
        
        /**
        * Removes the first found item with given semantic id from the list.
        * 
        * @param aSemanticId Semantic id for the item to be removed.
        * @return  ETrue  if an item for the given semantic id was found and removed.
        *          EFalse otherwise.
        */
        IMPORT_C TBool Remove(TInt aSemanticId);

        /**
        * Deletes all parameters in the list and resets the list.
        */
        IMPORT_C void Reset();

        /**
        * Returns the first item matching the given semantic ID.
        *
        * @param aIndex Position in which to start searching. On return it contains 
        *               the position of the found parameter. It is set to KErrNotFound, 
        *               if no matching items were found.
        * @param aSemanticId The semantic ID of the parameter.
        * @param aDataType The type id of data. Default is any type.
        * @return The first matching item.
        */
        IMPORT_C const TAiwGenericParam* FindFirst(
            TInt& aIndex, 
            TGenericParamId aSemanticId,
            TVariantTypeId aDataType = EVariantTypeAny) const;
        /**
        * Returns the next item matching the given semantic ID.
        * 
        * @param aIndex Position after which to start searching. On return it contains 
        *               the position of the found parameter. It is set to KErrNotFound, 
        *               if no matching items were found.
        * @param aSemanticId The semantic ID of the parameter.
        * @param aDataType The type id of data. Default is any type. 
        * @return The next matching item.       
        */
        IMPORT_C const TAiwGenericParam* FindNext(
            TInt& aIndex, 
            TGenericParamId aSemanticId,
            TVariantTypeId aDataType = EVariantTypeAny) const;
        
        /**
        * Externalizes this parameter list to a stream.
        *
        * @param aStream The stream. 
        * @see NewL(RReadStream& aStream)
        * @see NewLC(RReadStream& aStream)
        */
        IMPORT_C void ExternalizeL(RWriteStream& aStream) const;

        /**
        * Returns the externalized size of the parameter list in bytes.
        *
        * @return The size.
        */
        IMPORT_C TInt Size() const;

        /**
        * Internalizes the parameter list from a stream.
        *
        * @since Series60 2.8
        * @param aStream The stream.
        */
        IMPORT_C void InternalizeL(RReadStream& aStream);

        /**
        * Packs the parameter list to TIpcArgs structure for
        * passing the generic param list to server over process boundary.
        * Only one RFile handle parameter can be passed over process boundary.
        *
        * @since Series60 3.0
        * @param aArgs Inter process call arguments.
        * @return Packed parameter list.
        */
        IMPORT_C HBufC8* PackForServerL(TIpcArgs& aArgs);

        /**
        * Unpacks the list from client message structure.
        *
        * @since Series60 3.0
        * @param aArgs The list to be unpacked. 
        */
        IMPORT_C void UnpackFromClientL(const RMessage2& aArgs);
        
    private:  // Implementation
        CAiwGenericParamList();
        void ConstructL();
        void AppendL(RReadStream& aReadStream);
        
    private:  // Data
        /// Own: the parameter list
        RArray<TAiwGenericParam> iParameters;
    };


// INLINE FUNCTIONS
#include "aiwgenericparam.inl"

#endif // AIW_GENERIC_PARAM_H

// End of File