Class CFileStore

CFileStore

Support

Supported from 5.0

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 CFileStore File based persistent store -- abstract base class CPersistentStore Persistent store abstract base class CStreamStore Provides the core abstract framework for stores allowing streams to be created and manipulated

Defined in CFileStore:
Detach(), File(), FromL(), FromLC(), Layout(), OpenL(), OpenLC(), Reattach(), Reset(), SetTypeL(), Type(), ~CFileStore()

Inherited from CBase:
operator new()

Inherited from CPersistentStore:
Root(), SetRootL()

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

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

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.

Leave codes

The file must contain a direct file store or a permanent file store, otherwise OpenL() leaves with KErrNotSupported. If the function leaves, the file is closed.

See also:

• TFileMode
• CFileStore::Layout()

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

Description

Opens a file containing a store, using the specified set of factory functions and constructs a file store object.

The function invokes each factory function, in turn, until an attempt to construct a file store object is successful. The file store type is determined by the layout information held in the file store and assumes that one of the supplied factory functions is capable of opening that type.

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. const TFileStoreFactoryFunction aFactory[] An array of factory functions, one of which should be capable of opening the file store.

Return value

CFileStore* A pointer to the new file store object.

Leave codes

The file must contain a file store of a type that can be opened by one of the factory functions, otherwise OpenL() leaves with KErrNotSupported. If the function leaves, the file is closed.

See also:

• TFileMode
• CFileStore::Layout()

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

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.

Leave codes

The file must contain a direct file store or a permanent file store, otherwise OpenLC() leaves with KErrNotSupported. If the function leaves, the file is closed.

See also:

• TFileMode
• CFileStore::Layout()

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

Description

Opens a file containing a store, using the specified set of factory functions, and constructs a file store object placing a pointer onto the cleanup stack.

The function invokes each factory function, in turn, until an attempt to construct a file store object is successful. The file store type is determined by the layout information held in the file store and assumes that one of the supplied factory functions is capable of opening that type.

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. const TFileStoreFactoryFunction aFactory[] An array of factory functions, one of which should be capable of opening the file store.

Return value

CFileStore* A pointer to the new file store object.

Leave codes

The file must contain a file store of a type that can be opened by one of the factory functions, otherwise OpenLC() leaves with KErrNotSupported. If the function leaves, the file is closed.

See also:

• TFileMode
• CFileStore::Layout()

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

RFile& aFile A reference to the opened file.

Return value

CFileStore* A pointer to the new file store object.

Leave codes

The file must contain a direct file store or a permanent file store, otherwise FromL() leaves with KErrNotSupported. If the function leaves, the file is closed.

See also:

• CFileStore::Layout()

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

Description

Constructs a file store object from an opened file, using the specified set of factory functions.

The file must already be open before calling this function.

The function invokes each factory function, in turn, until an attempt to construct a file store object is successful. The file store type is determined by the layout information held in the file store and assumes that one of the supplied factory functions is capable of opening that type.

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. const TFileStoreFactoryFunction aFactory[] An array of factory functions, one of which should be capable of opening the file store.

Return value

CFileStore* A pointer to the new file store object.

Leave codes

The file must contain a file store of a type that can be opened by one of the factory functions, otherwise FromLC() leaves with KErrNotSupported. If the function leaves, the file is closed.

See also:

• CFileStore::Layout()

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

RFile& aFile A reference to the opened file.

Return value

CFileStore* A pointer to the new file store object.

Leave codes

The file must contain a direct file store or a permanent file store, otherwise FromLC() leaves with KErrNotSupported. If the function leaves, the file is closed.

See also:

• CFileStore::Layout()

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

Description

Constructs a file store object from an opened file, using the specified set of factory functions, and places the pointer onto the cleanup stack.

The file must already be open before calling this function.

The function invokes each factory function, in turn, until an attempt to construct a file store object is successful. The file store type is determined by the layout information held in the file store and assumes that one of the supplied factory functions is capable of opening that type.

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. const TFileStoreFactoryFunction aFactory[] An array of factory functions, one of which should be capable of opening the file store.

Return value

CFileStore* A pointer to the new file store object.

Leave codes

The file must contain a file store of a type that can be opened by one of the factory functions, otherwise FromLC() leaves with KErrNotSupported. If the function leaves, the file is closed.

See also:

• CFileStore::Layout()

~CFileStore();

Description

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

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

const TUidType& Type() const;

Description

Gets the UID type of the file store.

Return value

TUidType& 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.

See also:

• KDirectFileStoreLayoutUid
• KPermanentFileStoreLayoutUid

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()

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()

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()

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()

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()