diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/s32file.h --- a/epoc32/include/s32file.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/s32file.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,487 @@ -s32file.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: +// + +#if !defined(__S32FILE_H__) +#define __S32FILE_H__ +#if !defined(__F32FILE_H__) +#include +#endif +#if !defined(__S32STOR_H__) +#include +#endif + +#ifndef DEFAULT_FILE_BUF_SIZE + #define DEFAULT_FILE_BUF_SIZE 4096 +#else + #if DEFAULT_FILE_BUF_SIZE < 1536 + #error "DEFAULT_FILE_BUF_SIZE macro value can't be less than 1536" + #endif +#endif +/** +The default size of the file buffer. +@internalComponent +*/ +const TInt KDefaultFileBufSize=DEFAULT_FILE_BUF_SIZE; + +template +class TCapture; +class RPermanentFileStoreIter; + +/** A stream buffer hosted by a file. + * @publishedAll + * @released + +Instances of this class are used by file based persistent stores, i.e. CFileStore +type objects. An RFileBuf object is associated with a file and the file is +said to be attached to the stream buffer. + +An RFileBuf object is also used by RFileReadStream and RFileWriteStream objects +to provide buffered file I/O. + +The stream buffer has intermediate buffering capabilities. + +When used as the basis for a file store, it hosts multiple streams through +the TStreamExchange and RShareBuf classes. + +Open(), Close(), Attach(), Detach(), File() and Reattach() usage patterns: + +Pattern 1: RFileBuf owns the file +step 1a: Open()/Create()/Temp() is used to connect the buffer to a file +step 1b: Use the file buffer +step 1c: Close() releases this resource. + +Pattern 2: RFile is opened elsewhere and ownership is handed over to RFileBuf +This may happen if the file is already opened by another API, or from another process for example +step 2a: Attach() is used to hand ownership of the opened file to the buffer. After Attach() the supplied file handle is NULLed. +step 2b: Use the file buffer +step 2c: Close() releases the file resource. + +Pattern 3: RFileBuf is used transiently to manage an existing opened file: +step 3a: Attach() is used to bind the buffer to the already open file. After Attach() the supplied file handle is NULLed. +step 3b: Use the file buffer +step 3c: RFileBuf::File() is used to retrieve the file handle again, then Detach() is called to disconnect the buffer from the file. +At this point, the destruction of the file buffer will have no effect on the file. The retrieved file handle in step 3c must be used to close the file. + +Pattern 4: Transient direct file access to a buffered file +step 4a: RFileBuf::File() is used to retrieve the file handle. [Optional: Detach() is used to disconnect the file buffer] +step 4b: Use the file directly. Note that writing to the file may cause coherency problems with the RFileBuf buffer - in which case you need to Reset() the buffer as well. +step 4c: [Optional: Reattach() is used to hand the file back to the buffer]. Use of the buffer is resumed + +@see CFileStore +@see RFileReadStream +@see RFileWriteStream */ +class RFileBuf : public TStreamBuf + { +public: + IMPORT_C RFileBuf(); + IMPORT_C RFileBuf(TInt aSize); + RFileBuf(TCapture aCapture); + IMPORT_C void Reset(); + inline void Reset(TInt aSize); +// + IMPORT_C TInt Open(RFs& aFs,const TDesC& aName,TUint aFileMode); + IMPORT_C TInt Create(RFs& aFs,const TDesC& aName,TUint aFileMode); + IMPORT_C TInt Replace(RFs& aFs,const TDesC& aName,TUint aFileMode); + IMPORT_C TInt Temp(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode); + IMPORT_C void Attach(RFile& aFile,TInt aPos=0); + IMPORT_C void Close(); + inline void Detach(); + inline void Reattach(RFile& aFile); +// + IMPORT_C void SetSizeL(TInt aSize); + inline RFile& File() const; +protected: + IMPORT_C TInt UnderflowL(TInt aMaxLength); + IMPORT_C void OverflowL(); + IMPORT_C void DoRelease(); + IMPORT_C void DoSynchL(); + IMPORT_C TInt DoReadL(TAny* aPtr,TInt aMaxLength); + IMPORT_C TInt DoReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus); + IMPORT_C void DoWriteL(const TAny* aPtr,TInt aLength); + IMPORT_C TInt DoWriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus); + IMPORT_C TStreamPos DoSeekL(TMark aMark,TStreamLocation aLocation,TInt anOffset); +// + inline void SetBuf(TRead,TUint8* aPtr,TUint8* anEnd); + inline void SetBuf(TWrite,TUint8* aPtr,TUint8* anEnd); + inline void SetBuf(TArea anArea,TUint8* aPtr,TUint8* anEnd); +private: + TUint8* AllocL(); + void Free(); +// + void SetPos(TMark aMark,TInt aPos); + inline void SetPos(TRead,TInt aPos); + inline void SetPos(TWrite,TInt aPos); + inline TInt Pos(TRead) const; + inline TInt Pos(TWrite) const; + inline TInt MovePos(TRead,TInt anOffset); + inline TInt MovePos(TWrite,TInt anOffset); + TInt FileReadL(TAny* aPtr,TInt aMaxLength); + void FileWriteL(const TAny* aPtr,TInt aLength,TInt aSeek); + void FileWriteL(const TAny* aPtr,TInt aLength); + TInt EndL(); +// + inline TInt Lag(TRead) const; + inline TInt Lag(TWrite) const; + TInt Mark(TMark aMark) const; + inline TInt Mark(TRead) const; + inline TInt Mark(TWrite) const; + inline TUint8* Limit(TWrite) const; + inline void SetLimit(TWrite,TUint8* aLimit); + inline TInt Span(TWrite) const; + inline TInt Reach(TWrite) const; +private: + TUint8* iBase; + TInt iSize; + __MUTABLE RFile iFile; + TInt iRPos; + TInt iWPos; + TInt iExt; + TUint8* iWLim; + friend class CFileStore; + }; + +/** + * @publishedAll + * @released + * Supports the reading of a stream from a file. + */ +class RFileReadStream : public RReadStream + { +public: + /** Constructs an empty read stream object. */ + RFileReadStream() {} + IMPORT_C RFileReadStream(RFile& aFile,TInt aPos=0); + IMPORT_C TInt Open(RFs& aFs,const TDesC& aName,TUint aFileMode); + IMPORT_C void Attach(RFile& aFile,TInt aPos=0); +private: + RFileBuf iSource; + }; + +/** + * @publishedAll + * @released + * Supports the writing of a stream to a file. + */ +class RFileWriteStream : public RWriteStream + { +public: + /** Constructs an empty write stream object. */ + RFileWriteStream() {} + inline RFileWriteStream(const MExternalizer& anExter); + IMPORT_C RFileWriteStream(RFile& aFile,TInt aPos=0); + IMPORT_C TInt Open(RFs& aFs,const TDesC& aName,TUint aFileMode); + IMPORT_C TInt Create(RFs& aFs,const TDesC& aName,TUint aFileMode); + IMPORT_C TInt Replace(RFs& aFs,const TDesC& aName,TUint aFileMode); + IMPORT_C TInt Temp(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode); + IMPORT_C void Attach(RFile& aFile,TInt aPos=0); +private: + RFileBuf iSink; + }; +// +class CFileStore; + +/** + * @publishedAll + * @released + * A class containing a set of factory functions for opening an existing direct + file store and an existing permanent file store identified using a Uidtype. + */ +class FileStoreFactory + { +public: + IMPORT_C static CFileStore* DirectLC(RFileBuf& aBuf,const TUidType& aType); + IMPORT_C static CFileStore* PermanentLC(RFileBuf& aBuf,const TUidType& aType); + }; +// +const TInt KDirectFileStoreLayoutUidValue=268435511; +/** The value of the KPermanentFileStoreLayoutUidValue UID. */ +const TInt KPermanentFileStoreLayoutUidValue=268435536; +/** The UID that identifies a file store as being a direct file store. */ +const TUid KDirectFileStoreLayoutUid={KDirectFileStoreLayoutUidValue}; +/** The UID that identifies a file store as being a permanent file store. */ +const TUid KPermanentFileStoreLayoutUid={KPermanentFileStoreLayoutUidValue}; +// +typedef CFileStore* (*TFileStoreFactoryFunction)(RFileBuf& aBuf,const TUidType& aType); +// +#define KDirectFileStoreFactoryFunction (&FileStoreFactory::DirectLC) +#define KPermanentFileStoreFactoryFunction (&FileStoreFactory::PermanentLC) + +/** + * @publishedAll + * @released + * File based persistent store abstract base class. + +The class encapsulates the basic behaviour of file based stores. File based +stores are persistent stores, i.e. they have the ability to keep the external +representation of objects for longer than the lifetime of the applications +which created those objects. + +The class forms the base for the direct file store, CDirectFileStore, and +the permanent file store, CPermanentFileStore. In general, it is sufficient +for pointers to file based store objects to be of type CFileStore, rather +than of the concrete file store type. + +Existing file stores can be opened using the member functions OpenL(), OpenLC(), +FromL() and FromLC(). New file stores, however, must be created using the +appropriate member function of the concrete type. +*/ +class CFileStore : public CPersistentStore + { +public: + IMPORT_C static CFileStore* OpenL(RFs& aFs,const TDesC& aName,TUint aFileMode); + IMPORT_C static CFileStore* OpenLC(RFs& aFs,const TDesC& aName,TUint aFileMode); + IMPORT_C static CFileStore* FromL(RFile& aFile); + IMPORT_C static CFileStore* FromLC(RFile& aFile); +// + IMPORT_C static CFileStore* OpenL(RFs& aFs,const TDesC& aName,TUint aFileMode,const TFileStoreFactoryFunction aFactory[]); + IMPORT_C static CFileStore* OpenLC(RFs& aFs,const TDesC& aName,TUint aFileMode,const TFileStoreFactoryFunction aFactory[]); + IMPORT_C static CFileStore* FromL(RFile& aFile,const TFileStoreFactoryFunction aFactory[]); + IMPORT_C static CFileStore* FromLC(RFile& aFile,const TFileStoreFactoryFunction aFactory[]); +// + inline const TUidType& Type() const; + IMPORT_C void SetTypeL(const TUidType& aType); + /** Gets the UID that uniquely identifies the specific type of this file store. + + This function must be defined and implemented by classes derived from CFileStore. + The direct file store, CDirectFileStore and the permanent file store, CPermanentFileStore + both implement suitable functions. + + @return The UID that uniquely identifies the specific type of file store. + @see KDirectFileStoreLayoutUid + @see KPermanentFileStoreLayoutUid */ + virtual TUid Layout() const=0; +// + inline void Reset(); + inline void Reset(TInt aSize); + inline void Detach(); + inline void Reattach(RFile& aFile); + inline RFile& File() const; +// + IMPORT_C void MarshalL(); + IMPORT_C ~CFileStore(); +protected: + typedef CFileStore* (*TNewFunction)(RFile& aFile); +protected: + IMPORT_C static CFileStore* OpenL(RFs& aFs,const TDesC& aName,TUint aFileMode,TFileStoreFactoryFunction aFunction); + IMPORT_C static CFileStore* OpenLC(RFs& aFs,const TDesC& aName,TUint aFileMode,TFileStoreFactoryFunction aFunction); + IMPORT_C static CFileStore* CreateL(RFs& aFs,const TDesC& aName,TUint aFileMode,TNewFunction aFunction); + IMPORT_C static CFileStore* CreateLC(RFs& aFs,const TDesC& aName,TUint aFileMode,TNewFunction aFunction); + IMPORT_C static CFileStore* ReplaceL(RFs& aFs,const TDesC& aName,TUint aFileMode,TNewFunction aFunction); + IMPORT_C static CFileStore* ReplaceLC(RFs& aFs,const TDesC& aName,TUint aFileMode,TNewFunction aFunction); + IMPORT_C static CFileStore* TempL(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode,TNewFunction aFunction); + IMPORT_C static CFileStore* TempLC(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode,TNewFunction aFunction); +// + IMPORT_C static CFileStore* FromL(RFile& aFile,TFileStoreFactoryFunction aFunction); + IMPORT_C static CFileStore* FromLC(RFile& aFile,TFileStoreFactoryFunction aFunction); + IMPORT_C static CFileStore* NewL(RFile& aFile,TNewFunction aFunction); + IMPORT_C static CFileStore* NewLC(RFile& aFile,TNewFunction aFunction); +// + IMPORT_C CFileStore(RFile& aFile); + IMPORT_C CFileStore(RFileBuf& aBuf,const TUidType& aType); + IMPORT_C void Destruct(); +// + inline TStreamExchange& Host() const; + inline TBool IsHost(const MStreamBuf* aBuf) const; + IMPORT_C void SynchL(); + inline void SetSizeL(TInt aSize); + IMPORT_C void ChangedL(); + IMPORT_C void RefreshL(); +// + IMPORT_C void DoCommitL(); + IMPORT_C void DoRevertL(); +private: + virtual void ExternalizeL(RWriteStream& aStream) const=0; + virtual void InternalizeL(RReadStream& aStream)=0; +// + static CFileStore* DoNewL(RFile& aFile,TNewFunction aFunction); +private: + RFileBuf iBuf; + TUidType iType; + __MUTABLE TStreamExchange iHost; + }; +const TInt KFileStoreStartOffset=sizeof(TCheckedUid); +#if defined(__NO_CLASS_CONSTS__) +#define KFileStoreStart TStreamPos(KFileStoreStartOffset) +#else +const TStreamPos KFileStoreStart=TStreamPos(KFileStoreStartOffset); +#endif + +/** + * @publishedAll + * @released + * Direct file store. + +A direct file store implements a subset of the operations defined by the store +abstract framework. Direct file stores allow streams to be created and objects +externalised to them however once the streams have been committed and +closed, they cannot subsequently be changed, i.e. streams cannot be replaced, +deleted, extended or changed in any way. +*/ +class CDirectFileStore : public CFileStore + { +public: + inline static CDirectFileStore* OpenL(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CDirectFileStore* OpenLC(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CDirectFileStore* CreateL(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CDirectFileStore* CreateLC(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CDirectFileStore* ReplaceL(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CDirectFileStore* ReplaceLC(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CDirectFileStore* TempL(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode); + inline static CDirectFileStore* TempLC(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode); +// + inline static CDirectFileStore* FromL(RFile& aFile); + inline static CDirectFileStore* FromLC(RFile& aFile); + inline static CDirectFileStore* NewL(RFile& aFile); + inline static CDirectFileStore* NewLC(RFile& aFile); +// + IMPORT_C TUid Layout() const; +// + IMPORT_C CDirectFileStore(RFile& aFile); + IMPORT_C CDirectFileStore(RFileBuf& aBuf,const TUidType& aType); +protected: + IMPORT_C MStreamBuf* DoReadL(TStreamId anId) const; + IMPORT_C MStreamBuf* DoCreateL(TStreamId& anId); +private: + IMPORT_C void ExternalizeL(RWriteStream& aStream) const; + IMPORT_C void InternalizeL(RReadStream& aStream); + IMPORT_C void DoSetRootL(TStreamId anId); +// + IMPORT_C static CFileStore* DoNewL(RFile& aFile); + }; +// +class CPermanentStoreCoord; + +/** + * @publishedAll + * @released + * Permanent file store. + +This type of store supports full manipulation of store contents. Existing +streams within this type of store can be changed. + */ +class CPermanentFileStore : public CFileStore + { + friend class RPermanentFileStoreIter; +public: + inline static CPermanentFileStore* OpenL(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CPermanentFileStore* OpenLC(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CPermanentFileStore* CreateL(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CPermanentFileStore* CreateLC(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CPermanentFileStore* ReplaceL(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CPermanentFileStore* ReplaceLC(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline static CPermanentFileStore* TempL(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode); + inline static CPermanentFileStore* TempLC(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode); +// + inline static CPermanentFileStore* FromL(RFile& aFile); + inline static CPermanentFileStore* FromLC(RFile& aFile); + inline static CPermanentFileStore* NewL(RFile& aFile); + inline static CPermanentFileStore* NewLC(RFile& aFile); +// + IMPORT_C TUid Layout() const; +// + IMPORT_C CPermanentFileStore(RFile& aFile); + IMPORT_C CPermanentFileStore(RFileBuf& aBuf,const TUidType& aType); + IMPORT_C void MarshalL(); + IMPORT_C ~CPermanentFileStore(); +protected: + IMPORT_C MStreamBuf* DoReadL(TStreamId anId) const; + IMPORT_C MStreamBuf* DoCreateL(TStreamId& anId); + IMPORT_C MStreamBuf* DoWriteL(TStreamId anId); + IMPORT_C MStreamBuf* DoReplaceL(TStreamId anId); +private: + IMPORT_C void ExternalizeL(RWriteStream& aStream) const; + IMPORT_C void InternalizeL(RReadStream& aStream); + IMPORT_C void DoSetRootL(TStreamId anId); + IMPORT_C TStreamId DoExtendL(); + IMPORT_C void DoDeleteL(TStreamId anId); + IMPORT_C void DoCommitL(); + IMPORT_C void DoRevertL(); + IMPORT_C MIncrementalCollector* DoReclaimL(); + IMPORT_C MIncrementalCollector* DoCompactL(); +// + inline CPermanentStoreCoord& Coord() const; + CPermanentStoreCoord& CoordL() const; + CPermanentStoreCoord& TrimL(); +// + IMPORT_C static CFileStore* DoNewL(RFile& aFile); +private: + __MUTABLE CPermanentStoreCoord* iCoord; + }; + +/** + * @publishedAll + * @released + * File based dictionary store. + +A dictionary store is a store where a stream is accessed by UID, rather than +directly by stream ID. A dictionary store contains streams in the usual way +but, in addition, the root stream is a stream dictionary, i.e. a CStreamDictionary +type. +*/ +class CDictionaryFileStore : public CDictionaryStore + { +public: + IMPORT_C static CDictionaryFileStore* SystemL(RFs& aFs); + IMPORT_C static CDictionaryFileStore* SystemLC(RFs& aFs); + IMPORT_C static CDictionaryFileStore* OpenL(RFs& aFs,const TDesC& aName,TUid aUid3); + IMPORT_C static CDictionaryFileStore* OpenLC(RFs& aFs,const TDesC& aName,TUid aUid3); +private: + void ConstructL(RFs& aFs,const TDesC& aName,TUid aUid3); + void CreateStoreL(RFile& aFile,const TUidType& aType); + }; + +/** + * @publishedAll + * @released + * Uses a file directly to implement the page pool interface MPagePool. + +The pages are written sequentially through the file. You should call Close() +to release the file resource after CreateL(), OpenL(), ReplaceL() or Temp(). + +A file page pool uses a cache to store pages in-memory and to cache frequently +accessed pages. You should provide a cache object (CPageCache) to the pool +for this purpose. + +@see CPageCache +@see RFile +*/ +class RFilePagePool : public TCachePagePool + { +public: + IMPORT_C RFilePagePool(); + IMPORT_C RFilePagePool(CPageCache& aCache); +// + inline TInt Open(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline TInt Create(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline TInt Replace(RFs& aFs,const TDesC& aName,TUint aFileMode); + inline TInt Temp(RFs& aFs,const TDesC& aPath,TFileName& aName,TUint aFileMode); + inline void Attach(RFile& aFile); + IMPORT_C void Close(); + IMPORT_C void Release(); + IMPORT_C TInt Flush(); + IMPORT_C void FlushL(); + inline void Detach(); +// + inline RFile& File() const; +protected: + IMPORT_C TPageRef ExtendL(const TAny* aPage,TPageReclamation aReclamation); + IMPORT_C void WriteL(TPageRef aRef,const TAny* aPage,TPageChange aChange); + IMPORT_C void ReadL(TPageRef aRef,TAny* aPage); +private: + __MUTABLE RFile iFile; + }; + +#include +#endif