1 s32buf.h

     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 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 //

    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