diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/s32share.h --- a/epoc32/include/s32share.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/s32share.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,289 @@ -s32share.h +// 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +// which accompanies this distribution, and is available +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + +#ifndef __S32SHARE_H__ +#define __S32SHARE_H__ + +#include +#include + +class TStreamExchange; +/** + * @publishedAll + * @released + * Manages the position of a read mark or a write mark within a shared stream. + +A shared stream is one that shares its host with other streams. In practice, +the host is a stream buffer that is, itself, hosted by a file, an RFileBuf +object. + +TStreamMark objects are owned by RShareBuf, one for reading and one for writing. +They re-direct read/write operations through a TStreamExchange object to the +RFileBuf object, which handles the actual file read and write operations. + +@see RFileBuf +@see RShareBuf +@see TStreamExchange +*/ +class TStreamMark + { +public: + inline TStreamMark(); + inline TStreamMark(TStreamPos aPos); + inline TStreamMark& operator=(TStreamPos aPos); + inline operator TStreamMark*(); + inline operator const TStreamMark*() const; +// + inline TBool operator==(const TStreamMark& aMark) const; + inline TBool operator==(const TStreamMark* aPtr) const; + inline TBool operator!=(const TStreamMark& aMark) const; + inline TBool operator!=(const TStreamMark* aPtr) const; +// + inline TBool IsEmpty() const; + inline void Clear(); + inline TStreamPos Position() const; +// + inline TBool IsWith(TStreamExchange& aHost) const; + inline TBool RelatesTo(TStreamExchange& aHost) const; + inline void Withdraw(TStreamExchange& aHost); + inline void ExtractL(TStreamExchange& aHost); +// + inline TInt ReadL(TStreamExchange& aHost,TAny* aPtr,TInt aMaxLength); + IMPORT_C TInt ReadL(TStreamExchange& aHost,TDes8& aDes,TRequestStatus& aStatus); + inline TInt ReadL(TStreamExchange& aHost,TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus); + inline TStreamTransfer ReadL(TStreamExchange& aHost,MStreamInput& anInput,TStreamTransfer aTransfer); + inline TInt ReadL(TStreamExchange& aHost,MStreamInput& anInput,TInt aMaxLength); + inline void ReadL(TStreamExchange& aHost,MStreamInput& anInput); +// + inline void WriteL(TStreamExchange& aHost,const TAny* aPtr,TInt aLength); + IMPORT_C TInt WriteL(TStreamExchange& aHost,const TDesC8& aDes,TRequestStatus& aStatus); + inline TInt WriteL(TStreamExchange& aHost,const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus); + inline TStreamTransfer WriteL(TStreamExchange& aHost,MStreamOutput& anOutput,TStreamTransfer aTransfer); + inline TInt WriteL(TStreamExchange& aHost,MStreamOutput& anOutput,TInt aMaxLength); + inline void WriteL(TStreamExchange& aHost,MStreamOutput& anOutput); +// + inline void SeekL(TStreamExchange& aHost,TStreamPos aPos); + inline TStreamPos SeekL(TStreamExchange& aHost,TStreamLocation aLocation,TInt anOffset=0); + inline TStreamPos SeekL(TStreamExchange& aHost,TInt anOffset); +// + inline TStreamPos TellL(TStreamExchange& aHost) const; +private: + /** Constructs a default shared stream mark object. + + The position for the mark is uninitialised. + + An uninitialised mark means that a call to IsEmpty() returns true. + + @see IsEmpty() */ + TStreamMark(const TStreamMark&); + TStreamMark& operator=(const TStreamMark&); +private: + TStreamPos iPos; +private: + inline TBool IsTracking(TStreamMark*const& aRef) const; + inline void Track(TStreamMark*const& aRef); +private: + friend class TStreamExchange; +private: + IMPORT_C static void __DbgChkPos(TStreamPos aPos); + }; + +/** + * @publishedAll + * @released + * Manages access to a shared host buffer for shared stream buffers. + +The class maintains independent markers for the shared stream buffer that +has most recently read or written to the shared host buffer. + +This is the way in which multiple requests from the same shared stream buffer +are handled without the need for repeated seeking. The shared host buffer +only needs to seek when a new shared buffer needs to use it + +@see RShareBuf +*/ +class TStreamExchange + { +public: + inline TStreamExchange(); + inline TStreamExchange(MStreamBuf* aHost); + inline void Share(MStreamBuf* aHost); + inline TBool IsActive() const; + IMPORT_C MStreamBuf* Host(); + IMPORT_C MStreamBuf* HostL(); + IMPORT_C void Release(); +// + IMPORT_C TInt SizeL() const; +private: +/** 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 MStreamBuf::TMark TMark; +private: + /** Constructs an empty object. + + Call Share() to prepare for access to a shared stream buffer. */ + TStreamExchange(const TStreamExchange&); + TStreamExchange& operator=(const TStreamExchange&); +// + IMPORT_C TBool RefersTo(const TStreamMark& aMark); + IMPORT_C void Drop(const TStreamMark& aMark); + IMPORT_C void GetL(TStreamMark& aMark); + IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength,TStreamMark& aMark); + IMPORT_C TInt DoReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus,TStreamMark& aMark); + IMPORT_C TStreamTransfer DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer,TStreamMark& aMark); + IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength,TStreamMark& aMark); + IMPORT_C TInt DoWriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus,TStreamMark& aMark); + IMPORT_C TStreamTransfer DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer,TStreamMark& aMark); + IMPORT_C TStreamPos DoSeekL(TStreamMark& aMark,TStreamLocation aLocation,TInt anOffset); +// + void PrepareForReadingL(TStreamMark& aMark); + void PrepareForWritingL(TStreamMark& aMark); +// + TInt PrepareAndReadL(TAny* aPtr,TInt aMaxLength,TStreamMark& aMark); + TInt PrepareAndReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus,TStreamMark& aMark); + TStreamTransfer PrepareAndReadL(MStreamInput& anInput,TStreamTransfer aTransfer,TStreamMark& aMark); + void PrepareAndWriteL(const TAny* aPtr,TInt aLength,TStreamMark& aMark); + TInt PrepareAndWriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus,TStreamMark& aMark); + TStreamTransfer PrepareAndWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer,TStreamMark& aMark); + TStreamPos MarkSeekL(TStreamMark& aMark,TStreamLocation aLocation,TInt anOffset); +// + inline MStreamBuf& BufL() const; + inline MStreamBuf& Buf() const; +private: + MStreamBuf* iHost; + TStreamMark* iRMrk; + TStreamMark* iWMrk; +private: + friend class TStreamMark; + }; + +/** + * @publishedAll + * @released + * A shared stream buffer. + +This class is part of the framework used by CFileStore that allows multiple +stream buffers to concurrently access the single hosting file buffer, an RFileBuf +object. + +Each shared stream buffer maintains its own read and write positions. + +Read and write operations to RShareBuf are directed through separate TStreamMark +objects, one for read and one for write. The TStreamMark objects re-direct +read/write operations through a TStreamExchange object to the RFileBuf object, +which handles the actual file read and write operations. + +This stream buffer can also be accessed through RShareReadStream and RShareWriteStream +objects. + +@see TStreamMark +@see TStreamExchange +@see RFileBuf +@see RShareReadStream +@see RShareWriteStream +*/ +class RShareBuf : public MStreamBuf + { +public: + IMPORT_C RShareBuf(); + IMPORT_C void Open(TStreamExchange& aHost,TStreamPos aPos,TInt aMode=ERead|EWrite); + inline void Open(TStreamExchange& aHost,TInt aMode=ERead|EWrite); +protected: + IMPORT_C void DoRelease(); + IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength); + IMPORT_C TInt DoReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus); + IMPORT_C TStreamTransfer DoReadL(MStreamInput& anInput,TStreamTransfer aTransfer); + IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength); + IMPORT_C TInt DoWriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus); + IMPORT_C TStreamTransfer DoWriteL(MStreamOutput& anOutput,TStreamTransfer aTransfer); + IMPORT_C TStreamPos DoSeekL(TMark aMark,TStreamLocation aLocation,TInt anOffset); +private: + inline TStreamExchange& Host() const; +private: + TStreamExchange* iHost; + TStreamMark iRMark; + TStreamMark iWMark; + }; + +/** + * @publishedAll + * @released + * Supports the opening, for reading, of a stream which shares its host with other +streams. + +This is also called a shared read stream. + +The class uses a RShareBuf stream buffer. + +@see RShareBuf +@see RFileBuf +*/ +class RShareReadStream : public RReadStream + { +public: + /** Constructs an empty shared read stream object. + + Call Open() to prepare the shared stream for reading. + + @see RShareReadStream::Open() */ + RShareReadStream() {} + IMPORT_C RShareReadStream(TStreamExchange& aHost,TStreamPos aPos=KStreamBeginning); + IMPORT_C void Open(TStreamExchange& aHost,TStreamPos aPos=KStreamBeginning); +private: + RShareBuf iSource; + }; + +/** + * @publishedAll + * @released + * Supports the opening, for writing, of a stream which shares its host with other +streams. + +This is also called a shared write stream. + +The class uses a RShareBuf stream buffer. + +@see RShareBuf +@see RFileBuf +*/ +class RShareWriteStream : public RWriteStream + { +public: + /** Constructs an empty shared write stream object. + + Call Open() to prepare the shared stream for writing. + + @see RShareWriteStream::Open() */ + RShareWriteStream() {} + inline RShareWriteStream(const MExternalizer& anExter); + IMPORT_C RShareWriteStream(TStreamExchange& aHost,TStreamPos aPos=KStreamBeginning); + IMPORT_C void Open(TStreamExchange& aHost,TStreamPos aPos=KStreamBeginning); +private: + RShareBuf iSink; + }; + +#include +#endif