// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#if !defined(__S32BUF_H__)

#define __S32BUF_H__

#if !defined(__E32STD_H__)

#include <e32std.h>

#endif

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

of a new seek position is based.

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

@see MStreamBuf::SeekL() */

enum TStreamLocation 

	/** The seek position is calculated relative to the beginning of the 

	stream.*/

	{EStreamBeginning,

	/** The seek position is calculated relative to the end of the stream.*/

	EStreamMark,

	/** The seek position is calculated relative to the existing read or 

	write mark in the stream. */

	EStreamEnd};

/**

 * @publishedAll 

 * @released

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

Position is the offset from the beginning of a seekable stream. The class 

provides convenient operators for performing arithmetic on the offset value 

and for doing comparisons between stream position objects.

It can be considered as an absolute stream position.

Objects of this type are usually created as a result of calling 

MStreamBuf::SeekL() or MStreamBuf::TellL(); they allow a program to remember 

the current read position in a stream buffer and reset it to the same 

location later.

@see MStreamBuf::SeekL()

@see MStreamBuf::TellL()  

*/

class TStreamPos

	{

public:

	/** Constructs an empty stream position object. */

	TStreamPos() {}

	inline TStreamPos(TInt anOffset);

//

	inline TBool operator==(TStreamPos aPos) const;

	inline TBool operator!=(TStreamPos aPos) const;

	inline TBool operator<(TStreamPos aPos) const;

	inline TBool operator<=(TStreamPos aPos) const;

	inline TBool operator>(TStreamPos aPos) const;

	inline TBool operator>=(TStreamPos aPos) const;

//

	inline TInt operator-(TStreamPos aPos) const;

	inline TStreamPos operator+(TInt anOffset) const;

	inline TStreamPos operator-(TInt anOffset) const;

//

	inline TStreamPos& operator+=(TInt anOffset);

	inline TStreamPos& operator-=(TInt anOffset);

//

	inline TInt Offset() const;

private:

	TInt iOff;

	};

inline TStreamPos operator+(TInt anOffset,TStreamPos aPos);

#if defined(__NO_CLASS_CONSTS__)

/** Constructs a TStreamPos object that denotes the beginning of any seekable 

stream.

@see TStreamPos */

#define KStreamBeginning TStreamPos(0)

#else

const TStreamPos KStreamBeginning=TStreamPos(0);

#endif

/**

 * @publishedAll 

 * @released

 * Stream transfer object.

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

or remains to be transferred, between streams.

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

@see MStreamBuf

@see TStreamBuf

@see TStreamMark

@see TStreamExchange

@see RShareBuf  

*/

class TStreamTransfer

	{

public:

	/** An enumerator type passed to a constructor of this class to indicate 

	that there is no explicit limit to the amount of data that can be 

	transferred between streams. The enumeration is not used. */

	enum TUnlimited {EUnlimited};

public:

	/** Constructs a stream transfer object specifying that there is no 

	explicit limit to the amount of data that can be transferred between 

	streams.

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

	themselves.

	The arithmetical operators do not change the state of an unlimited stream 

	transfer object. */

	TStreamTransfer() {}

	inline TStreamTransfer(TInt aMaxLength);

	inline TStreamTransfer(TUnlimited);

//

	inline TBool operator==(TInt aLength) const;

	inline TBool operator>(TInt aLength) const;

	inline TStreamTransfer operator-(TInt aLength) const;

	inline TInt operator[](TInt aMaxLength) const;

//

	inline TStreamTransfer& operator-=(TInt aLength);

//

	inline TInt Left() const;

private:

	TInt iVal;

private:

	IMPORT_C static void __DbgChkNonNegative(TInt aLength);

	};

inline TBool operator==(TInt aLength,TStreamTransfer aTransfer);

inline TBool operator<(TInt aLength,TStreamTransfer aTransfer);

#if defined(__NO_CLASS_CONSTS__)

/** Constructs a TStreamTransfer object indicating that no explicit limit is 

imposed on transfers between streams.

@see TStreamTransfer

@see MStreamBuf::ReadL()

@see MStreamBuf::WriteL() */

