|
1 // Copyright (c) 1998-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 // |
|
15 |
|
16 #if !defined(__S32BUF_H__) |
|
17 #define __S32BUF_H__ |
|
18 #if !defined(__E32STD_H__) |
|
19 #include <e32std.h> |
|
20 #endif |
|
21 |
|
22 /** Defines the type of location within a stream on which the calculation |
|
23 of a new seek position is based. |
|
24 |
|
25 The type is used by the stream buffer SeekL() functions. |
|
26 |
|
27 @see MStreamBuf::SeekL() */ |
|
28 enum TStreamLocation |
|
29 /** The seek position is calculated relative to the beginning of the |
|
30 stream.*/ |
|
31 {EStreamBeginning, |
|
32 /** The seek position is calculated relative to the end of the stream.*/ |
|
33 EStreamMark, |
|
34 /** The seek position is calculated relative to the existing read or |
|
35 write mark in the stream. */ |
|
36 EStreamEnd}; |
|
37 |
|
38 /** |
|
39 * @publishedAll |
|
40 * @released |
|
41 * Holds the position of the read or write mark within a seekable stream. |
|
42 |
|
43 Position is the offset from the beginning of a seekable stream. The class |
|
44 provides convenient operators for performing arithmetic on the offset value |
|
45 and for doing comparisons between stream position objects. |
|
46 |
|
47 It can be considered as an absolute stream position. |
|
48 |
|
49 Objects of this type are usually created as a result of calling |
|
50 MStreamBuf::SeekL() or MStreamBuf::TellL(); they allow a program to remember |
|
51 the current read position in a stream buffer and reset it to the same |
|
52 location later. |
|
53 |
|
54 @see MStreamBuf::SeekL() |
|
55 @see MStreamBuf::TellL() |
|
56 */ |
|
57 class TStreamPos |
|
58 { |
|
59 public: |
|
60 /** Constructs an empty stream position object. */ |
|
61 TStreamPos() {} |
|
62 inline TStreamPos(TInt anOffset); |
|
63 // |
|
64 inline TBool operator==(TStreamPos aPos) const; |
|
65 inline TBool operator!=(TStreamPos aPos) const; |
|
66 inline TBool operator<(TStreamPos aPos) const; |
|
67 inline TBool operator<=(TStreamPos aPos) const; |
|
68 inline TBool operator>(TStreamPos aPos) const; |
|
69 inline TBool operator>=(TStreamPos aPos) const; |
|
70 // |
|
71 inline TInt operator-(TStreamPos aPos) const; |
|
72 inline TStreamPos operator+(TInt anOffset) const; |
|
73 inline TStreamPos operator-(TInt anOffset) const; |
|
74 // |
|
75 inline TStreamPos& operator+=(TInt anOffset); |
|
76 inline TStreamPos& operator-=(TInt anOffset); |
|
77 // |
|
78 inline TInt Offset() const; |
|
79 private: |
|
80 TInt iOff; |
|
81 }; |
|
82 inline TStreamPos operator+(TInt anOffset,TStreamPos aPos); |
|
83 #if defined(__NO_CLASS_CONSTS__) |
|
84 /** Constructs a TStreamPos object that denotes the beginning of any seekable |
|
85 stream. |
|
86 |
|
87 @see TStreamPos */ |
|
88 #define KStreamBeginning TStreamPos(0) |
|
89 #else |
|
90 const TStreamPos KStreamBeginning=TStreamPos(0); |
|
91 #endif |
|
92 |
|
93 /** |
|
94 * @publishedAll |
|
95 * @released |
|
96 * Stream transfer object. |
|
97 |
|
98 Holds and maintains a value that represents how much data is to be transferred, |
|
99 or remains to be transferred, between streams. |
|
100 |
|
101 Objects of this type are used by ReadL() and WriteL() functions of MStreamBuf. |
|
102 |
|
103 @see MStreamBuf |
|
104 @see TStreamBuf |
|
105 @see TStreamMark |
|
106 @see TStreamExchange |
|
107 @see RShareBuf |
|
108 */ |
|
109 class TStreamTransfer |
|
110 { |
|
111 public: |
|
112 /** An enumerator type passed to a constructor of this class to indicate |
|
113 that there is no explicit limit to the amount of data that can be |
|
114 transferred between streams. The enumeration is not used. */ |
|
115 enum TUnlimited {EUnlimited}; |
|
116 public: |
|
117 /** Constructs a stream transfer object specifying that there is no |
|
118 explicit limit to the amount of data that can be transferred between |
|
119 streams. |
|
120 |
|
121 The amount of data to be transferred is only limited by the streams |
|
122 themselves. |
|
123 |
|
124 The arithmetical operators do not change the state of an unlimited stream |
|
125 transfer object. */ |
|
126 TStreamTransfer() {} |
|
127 inline TStreamTransfer(TInt aMaxLength); |
|
128 inline TStreamTransfer(TUnlimited); |
|
129 // |
|
130 inline TBool operator==(TInt aLength) const; |
|
131 inline TBool operator>(TInt aLength) const; |
|
132 inline TStreamTransfer operator-(TInt aLength) const; |
|
133 inline TInt operator[](TInt aMaxLength) const; |
|
134 // |
|
135 inline TStreamTransfer& operator-=(TInt aLength); |
|
136 // |
|
137 inline TInt Left() const; |
|
138 private: |
|
139 TInt iVal; |
|
140 private: |
|
141 IMPORT_C static void __DbgChkNonNegative(TInt aLength); |
|
142 }; |
|
143 inline TBool operator==(TInt aLength,TStreamTransfer aTransfer); |
|
144 inline TBool operator<(TInt aLength,TStreamTransfer aTransfer); |
|
145 #if defined(__NO_CLASS_CONSTS__) |
|
146 /** Constructs a TStreamTransfer object indicating that no explicit limit is |
|
147 imposed on transfers between streams. |
|
148 |
|
149 @see TStreamTransfer |
|
150 @see MStreamBuf::ReadL() |
|
151 @see MStreamBuf::WriteL() */ |
|
152 #define KStreamUnlimited TStreamTransfer(TStreamTransfer::EUnlimited) |
|
153 #else |
|
154 const TStreamTransfer KStreamUnlimited=TStreamTransfer::EUnlimited; |
|
155 #endif |
|
156 // |
|
157 class MStreamInput; |
|
158 class MStreamOutput; |
|
159 |
|
160 /** |
|
161 * @publishedAll |
|
162 * @released |
|
163 * A stream buffer that provides a generic I/O interface for streamed data. |
|
164 |
|
165 A stream buffer: |
|
166 |
|
167 may be buffered or unbuffered |
|
168 |
|
169 may provide read-only, write-only or read/write capability |
|
170 |
|
171 may be seekable, or unseekable. |
|
172 |
|
173 A seekable stream buffer maintains independent read and write pointers, which |
|
174 can be manipulated separately. This is unlike the RFile interface which |
|
175 maintains a single current position in the file. For example, file streams |
|
176 and memory streams are seekable streams, but socket, serial-comms, and filtered |
|
177 streams are not. |
|
178 |
|
179 Objects of this type are used by the stream interface classes derived from |
|
180 RReadStream and RWriteStream. |
|
181 |
|
182 The class has no member data. |
|
183 |
|
184 Derive from this class, if the stream has no intermediate buffering |
|
185 capabilities, otherwise derive from TStreamBuf. |
|
186 |
|
187 Get a reference to the stream buffer used by a read stream by calling |
|
188 RReadStream::Source(). Get a reference to the stream buffer used by a write |
|
189 stream by calling RWriteStream::Sink() |
|
190 |
|
191 @see RReadStream |
|
192 @see RWriteStream |
|
193 @see TStreamBuf |
|
194 */ |
|
195 class MStreamBuf |
|
196 { |
|
197 public: |
|
198 /** Indicates that an operation applies to the read mark in a stream or to |
|
199 the read area in an stream buffer. */ |
|
200 enum TRead {ERead=0x01}; |
|
201 |
|
202 /** Indicates that an operation applies to the write mark in a stream or |
|
203 to the write area in an stream buffer. */ |
|
204 enum TWrite {EWrite=0x02}; |
|
205 |
|
206 /** Used to identify the type of mark in a stream. |
|
207 |
|
208 The type is used by functions of this class and derived classes that perform |
|
209 seek operations to marks within a stream. |
|
210 |
|
211 The type uses the ERead and EWrite enumeration values, as bit flags, to |
|
212 identify the read and write marks respectively. |
|
213 |
|
214 ERead is an MStreamBuf::TRead enumerator. EWrite is an MStreamBuf::EWrite |
|
215 enumerator. |
|
216 |
|
217 @see MStreamBuf::TRead |
|
218 @see MStreamBuf::TWrite */ |
|
219 typedef TInt TMark; |
|
220 public: |
|
221 IMPORT_C void Close(); |
|
222 inline void Release(); |
|
223 IMPORT_C TInt Synch(); |
|
224 inline void SynchL(); |
|
225 // |
|
226 IMPORT_C void PushL(); |
|
227 // |
|
228 inline TInt ReadL(TAny* aPtr,TInt aMaxLength); |
|
229 IMPORT_C TInt Read(TDes8& aDes,TRequestStatus& aStatus); |
|
230 IMPORT_C TInt Read(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus); |
|
231 IMPORT_C TInt ReadL(TDes8& aDes,TRequestStatus& aStatus); |
|
232 inline TInt ReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus); |
|
233 inline TStreamTransfer ReadL(MStreamInput& anInput,TStreamTransfer aTransfer); |
|
234 IMPORT_C TInt ReadL(MStreamInput& anInput,TInt aMaxLength); |
|
235 inline void ReadL(MStreamInput& anInput); |
|
236 // |
|
237 inline void WriteL(const TAny* aPtr,TInt aLength); |
|
238 IMPORT_C TInt Write(const TDesC8& aDes,TRequestStatus& aStatus); |
|
239 IMPORT_C TInt Write(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus); |
|
240 IMPORT_C TInt WriteL(const TDesC8& aDes,TRequestStatus& aStatus); |
|
241 inline TInt WriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus); |
|
242 inline TStreamTransfer WriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer); |
|
243 IMPORT_C TInt WriteL(MStreamOutput& anOutput,TInt aMaxLength); |
|
244 inline void WriteL(MStreamOutput& anOutput); |
|
245 // |
|
246 inline void SeekL(TMark aMark,TStreamPos aPos); |
|
247 inline TStreamPos SeekL(TMark aMark,TStreamLocation aLocation,TInt anOffset=0); |
|
248 inline TStreamPos SeekL(TRead,TStreamLocation aLocation,TInt anOffset=0); |
|
249 inline TStreamPos SeekL(TWrite,TStreamLocation aLocation,TInt anOffset=0); |
|
250 inline TStreamPos SeekL(TRead,TInt anOffset); |
|
251 inline TStreamPos SeekL(TWrite,TInt anOffset); |
|
252 // |
|
253 inline TStreamPos TellL(TRead) const; |
|
254 inline TStreamPos TellL(TWrite) const; |
|
255 inline TInt SizeL() const; |
|
256 protected: |
|
257 MStreamBuf() {} |
|
258 private: |
|
259 MStreamBuf(const MStreamBuf&); |
|
260 MStreamBuf& operator=(const MStreamBuf&); |
|
261 // |
|
262 virtual IMPORT_C void DoRelease(); |
|
263 virtual IMPORT_C void DoSynchL(); |
|
264 virtual IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength); |
|
265 virtual IMPORT_C TInt DoReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus); |
|
266 virtual IMPORT_C TStreamTransfer DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer); |
|
267 virtual IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength); |
|
268 virtual IMPORT_C TInt DoWriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus); |
|
269 virtual IMPORT_C TStreamTransfer DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer); |
|
270 virtual IMPORT_C TStreamPos DoSeekL(TMark aMark,TStreamLocation aLocation,TInt anOffset); |
|
271 }; |
|
272 |
|
273 /** |
|
274 * @publishedAll |
|
275 * @released |
|
276 * An interface to an object that acts as a target for read operations from |
|
277 a stream. The object behaves as a generic data sink. |
|
278 |
|
279 A stream input object can act as an intelligent buffer, and is useful for |
|
280 performing filtering, compression or any other general kind of conversion |
|
281 operation that might be needed after reading from a stream. |
|
282 |
|
283 The class is pure interface and requires an implementation. |
|
284 |
|
285 @see MStreamBuf::ReadL() |
|
286 */ |
|
287 class MStreamInput |
|
288 { |
|
289 public: |
|
290 /** Reads data from an intermediate buffer into this stream input object. |
|
291 |
|
292 This function is called by the default implementation of |
|
293 TStreamBuf::DoReadL(MStreamInput&,TStreamTransfer) |
|
294 and assumes that the source is a stream buffer's intermediate buffer. |
|
295 |
|
296 @param aPtr A pointer into the intermediate buffer from which the read |
|
297 operation starts. |
|
298 @param aMaxLength The maximum amount of data to be read. |
|
299 @return The amount of data read. |
|
300 @see TStreamBuf::DoReadL() |
|
301 @see TStreamBuf */ |
|
302 virtual TInt PushL(const TAny* aPtr,TInt aMaxLength)=0; |
|
303 |
|
304 /** Reads data from the specified stream into this stream input object. |
|
305 |
|
306 This function is called by the default implementation of |
|
307 MStreamBuf::DoReadL(MStreamInput&,TStreamTransfer). |
|
308 It may also be called by TStreamBuf::DoReadL(MStreamInput&,TStreamTransfer), |
|
309 depending on the amount of data to be transferred and the nature of the |
|
310 buffering scheme. |
|
311 |
|
312 @param aSource The stream from which data is to be read. |
|
313 @param aTransfer Defines the amount of data available to be read. |
|
314 @return The amount of data that was not consumed. |
|
315 @see MStreamBuf::DoReadL() |
|
316 @see TStreamBuf::DoReadL() */ |
|
317 virtual TStreamTransfer ReadFromL(MStreamBuf& aSource,TStreamTransfer aTransfer)=0; |
|
318 }; |
|
319 |
|
320 /** |
|
321 * @publishedAll |
|
322 * @released |
|
323 * An interface to an object that acts as source for write operations to a |
|
324 stream. The object behaves as a generic data source. |
|
325 |
|
326 A stream output object can act as an intelligent buffer, and is useful for |
|
327 performing filtering, compression or any other general kind of conversion |
|
328 operation that might be needed before writing to a stream. |
|
329 |
|
330 The class is pure interface and requires an implementation. |
|
331 |
|
332 @see MStreamBuf::WriteL() |
|
333 */ |
|
334 class MStreamOutput |
|
335 { |
|
336 public: |
|
337 /** Writes data to an intermediate buffer from this stream output object. |
|
338 |
|
339 This function is called by the default implementation of |
|
340 TStreamBuf::DoWriteL(MStreamOutput&,TStreamTransfer) |
|
341 and assumes that the target is a stream buffer's intermediate buffer. |
|
342 |
|
343 @param aPtr A pointer into the intermediate buffer where the write operation |
|
344 starts. |
|
345 @param aMaxLength The maximum amount of data to be written. |
|
346 @return The amount of data written. |
|
347 @see TStreamBuf::DoWriteL() |
|
348 @see TStreamBuf */ |
|
349 virtual TInt PullL(TAny* aPtr,TInt aMaxLength)=0; |
|
350 |
|
351 /** Writes data to the specified stream from this stream output object. |
|
352 |
|
353 This function is called by the default implementation of |
|
354 MStreamBuf::DoWriteL(MStreamOutput&,TStreamTransfer). |
|
355 It may also be called by TStreamBuf::DoWriteL(MStreamOutput&,TStreamTransfer), |
|
356 depending on the amount of data to be transferred and the nature of the |
|
357 buffering scheme. |
|
358 |
|
359 @param aSink The stream to which data is to be written. |
|
360 @param aTransfer Defines the amount of data available to be written. |
|
361 @return The amount of data that was not consumed. |
|
362 @see MStreamBuf::DoWriteL() |
|
363 @see TStreamBuf::DoWriteL() */ |
|
364 virtual TStreamTransfer WriteToL(MStreamBuf& aSink,TStreamTransfer aTransfer)=0; |
|
365 }; |
|
366 |
|
367 /** |
|
368 * @publishedAll |
|
369 * @released |
|
370 * Adds buffering capabilities to a stream buffer |
|
371 |
|
372 The class provides pointers to mark out the current read and write areas within |
|
373 the intermediate buffer. The class also defines the pure virtual functions |
|
374 UnderflowL() and OverflowL() which must be provided by a derived class. |
|
375 |
|
376 Streams which have buffering capabilities derive from this class, otherwise |
|
377 they derive from MStreamBuf. |
|
378 |
|
379 Note that the class does not provide the buffer; this is left to the class |
|
380 derived from it. For example, the memory buffer classes use the memory area |
|
381 directly, the file buffer class allocate a heap cell to use as a buffer. |
|
382 |
|
383 @see UnderflowL() |
|
384 @see OverflowL() |
|
385 */ |
|
386 class TStreamBuf : public MStreamBuf |
|
387 { |
|
388 protected: |
|
389 /** Used to identify the type of area within an intermediate buffer. |
|
390 |
|
391 The type is used by functions of this class that set or get pointers into |
|
392 the intermediate buffer. |
|
393 |
|
394 The type uses the ERead and EWrite enumeration values, as bit flags, to |
|
395 identify the read and write areas respectively. |
|
396 |
|
397 ERead is an MStreamBuf::TRead enumerator. EWrite is an MStreamBuf::EWrite |
|
398 enumerator. |
|
399 |
|
400 @see MStreamBuf::TRead |
|
401 @see MStreamBuf::TWrite */ |
|
402 typedef TInt TArea; |
|
403 protected: |
|
404 IMPORT_C TStreamBuf(); |
|
405 // |
|
406 IMPORT_C void SetBuf(TArea anArea,TUint8* aPtr,TUint8* anEnd); |
|
407 IMPORT_C void SetPtr(TArea anArea,TUint8* aPtr); |
|
408 IMPORT_C void SetEnd(TArea anArea,TUint8* anEnd); |
|
409 IMPORT_C TUint8* Ptr(TArea anArea) const; |
|
410 IMPORT_C TUint8* End(TArea anArea) const; |
|
411 IMPORT_C TInt Avail(TArea anArea) const; |
|
412 // |
|
413 IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength); |
|
414 IMPORT_C TStreamTransfer DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer); |
|
415 IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength); |
|
416 IMPORT_C TStreamTransfer DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer); |
|
417 // |
|
418 inline void SetBuf(TRead,TUint8* aPtr,TUint8* anEnd); |
|
419 inline void SetBuf(TWrite,TUint8* aPtr,TUint8* anEnd); |
|
420 inline void SetPtr(TRead,TUint8* aPtr); |
|
421 inline void SetPtr(TWrite,TUint8* aPtr); |
|
422 inline void SetEnd(TRead,TUint8* anEnd); |
|
423 inline void SetEnd(TWrite,TUint8* anEnd); |
|
424 inline TUint8* Ptr(TRead) const; |
|
425 inline TUint8* Ptr(TWrite) const; |
|
426 inline TUint8* End(TRead) const; |
|
427 inline TUint8* End(TWrite) const; |
|
428 inline TInt Avail(TRead) const; |
|
429 inline TInt Avail(TWrite) const; |
|
430 private: |
|
431 /** Re-fills the intermediate buffer and resets the start and end points |
|
432 of the read area. |
|
433 |
|
434 The implementation of this function depends on the way the stream itself is |
|
435 implemented. For example, the in-memory streams have simple implementations. |
|
436 |
|
437 @param aMaxLength The maximum amount of data required for the intermediate |
|
438 buffer. |
|
439 @return The amount of data available in the intermediate buffer. */ |
|
440 virtual TInt UnderflowL(TInt aMaxLength)=0; |
|
441 |
|
442 /** Empties the intermediate buffer and resets the start and end points |
|
443 of the write area. |
|
444 |
|
445 The implementation of this function depends on the way the stream itself is |
|
446 implemented. For example, the in-memory streams have simple implementations. */ |
|
447 virtual void OverflowL()=0; |
|
448 private: |
|
449 TUint8* iRPtr; |
|
450 TUint8* iREnd; |
|
451 TUint8* iWPtr; |
|
452 TUint8* iWEnd; |
|
453 }; |
|
454 |
|
455 /** |
|
456 * @publishedAll |
|
457 * @released |
|
458 * Interface to a stream filter. |
|
459 |
|
460 A stream filter is an object that allows stream data to be filtered after |
|
461 retrieval from a host or filtered before being written to a host. |
|
462 |
|
463 The class is abstract and a derived class must be defined an implemented. |
|
464 */ |
|
465 class TStreamFilter : public MStreamBuf |
|
466 { |
|
467 public: |
|
468 enum {EAttached=0x10}; |
|
469 protected: |
|
470 IMPORT_C TStreamFilter(); |
|
471 inline void Set(MStreamBuf* aHost,TInt aMode); |
|
472 inline void Committed(); |
|
473 inline TBool IsCommitted() const; |
|
474 IMPORT_C void EmitL(const TAny* aPtr,TInt aLength); |
|
475 // |
|
476 IMPORT_C void DoRelease(); |
|
477 IMPORT_C void DoSynchL(); |
|
478 IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength); |
|
479 IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength); |
|
480 private: |
|
481 /** Calculates the maximum size of unfiltered data necessary to give the |
|
482 specified amount of filtered data. |
|
483 |
|
484 @param aMaxLength The amount of filtered data required. |
|
485 @return The maximum amount of unfiltered data guaranteed not to generate |
|
486 more than aMaxLength bytes of filtered output. */ |
|
487 virtual TInt Capacity(TInt aMaxLength)=0; |
|
488 |
|
489 /** Performs the filtration process. |
|
490 |
|
491 @param aPtr Pointer to the output location for the filtered data. |
|
492 @param aMaxLength The maximum amount of space available for the filtered |
|
493 data. |
|
494 @param aFrom A reference to a pointer to the unfiltered data source. This |
|
495 pointer should be advanced as the source is consumed. |
|
496 @param anEnd Pointer to the first byte beyond the end of the unfiltered |
|
497 data source. |
|
498 @return The size of the filtered data. */ |
|
499 virtual TInt FilterL(TAny* aPtr,TInt aMaxLength,const TUint8*& aFrom,const TUint8* anEnd)=0; |
|
500 private: |
|
501 MStreamBuf* iHost; |
|
502 TInt iMode; |
|
503 private: |
|
504 friend class TFilterInput; |
|
505 friend class TFilterOutput; |
|
506 private: |
|
507 IMPORT_C static void __DbgChkMode(TInt aMode); |
|
508 }; |
|
509 |
|
510 #include <s32buf.inl> |
|
511 #endif |