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