Class CFileStore

class CFileStore : public CPersistentStore;

Description

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.

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CStreamStore - Provides the core abstract framework for stores allowing streams to be created and manipulated

• CPersistentStore - Persistent store abstract base class

• CFileStore - File based persistent store abstract base class

Members

Defined in CFileStore:
CFileStore(), CFileStore(), ChangedL(), CreateL(), CreateLC(), Destruct(), Detach(), DoCommitL(), DoRevertL(), ExternalizeL(), File(), FromL(), FromL(), FromL(), FromLC(), FromLC(), FromLC(), Host(), InternalizeL(), IsHost(), Layout(), MarshalL(), NewL(), NewLC(), OpenL(), OpenL(), OpenL(), OpenLC(), OpenLC(), OpenLC(), Reattach(), RefreshL(), ReplaceL(), ReplaceLC(), Reset(), Reset(), SetSizeL(), SetTypeL(), SynchL(), TNewFunction, TempL(), TempLC(), Type(), ~CFileStore()

Inherited from CBase:
Extension_(), operator new()

Inherited from CPersistentStore:
DoSetRootL(), Root(), SetRootL(), iRoot

Inherited from CStreamStore:
Commit(), CommitL(), CompactL(), Delete(), DeleteL(), DoCompactL(), DoCreateL(), DoDeleteL(), DoExtendL(), DoReadL(), DoReclaimL(), DoReplaceL(), DoWriteL(), ExtendL(), ReclaimL(), Revert(), RevertL()

IMPORT_C ~CFileStore();

Description

Frees resources owned by the object, prior to its destruction. In particular, it closes the associated file.

protected: static IMPORT_C CFileStore *NewL(RFile &aFile, TNewFunction aFunction);

Description

Parameters

RFile &aFile TNewFunction aFunction

Return value

CFileStore *

protected: static IMPORT_C CFileStore *NewLC(RFile &aFile, TNewFunction aFunction);

Description

Parameters

RFile &aFile TNewFunction aFunction

Return value

CFileStore *

protected: IMPORT_C CFileStore(RFile &aFile);

Description

Parameters

RFile &aFile

protected: IMPORT_C CFileStore(RFileBuf &aBuf, const TUidType &aType);

Description

Parameters

RFileBuf &aBuf const TUidType &aType

static IMPORT_C CFileStore *OpenL(RFs &aFs, const TDesC &aName, TUint aFileMode);

Description

Opens a file containing a store and constructs an appropriate file store object.

The resulting file store object is of concrete type, i.e. either CDirectFileStore or CPermanentFileStore. The specific type is determined from the layout information held in the file store.

Parameters

RFs &aFs Handle to a file server session. const TDesC &aName The full path name of the file containing the store. TUint aFileMode The mode in which the file is to be accessed. The mode is defined by the TFileMode type.

Return value

CFileStore * A pointer to the new file store object.

See also:

• TFileMode
• CFileStore::Layout()

static IMPORT_C CFileStore *OpenLC(RFs &aFs, const TDesC &aName, TUint aFileMode);

Description

Opens a file containing a store, constructs an appropriate file store object and places the pointer onto the cleanup stack.

The resulting file store object is of concrete type, i.e. either CDirectFileStore or CPermanentFileStore. The specific type is determined from the layout information held in the file store.

Parameters

RFs &aFs Handle to a file server session. const TDesC &aName The full path name of the file containing the store. TUint aFileMode The mode in which the file is to be accessed. The mode is defined by the TFileMode type.

Return value

CFileStore * A pointer to the new file store object.

See also:

• TFileMode
• CFileStore::Layout()

static IMPORT_C CFileStore *FromL(RFile &aFile);

Description

Constructs a file store object from an opened file.

The file must already be open before calling this function.

The resulting file store object is of concrete type, i.e. either CDirectFileStore or CPermanentFileStore. The specific type is determined from the layout information held in the file store.

Note that ownership of the file passes to the store. The referenced RFile is cleared and is no longer valid:

Parameters

RFile &aFile A reference to the opened file.

Return value

CFileStore * A pointer to the new file store object.