#define KStreamUnlimited TStreamTransfer(TStreamTransfer::EUnlimited)

#else

const TStreamTransfer KStreamUnlimited=TStreamTransfer::EUnlimited;

#endif

//

class MStreamInput;

class MStreamOutput;

/**

 * @publishedAll 

 * @released

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

A stream buffer:

may be buffered or unbuffered

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

may be seekable, or unseekable.

A seekable stream buffer maintains independent read and write pointers, which 

can be manipulated separately. This is unlike the RFile interface which 

maintains a single current position in the file. For example, file streams 

and memory streams are seekable streams, but socket, serial-comms, and filtered 

streams are not.

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

RReadStream and RWriteStream.

The class has no member data.

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

capabilities, otherwise derive from TStreamBuf.

Get a reference to the stream buffer used by a read stream by calling 

RReadStream::Source(). Get a reference to the stream buffer used by a write 

stream by calling RWriteStream::Sink()

@see RReadStream

@see RWriteStream

@see TStreamBuf 

*/

class MStreamBuf

	{

public:

	/** Indicates that an operation applies to the read mark in a stream or to 

	the read area in an stream buffer. */

	enum TRead {ERead=0x01};

	/** Indicates that an operation applies to the write mark in a stream or 

	to the write area in an stream buffer. */

	enum TWrite {EWrite=0x02};

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

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

	seek operations to marks within a stream.

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

	identify the read and write marks respectively.

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

	enumerator.

	@see MStreamBuf::TRead

	@see MStreamBuf::TWrite */

	typedef TInt TMark;

public:

	IMPORT_C void Close();

	inline void Release();

	IMPORT_C TInt Synch();

	inline void SynchL();

//

	IMPORT_C void PushL();

//

	inline TInt ReadL(TAny* aPtr,TInt aMaxLength);

	IMPORT_C TInt Read(TDes8& aDes,TRequestStatus& aStatus);

	IMPORT_C TInt Read(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus);

	IMPORT_C TInt ReadL(TDes8& aDes,TRequestStatus& aStatus);

	inline TInt ReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus);

	inline TStreamTransfer ReadL(MStreamInput& anInput,TStreamTransfer aTransfer);

	IMPORT_C TInt ReadL(MStreamInput& anInput,TInt aMaxLength);

	inline void ReadL(MStreamInput& anInput);

//

	inline void WriteL(const TAny* aPtr,TInt aLength);

	IMPORT_C TInt Write(const TDesC8& aDes,TRequestStatus& aStatus);

	IMPORT_C TInt Write(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus);

	IMPORT_C TInt WriteL(const TDesC8& aDes,TRequestStatus& aStatus);

	inline TInt WriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus);

	inline TStreamTransfer WriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer);

	IMPORT_C TInt WriteL(MStreamOutput& anOutput,TInt aMaxLength);

	inline void WriteL(MStreamOutput& anOutput);

//

	inline void SeekL(TMark aMark,TStreamPos aPos);

	inline TStreamPos SeekL(TMark aMark,TStreamLocation aLocation,TInt anOffset=0);

	inline TStreamPos SeekL(TRead,TStreamLocation aLocation,TInt anOffset=0);

	inline TStreamPos SeekL(TWrite,TStreamLocation aLocation,TInt anOffset=0);

	inline TStreamPos SeekL(TRead,TInt anOffset);

	inline TStreamPos SeekL(TWrite,TInt anOffset);

//

	inline TStreamPos TellL(TRead) const;

	inline TStreamPos TellL(TWrite) const;

	inline TInt SizeL() const;

protected:

	MStreamBuf() {}

private:

	MStreamBuf(const MStreamBuf&);

	MStreamBuf& operator=(const MStreamBuf&);

//

	virtual IMPORT_C void DoRelease();

	virtual IMPORT_C void DoSynchL();

	virtual IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength);

	virtual IMPORT_C TInt DoReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus);

	virtual IMPORT_C TStreamTransfer DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer);

	virtual IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength);

	virtual IMPORT_C TInt DoWriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus);

	virtual IMPORT_C TStreamTransfer DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer);

	virtual IMPORT_C TStreamPos DoSeekL(TMark aMark,TStreamLocation aLocation,TInt anOffset);

	};

