Class CStreamStore

class CStreamStore : public CBase;

Description

Provides the core abstract framework for stores allowing streams to be created and manipulated.

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

Members

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

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

inline TStreamId ExtendL();

Description

Generates a new stream within this store, and returns its id. This function can be used to create a new stream in advance of being written to.

This function is not supported by the direct file store, CDirectFileStore.

Return value

TStreamId The stream id for the newly generated stream.

See also:

• CDirectFileStore

IMPORT_C void Delete(TStreamId anId);

Description

Deletes the specified stream from this store.

This function is deprecated.

If unsuccessful, the function fails silently with no way to return information to the user.

The function is not supported by the direct file store, CDirectFileStore.

Parameters

TStreamId anId The id of the stream to be deleted.

IMPORT_C void DeleteL(TStreamId anId);

Description

Deletes the specified stream from this store, leaving if unsuccessful.

The function is not supported by the direct file store, CDirectFileStore.

Parameters

TStreamId anId The id of the stream to be deleted from this store.

See also:

• CDirectFileStore

IMPORT_C TInt Commit();

Description

Commits changes.

This function establishes a new commit point. Typically, this is done after changes to new or existing streams are complete and the streams themselves have been committed.

Establishing a new commit point makes changes to the store permanent. Until such changes are committed, they can be rolled back or reverted, effectively causing the store to revert back to its state before the changes were made.

This ensures that persistent data moves from one consistent state to another and guarantees the integrity of persistent store data in the event of failures. In particular, if a process terminates or a media failure occurs, the store reverts automatically to its state at the last successful commit point.

Note that this function is not implemented by the direct file store CDirectFileStore and the non-persistent in-memory store CBufStore.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• CDirectFileStore
• CBufStore

inline void CommitL();

Description

Commit changes and leaves if unsuccessful.

See also:

• CStreamStore::Commit()

IMPORT_C void Revert();

Description

Rolls back the store to its state at the last commit point.

This function is deprecated; use RevertL() instead.

If unsuccessful, the function fails silently with no way to return information to the user.

The function is not supported by the direct file store CDirectFileStore and the non-persistent in-memory store CBufStore.

See also:

• CDirectFileStore
• CBufStore

inline void RevertL();

Description

Rolls back the store to its state at the last commit point and leaves if unsuccessful.

The function is not supported by the direct file store CDirectFileStore and the non-persistent in-memory store CBufStore.

See also:

• CDirectFileStore
• CBufStore

IMPORT_C TInt ReclaimL();

Description

Reclaims space within a store, returning the total amount of free space available within that store.

The function does not return until the reclamation process is complete. This can take an extended amount of time.

The function is only supported by the permanent file store, CPermanentFileStore, but not by other derived classes, e.g., CDirectFileStore or CBufStore.

Return value

TInt The amount of free space available within the store.

See also:

• CPermanentFileStore

IMPORT_C TInt CompactL();

Description

Compacts the store. This returns free space to the appropriate system pool, for example, the filing system in the case of file-based stores.

On completion, the function returns the total amount of free space available within the store.

The function does not return until the compaction process is complete. This can take an extended amount of time.

Note:

this function is only supported by the permanent file store, CPermanentFileStore, and not by CDirectFileStore or CBufStore.

Streams must be closed before calling this function.

Return value

TInt The amount of free space available within the store.

See also:

• CPermanentFileStore

private: virtual IMPORT_C TStreamId DoExtendL();

Description

Generates a new stream within this store, and returns its id. This function is intended to create a new stream in advance of being written to.

This is called by ExtendL().

Return value

TStreamId The new stream id.

See also:

• CStreamStore::ExtendL()

private: virtual IMPORT_C void DoDeleteL(TStreamId anId);

Description

Parameters

TStreamId anId

private: virtual MStreamBuf *DoReadL(TStreamId anId) const=0;

Description

Opens the requested stream for reading. The function should return a stream buffer positioned at the beginning of this stream.

This function is called by the OpenL() and OpenLC() member functions of RStoreReadStream.

Parameters

TStreamId anId The stream to be read.

Return value

MStreamBuf * A stream buffer positioned at the beginning of the stream to be read.

See also:

• RStoreReadStream::OpenL()
• RStoreReadStream::OpenLC()

private: virtual MStreamBuf *DoCreateL(TStreamId &anId)=0;

Description

Creates a new stream in the store. The function gets the allocated stream id in the anId parameter. A stream buffer for the stream should be returned, ready to write into the new stream. This provides the implementation for the RStoreWriteStream::CreateL() functions.

Parameters

TStreamId &anId On return, contains the allocated stream id.

Return value

MStreamBuf * The stream buffer to be written to.

private: virtual IMPORT_C MStreamBuf *DoWriteL(TStreamId anId);

Description

Parameters

TStreamId anId

Return value

MStreamBuf *

private: virtual IMPORT_C MStreamBuf *DoReplaceL(TStreamId anId);

Description

Parameters

TStreamId anId

Return value

MStreamBuf *

private: 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.

private: 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 IMPORT_C MIncrementalCollector *DoReclaimL();

Description

Initialises an object for reclaiming space in the store. This function provides the direct implementation for RStoreReclaim::OpenL().

Note:

Actually reclaiming the space is done by repeated calls to MIncrementalCollector::Next(), before releasing the object.

Return value

MIncrementalCollector * Pointer to an incremental collector, which implements the interface for reclaiming store space.

private: virtual IMPORT_C MIncrementalCollector *DoCompactL();

Description

Initialises an object for compacting space in the store. This function provides the direct implementation for RStoreReclaim::CompactL().

Note:

Actually compacting the space is done by repeated calls to MIncrementalCollector::Next() before releasing the object.

Return value

MIncrementalCollector * Pointer to an incremental collector, which implements the interface for compacting store space.