See also:

• CFileStore::Layout()

static IMPORT_C CFileStore *FromLC(RFile &aFile);

Description

Constructs a file store object from an opened file, and places the pointer onto the cleanup stack.

The file must already be open before calling this function.

The resulting file store object is of concrete type, i.e. either CDirectFileStore or CPermanentFileStore. The specific type is determined from the layout information held in the file store.

Note that ownership of the file passes to the store. The referenced RFile is cleared and is no longer valid:

Parameters

RFile &aFile A reference to the opened file.

Return value

CFileStore * A pointer to the new file store object.

See also:

• CFileStore::Layout()

static IMPORT_C CFileStore *OpenL(RFs &aFs, const TDesC &aName, TUint aFileMode, const TFileStoreFactoryFunction aFactory[]);

Description

Parameters

RFs &aFs const TDesC &aName TUint aFileMode const TFileStoreFactoryFunction aFactory

Return value

CFileStore *

static IMPORT_C CFileStore *OpenLC(RFs &aFs, const TDesC &aName, TUint aFileMode, const TFileStoreFactoryFunction aFactory[]);

Description

Parameters

RFs &aFs const TDesC &aName TUint aFileMode const TFileStoreFactoryFunction aFactory

Return value

CFileStore *

static IMPORT_C CFileStore *FromL(RFile &aFile, const TFileStoreFactoryFunction aFactory[]);

Description

Parameters

RFile &aFile const TFileStoreFactoryFunction aFactory

Return value

CFileStore *

static IMPORT_C CFileStore *FromLC(RFile &aFile, const TFileStoreFactoryFunction aFactory[]);

Description

Parameters

RFile &aFile const TFileStoreFactoryFunction aFactory

Return value

CFileStore *

inline const TUidType &Type() const;

Description

Gets the UID type of the file store.

Return value

const TUidType & The UID type object containing the file store type.

See also:

• TUid

IMPORT_C void SetTypeL(const TUidType &aType);

Description

Sets the UID type of the file store.

The first UID, i.e. the first TUid component, of the TUidType must be the file store type as returned by CFileStore::Layout(), otherwise the function raises a STORE-File 9 panic.

Parameters

const TUidType &aType The UID type object containing the file store type.

See also:

• TUid

virtual TUid Layout() const=0;

Description

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 value

TUid The UID that uniquely identifies the specific type of file store.

inline void Reset();

Description

Frees the file store’s buffer space.

The buffer space is automatically re-allocated when needed.

This function should only be used immediately after a successful call to CommitL() or RevertL().

See also:

• CStreamStore::CommitL()
• CStreamStore::RevertL()

inline void Reset(TInt aSize);

Description

Frees the file store’s buffer space and changes the size of future buffer space allocations.

The buffer space is automatically re-allocated when needed, using the new size value.

This function should only be used immediately after a successful call to CommitL() or RevertL().

Parameters

TInt aSize The size of future buffer space allocations.

See also:

• CStreamStore::CommitL()
• CStreamStore::RevertL()

inline void Detach();

Description

Detaches the file store from its associated file.

In effect, the file store gives up ownership of the file.

Detaching is useful in cases where a file needs to be closed and later re-opened; for example, to give up a write lock for backup purposes.

It is very important that the contents of the file should not change while it is detached.

See also:

• File()
• Reattach()

inline void Reattach(RFile &aFile);

Description

Reattaches a file to the file store. The file should be the one that was detached using the Detach() function.

Parameters

RFile &aFile The file to be associated with this file store.

See also:

• File()

inline RFile &File() const;

Description

Gets a reference to the file associated with this file store.

This function is called prior to detaching the file store.

Return value

RFile & A reference to the associated file.

See also:

• Detach()

IMPORT_C void MarshalL();

Description

protected: static IMPORT_C CFileStore *OpenL(RFs &aFs, const TDesC &aName, TUint aFileMode, TFileStoreFactoryFunction aFunction);

Description

Parameters

RFs &aFs const TDesC &aName TUint aFileMode TFileStoreFactoryFunction aFunction