/**

 * @publishedAll 

 * @released

 * An interface to an object that acts as a target for read operations from 

a stream. The object behaves as a generic data sink.

A stream input object can act as an intelligent buffer, and is useful for 

performing filtering, compression or any other general kind of conversion 

operation that might be needed after reading from a stream.

The class is pure interface and requires an implementation.

@see MStreamBuf::ReadL()  

*/

class MStreamInput

	{

public:

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

	This function is called by the default implementation of 

	TStreamBuf::DoReadL(MStreamInput&,TStreamTransfer) 

	and assumes that the source is a stream buffer's intermediate buffer.

	@param aPtr A pointer into the intermediate buffer from which the read 

	operation starts.

	@param aMaxLength The maximum amount of data to be read.

	@return The amount of data read.

	@see TStreamBuf::DoReadL()

	@see TStreamBuf */

	virtual TInt PushL(const TAny* aPtr,TInt aMaxLength)=0;

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

	This function is called by the default implementation of

	MStreamBuf::DoReadL(MStreamInput&,TStreamTransfer). 

	It may also be called by TStreamBuf::DoReadL(MStreamInput&,TStreamTransfer), 

	depending on the amount of data to be transferred and the nature of the 

	buffering scheme.

	@param aSource The stream from which data is to be read.

	@param aTransfer Defines the amount of data available to be read.

	@return The amount of data that was not consumed.

	@see MStreamBuf::DoReadL()

	@see TStreamBuf::DoReadL() */

	virtual	TStreamTransfer ReadFromL(MStreamBuf& aSource,TStreamTransfer aTransfer)=0;

	};

/**

 * @publishedAll 

 * @released

 * An interface to an object that acts as source for write operations to a 

stream. The object behaves as a generic data source.

A stream output object can act as an intelligent buffer, and is useful for 

performing filtering, compression or any other general kind of conversion 

operation that might be needed before writing to a stream.

The class is pure interface and requires an implementation.

@see MStreamBuf::WriteL()  

*/

class MStreamOutput

	{

public:

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

	This function is called by the default implementation of 

	TStreamBuf::DoWriteL(MStreamOutput&,TStreamTransfer) 

	and assumes that the target is a stream buffer's intermediate buffer.

	@param aPtr A pointer into the intermediate buffer where the write operation 

	starts.

	@param aMaxLength The maximum amount of data to be written.

	@return The amount of data written.

	@see TStreamBuf::DoWriteL()

	@see TStreamBuf */

	virtual TInt PullL(TAny* aPtr,TInt aMaxLength)=0;

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

	This function is called by the default implementation of 

	MStreamBuf::DoWriteL(MStreamOutput&,TStreamTransfer). 

	It may also be called by TStreamBuf::DoWriteL(MStreamOutput&,TStreamTransfer), 

	depending on the amount of data to be transferred and the nature of the 

	buffering scheme.

	@param aSink The stream to which data is to be written.

	@param aTransfer Defines the amount of data available to be written.

	@return The amount of data that was not consumed.

	@see MStreamBuf::DoWriteL()

	@see TStreamBuf::DoWriteL() */

	virtual TStreamTransfer WriteToL(MStreamBuf& aSink,TStreamTransfer aTransfer)=0;

	};

/**

 * @publishedAll 

 * @released

 * Adds buffering capabilities to a stream buffer

The class provides pointers to mark out the current read and write areas within 

the intermediate buffer. The class also defines the pure virtual functions 

UnderflowL() and OverflowL() which must be provided by a derived class.

Streams which have buffering capabilities derive from this class, otherwise 

they derive from MStreamBuf.

Note that the class does not provide the buffer; this is left to the class 

derived from it. For example, the memory buffer classes use the memory area 

directly, the file buffer class allocate a heap cell to use as a buffer.

@see UnderflowL()

@see OverflowL()  

*/

