diff -r 000000000000 -r 99ef825efeca serviceapifw_plat/liw_generic_parameter_api/inc/liwgenericparam.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/serviceapifw_plat/liw_generic_parameter_api/inc/liwgenericparam.h Mon Mar 30 12:51:20 2009 +0300 @@ -0,0 +1,525 @@ +/* +* 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 "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: A generic parameter class. +* +*/ + + + + + + + +#ifndef LIW_GENERIC_PARAM_H +#define LIW_GENERIC_PARAM_H + +// INCLUDES +#include +#include "liwgenericparam.hrh" +#include "liwvariant.h" + +namespace LIW +{ + /* + * LIW generic parameter id. This data type should always be used when dealing + * with LIW generic parameters. UIDs can be used as LIW generic parameter IDs. + * However, values from 0 to 131071 are reserved. + * @see TLiwGenericParam + * @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 TLiwVariant +* @see CLiwGenericParamList +*/ +class TLiwGenericParam + { + public: // Constructors and destructor + /** + * Constructs a generic parameter. + */ + inline TLiwGenericParam(); + + /** + * Constructs a generic parameter. + * + * @param aSemanticId The semantic ID of the parameter, one of TGenericParamId values. + */ + inline TLiwGenericParam(LIW::TGenericParamId aSemanticId); + + /** + * Constructs a generic parameter. + * + * @param aSemanticId The semantic ID of the parameter, one of TGenericParamId values. + * @param aValue The parameter value. + */ + inline TLiwGenericParam(LIW::TGenericParamId aSemanticId, const TLiwVariant& aValue); + + /** + * Constructs a generic parameter. + * + * @param aName Name of the generic parameter + * @param aValue The parameter value. + */ + inline TLiwGenericParam(const TDesC8& aName, const TLiwVariant& aValue); + + public: // Interface + /** + * Sets the semantic ID. Possibly set previous ID is overwritten. + * + * @param aSemanticId The semantic ID of the parameter. + */ + inline void SetSemanticId(LIW::TGenericParamId aSemanticId); + + /** + * Set name. Possibly set previous name is overwritten. + * + * @param aName Parameter name. + */ + inline void SetNameL(const TDesC8& aName); + + /** + * Set name and value. Possibly set previous name and value is overwritten. + * + * @param aName the parameter name. + * + * @param aValue the parameter value + */ + inline void SetNameAndValueL(const TDesC8& aName, const TLiwVariant& aValue); + + /** + * Returns the semantic ID of this parameter. + * + * @return The semantic ID. + */ + inline LIW::TGenericParamId SemanticId() const; + + /** + * Returns the name of this parameter. + * + * @return The name of the parameter. + */ + inline const TDesC8& Name() const; + + /** + * Returns the value of this parameter. + * + * @return The value of the parameter. + */ + inline TLiwVariant& Value(); + + /** + * Returns the const value of this parameter. + * + * @return The const value of the parameter. + */ + inline const TLiwVariant& Value() const; + + /** + * Resets the semantic ID and the value of this parameter. + */ + inline void Reset(); + + /** + * TLiwGenericParam cleanup method + * + * !!!!!!!!!!!!!!!!!!!!!!!!!!!! IMPORTANT NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!! + * + * Parameters can be pushed into the CleanupStack using this method + * along with TCleanupItem + * + * @ param aObj - TLiwGenericParam Object but of type TAny* for usage with TCleanupItem + * + * Example 1: Here the client explicitly pushes the parameter into the CleanupStack using TCleanupItem + * + * @code + * TLiwGenericParam param; + * CleanupStack::PushL( TCleanupItem( TLiwGenericParam::ParamCleanup , ¶m ) ); + * User::Leave(KErrGeneral); //This calls the ParamCleanup method which cleans up TLiwGenericParam + * CleanupStack::Pop(¶m); + * param.Reset(); + * @endcode + * + * Example 2: Here the client calls the PushL method of TLiwGenericParam which pushes the object into + * the CleanupStack using TCleanupItem + * + * @code + * TLiwGenericParam param; + * param.PushL(); + * User::Leave(KErrGeneral); //This calls the ParamCleanup method which cleans up TLiwGenericParam + * CleanupStack::Pop(¶m); + * param.Reset(); + * @endcode + * + * The clients can use the convenient PushL method which is recommended (as shown in e.g 2) rather than + * explicitly pushing the parameter object into the CleanupStack using TCleanupItem and ParamCleanup. + * + * @ see PushL() method + */ + IMPORT_C static void ParamCleanup(TAny* aObj); + + /** + * A friendly and convenient method to push the TLiwGenericParam Object into the CleanupStack + * + * !!!!!!!!!!!!!!!!!!!!!!!!!!!! IMPORTANT NOTE !!!!!!!!!!!!!!!!!!!!!!!!!!!! + * + * This method informs the CleanupStack that ParamCleanup method should be called incase of any Leave + * + * Example: + * + * @code + * TLiwGenericParam param; + * param.PushL(); //This pushes the parameter object "param" into the CleanupStack using TCleanupItem and ParamCleanup. + * User::Leave(KErrGeneral); //This calls the ParamCleanup method which cleans up TLiwGenericParam + * CleanupStack::Pop(¶m); //These statements are not executed + * param.Reset(); + * @endcode + * + * This method is recommended than explicitly pushing the parameter object into the CleanupStack + * using TCleanupItem and ParamCleanup. + * + * @see ParamCleanup() method + */ + IMPORT_C void PushL(); + + private: // Interface for friend classes + void Destroy(); + void CopyLC(const TLiwGenericParam& 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 + LIW::TGenericParamId iSemanticId; + /// Own: value of this parameter + TLiwVariant iValue; + /// Reserved member + TAny* iReserved; + + private: // friend declarations + friend class CLiwGenericParamList; + friend class CLiwDefaultList; + friend class CLiwDefaultMap; + }; + + +// 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 TLiwGenericParam& aLhs, const TLiwGenericParam& 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 TLiwGenericParam& aLhs, const TLiwGenericParam& aRhs); + + +/** + * Generic parameter list. + * A list containing TLiwGenericParam objects. Used for passing parameters + * between consumers and providers. + * + * @lib ServiceHandler.lib + * @since Series 60 2.6 + */ +NONSHARABLE_CLASS(CLiwGenericParamList): public CBase + { + public: // Constructors and destructor + /** + * Creates an instance of this class. + * + * @return A pointer to the new instance. + */ + IMPORT_C static CLiwGenericParamList* 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 CLiwGenericParamList* 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 CLiwGenericParamList* 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 CLiwGenericParamList* NewLC(RReadStream& aReadStream); + + /** + * Destructor. + */ + virtual ~CLiwGenericParamList(); + + 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(LIW::TGenericParamId aSemanticId, + LIW::TVariantTypeId aDataType = LIW::EVariantTypeAny) const; + + /** + * Returns a parameter from this list. + * + * @param aIndex Index of the parameter. + * @return The parameter at the aIndex position. + * @pre aIndex>=0 && aIndexAtL(0,outParam); + * //This fills the "outParam" with the parameter value present in the 0th position of parameter list, but + * //if there is any Leave in AtL, then ParamCleanup method is called for proper cleanup + * + * CleanupStack::Pop(&outParam); + * outParam.Reset(); + * CleanupStack::PopAndDestroy(param); + * @endcode + * + * @return false if no element is found at the passed index; + * true if an element is found + * + * @see CLiwDefaultList::AtL + * @see TLiwGenericParam::PushL + */ + IMPORT_C void AtL(TInt aIndex, TLiwGenericParam& aParam) 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 TLiwGenericParam& 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 CLiwGenericParamList& 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); + + /** + * Removes the first found item with given string based 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 void Remove(const TDesC8& aName); + + /** + * 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 TLiwGenericParam* FindFirst( + TInt& aIndex, + LIW::TGenericParamId aSemanticId, + LIW::TVariantTypeId aDataType = LIW::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 TLiwGenericParam* FindNext( + TInt& aIndex, + LIW::TGenericParamId aSemanticId, + LIW::TVariantTypeId aDataType = LIW::EVariantTypeAny) const; + + /** + * Returns item matching the given name. + * + * @param aIndex Position in which to start searching, on return contains + * position of the found parameter. Is set to KErrNotFound, + * if no matching items were found. + * @param aName Parameter name. + * @param aDataType The type id of data. Default is any type. + * @return The first matching item. + */ + IMPORT_C const TLiwGenericParam* FindFirst( + TInt& aIndex, + const TDesC8& aName, + LIW::TVariantTypeId aDataType = LIW::EVariantTypeAny) const; + + /** + * Returns item matching the given name. + * + * @param aIndex Position in which to start searching, on return contains + * position of the found parameter. Is set to KErrNotFound, + * if no matching items were found. + * @param aName Parameter name. + * @param aDataType The type id of data. Default is any type. + * @return The first matching item. + */ + IMPORT_C const TLiwGenericParam* FindNext( + TInt& aIndex, + const TDesC8& aName, + LIW::TVariantTypeId aDataType = LIW::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 + CLiwGenericParamList(); + void ConstructL(); + void AppendL(RReadStream& aReadStream); + + private: // Data + /// Own: the parameter list + RArray iParameters; + friend class CLiwDefaultList; + friend class CLiwDefaultMap; + }; + + +// INLINE FUNCTIONS +#include "liwgenericparam.inl" + +#endif // LIW_GENERIC_PARAM_H + +// End of File