1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/etelutils.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,280 @@
1.4 +// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// 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
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// Contains various utility classes which are used throughout Telephony.
1.18 +//
1.19 +//
1.20 +
1.21 +
1.22 +
1.23 +/**
1.24 + @file
1.25 + @publishedPartner
1.26 + @released
1.27 +*/
1.28 +
1.29 +#if !defined(__ETELUTILS_H__)
1.30 +/** @internalComponent */
1.31 +#define __ETELUTILS_H__
1.32 +
1.33 +#include <e32base.h>
1.34 +
1.35 +/**
1.36 +Base class for generic actions in retrieving a variable length buffer in two phases.
1.37 +
1.38 +This class is abstract.
1.39 +
1.40 +@publishedPartner
1.41 +@released
1.42 +*/
1.43 +class CAsyncRetrieveVariableLengthBufferV2 : public CActive
1.44 + {
1.45 +protected:
1.46 + //
1.47 + // Start the retrieval
1.48 + //
1.49 +
1.50 + IMPORT_C void Start(TRequestStatus& aReqStatus, TDes8* aPhase1Request, TDes8* aPhase2Request);
1.51 + IMPORT_C CAsyncRetrieveVariableLengthBufferV2();
1.52 + IMPORT_C virtual ~CAsyncRetrieveVariableLengthBufferV2();
1.53 +
1.54 + IMPORT_C TBool CompleteIfInUse(TRequestStatus& aReqStatus);
1.55 + IMPORT_C void FreeBuffer();
1.56 +
1.57 +private:
1.58 + IMPORT_C virtual void RestoreListL();
1.59 + virtual void Get(TInt aIpc, TRequestStatus& aReqStatus, TDes8& aDes1, TDes8& aDes2) = 0;
1.60 + virtual void CancelReq(TInt aIpc1,TInt aIpc2) = 0;
1.61 +
1.62 + IMPORT_C virtual void DoCancel();
1.63 + IMPORT_C virtual void RunL();
1.64 +
1.65 + void StartPhase2L();
1.66 +
1.67 +protected:
1.68 + /**
1.69 + Maintains the current phase of buffer retrieval.
1.70 + */
1.71 + enum {
1.72 + EIdle,
1.73 + ERetrievePhase1,
1.74 + ERetrievePhase2
1.75 + } iState;
1.76 +
1.77 + CBufBase* iResultsBuf;
1.78 + TPtr8 iResultsPtr;
1.79 + TInt iIpcPhase1;
1.80 + TInt iIpcPhase2;
1.81 + TInt iIpcCancel;
1.82 +private:
1.83 + /**
1.84 + Pointer to the user's asynchronous request status object.
1.85 + */
1.86 + TRequestStatus* iUserStatus;
1.87 + TDes8* iPhase1RequestData;
1.88 + TDes8* iPhase2RequestData;
1.89 + TPckgBuf<TInt> iBufferSize;
1.90 + };
1.91 +
1.92 +
1.93 +///////////////////////////////////////////////////////////////////////////
1.94 +/* following classes define interface to TLV ( TYPE- LENGTH-VALUE) structured data:
1.95 +-------------------------------------------------------------------------------------------------
1.96 +| | | | | | |
1.97 +|ItemId | Length Of The Item Data | Item Data | ItemId | Length Of The Item Data | Item Data |
1.98 +| | | | | | |
1.99 +-------------------------------------------------------------------------------------------------
1.100 +*/
1.101 +
1.102 +/**
1.103 +Defines interface for specifying the Tag of a TLV object.
1.104 +
1.105 +@publishedPartner
1.106 +@released
1.107 +*/
1.108 +class MTlvItemIdType
1.109 +{
1.110 +public:
1.111 +/**Externalize object by serializing to provided descriptor*/
1.112 + virtual void ExternalizeL(TDes8& aBuffer) const =0;
1.113 +/** Internalize object by de-serializing of data in provided buffer*/
1.114 + virtual void InternalizeL(TDesC8& aBuffer)=0;
1.115 +/** The length of serialized data member */
1.116 + virtual TUint SerializedLength() const =0;
1.117 +/** compares whether two objects contains the same data*/
1.118 + virtual TBool IsEqual(const MTlvItemIdType&) const=0;
1.119 +};
1.120 +
1.121 +/**
1.122 +Defines interface for specifying the Length of a TLV object.
1.123 +
1.124 +@publishedPartner
1.125 +@released
1.126 +*/
1.127 +class MTlvItemDataLengthType
1.128 +{
1.129 +public:
1.130 +/**Externalize object by serializing to provided descriptor*/
1.131 + virtual void ExternalizeL(TDes8& aBuffer)const=0;
1.132 +/** Internalize object by de-serializing of data in provided buffer*/
1.133 + virtual void InternalizeL(TDesC8& aBuffer)=0;
1.134 +/** The length of serialized data member */
1.135 + virtual TUint SerializedLength() const=0;
1.136 +/** Sets length of the data it relates to*/
1.137 + virtual void SetDataLength(TUint)=0;
1.138 +/** Gets length of the data it relates to*/
1.139 + virtual TUint DataLength() const =0;
1.140 +};
1.141 +
1.142 +/**
1.143 +Provides methods to append, remove or perform iterative lookup for items in container buffer.
1.144 +Classes ItemIdType and ItemDataLengthType have to implement interfaces MTlvItemIdType and
1.145 +MTlvItemDataLengthType in order to enable proper encoding and decoding of the first two fields
1.146 +in the unit.
1.147 +
1.148 +@internalComponent
1.149 +@released
1.150 +*/
1.151 +class TTlvStructBase
1.152 + {
1.153 + protected:
1.154 + /** Default constructor initializes data members*/
1.155 + IMPORT_C TTlvStructBase(TPtr8&,TUint8);
1.156 + /** Base class implementation of methods in the templated class*/
1.157 + IMPORT_C TInt AppendItemL(MTlvItemIdType& aId,MTlvItemDataLengthType& aDataLengthType,const TPtr8& aData);
1.158 + IMPORT_C TInt RemoveNextItemL(MTlvItemIdType& aIdToRemove,MTlvItemIdType& aId, MTlvItemDataLengthType& aDataLength);
1.159 + IMPORT_C TInt AnyNextItemL(MTlvItemIdType& aIdFound,TPtr8& aData,MTlvItemIdType& aId, MTlvItemDataLengthType& aDataLength);
1.160 + IMPORT_C TInt NextItemL(const MTlvItemIdType& aWantedId,TPtr8& aData,MTlvItemIdType& aId, MTlvItemDataLengthType& aDataLength);
1.161 + public:
1.162 + /** Sets position of the cursor to start position (0)*/
1.163 + IMPORT_C void ResetCursorPos();
1.164 +
1.165 + protected:
1.166 + /** Reference to external buffer that holds encoded TLV data*/
1.167 + TPtr8& iPtr;
1.168 + /** Cursor indicates last accessed item in the buffer*/
1.169 + TUint iCursorPos;
1.170 + /** Position in the buffer that indicates start of the zone that hasn't been assigned to any element.
1.171 + this free zone ends at the end of the buffer*/
1.172 + TUint iFreeSpacePos;
1.173 + /** Character used to populate the zone that hasn't been assigned to any element.
1.174 + this free zone ends at the end of the buffer*/
1.175 + TUint8 iFreeSpaceChar;
1.176 + };
1.177 +
1.178 +/**
1.179 +Provides methods to append, remove or perform iterative lookup for items in container buffer.
1.180 +Classes ItemIdType and ItemDataLengthType have to implement interfaces MTlvItemIdType and
1.181 +MTlvItemDataLengthType in order to enable proper encoding and decoding of the first two fields
1.182 +in the unit.
1.183 +
1.184 +@publishedPartner
1.185 +@released
1.186 +*/
1.187 +template <class ItemIdType, class ItemDataLengthType>
1.188 +class TTlvStruct: public TTlvStructBase
1.189 + {
1.190 + public:
1.191 +
1.192 + inline TTlvStruct(TPtr8&,TUint8);
1.193 + inline TInt NextItemL(ItemIdType aId,TPtr8& aData);
1.194 + inline TInt AnyNextItemL(ItemIdType& aId, TPtr8& aData);
1.195 + inline TInt AppendItemL(ItemIdType aId,const TPtr8& aData);
1.196 + inline TInt RemoveNextItemL(ItemIdType aId);
1.197 +
1.198 + protected:
1.199 + /** Default constructor is protected in order to enforce proper initialization of reference to external data buffer via provided public constructor*/
1.200 + TTlvStruct();
1.201 + /** Type of the identifier*/
1.202 + ItemIdType iItemIdType;
1.203 + /** The type used to define length of data portion of the item*/
1.204 + ItemDataLengthType iItemDataLengthType;
1.205 +};
1.206 +
1.207 +/**
1.208 +Default constructor initializes data members and cursor position to 0.
1.209 +
1.210 +@param aPtr Ptr descriptor to TLV buffer that is to be read or written to.
1.211 +@param aFreeSpaceChar Character used to populate the zone that hasn't been assigned to any element.
1.212 +*/
1.213 +template <class ItemIdType,class ItemDataLengthType>
1.214 + TTlvStruct<ItemIdType,ItemDataLengthType>::TTlvStruct(TPtr8& aPtr,TUint8 aFreeSpaceChar):TTlvStructBase(aPtr,aFreeSpaceChar)
1.215 + {
1.216 + }
1.217 +
1.218 +/**
1.219 +Look up in the buffer for an item with specified identifier.
1.220 +Look-up starts from the position of the cursor;
1.221 +Returns KErrNone if the item is present in the buffer, KErrNotFound otherwise.
1.222 +Sets supplied pointer so that it has length of item's data portion and points to it.
1.223 +Internal cursor is moved to first position after the end of the found item
1.224 +(subsequent item start position in the buffer).
1.225 +
1.226 +@param aId Id of item to find.
1.227 +@param aData Descriptor which will hold the found item.
1.228 +@return System-wide error code.. If item of requested Id was not found then KErrNotFound will be returned.
1.229 +*/
1.230 +template <class ItemIdType, class ItemDataLengthType>
1.231 +TInt TTlvStruct<ItemIdType,ItemDataLengthType>::NextItemL(ItemIdType aId,TPtr8& aData)
1.232 + {
1.233 + return TTlvStructBase::NextItemL(aId,aData,iItemIdType,iItemDataLengthType);
1.234 + }
1.235 +
1.236 +/**
1.237 +Look up in the buffer for the item with specified identifier.
1.238 +Look-up starts from the position of the cursor in the buffer.
1.239 +
1.240 +Returns KErrNone if item is found, KErrNotFound otherwise (end of buffer is reached).
1.241 +Sets supplied pointer so that it points to item data portion and has length set to value of data length.
1.242 +Internal cursor is moved to first position after the end of the found item (subsequent item start position in the buffer).
1.243 +
1.244 +@param aId Id of found item.
1.245 +@param aData Descriptor which will hold the found item.
1.246 +@return System-wide error code.. If no next item found then KErrNotFound will be returned.
1.247 +*/
1.248 +template <class ItemIdType, class ItemDataLengthType>
1.249 +TInt TTlvStruct<ItemIdType,ItemDataLengthType>::AnyNextItemL(ItemIdType& aId,TPtr8& aData)
1.250 + {
1.251 + return TTlvStructBase::AnyNextItemL(aId,aData,iItemIdType,iItemDataLengthType);
1.252 + }
1.253 +
1.254 +/**
1.255 +Removes item identified by specified identifier (aId) from the buffer, where look-up starts at current cursor position, or 0 if it's reset.
1.256 +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.
1.257 +
1.258 +@param aId Id of item to remove.
1.259 +@return System-wide error code.. If item of requested Id was not found then KErrNotFound will be returned.
1.260 +*/
1.261 +template <class ItemIdType, class ItemDataLengthType>
1.262 +TInt TTlvStruct<ItemIdType,ItemDataLengthType>::RemoveNextItemL(ItemIdType aId)
1.263 + {
1.264 + return TTlvStructBase::RemoveNextItemL(aId,iItemIdType,iItemDataLengthType);
1.265 + }
1.266 +
1.267 +/**
1.268 +Adds item identified by supplied aId argument to the buffer; content of the item is copied from provided descriptor to the buffer.
1.269 +Supplied item identifier (aId) and length of the descriptor are used to set item identifier field and length field at the start of
1.270 +item unit within the buffer.
1.271 +Returns KErrNone if successful, error code otherwise.
1.272 +Internal cursor is moved to first position after the end of the found item (subsequent item start position in the buffer).
1.273 +
1.274 +@param aId Id of item to add.
1.275 +@param aData Descriptor containing data to add.
1.276 +@return System-wide error code.. If size of item to be appended is greater than free space in buffer then KErrOverflow will be returned.
1.277 +*/
1.278 +template <class ItemIdType, class ItemDataLengthType>
1.279 +TInt TTlvStruct<ItemIdType,ItemDataLengthType>::AppendItemL(ItemIdType aId,const TPtr8& aData)
1.280 + {
1.281 + return TTlvStructBase::AppendItemL(aId,iItemDataLengthType,aData);
1.282 + }
1.283 +#endif