--- /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 <e32base.h>
+
+/**
+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<TInt> 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 ItemIdType, class ItemDataLengthType>
+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 <class ItemIdType,class ItemDataLengthType>
+ TTlvStruct<ItemIdType,ItemDataLengthType>::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 <class ItemIdType, class ItemDataLengthType>
+TInt TTlvStruct<ItemIdType,ItemDataLengthType>::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 <class ItemIdType, class ItemDataLengthType>
+TInt TTlvStruct<ItemIdType,ItemDataLengthType>::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 <class ItemIdType, class ItemDataLengthType>
+TInt TTlvStruct<ItemIdType,ItemDataLengthType>::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 <class ItemIdType, class ItemDataLengthType>
+TInt TTlvStruct<ItemIdType,ItemDataLengthType>::AppendItemL(ItemIdType aId,const TPtr8& aData)
+ {
+ return TTlvStructBase::AppendItemL(aId,iItemDataLengthType,aData);
+ }
+#endif