Return value

CFileStore *

protected: static IMPORT_C CFileStore *OpenLC(RFs &aFs, const TDesC &aName, TUint aFileMode, TFileStoreFactoryFunction aFunction);

Description

Parameters

RFs &aFs const TDesC &aName TUint aFileMode TFileStoreFactoryFunction aFunction

Return value

CFileStore *

protected: static IMPORT_C CFileStore *CreateL(RFs &aFs, const TDesC &aName, TUint aFileMode, TNewFunction aFunction);

Description

Parameters

RFs &aFs const TDesC &aName TUint aFileMode TNewFunction aFunction

Return value

CFileStore *

protected: static IMPORT_C CFileStore *CreateLC(RFs &aFs, const TDesC &aName, TUint aFileMode, TNewFunction aFunction);

Description

Parameters

RFs &aFs const TDesC &aName TUint aFileMode TNewFunction aFunction

Return value

CFileStore *

protected: static IMPORT_C CFileStore *ReplaceL(RFs &aFs, const TDesC &aName, TUint aFileMode, TNewFunction aFunction);

Description

Parameters

RFs &aFs const TDesC &aName TUint aFileMode TNewFunction aFunction

Return value

CFileStore *

protected: static IMPORT_C CFileStore *ReplaceLC(RFs &aFs, const TDesC &aName, TUint aFileMode, TNewFunction aFunction);

Description

Parameters

RFs &aFs const TDesC &aName TUint aFileMode TNewFunction aFunction

Return value

CFileStore *

protected: static IMPORT_C CFileStore *TempL(RFs &aFs, const TDesC &aPath, TFileName &aName, TUint aFileMode, TNewFunction aFunction);

Description

Parameters

RFs &aFs const TDesC &aPath TFileName &aName TUint aFileMode TNewFunction aFunction

Return value

CFileStore *

protected: static IMPORT_C CFileStore *TempLC(RFs &aFs, const TDesC &aPath, TFileName &aName, TUint aFileMode, TNewFunction aFunction);

Description

Parameters

RFs &aFs const TDesC &aPath TFileName &aName TUint aFileMode TNewFunction aFunction

Return value

CFileStore *

protected: static IMPORT_C CFileStore *FromL(RFile &aFile, TFileStoreFactoryFunction aFunction);

Description

Parameters

RFile &aFile TFileStoreFactoryFunction aFunction

Return value

CFileStore *

protected: static IMPORT_C CFileStore *FromLC(RFile &aFile, TFileStoreFactoryFunction aFunction);

Description

Parameters

RFile &aFile TFileStoreFactoryFunction aFunction

Return value

CFileStore *

protected: IMPORT_C void Destruct();

Description

protected: inline TStreamExchange &Host() const;

Description

Return value

TStreamExchange &

protected: inline TBool IsHost(const MStreamBuf *aBuf) const;

Description

Parameters

const MStreamBuf *aBuf

Return value

TBool

protected: IMPORT_C void SynchL();

Description

protected: inline void SetSizeL(TInt aSize);

Description

Parameters

TInt aSize

protected: IMPORT_C void ChangedL();

Description

protected: IMPORT_C void RefreshL();

Description

protected: virtual IMPORT_C void DoCommitL();

Description

Commits any changes to the store. For a store that provides atomic updates, this writes all of the pending updates to the to the permanent storage medium. After committing the store contains all or none of the updates since the last commit/revert.

This function provides the implementation for the public CommitL() function.

protected: virtual IMPORT_C void DoRevertL();

Description

Discards any pending changes to the store. This includes all changes which have not been committed to a permanent storage medium.

This function provides the implementation for the public Revert() function.

Note:

The function need only be implemented by stores that provide atomic updates, as revert has no meaning for other implementations.

private: virtual void ExternalizeL(RWriteStream &aStream) const=0;

Description

Parameters

RWriteStream &aStream

private: virtual void InternalizeL(RReadStream &aStream)=0;

Description

Parameters

RReadStream &aStream

protected: typedef CFileStore*(* CFileStore::TNewFunction)(RFile& aFile);

Description