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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
17 inline TStreamPos::TStreamPos(TInt anOffset)
19 /** Constructs the stream position object from the specified value.
21 @param anOffset The position value. */
23 inline TBool TStreamPos::operator==(TStreamPos aPos) const
24 /** Tests whether the stream position is equal to the specified stream position.
26 @param aPos The stream position to be compared.
27 @return True, if this object's stream position value is equal to the specified
28 stream position's value; false, otherwise. */
29 {return iOff==aPos.iOff;}
30 inline TBool TStreamPos::operator!=(TStreamPos aPos) const
31 /** Tests whether the stream position is not equal to the specified stream position.
33 @param aPos The stream position to be compared.
34 @return True, if this object's stream position value is not equal to the specified
35 stream position's value; false, otherwise. */
36 {return iOff!=aPos.iOff;}
37 inline TBool TStreamPos::operator<(TStreamPos aPos) const
38 /** Tests whether the stream position is less than the specified stream position.
40 @param aPos The stream position to be compared.
41 @return True, if this object's stream position value is less than the specified
42 stream position's value; false, otherwise. */
43 {return iOff<aPos.iOff;}
44 inline TBool TStreamPos::operator<=(TStreamPos aPos) const
45 /** Tests whether the stream position is less than or equal to the specified stream
48 @param aPos The stream position to be compared.
49 @return True, if this object's stream position value is less than or equal
50 to the specified stream position's value; false, otherwise. */
51 {return iOff<=aPos.iOff;}
52 inline TBool TStreamPos::operator>(TStreamPos aPos) const
53 /** Tests whether the stream position is greater than the specified stream position.
55 @param aPos The stream position to be compared.
56 @return True, if this object's stream position value is greater than the specified
57 stream position's value; false, otherwise. */
58 {return iOff>aPos.iOff;}
59 inline TBool TStreamPos::operator>=(TStreamPos aPos) const
60 /** Tests whether the stream position is greater than or equal to the specified
63 @param aPos The stream position to be compared.
64 @return True, if this object's stream position value is greater than or equal
65 to the specified stream position's value; false, otherwise. */
66 {return iOff>=aPos.iOff;}
67 inline TInt TStreamPos::operator-(TStreamPos aPos) const
68 /** Gets the result of subtracting the specified stream position value from this
69 object's stream position value.
71 @param aPos The stream position whose value is to be subtracted.
72 @return The result of the calculation. */
73 {return iOff-aPos.iOff;}
74 inline TStreamPos TStreamPos::operator+(TInt anOffset) const
75 /** Gets a stream position object that holds the result of adding the specified
76 value to this object's stream position value.
78 @param anOffset The value to be added.
79 @return The stream position object holding the result of the calculation. */
80 {return TStreamPos(iOff+anOffset);}
81 inline TStreamPos TStreamPos::operator-(TInt anOffset) const
82 /** Gets a stream position object that holds the result of subtracting the specified
83 value from this object's stream position value.
85 @param anOffset The value to be subtracted.
86 @return The stream position object holding the result of the calculation. */
87 {return TStreamPos(iOff-anOffset);}
88 inline TStreamPos& TStreamPos::operator+=(TInt anOffset)
89 /** Adds the specified value to this stream position object.
91 @param anOffset The value to be added.
92 @return A reference to this stream position object. */
93 {iOff+=anOffset;return *this;}
94 inline TStreamPos& TStreamPos::operator-=(TInt anOffset)
95 /** Subtracts the specified value from this stream position object.
97 @param anOffset The value to be subtracted.
98 @return A reference to this stream position object. */
99 {iOff-=anOffset;return *this;}
100 inline TInt TStreamPos::Offset() const
101 /** Gets the stream position value.
103 @return The stream position value. */
105 inline TStreamPos operator+(TInt anOffset,TStreamPos aPos)
106 {return aPos+anOffset;}
108 // Class TStreamTransfer
109 inline TStreamTransfer::TStreamTransfer(TInt aMaxLength)
111 /** Constructs a stream transfer object specifying a length value.
113 This value represents the maximum amount of data that can be transferred between
116 @param aMaxLength The maximum length of data that can be transferred. In debug
117 mode, the function raises a STORE-Stream 13 panic, if this value is negative. */
120 __DbgChkNonNegative(aMaxLength);
123 inline TStreamTransfer::TStreamTransfer(TUnlimited)
125 /** Constructs a stream transfer object specifying that there is no explicit limit
126 to the amount of data that can be transferred between streams.
128 The amount of data to be transferred is only limited by the streams themselves.
130 The arithmetical operators do not change the state of an unlimited stream
133 @param (The enumerator value is not used). */
135 inline TBool TStreamTransfer::operator==(TInt aLength) const
136 /** Tests whether the stream transfer value is equal to the specified value.
138 @param aLength The length to compared. In debug mode, the function raises
139 a STORE-Stream 13 panic, if this value is negative.
140 @return True, if the stream transfer value is equal to the specified value;
144 __DbgChkNonNegative(aLength);
146 return iVal==aLength;
148 inline TBool TStreamTransfer::operator>(TInt aLength) const
149 /** Tests whether the stream transfer value is greater than the specified value.
151 @param aLength The length to compared. In debug mode, the function raises
152 a STORE-Stream 13 panic, if this value is negative.
153 @return True, if the stream transfer value is greater than the specified value;
157 __DbgChkNonNegative(aLength);
159 return TUint(iVal)>TUint(aLength);
161 inline TStreamTransfer TStreamTransfer::operator-(TInt aLength) const
162 /** Subtracts the specified value from the stream transfer value.
164 If this stream transfer object was originally constructed as an unlimited
165 type, i.e. using the TStreamTransfer(TUnlimited) constructor, then this operator
166 does not change the state of the object, and it remains an unlimited type.
168 @param aLength The length to be subtracted. In debug mode, the function raises
169 a STORE-Stream 13 panic, if this value is negative.
170 @return A stream transfer object containing the result of the subtraction. */
173 __DbgChkNonNegative(aLength);
175 return iVal<0?*this:TStreamTransfer(iVal-aLength);
177 inline TInt TStreamTransfer::operator[](TInt aMaxLength) const
178 {return *this>aMaxLength?aMaxLength:iVal;}
179 inline TStreamTransfer& TStreamTransfer::operator-=(TInt aLength)
180 /** Subtracts the specified value from the stream transfer value, updating this
181 stream transfer object.
183 If this stream transfer object was originally constructed as an unlimited
184 type, i.e. using the TStreamTransfer(TUnlimited) constructor, then this operator
185 does not change the state of the object, and it remains an unlimited type.
187 If this stream transfer object was not an unlimited type, then, in debug mode,
188 the function raises a STORE-Stream 13 panic, if the result of the calculation
191 @param aLength The length to be subtracted. In debug mode, the function raises
192 a STORE-Stream 13 panic, if this value is negative.
193 @return A reference to this stream transfer object. */
196 __DbgChkNonNegative(aLength);
202 __DbgChkNonNegative(iVal);
207 inline TInt TStreamTransfer::Left() const
208 /** Gets the stream transfer value.
210 @return The current stream transfer value. */
213 __DbgChkNonNegative(iVal);
217 inline TBool operator==(TInt aLength,TStreamTransfer aTransfer)
218 {return aTransfer==aLength;}
219 inline TBool operator<(TInt aLength,TStreamTransfer aTransfer)
220 {return aTransfer>aLength;}
223 inline void MStreamBuf::Release()
224 /** Frees resources before abandoning the stream buffer.
226 The function calls the virtual function DoRelease() to implement this behaviour.
228 Release() is called by both RReadStream::Release() and RWriteStream::Release().
230 @see MStreamBuf::DoRelease()
231 @see RReadStream::Release()
232 @see RWriteStream::Release() */
234 inline void MStreamBuf::SynchL()
235 /** Synchronises the stream buffer with the stream, leaving if any error occurs.
237 In effect, this ensures that buffered data is delivered to the stream.
239 The function calls the virtual function DoSynchL() to implement this behaviour.
241 @see MStreamBuf::DoSynchL() */
243 inline TInt MStreamBuf::ReadL(TAny* aPtr,TInt aMaxLength)
244 /** Reads data from the stream buffer into the specified memory location.
246 The function calls the virtual function DoReadL(TAny*,TInt) to implement this
249 @param aPtr A pointer to the target memory location for the data read from
251 @param aMaxLength The maximum number of bytes to be read.
252 @return The number of bytes read.
253 @see MStreamBuf::DoReadL() */
254 {return DoReadL(aPtr,aMaxLength);}
255 inline TInt MStreamBuf::ReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus)
256 /** Reads data, asynchronously, from the stream buffer into the specified descriptor.
258 The function calls the virtual function DoReadL(TDes8&,TInt,TRequestStatus&)
259 to implement this behaviour.
261 If the function leaves, then no read request will have been initiated.
263 @param aDes The target descriptor for the data read from the stream buffer.
264 @param aMaxLength The maximum number of bytes to be read.
265 @param aStatus The request status that indicates the completion status of this
266 asynchronous request.
267 @return The maximum number of bytes to be read, as used in this request. This
268 can be different to the value supplied in aMaxLength; this is dependent on
270 @see MStreamBuf::DoReadL() */
271 {return DoReadL(aDes,aMaxLength,aStatus);}
272 inline TStreamTransfer MStreamBuf::ReadL(MStreamInput& anInput,TStreamTransfer aTransfer)
273 /** Reads data from the stream buffer into the specified data sink.
275 The function calls the virtual function DoReadL(MStreamInput&,TStreamTransfer)
276 to implement this behaviour.
278 @param anInput The data sink that is the target for the read operation.
279 @param aTransfer Defines the amount of data available to be read.
280 @return The amount of data that was not consumed. */
281 {return DoReadL(anInput,aTransfer);}
282 inline void MStreamBuf::ReadL(MStreamInput& anInput)
283 /** Reads data from the stream buffer into the specified data sink.
285 The function uses the virtual function DoReadL(MStreamInput&,TStreamTransfer)
286 to implement this behaviour.
288 No explicit limit is placed on the amount of data that can be read.
290 @param anInput The data sink that is the target for the read operation. */
291 {DoReadL(anInput,KStreamUnlimited);}
292 inline void MStreamBuf::WriteL(const TAny* aPtr,TInt aLength)
293 /** Writes data from the specified memory location into the stream buffer.
295 The function calls the virtual function DoWriteL(TAny*,TInt) to implement
298 @param aPtr A pointer to the memory location from which data is to be written
299 to the stream buffer.
300 @param aLength The number of bytes to be written.
301 @see MStreamBuf::DoWriteL() */
302 {DoWriteL(aPtr,aLength);}
303 inline TInt MStreamBuf::WriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus)
304 /** Writes data, asynchronously, from the specified descriptor into the stream buffer.
306 The function calls the virtual function DoWriteL(const TDesC8&,TInt,TRequestStatus&)
307 to implement this behaviour.
309 If the function leaves, then no write request will have been initiated.
311 @param aDes The source descriptor for the data to be written into the stream
313 @param aMaxLength The maximum number of bytes to be written.
314 @param aStatus The request status that indicates the completion status of this
315 asynchronous request.
316 @return The maximum number of bytes to be written, as used in this request.
317 This can be different to the value supplied in aMaxLength; this is dependent
318 on the implementation.
319 @see MStreamBuf::DoWriteL() */
320 {return DoWriteL(aDes,aMaxLength,aStatus);}
321 inline TStreamTransfer MStreamBuf::WriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer)
322 /** Writes data into the stream buffer from the specified data source.
324 The function calls the virtual function DoWriteL(MStreamOutput&,TStreamTransfer)
325 to implement this behaviour.
327 @param anOutput The data source for the write operation.
328 @param aTransfer Defines the amount of data to be pulled from the output stream
330 @return A stream transfer object defining the amount of data that was not consumed. */
331 {return DoWriteL(anOutput,aTransfer);}
332 inline void MStreamBuf::WriteL(MStreamOutput& anOutput)
333 /**Writes data into the stream buffer from the specified data source.
335 The function calls the virtual function DoWriteL(MStreamOutput&,TStreamTransfer) to implement this behaviour.
337 No explicit limit is placed on the amount of data that can be written.
339 @param anOutput The data source for the write operation.
340 @param aMaxLength The maximum amount of data available to be written.
342 {DoWriteL(anOutput,KStreamUnlimited);}
343 inline void MStreamBuf::SeekL(TMark aMark,TStreamPos aPos)
344 /**Moves the position of the read or write mark in the stream.
346 The new position is calculated by adding the specified value to the position of the beginning of the stream.
348 The function calls virtual function DoSeekL(TMark,TStreamLocation,TInt) to implement this behaviour.
350 As there are two current positions, one for the read mark and one for the write mark, it is not valid, in general, to use a single call to SeekL() to move both the read and write marks.
351 Not all streams are seekable.
353 @param aMark The type of mark, i.e. read or write.
354 @param aLocation A stream position value on which the calculation of the new position is based.
356 {DoSeekL(aMark,EStreamBeginning,aPos.Offset());}
357 inline TStreamPos MStreamBuf::SeekL(TMark aMark,TStreamLocation aLocation,TInt anOffset)
358 /** Moves the position of the read mark or the write mark in the stream.
360 The new position is calculated by adding the specified offset to one of:
362 the position of the beginning of the stream
364 the position of the end of the stream
366 the position of the current read mark or write mark.
368 The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt)
369 to implement this behaviour.
371 As there are two current positions, one for the read mark and one for the
372 write mark, it is not valid, in general, to use a single call to SeekL() to
373 move both the read and write marks.
375 Not all streams are seekable.
377 @param aMark The type of mark, i.e read or write.
378 @param aLocation The location in the stream on which the calculation of the
379 new position is based.
380 @param anOffset The offset value.
381 @return The new stream position of the read or write mark. */
382 {return DoSeekL(aMark,aLocation,anOffset);}
383 inline TStreamPos MStreamBuf::SeekL(TRead,TStreamLocation aLocation,TInt anOffset)
384 /** Moves the position of the read mark in the stream.
386 The new position is calculated by adding the specified offset to one of:
388 the position of the beginning of the stream
390 the position of the end of the stream
392 the position of the current read mark.
394 The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt)
395 to implement this behaviour.
397 Not all streams are seekable.
399 @param (The enumerator value is not used)
400 @param aLocation The location in the stream on which the calculation of the
401 new position is based.
402 @param anOffset The offset value.
403 @return The new stream position of the read mark. */
404 {return DoSeekL(ERead,aLocation,anOffset);}
405 inline TStreamPos MStreamBuf::SeekL(TWrite,TStreamLocation aLocation,TInt anOffset)
406 /** Moves the position of the write mark in the stream.
408 The new position is calculated by adding the specified offset to one of:
410 the position of the beginning of the stream
412 the position of the end of the stream
414 the position of the current write mark.
416 The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt)
417 to implement this behaviour.
419 Not all streams are seekable.
421 @param (The enumerator value is not used)
422 @param aLocation The location in the stream on which the calculation of the
423 new position is based.
424 @param anOffset The offset value.
425 @return The new stream position of the write mark. */
426 {return DoSeekL(EWrite,aLocation,anOffset);}
427 inline TStreamPos MStreamBuf::SeekL(TRead,TInt anOffset)
428 /** Moves the position of the read mark in the stream by the specified offset.
430 The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt)
431 to implement this behaviour.
433 Not all streams are seekable.
435 @param (The enumerator value is not used)
436 @param anOffset The amount by which the position of the read mark is to be
437 moved relative to the existing position of the read mark.
438 @return The new stream position of the read mark. */
439 {return DoSeekL(ERead,EStreamMark,anOffset);}
440 inline TStreamPos MStreamBuf::SeekL(TWrite,TInt anOffset)
441 /** Moves the position of the write mark in the stream by the specified offset.
443 The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt)
444 to implement this behaviour.
446 Not all streams are seekable.
448 @param (The enumerator value is not used)
449 @param anOffset The amount by which the position of the write mark is to be
450 moved relative to the existing position of the write mark.
451 @return The new stream position of the write mark. */
452 {return DoSeekL(EWrite,EStreamMark,anOffset);}
453 inline TStreamPos MStreamBuf::TellL(TRead) const
454 /** Gets the position of the read mark within the stream.
456 The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt)
457 to implement this behaviour.
459 @param (The enumerator value is not used).
460 @return The stream position. */
461 {return CONST_CAST(MStreamBuf*,this)->DoSeekL(ERead,EStreamMark,0);}
462 inline TStreamPos MStreamBuf::TellL(TWrite) const
463 /** Gets the position of the write mark within the stream.
465 The function calls the virtual function DoSeekL(TMark,TStreamLocation,TInt)
466 to implement this behaviour.
468 @param (The enumerator value is not used).
469 @return The stream position. */
470 {return CONST_CAST(MStreamBuf*,this)->DoSeekL(EWrite,EStreamMark,0);}
471 inline TInt MStreamBuf::SizeL() const
472 /** Gets the size of the stream.
474 @return The size of the stream, in bytes. */
475 {return CONST_CAST(MStreamBuf*,this)->DoSeekL(0,EStreamEnd,0).Offset();}
478 inline void TStreamBuf::SetBuf(TRead,TUint8* aPtr,TUint8* anEnd)
479 /** Sets the start and end points of the read area within the intermediate buffer.
481 A start point is always within an area; an end point is always the first byte
482 beyond the end of an area.
484 @param (The enumerator is not used).
485 @param aPtr The start point.
486 @param anEnd The end point.
487 @see MStreamBuf::TRead */
488 {iRPtr=aPtr;iREnd=anEnd;}
489 inline void TStreamBuf::SetBuf(TWrite,TUint8* aPtr,TUint8* anEnd)
490 /** Sets the start and end points of the write area within the intermediate buffer.
492 A start point is always within an area; an end point is always the first byte
493 beyond the end of an area.
495 @param (The enumerator is not used).
496 @param aPtr The start point.
497 @param anEnd The end point.
498 @see MStreamBuf::TWrite */
499 {iWPtr=aPtr;iWEnd=anEnd;}
500 inline void TStreamBuf::SetPtr(TRead,TUint8* aPtr)
501 /** Sets the start point of the write area within the intermediate buffer.
503 A start point is always within an area.
505 @param (The enumerator is not used).
506 @param aPtr The start point.
507 @see MStreamBuf::TWrite */
509 inline void TStreamBuf::SetPtr(TWrite,TUint8* aPtr)
510 /** Sets the start point of the write area within the intermediate buffer.
512 A start point is always within an area.
514 @param (The enumerator is not used).
515 @param aPtr The start point.
516 @see MStreamBuf::TWrite */
518 inline void TStreamBuf::SetEnd(TRead,TUint8* anEnd)
520 inline void TStreamBuf::SetEnd(TWrite,TUint8* anEnd)
522 inline TUint8* TStreamBuf::Ptr(TRead) const
523 /** Gets the current start point of the read area within the intermediate buffer.
525 @param (The enumerator is not used).
526 @return The start point.
527 @see MStreamBuf::TRead */
529 inline TUint8* TStreamBuf::Ptr(TWrite) const
530 /** Gets the current start point of the write area within the intermediate buffer.
532 @param (The enumerator is not used).
533 @return The start point.
534 @see MStreamBuf::TWrite */
536 inline TUint8* TStreamBuf::End(TRead) const
537 /** Gets the current end point of the read area within the intermediate buffer.
539 An end point is always the first byte beyond the end of an area.
541 @param (The enumerator is not used).
542 @return The end point.
543 @see MStreamBuf::TRead */
545 inline TUint8* TStreamBuf::End(TWrite) const
546 /** Gets the current end point of the write area within the intermediate buffer.
548 An end point is always the first byte beyond the end of an area.
550 @param (The enumerator is not used).
551 @return The end point.
552 @see MStreamBuf::TWrite */
554 inline TInt TStreamBuf::Avail(TRead) const
555 /** Gets the number of bytes available in the read area within the intermediate
558 @param (The enumerator is not used).
559 @return The number of bytes available.
560 @see MStreamBuf::TRead */
561 {return iREnd-iRPtr;}
562 inline TInt TStreamBuf::Avail(TWrite) const
563 /** Gets the number of bytes available in the write area within the intermediate
566 @param (The enumerator is not used).
567 @return The number of bytes available.
568 @see MStreamBuf::TWrite */
569 {return iWEnd-iWPtr;}
571 // Class TStreamFilter
572 inline void TStreamFilter::Set(MStreamBuf* aHost,TInt aMode)
573 /** Sets up the filter to use the specified host for streamed data.
575 Taking ownership of the host stream buffer means that calls to SynchL() propagate
576 to the host buffer after the filter has flushed its data, and that when the
577 filter is released it also releases the host buffer.
579 @param aHost The host for the streamed data - a stream buffer.
580 @param aMode The mode in which the stream buffer is to be used. It can be used
581 in either read or write modes, represented by ERead and EWrite, but not both
582 at the same time. In debug mode, setting both raises a STORE-Stream 18 panic.
583 In addition, specify EAttached to indicate that the filter should take ownership
584 of the host stream buffer.
585 @see MStreamBuf::TRead
586 @see MStreamBuf::TWrite */
591 iHost=aHost;iMode=aMode;
593 inline void TStreamFilter::Committed()
594 /** Flags the streamed data as committed. */
596 inline TBool TStreamFilter::IsCommitted() const
597 /** Tests whether the streamed data is committed.
599 @return True, if streamed data is committed; false, otherwise. */
600 {return iHost==NULL||!(iMode&EWrite);}