class TStreamBuf : public MStreamBuf

	{

protected:

	/** Used to identify the type of area within an intermediate buffer.

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

	the intermediate buffer.

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

	identify the read and write areas respectively.

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

	enumerator.

	@see MStreamBuf::TRead

	@see MStreamBuf::TWrite */

	typedef TInt TArea;

protected:

	IMPORT_C TStreamBuf();

//

	IMPORT_C void SetBuf(TArea anArea,TUint8* aPtr,TUint8* anEnd);

	IMPORT_C void SetPtr(TArea anArea,TUint8* aPtr);

	IMPORT_C void SetEnd(TArea anArea,TUint8* anEnd);

	IMPORT_C TUint8* Ptr(TArea anArea) const;

	IMPORT_C TUint8* End(TArea anArea) const;

	IMPORT_C TInt Avail(TArea anArea) const;

//

	IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength);

	IMPORT_C TStreamTransfer DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer);

	IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength);

	IMPORT_C TStreamTransfer DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer);

//

	inline void SetBuf(TRead,TUint8* aPtr,TUint8* anEnd);

	inline void SetBuf(TWrite,TUint8* aPtr,TUint8* anEnd);

	inline void SetPtr(TRead,TUint8* aPtr);

	inline void SetPtr(TWrite,TUint8* aPtr);

	inline void SetEnd(TRead,TUint8* anEnd);

	inline void SetEnd(TWrite,TUint8* anEnd);

	inline TUint8* Ptr(TRead) const;

	inline TUint8* Ptr(TWrite) const;

	inline TUint8* End(TRead) const;

	inline TUint8* End(TWrite) const;

	inline TInt Avail(TRead) const;

	inline TInt Avail(TWrite) const;

private:

	/** Re-fills the intermediate buffer and resets the start and end points 

	of the read area.

	The implementation of this function depends on the way the stream itself is 

	implemented. For example, the in-memory streams have simple implementations.

	@param aMaxLength The maximum amount of data required for the intermediate 

	buffer.

	@return The amount of data available in the intermediate buffer. */

	virtual TInt UnderflowL(TInt aMaxLength)=0;

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

	of the write area.

	The implementation of this function depends on the way the stream itself is 

	implemented. For example, the in-memory streams have simple implementations. */

	virtual void OverflowL()=0;

private:

	TUint8* iRPtr;

	TUint8* iREnd;

	TUint8* iWPtr;

	TUint8* iWEnd;

	};

/**

 * @publishedAll 

 * @released

 * Interface to a stream filter.

A stream filter is an object that allows stream data to be filtered after 

retrieval from a host or filtered before being written to a host.

The class is abstract and a derived class must be defined an implemented.  

*/

class TStreamFilter : public MStreamBuf

	{

public:

	enum {EAttached=0x10};

protected:

	IMPORT_C TStreamFilter();

	inline void Set(MStreamBuf* aHost,TInt aMode);

	inline void Committed();

	inline TBool IsCommitted() const;

	IMPORT_C void EmitL(const TAny* aPtr,TInt aLength);

//

	IMPORT_C void DoRelease();

	IMPORT_C void DoSynchL();

	IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength);

	IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength);

private:

	/** Calculates the maximum size of unfiltered data necessary to give the 

	specified amount of filtered data.

	@param aMaxLength The amount of filtered data required.

	@return The maximum amount of unfiltered data guaranteed not to generate 

	more than aMaxLength bytes of filtered output. */

	virtual TInt Capacity(TInt aMaxLength)=0;

	/** Performs the filtration process.

	@param aPtr Pointer to the output location for the filtered data.

	@param aMaxLength The maximum amount of space available for the filtered 

	data.

	@param aFrom A reference to a pointer to the unfiltered data source. This 

	pointer should be advanced as the source is consumed.

	@param anEnd Pointer to the first byte beyond the end of the unfiltered 

	data source.

	@return The size of the filtered data. */

	virtual TInt FilterL(TAny* aPtr,TInt aMaxLength,const TUint8*& aFrom,const TUint8* anEnd)=0;

private:

	MStreamBuf* iHost;

	TInt iMode;

private:

	friend class TFilterInput;

	friend class TFilterOutput;

private:

	IMPORT_C static void __DbgChkMode(TInt aMode);

	};

#include <s32buf.inl>

#endif