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 CFileStore::OpenL(RFs &,const TDesC &,TUint), CFileStore::OpenLC(RFs &,const TDesC &,TUint), CFileStore::FromL(RFile &) and CFileStore::FromLC(RFile &). 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 - ...

• CPersistentStore - ...

• CFileStore - File based persistent store abstract base class.

Members

Defined in CFileStore:

• CFileStore(RFile &)
• CFileStore(RFileBuf &,const TUidType &)
• ChangedL()
• CreateL(RFs &,const TDesC &,TUint,TNewFunction)
• CreateLC(RFs &,const TDesC &,TUint,TNewFunction)
• Destruct()
• Detach()Detaches the file store from its associated file.
• DoCommitL()Commits any changes to the store. For a store that provides atomic updates, this...
• DoRevertL()Discards any pending changes to the store. This includes all changes which have ...
• ExternalizeL(RWriteStream &)const
• File()constGets a reference to the file associated with this file store.
• FromL(RFile &)Constructs a file store object from an opened file.
• FromL(RFile &,TFileStoreFactoryFunction)
• FromL(RFile &,const TFileStoreFactoryFunction)
• FromLC(RFile &)Constructs a file store object from an opened file, and places the pointer onto ...
• FromLC(RFile &,TFileStoreFactoryFunction)
• FromLC(RFile &,const TFileStoreFactoryFunction)
• Host()const
• InternalizeL(RReadStream &)
• IsHost(const MStreamBuf *)const
• Layout()constGets the UID that uniquely identifies the specific type of this file store.
• MarshalL()
• NewL(RFile &,TNewFunction)
• NewLC(RFile &,TNewFunction)
• OpenL(RFs &,const TDesC &,TUint)Opens a file containing a store and constructs an appropriate file store object.
• OpenL(RFs &,const TDesC &,TUint,TFileStoreFactoryFunction)
• OpenL(RFs &,const TDesC &,TUint,const TFileStoreFactoryFunction)
• OpenLC(RFs &,const TDesC &,TUint)Opens a file containing a store, constructs an appropriate file store object and...
• OpenLC(RFs &,const TDesC &,TUint,TFileStoreFactoryFunction)
• OpenLC(RFs &,const TDesC &,TUint,const TFileStoreFactoryFunction)
• Reattach(RFile &)Reattaches a file to the file store. The file should be the one that was detache...
• RefreshL()
• ReplaceL(RFs &,const TDesC &,TUint,TNewFunction)
• ReplaceLC(RFs &,const TDesC &,TUint,TNewFunction)
• Reset()Frees the file store’s buffer space.
• Reset(TInt)Frees the file store’s buffer space and changes the size of future buffer s...
• SetSizeL(TInt)
• SetTypeL(const TUidType &)Sets the UID type of the file store.
• SynchL()
• TNewFunction
• TempL(RFs &,const TDesC &,TFileName &,TUint,TNewFunction)
• TempLC(RFs &,const TDesC &,TFileName &,TUint,TNewFunction)
• Type()constGets the UID type of the file store.
• ~CFileStore()Frees resources owned by the object, prior to its destruction. In particular, it...

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• Extension_(TUint,TAny *&,TAny *)Extension function
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

Inherited from CPersistentStore:

• Root()constReturns the stream id of the root stream.
• SetRootL(TStreamId)Sets the specified stream as the root stream.
• iRoot

Inherited from CStreamStore:

• Commit()Commits changes.
• CommitL()Commit changes and leaves if unsuccessful.
• CompactL()Compacts the store. This returns free space to the appropriate system pool, for ...
• Delete(TStreamId)Deletes the specified stream from this store.
• DeleteL(TStreamId)Deletes the specified stream from this store, leaving if unsuccessful.
• ExtendL()Generates a new stream within this store, and returns its id. This function can ...
• ReclaimL()Reclaims space within a store, returning the total amount of free space availabl...
• Revert()Rolls back the store to its state at the last commit point.
• RevertL()Rolls back the store to its state at the last commit point and leaves if unsucce...

IMPORT_C ~CFileStore();

Description

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

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

Description

Parameters

Return value

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

Description

Parameters

Return value

protected: IMPORT_C CFileStore(RFile &aFile);

Description

Parameters

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

Description

Parameters

IMPORT_C static 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

Return value

See also:

• CFileStore::Layout()constGets the UID that uniquely identifies the specific type of this file store.

IMPORT_C static 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

Return value

See also:

• CFileStore::Layout()constGets the UID that uniquely identifies the specific type of this file store.

IMPORT_C static 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

Return value

See also:

• CFileStore::Layout()constGets the UID that uniquely identifies the specific type of this file store.

IMPORT_C static 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

Return value

See also:

• CFileStore::Layout()constGets the UID that uniquely identifies the specific type of this file store.

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

Description

Parameters

Return value

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

Description

Parameters

Return value

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

Description

Parameters

Return value

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

Description

Parameters

Return value

inline const TUidType& Type() const;

Description

Gets the UID type of the file store.

Return value

See also:

• TUidA globally unique 32-bit number.

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()const, otherwise the function raises a STORE-File 9 panic.

Parameters

See also:

• TUidA globally unique 32-bit number.

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

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 CStreamStore::CommitL() or CStreamStore::RevertL().

See also:

• CStreamStore::CommitL()Commit changes and leaves if unsuccessful.
• CStreamStore::RevertL()Rolls back the store to its state at the last commit point and leaves if unsucce...

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 CStreamStore::CommitL() or CStreamStore::RevertL().

Parameters

See also:

• CStreamStore::CommitL()Commit changes and leaves if unsuccessful.
• CStreamStore::RevertL()Rolls back the store to its state at the last commit point and leaves if unsucce...

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:

• CFileStore::File()constGets a reference to the file associated with this file store.
• CFileStore::Reattach(RFile &)Reattaches a file to the file store. The file should be the one that was detache...

inline void Reattach(RFile &aFile);

Description

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

Parameters

See also:

• CFileStore::File()constGets a reference to the file associated with this file store.

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

See also:

• CFileStore::Detach()Detaches the file store from its associated file.

IMPORT_C void MarshalL();

Description

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

Description

Parameters

Return value

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

Description

Parameters

Return value

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

Description

Parameters

Return value

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

Description

Parameters

Return value

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

Description

Parameters

Return value

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

Description

Parameters

Return value

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

Description

Parameters

Return value

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

Description

Parameters

Return value

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

Description

Parameters

Return value

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

Description

Parameters

Return value

protected: IMPORT_C void Destruct();

Description

protected: inline TStreamExchange& Host() const;

Description

Return value

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

Description

Parameters

Return value

protected: IMPORT_C void SynchL();

Description

protected: inline void SetSizeL(TInt aSize);

Description

Parameters

protected: IMPORT_C void ChangedL();

Description

protected: IMPORT_C void RefreshL();

Description

protected: IMPORT_C virtual 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 CStreamStore::CommitL() function.

protected: IMPORT_C virtual 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 CStreamStore::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

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

Description

Parameters

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

Description