williamr@2: /*
williamr@2: * Copyright (c) 2003-2005 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:     A generic parameter class.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef AIW_GENERIC_PARAM_H
williamr@2: #define AIW_GENERIC_PARAM_H
williamr@2: 
williamr@2: // INCLUDES
williamr@2: #include <e32base.h>
williamr@2: #include "aiwgenericparam.hrh"
williamr@2: #include "aiwvariant.h"
williamr@2: 
williamr@2: /**
williamr@2:  * AIW generic parameter id. This data type should always be used when dealing 
williamr@2:  * with AIW generic parameters. UIDs can be used as AIW generic parameter IDs. 
williamr@2:  * However, values from 0 to 131071 are reserved.
williamr@2:  * @see TAiwGenericParam 
williamr@2:  * @see TGenericParamIdValue
williamr@2:  */ 
williamr@2: typedef TInt TGenericParamId;
williamr@2: 
williamr@2: // CLASS DECLARATION
williamr@2: 
williamr@2: /**
williamr@2: * Generic parameter class for passing data between applications.
williamr@2: * A generic parameter is a pair of semantic ID and
williamr@2: * variant value. The semantic ID tells the purpose of the parameter,
williamr@2: * for example a file name, URL or phone number. The variant value contains
williamr@2: * the data format and actual value. This class does not implement any
williamr@2: * consistency checks between the semantic ID and value's data format.
williamr@2: * So one semantic ID can be expressed as alternative data formats.
williamr@2: *
williamr@2: * @lib ServiceHandler.lib
williamr@2: * @since Series 60 2.6
williamr@2: * @see TAiwVariant
williamr@2: * @see CAiwGenericParamList
williamr@2: */
williamr@2: class TAiwGenericParam
williamr@2:     {
williamr@2:     public:  // Constructors and destructor
williamr@2:         /**
williamr@2:         * Constructs a generic parameter.
williamr@2:         */
williamr@2:         inline TAiwGenericParam();
williamr@2:         
williamr@2:         /**
williamr@2:         * Constructs a generic parameter.
williamr@2:         *
williamr@2:         * @param aSemanticId The semantic ID of the parameter, one of TGenericParamId values.
williamr@2:         */        
williamr@2:         inline TAiwGenericParam(TGenericParamId aSemanticId);
williamr@2:         
williamr@2:         /**
williamr@2:         * Constructs a generic parameter.
williamr@2:         *
williamr@2:         * @param aSemanticId The semantic ID of the parameter, one of TGenericParamId values.
williamr@2:         * @param aValue The parameter value.
williamr@2:         */        
williamr@2:         inline TAiwGenericParam(TGenericParamId aSemanticId, const TAiwVariant& aValue);
williamr@2: 
williamr@2:     public:  // Interface
williamr@2:         /**
williamr@2:         * Sets the semantic ID. Possibly set previous ID is overwritten.
williamr@2:         *
williamr@2:         * @param aSemanticId The semantic ID of the parameter.
williamr@2:         */
williamr@2:         inline void SetSemanticId(TGenericParamId aSemanticId);
williamr@2: 
williamr@2:         /**
williamr@2:         * Returns the semantic ID of this parameter.
williamr@2:         *
williamr@2:         * @return The semantic ID.
williamr@2:         */
williamr@2:         inline TGenericParamId SemanticId() const;
williamr@2: 
williamr@2:         /**
williamr@2:         * Returns the value of this parameter.
williamr@2:         *
williamr@2:         * @return The value of the parameter.        
williamr@2:         */
williamr@2:         inline TAiwVariant& Value();
williamr@2: 
williamr@2:         /**
williamr@2:         * Returns the const value of this parameter.
williamr@2:         *
williamr@2:         * @return The const value of the parameter.        
williamr@2:         */
williamr@2:         inline const TAiwVariant& Value() const;
williamr@2: 
williamr@2:         /**
williamr@2:         * Resets the semantic ID and the value of this parameter.
williamr@2:         */
williamr@2:         inline void Reset();
williamr@2: 
williamr@2:     private:  // Interface for friend classes
williamr@2:         void Destroy();
williamr@2:         void CopyLC(const TAiwGenericParam& aParam);
williamr@2:         static void CleanupDestroy(TAny* aObj);
williamr@2:         operator TCleanupItem();
williamr@2:         void InternalizeL(RReadStream& aStream);
williamr@2:         void ExternalizeL(RWriteStream& aStream) const;
williamr@2:         TInt Size() const; 
williamr@2: 
williamr@2:     private:  // Data
williamr@2:         /// Own: semantic ID of this parameter
williamr@2:         TGenericParamId iSemanticId;
williamr@2:         /// Own: value of this parameter
williamr@2:         TAiwVariant iValue;
williamr@2:         /// Reserved member
williamr@2:         TAny* iReserved;
williamr@2: 
williamr@2:     private:  // friend declarations
williamr@2:         friend class CAiwGenericParamList;
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: // FUNCTIONS
williamr@2: 
williamr@2: /**
williamr@2: * Returns ETrue if two generic params are equal.
williamr@2: *
williamr@2: * @param aLhs Left hand side.
williamr@2: * @param aRhs Right hand side.
williamr@2: * @return ETrue if equal, EFalse otherwise.
williamr@2: */ 
williamr@2: IMPORT_C TBool operator==(const TAiwGenericParam& aLhs, const TAiwGenericParam& aRhs);
williamr@2: 
williamr@2: /**
williamr@2: * Returns ETrue if two generic params are not equal.
williamr@2: *
williamr@2: * @param aLhs Left hand side.
williamr@2: * @param aRhs Right hand side.
williamr@2: * @return ETrue if not equal, EFalse otherwise.
williamr@2: */
williamr@2: inline TBool operator!=(const TAiwGenericParam& aLhs, const TAiwGenericParam& aRhs);
williamr@2:         
williamr@2: 
williamr@2: /**
williamr@2:  * Generic parameter list.
williamr@2:  * A list containing TAiwGenericParam objects. Used for passing parameters 
williamr@2:  * between consumers and providers.
williamr@2:  *
williamr@2:  * @lib ServiceHandler.lib
williamr@2:  * @since Series 60 2.6
williamr@2:  */
williamr@2: NONSHARABLE_CLASS(CAiwGenericParamList): public CBase
williamr@2:     {
williamr@2:     public:   // Constructors and destructor
williamr@2:         /**
williamr@2:         * Creates an instance of this class.
williamr@2:         *
williamr@2:         * @return A pointer to the new instance.
williamr@2:         */
williamr@2:         IMPORT_C static CAiwGenericParamList* NewL();
williamr@2:         
williamr@2:         /**
williamr@2:         * Creates an instance of this class.
williamr@2:         *
williamr@2:         * @param aReadStream A stream to initialize this parameter list from.
williamr@2:         * @return A pointer to the new instance.
williamr@2:         */        
williamr@2:         IMPORT_C static CAiwGenericParamList* NewL(RReadStream& aReadStream);
williamr@2: 
williamr@2:         /**
williamr@2:         * Creates an instance of this class. Leaves the created instance on the
williamr@2:         * cleanup stack.
williamr@2:         *
williamr@2:         * @return A pointer to the new instance.
williamr@2:         */
williamr@2:         IMPORT_C static CAiwGenericParamList* NewLC();
williamr@2:         
williamr@2:         /**
williamr@2:         * Creates an instance of this class. Leaves the created instance on the
williamr@2:         * cleanup stack.
williamr@2:         *
williamr@2:         * @param aReadStream A stream to initialize this parameter list from.
williamr@2:         * @return A pointer to the new instance.
williamr@2:         */        
williamr@2:         IMPORT_C static CAiwGenericParamList* NewLC(RReadStream& aReadStream);
williamr@2: 
williamr@2:         /**
williamr@2:         * Destructor.
williamr@2:         */
williamr@2:         virtual ~CAiwGenericParamList();
williamr@2:         
williamr@2:     public:  // Interface
williamr@2:         /**
williamr@2:         * Returns the number of parameters in the list. 
williamr@2:         *
williamr@2:         * @return The number of parameters in the list. 
williamr@2:         */
williamr@2:         IMPORT_C TInt Count() const;
williamr@2:         
williamr@2:         /**
williamr@2:         * Returns the number of the parameters in the list by semantic id and datatype.
williamr@2:         *
williamr@2:         * @param aSemanticId The semantic ID of the parameter.
williamr@2:         * @param aDataType The type id of data. Default is any type.
williamr@2:         * @return The number of parameters in the list by semantic id and datatype.
williamr@2:         */
williamr@2:         IMPORT_C TInt Count(TGenericParamId aSemanticId, 
williamr@2:                 TVariantTypeId aDataType = EVariantTypeAny) const;  
williamr@2:             
williamr@2:         /**
williamr@2:         * Returns a parameter from this list.
williamr@2:         *
williamr@2:         * @param aIndex Index of the parameter.
williamr@2:         * @return The parameter at the aIndex position.
williamr@2:         * @pre aIndex>=0 && aIndex<Count()
williamr@2:         */
williamr@2:         IMPORT_C const TAiwGenericParam& operator[](TInt aIndex) const;
williamr@2: 
williamr@2:         /**
williamr@2:         * Appends a parameter to this list.
williamr@2:         *
williamr@2:         * @param aParam The parameter to append to this list. This object takes
williamr@2:         *               an own copy of the data in aParam.
williamr@2:         */
williamr@2:         IMPORT_C void AppendL(const TAiwGenericParam& aParam);
williamr@2: 
williamr@2:         /**
williamr@2:         * Copies the given list and appends it to end of this list.
williamr@2:         *
williamr@2:         * @since Series 60 2.8        
williamr@2:         * @param aList A list to be copied and appended.
williamr@2:         */
williamr@2:         IMPORT_C void AppendL(const CAiwGenericParamList& aList);
williamr@2:         
williamr@2:         /**
williamr@2:         * Removes the first found item with given semantic id from the list.
williamr@2:         * 
williamr@2:         * @param aSemanticId Semantic id for the item to be removed.
williamr@2:         * @return  ETrue  if an item for the given semantic id was found and removed.
williamr@2:         *          EFalse otherwise.
williamr@2:         */
williamr@2:         IMPORT_C TBool Remove(TInt aSemanticId);
williamr@2: 
williamr@2:         /**
williamr@2:         * Deletes all parameters in the list and resets the list.
williamr@2:         */
williamr@2:         IMPORT_C void Reset();
williamr@2: 
williamr@2:         /**
williamr@2:         * Returns the first item matching the given semantic ID.
williamr@2:         *
williamr@2:         * @param aIndex Position in which to start searching. On return it contains 
williamr@2:         *               the position of the found parameter. It is set to KErrNotFound, 
williamr@2:         *               if no matching items were found.
williamr@2:         * @param aSemanticId The semantic ID of the parameter.
williamr@2:         * @param aDataType The type id of data. Default is any type.
williamr@2:         * @return The first matching item.
williamr@2:         */
williamr@2:         IMPORT_C const TAiwGenericParam* FindFirst(
williamr@2:             TInt& aIndex, 
williamr@2:             TGenericParamId aSemanticId,
williamr@2:             TVariantTypeId aDataType = EVariantTypeAny) const;
williamr@2:         /**
williamr@2:         * Returns the next item matching the given semantic ID.
williamr@2:         * 
williamr@2:         * @param aIndex Position after which to start searching. On return it contains 
williamr@2:         *               the position of the found parameter. It is set to KErrNotFound, 
williamr@2:         *               if no matching items were found.
williamr@2:         * @param aSemanticId The semantic ID of the parameter.
williamr@2:         * @param aDataType The type id of data. Default is any type. 
williamr@2:         * @return The next matching item.       
williamr@2:         */
williamr@2:         IMPORT_C const TAiwGenericParam* FindNext(
williamr@2:             TInt& aIndex, 
williamr@2:             TGenericParamId aSemanticId,
williamr@2:             TVariantTypeId aDataType = EVariantTypeAny) const;
williamr@2:         
williamr@2:         /**
williamr@2:         * Externalizes this parameter list to a stream.
williamr@2:         *
williamr@2:         * @param aStream The stream. 
williamr@2:         * @see NewL(RReadStream& aStream)
williamr@2:         * @see NewLC(RReadStream& aStream)
williamr@2:         */
williamr@2:         IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
williamr@2: 
williamr@2:         /**
williamr@2:         * Returns the externalized size of the parameter list in bytes.
williamr@2:         *
williamr@2:         * @return The size.
williamr@2:         */
williamr@2:         IMPORT_C TInt Size() const;
williamr@2: 
williamr@2:         /**
williamr@2:         * Internalizes the parameter list from a stream.
williamr@2:         *
williamr@2:         * @since Series60 2.8
williamr@2:         * @param aStream The stream.
williamr@2:         */
williamr@2:         IMPORT_C void InternalizeL(RReadStream& aStream);
williamr@2: 
williamr@2:         /**
williamr@2:         * Packs the parameter list to TIpcArgs structure for
williamr@2:         * passing the generic param list to server over process boundary.
williamr@2:         * Only one RFile handle parameter can be passed over process boundary.
williamr@2:         *
williamr@2:         * @since Series60 3.0
williamr@2:         * @param aArgs Inter process call arguments.
williamr@2:         * @return Packed parameter list.
williamr@2:         */
williamr@2:         IMPORT_C HBufC8* PackForServerL(TIpcArgs& aArgs);
williamr@2: 
williamr@2:         /**
williamr@2:         * Unpacks the list from client message structure.
williamr@2:         *
williamr@2:         * @since Series60 3.0
williamr@2:         * @param aArgs The list to be unpacked. 
williamr@2:         */
williamr@2:         IMPORT_C void UnpackFromClientL(const RMessage2& aArgs);
williamr@2:         
williamr@2:     private:  // Implementation
williamr@2:         CAiwGenericParamList();
williamr@2:         void ConstructL();
williamr@2:         void AppendL(RReadStream& aReadStream);
williamr@2:         
williamr@2:     private:  // Data
williamr@2:         /// Own: the parameter list
williamr@2:         RArray<TAiwGenericParam> iParameters;
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: // INLINE FUNCTIONS
williamr@2: #include "aiwgenericparam.inl"
williamr@2: 
williamr@2: #endif // AIW_GENERIC_PARAM_H
williamr@2: 
williamr@2: // End of File