diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/etelutils.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/etelutils.h Tue Mar 16 16:12:26 2010 +0000 @@ -0,0 +1,280 @@ +// Copyright (c) 2004-2009 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: +// Contains various utility classes which are used throughout Telephony. +// +// + + + +/** + @file + @publishedPartner + @released +*/ + +#if !defined(__ETELUTILS_H__) +/** @internalComponent */ +#define __ETELUTILS_H__ + +#include + +/** +Base class for generic actions in retrieving a variable length buffer in two phases. + +This class is abstract. + +@publishedPartner +@released +*/ +class CAsyncRetrieveVariableLengthBufferV2 : public CActive + { +protected: + // + // Start the retrieval + // + + IMPORT_C void Start(TRequestStatus& aReqStatus, TDes8* aPhase1Request, TDes8* aPhase2Request); + IMPORT_C CAsyncRetrieveVariableLengthBufferV2(); + IMPORT_C virtual ~CAsyncRetrieveVariableLengthBufferV2(); + + IMPORT_C TBool CompleteIfInUse(TRequestStatus& aReqStatus); + IMPORT_C void FreeBuffer(); + +private: + IMPORT_C virtual void RestoreListL(); + virtual void Get(TInt aIpc, TRequestStatus& aReqStatus, TDes8& aDes1, TDes8& aDes2) = 0; + virtual void CancelReq(TInt aIpc1,TInt aIpc2) = 0; + + IMPORT_C virtual void DoCancel(); + IMPORT_C virtual void RunL(); + + void StartPhase2L(); + +protected: + /** + Maintains the current phase of buffer retrieval. + */ + enum { + EIdle, + ERetrievePhase1, + ERetrievePhase2 + } iState; + + CBufBase* iResultsBuf; + TPtr8 iResultsPtr; + TInt iIpcPhase1; + TInt iIpcPhase2; + TInt iIpcCancel; +private: + /** + Pointer to the user's asynchronous request status object. + */ + TRequestStatus* iUserStatus; + TDes8* iPhase1RequestData; + TDes8* iPhase2RequestData; + TPckgBuf iBufferSize; + }; + + +/////////////////////////////////////////////////////////////////////////// +/* following classes define interface to TLV ( TYPE- LENGTH-VALUE) structured data: +------------------------------------------------------------------------------------------------- +| | | | | | | +|ItemId | Length Of The Item Data | Item Data | ItemId | Length Of The Item Data | Item Data | +| | | | | | | +------------------------------------------------------------------------------------------------- +*/ + +/** +Defines interface for specifying the Tag of a TLV object. + +@publishedPartner +@released +*/ +class MTlvItemIdType +{ +public: +/**Externalize object by serializing to provided descriptor*/ + virtual void ExternalizeL(TDes8& aBuffer) const =0; +/** Internalize object by de-serializing of data in provided buffer*/ + virtual void InternalizeL(TDesC8& aBuffer)=0; +/** The length of serialized data member */ + virtual TUint SerializedLength() const =0; +/** compares whether two objects contains the same data*/ + virtual TBool IsEqual(const MTlvItemIdType&) const=0; +}; + +/** +Defines interface for specifying the Length of a TLV object. + +@publishedPartner +@released +*/ +class MTlvItemDataLengthType +{ +public: +/**Externalize object by serializing to provided descriptor*/ + virtual void ExternalizeL(TDes8& aBuffer)const=0; +/** Internalize object by de-serializing of data in provided buffer*/ + virtual void InternalizeL(TDesC8& aBuffer)=0; +/** The length of serialized data member */ + virtual TUint SerializedLength() const=0; +/** Sets length of the data it relates to*/ + virtual void SetDataLength(TUint)=0; +/** Gets length of the data it relates to*/ + virtual TUint DataLength() const =0; +}; + +/** +Provides methods to append, remove or perform iterative lookup for items in container buffer. +Classes ItemIdType and ItemDataLengthType have to implement interfaces MTlvItemIdType and +MTlvItemDataLengthType in order to enable proper encoding and decoding of the first two fields +in the unit. + +@internalComponent +@released +*/ +class TTlvStructBase + { + protected: + /** Default constructor initializes data members*/ + IMPORT_C TTlvStructBase(TPtr8&,TUint8); + /** Base class implementation of methods in the templated class*/ + IMPORT_C TInt AppendItemL(MTlvItemIdType& aId,MTlvItemDataLengthType& aDataLengthType,const TPtr8& aData); + IMPORT_C TInt RemoveNextItemL(MTlvItemIdType& aIdToRemove,MTlvItemIdType& aId, MTlvItemDataLengthType& aDataLength); + IMPORT_C TInt AnyNextItemL(MTlvItemIdType& aIdFound,TPtr8& aData,MTlvItemIdType& aId, MTlvItemDataLengthType& aDataLength); + IMPORT_C TInt NextItemL(const MTlvItemIdType& aWantedId,TPtr8& aData,MTlvItemIdType& aId, MTlvItemDataLengthType& aDataLength); + public: + /** Sets position of the cursor to start position (0)*/ + IMPORT_C void ResetCursorPos(); + + protected: + /** Reference to external buffer that holds encoded TLV data*/ + TPtr8& iPtr; + /** Cursor indicates last accessed item in the buffer*/ + TUint iCursorPos; + /** Position in the buffer that indicates start of the zone that hasn't been assigned to any element. + this free zone ends at the end of the buffer*/ + TUint iFreeSpacePos; + /** Character used to populate the zone that hasn't been assigned to any element. + this free zone ends at the end of the buffer*/ + TUint8 iFreeSpaceChar; + }; + +/** +Provides methods to append, remove or perform iterative lookup for items in container buffer. +Classes ItemIdType and ItemDataLengthType have to implement interfaces MTlvItemIdType and +MTlvItemDataLengthType in order to enable proper encoding and decoding of the first two fields +in the unit. + +@publishedPartner +@released +*/ +template +class TTlvStruct: public TTlvStructBase + { + public: + + inline TTlvStruct(TPtr8&,TUint8); + inline TInt NextItemL(ItemIdType aId,TPtr8& aData); + inline TInt AnyNextItemL(ItemIdType& aId, TPtr8& aData); + inline TInt AppendItemL(ItemIdType aId,const TPtr8& aData); + inline TInt RemoveNextItemL(ItemIdType aId); + + protected: + /** Default constructor is protected in order to enforce proper initialization of reference to external data buffer via provided public constructor*/ + TTlvStruct(); + /** Type of the identifier*/ + ItemIdType iItemIdType; + /** The type used to define length of data portion of the item*/ + ItemDataLengthType iItemDataLengthType; +}; + +/** +Default constructor initializes data members and cursor position to 0. + +@param aPtr Ptr descriptor to TLV buffer that is to be read or written to. +@param aFreeSpaceChar Character used to populate the zone that hasn't been assigned to any element. +*/ +template + TTlvStruct::TTlvStruct(TPtr8& aPtr,TUint8 aFreeSpaceChar):TTlvStructBase(aPtr,aFreeSpaceChar) + { + } + +/** +Look up in the buffer for an item with specified identifier. +Look-up starts from the position of the cursor; +Returns KErrNone if the item is present in the buffer, KErrNotFound otherwise. +Sets supplied pointer so that it has length of item's data portion and points to it. +Internal cursor is moved to first position after the end of the found item +(subsequent item start position in the buffer). + +@param aId Id of item to find. +@param aData Descriptor which will hold the found item. +@return System-wide error code.. If item of requested Id was not found then KErrNotFound will be returned. +*/ +template +TInt TTlvStruct::NextItemL(ItemIdType aId,TPtr8& aData) + { + return TTlvStructBase::NextItemL(aId,aData,iItemIdType,iItemDataLengthType); + } + +/** +Look up in the buffer for the item with specified identifier. +Look-up starts from the position of the cursor in the buffer. + +Returns KErrNone if item is found, KErrNotFound otherwise (end of buffer is reached). +Sets supplied pointer so that it points to item data portion and has length set to value of data length. +Internal cursor is moved to first position after the end of the found item (subsequent item start position in the buffer). + +@param aId Id of found item. +@param aData Descriptor which will hold the found item. +@return System-wide error code.. If no next item found then KErrNotFound will be returned. +*/ +template +TInt TTlvStruct::AnyNextItemL(ItemIdType& aId,TPtr8& aData) + { + return TTlvStructBase::AnyNextItemL(aId,aData,iItemIdType,iItemDataLengthType); + } + +/** +Removes item identified by specified identifier (aId) from the buffer, where look-up starts at current cursor position, or 0 if it's reset. +returns KErrNone if item is found ( and removed), otherwise error code - in the case where there is no more space in the assigned buffer, KErrOverflow is passed back. + +@param aId Id of item to remove. +@return System-wide error code.. If item of requested Id was not found then KErrNotFound will be returned. +*/ +template +TInt TTlvStruct::RemoveNextItemL(ItemIdType aId) + { + return TTlvStructBase::RemoveNextItemL(aId,iItemIdType,iItemDataLengthType); + } + +/** +Adds item identified by supplied aId argument to the buffer; content of the item is copied from provided descriptor to the buffer. +Supplied item identifier (aId) and length of the descriptor are used to set item identifier field and length field at the start of +item unit within the buffer. +Returns KErrNone if successful, error code otherwise. +Internal cursor is moved to first position after the end of the found item (subsequent item start position in the buffer). + +@param aId Id of item to add. +@param aData Descriptor containing data to add. +@return System-wide error code.. If size of item to be appended is greater than free space in buffer then KErrOverflow will be returned. +*/ +template +TInt TTlvStruct::AppendItemL(ItemIdType aId,const TPtr8& aData) + { + return TTlvStructBase::AppendItemL(aId,iItemDataLengthType,aData); + } +#endif