Symaptic: os/persistentdata/persistentstorage/store/INC/S32BUF.H@260cb5ec6c19

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

    16 #if !defined(__S32BUF_H__)

    17 #define __S32BUF_H__

    18 #if !defined(__E32STD_H__)

    19 #include <e32std.h>

    20 #endif

    22 /** Defines the type of location within a stream on which the calculation

    23 of a new seek position is based.

    25 The type is used by the stream buffer SeekL() functions.

    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};

    38 /**

    39  * @publishedAll

    40  * @released

    41  * Holds the position of the read or write mark within a seekable stream.

    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.

    47 It can be considered as an absolute stream position.

    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.

    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.

    87 @see TStreamPos */

    88 #define KStreamBeginning TStreamPos(0)

    89 #else

    90 const TStreamPos KStreamBeginning=TStreamPos(0);

    91 #endif

    93 /**

    94  * @publishedAll

    95  * @released

    96  * Stream transfer object.

    98 Holds and maintains a value that represents how much data is to be transferred,

    99 or remains to be transferred, between streams.

   101 Objects of this type are used by ReadL() and WriteL() functions of MStreamBuf.

   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.

   121 	The amount of data to be transferred is only limited by the streams

   122 	themselves.

   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.

   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;

   160 /**

   161  * @publishedAll

   162  * @released

   163  * A stream buffer that provides a generic I/O interface for streamed data.

   165 A stream buffer:

   167 may be buffered or unbuffered

   169 may provide read-only, write-only or read/write capability

   171 may be seekable, or unseekable.

   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.

   179 Objects of this type are used by the stream interface classes derived from

   180 RReadStream and RWriteStream.

   182 The class has no member data.

   184 Derive from this class, if the stream has no intermediate buffering

   185 capabilities, otherwise derive from TStreamBuf.

   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()

   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};

   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};

   206 	/** Used to identify the type of mark in a stream.

   208 	The type is used by functions of this class and derived classes that perform

   209 	seek operations to marks within a stream.

   211 	The type uses the ERead and EWrite enumeration values, as bit flags, to

   212 	identify the read and write marks respectively.

   214 	ERead is an MStreamBuf::TRead enumerator. EWrite is an MStreamBuf::EWrite

   215 	enumerator.

   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 	};

   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.

   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.

   283 The class is pure interface and requires an implementation.

   285 @see MStreamBuf::ReadL()

   286 */

   287 class MStreamInput

   288 	{

   289 public:

   290 	/** Reads data from an intermediate buffer into this stream input object.

   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.

   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;

   304 	/** Reads data from the specified stream into this stream input object.

   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.

   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 	};

   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.

   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.

   330 The class is pure interface and requires an implementation.

   332 @see MStreamBuf::WriteL()

   333 */

   334 class MStreamOutput

   335 	{

   336 public:

   337 	/** Writes data to an intermediate buffer from this stream output object.

   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.

   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;

   351 	/** Writes data to the specified stream from this stream output object.

   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.

   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 	};

   367 /**

   368  * @publishedAll

   369  * @released

   370  * Adds buffering capabilities to a stream buffer

   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.

   376 Streams which have buffering capabilities derive from this class, otherwise

   377 they derive from MStreamBuf.

   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.

   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.

   391 	The type is used by functions of this class that set or get pointers into

   392 	the intermediate buffer.

   394 	The type uses the ERead and EWrite enumeration values, as bit flags, to

   395 	identify the read and write areas respectively.

   397 	ERead is an MStreamBuf::TRead enumerator. EWrite is an MStreamBuf::EWrite

   398 	enumerator.

   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.

   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.

   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;

   442 	/** Empties the intermediate buffer and resets the start and end points

   443 	of the write area.

   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 	};

   455 /**

   456  * @publishedAll

   457  * @released

   458  * Interface to a stream filter.

   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.

   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.

   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;

   489 	/** Performs the filtration process.

   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 	};

   510 #include <s32buf.inl>

   511 #endif

author	sl
	Tue, 10 Jun 2014 14:32:02 +0200
changeset 1	260cb5ec6c19
permissions	-rw-r--r--