|
1 // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Contains various utility classes which are used throughout Telephony. |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 @file |
|
20 @publishedPartner |
|
21 @released |
|
22 */ |
|
23 |
|
24 #if !defined(__ETELUTILS_H__) |
|
25 /** @publishedPartner */ |
|
26 #define __ETELUTILS_H__ |
|
27 |
|
28 #include <e32base.h> |
|
29 |
|
30 /** |
|
31 Base class for generic actions in retrieving a variable length buffer in two phases. |
|
32 |
|
33 This class is abstract. |
|
34 |
|
35 @publishedPartner |
|
36 @released |
|
37 */ |
|
38 class CAsyncRetrieveVariableLengthBufferV2 : public CActive |
|
39 { |
|
40 protected: |
|
41 // |
|
42 // Start the retrieval |
|
43 // |
|
44 |
|
45 IMPORT_C void Start(TRequestStatus& aReqStatus, TDes8* aPhase1Request, TDes8* aPhase2Request); |
|
46 IMPORT_C CAsyncRetrieveVariableLengthBufferV2(); |
|
47 IMPORT_C virtual ~CAsyncRetrieveVariableLengthBufferV2(); |
|
48 |
|
49 IMPORT_C TBool CompleteIfInUse(TRequestStatus& aReqStatus); |
|
50 IMPORT_C void FreeBuffer(); |
|
51 |
|
52 private: |
|
53 IMPORT_C virtual void RestoreListL(); |
|
54 virtual void Get(TInt aIpc, TRequestStatus& aReqStatus, TDes8& aDes1, TDes8& aDes2) = 0; |
|
55 virtual void CancelReq(TInt aIpc1,TInt aIpc2) = 0; |
|
56 |
|
57 IMPORT_C virtual void DoCancel(); |
|
58 IMPORT_C virtual void RunL(); |
|
59 |
|
60 void StartPhase2L(); |
|
61 |
|
62 protected: |
|
63 /** |
|
64 Maintains the current phase of buffer retrieval. |
|
65 */ |
|
66 enum { |
|
67 EIdle, |
|
68 ERetrievePhase1, |
|
69 ERetrievePhase2 |
|
70 } iState; |
|
71 |
|
72 CBufBase* iResultsBuf; |
|
73 TPtr8 iResultsPtr; |
|
74 TInt iIpcPhase1; |
|
75 TInt iIpcPhase2; |
|
76 TInt iIpcCancel; |
|
77 private: |
|
78 /** |
|
79 Pointer to the user's asynchronous request status object. |
|
80 */ |
|
81 TRequestStatus* iUserStatus; |
|
82 TDes8* iPhase1RequestData; |
|
83 TDes8* iPhase2RequestData; |
|
84 TPckgBuf<TInt> iBufferSize; |
|
85 }; |
|
86 |
|
87 |
|
88 // |
|
89 /* following classes define interface to TLV ( TYPE- LENGTH-VALUE) structured data: |
|
90 ------------------------------------------------------------------------------------------------- |
|
91 | | | | | | | |
|
92 |ItemId | Length Of The Item Data | Item Data | ItemId | Length Of The Item Data | Item Data | |
|
93 | | | | | | | |
|
94 ------------------------------------------------------------------------------------------------- |
|
95 */ |
|
96 |
|
97 /** |
|
98 Defines interface for specifying the Tag of a TLV object. |
|
99 |
|
100 @publishedPartner |
|
101 @released |
|
102 */ |
|
103 class MTlvItemIdType |
|
104 { |
|
105 public: |
|
106 /**Externalize object by serializing to provided descriptor*/ |
|
107 virtual void ExternalizeL(TDes8& aBuffer) const =0; |
|
108 /** Internalize object by de-serializing of data in provided buffer*/ |
|
109 virtual void InternalizeL(TDesC8& aBuffer)=0; |
|
110 /** The length of serialized data member */ |
|
111 virtual TUint SerializedLength() const =0; |
|
112 /** compares whether two objects contains the same data*/ |
|
113 virtual TBool IsEqual(const MTlvItemIdType&) const=0; |
|
114 }; |
|
115 |
|
116 /** |
|
117 Defines interface for specifying the Length of a TLV object. |
|
118 |
|
119 @publishedPartner |
|
120 @released |
|
121 */ |
|
122 class MTlvItemDataLengthType |
|
123 { |
|
124 public: |
|
125 /**Externalize object by serializing to provided descriptor*/ |
|
126 virtual void ExternalizeL(TDes8& aBuffer)const=0; |
|
127 /** Internalize object by de-serializing of data in provided buffer*/ |
|
128 virtual void InternalizeL(TDesC8& aBuffer)=0; |
|
129 /** The length of serialized data member */ |
|
130 virtual TUint SerializedLength() const=0; |
|
131 /** Sets length of the data it relates to*/ |
|
132 virtual void SetDataLength(TUint)=0; |
|
133 /** Gets length of the data it relates to*/ |
|
134 virtual TUint DataLength() const =0; |
|
135 }; |
|
136 |
|
137 /** |
|
138 Provides methods to append, remove or perform iterative lookup for items in container buffer. |
|
139 Classes ItemIdType and ItemDataLengthType have to implement interfaces MTlvItemIdType and |
|
140 MTlvItemDataLengthType in order to enable proper encoding and decoding of the first two fields |
|
141 in the unit. |
|
142 |
|
143 @publishedPartner |
|
144 @released |
|
145 */ |
|
146 class TTlvStructBase |
|
147 { |
|
148 protected: |
|
149 /** Default constructor initializes data members*/ |
|
150 IMPORT_C TTlvStructBase(TPtr8&,TUint8); |
|
151 /** Base class implementation of methods in the templated class*/ |
|
152 IMPORT_C TInt AppendItemL(MTlvItemIdType& aId,MTlvItemDataLengthType& aDataLengthType,const TPtr8& aData); |
|
153 IMPORT_C TInt RemoveNextItemL(MTlvItemIdType& aIdToRemove,MTlvItemIdType& aId, MTlvItemDataLengthType& aDataLength); |
|
154 IMPORT_C TInt AnyNextItemL(MTlvItemIdType& aIdFound,TPtr8& aData,MTlvItemIdType& aId, MTlvItemDataLengthType& aDataLength); |
|
155 IMPORT_C TInt NextItemL(const MTlvItemIdType& aWantedId,TPtr8& aData,MTlvItemIdType& aId, MTlvItemDataLengthType& aDataLength); |
|
156 public: |
|
157 /** Sets position of the cursor to start position (0)*/ |
|
158 IMPORT_C void ResetCursorPos(); |
|
159 |
|
160 protected: |
|
161 /** Reference to external buffer that holds encoded TLV data*/ |
|
162 TPtr8& iPtr; |
|
163 /** Cursor indicates last accessed item in the buffer*/ |
|
164 TUint iCursorPos; |
|
165 /** Position in the buffer that indicates start of the zone that hasn't been assigned to any element. |
|
166 this free zone ends at the end of the buffer*/ |
|
167 TUint iFreeSpacePos; |
|
168 /** Character used to populate the zone that hasn't been assigned to any element. |
|
169 this free zone ends at the end of the buffer*/ |
|
170 TUint8 iFreeSpaceChar; |
|
171 }; |
|
172 |
|
173 /** |
|
174 Provides methods to append, remove or perform iterative lookup for items in container buffer. |
|
175 Classes ItemIdType and ItemDataLengthType have to implement interfaces MTlvItemIdType and |
|
176 MTlvItemDataLengthType in order to enable proper encoding and decoding of the first two fields |
|
177 in the unit. |
|
178 |
|
179 @publishedPartner |
|
180 @released |
|
181 */ |
|
182 template <class ItemIdType, class ItemDataLengthType> |
|
183 class TTlvStruct: public TTlvStructBase |
|
184 { |
|
185 public: |
|
186 |
|
187 inline TTlvStruct(TPtr8&,TUint8); |
|
188 inline TInt NextItemL(ItemIdType aId,TPtr8& aData); |
|
189 inline TInt AnyNextItemL(ItemIdType& aId, TPtr8& aData); |
|
190 inline TInt AppendItemL(ItemIdType aId,const TPtr8& aData); |
|
191 inline TInt RemoveNextItemL(ItemIdType aId); |
|
192 |
|
193 protected: |
|
194 /** Default constructor is protected in order to enforce proper initialization of reference to external data buffer via provided public constructor*/ |
|
195 TTlvStruct(); |
|
196 /** Type of the identifier*/ |
|
197 ItemIdType iItemIdType; |
|
198 /** The type used to define length of data portion of the item*/ |
|
199 ItemDataLengthType iItemDataLengthType; |
|
200 }; |
|
201 |
|
202 /** |
|
203 Default constructor initializes data members and cursor position to 0. |
|
204 |
|
205 @param aPtr Ptr descriptor to TLV buffer that is to be read or written to. |
|
206 @param aFreeSpaceChar Character used to populate the zone that hasn't been assigned to any element. |
|
207 */ |
|
208 template <class ItemIdType,class ItemDataLengthType> |
|
209 TTlvStruct<ItemIdType,ItemDataLengthType>::TTlvStruct(TPtr8& aPtr,TUint8 aFreeSpaceChar):TTlvStructBase(aPtr,aFreeSpaceChar) |
|
210 { |
|
211 } |
|
212 |
|
213 /** |
|
214 Look up in the buffer for an item with specified identifier. |
|
215 Look-up starts from the position of the cursor; |
|
216 Returns KErrNone if the item is present in the buffer, KErrNotFound otherwise. |
|
217 Sets supplied pointer so that it has length of item's data portion and points to it. |
|
218 Internal cursor is moved to first position after the end of the found item |
|
219 (subsequent item start position in the buffer). |
|
220 |
|
221 @param aId Id of item to find. |
|
222 @param aData Descriptor which will hold the found item. |
|
223 @return System-wide error code.. If item of requested Id was not found then KErrNotFound will be returned. |
|
224 */ |
|
225 template <class ItemIdType, class ItemDataLengthType> |
|
226 TInt TTlvStruct<ItemIdType,ItemDataLengthType>::NextItemL(ItemIdType aId,TPtr8& aData) |
|
227 { |
|
228 return TTlvStructBase::NextItemL(aId,aData,iItemIdType,iItemDataLengthType); |
|
229 } |
|
230 |
|
231 /** |
|
232 Look up in the buffer for the item with specified identifier. |
|
233 Look-up starts from the position of the cursor in the buffer. |
|
234 |
|
235 Returns KErrNone if item is found, KErrNotFound otherwise (end of buffer is reached). |
|
236 Sets supplied pointer so that it points to item data portion and has length set to value of data length. |
|
237 Internal cursor is moved to first position after the end of the found item (subsequent item start position in the buffer). |
|
238 |
|
239 @param aId Id of found item. |
|
240 @param aData Descriptor which will hold the found item. |
|
241 @return System-wide error code.. If no next item found then KErrNotFound will be returned. |
|
242 */ |
|
243 template <class ItemIdType, class ItemDataLengthType> |
|
244 TInt TTlvStruct<ItemIdType,ItemDataLengthType>::AnyNextItemL(ItemIdType& aId,TPtr8& aData) |
|
245 { |
|
246 return TTlvStructBase::AnyNextItemL(aId,aData,iItemIdType,iItemDataLengthType); |
|
247 } |
|
248 |
|
249 /** |
|
250 Removes item identified by specified identifier (aId) from the buffer, where look-up starts at current cursor position, or 0 if it's reset. |
|
251 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. |
|
252 |
|
253 @param aId Id of item to remove. |
|
254 @return System-wide error code.. If item of requested Id was not found then KErrNotFound will be returned. |
|
255 */ |
|
256 template <class ItemIdType, class ItemDataLengthType> |
|
257 TInt TTlvStruct<ItemIdType,ItemDataLengthType>::RemoveNextItemL(ItemIdType aId) |
|
258 { |
|
259 return TTlvStructBase::RemoveNextItemL(aId,iItemIdType,iItemDataLengthType); |
|
260 } |
|
261 |
|
262 /** |
|
263 Adds item identified by supplied aId argument to the buffer; content of the item is copied from provided descriptor to the buffer. |
|
264 Supplied item identifier (aId) and length of the descriptor are used to set item identifier field and length field at the start of |
|
265 item unit within the buffer. |
|
266 Returns KErrNone if successful, error code otherwise. |
|
267 Internal cursor is moved to first position after the end of the found item (subsequent item start position in the buffer). |
|
268 |
|
269 @param aId Id of item to add. |
|
270 @param aData Descriptor containing data to add. |
|
271 @return System-wide error code.. If size of item to be appended is greater than free space in buffer then KErrOverflow will be returned. |
|
272 */ |
|
273 template <class ItemIdType, class ItemDataLengthType> |
|
274 TInt TTlvStruct<ItemIdType,ItemDataLengthType>::AppendItemL(ItemIdType aId,const TPtr8& aData) |
|
275 { |
|
276 return TTlvStructBase::AppendItemL(aId,iItemDataLengthType,aData); |
|
277 } |
|
278 #endif |