Class CStreamStore

CStreamStore

Support

Supported from 5.0

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

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:
operator new()

See also:

• Using CStreamStore

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.

Leave codes

If this function is called on a direct file store, it leaves with KErrNotSupported .

See also:

• CDirectFileStore

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.

Leave codes

If this function is called on a direct file store, it leaves with KErrNotSupported .

See also:

• CDirectFileStore

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.

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

void CommitL();

Description

Commit changes and leaves if unsuccessful.

See also:

• CStreamStore::Commit()

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.

Leave codes

If this function is called on a direct file store or a non persistent in-memory store, it leaves with KErrNotSupported. The function may also leave if the store is on removable media, and the media is removed before the revert operation can be implemented. The calling code, or parent application, must be able to handle such situations.

See also:

• CDirectFileStore
• CBufStore

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

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.

Leave codes

If the function is called on any object other than a permanent file store, it leaves with KErrNotSupported .

See also:

• CPermanentFileStore

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.

Leave codes

If the function is called on any object other than a permanent file store, it leaves with KErrNotSupported .

See also:

• CPermanentFileStore

Description

These functions are all part of the store framework, and need to be understood only by those who wish to implement their own classes derived either from CStreamStore or from CStreamStore derived classes.

private: virtual 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()

virtual void DoDeleteL(TStreamId anId);

Description

Deletes the specified stream from the store.

This is called by DeleteL().

Parameters

TStreamId anId The id of the stream to be deleted.

See also:

• CStreamStore::Delete()
• CStreamStore::DeleteL()

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

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.

virtual MStreamBuf* DoWriteL(TStreamId anId);

Description

Opens the specified existing stream for writing. A stream buffer is returned ready to overwrite the existing stream data. This function provides the implementation for the RStoreWriteStream::OpenL() functions.

Note:

• The CStreamStore implementation may allow the existing stream size to be changed as a result of committing the stream, but this is not required. e.g. CBufStore will change the stream size following commit, whereas CPermanentFileStore will leave the existing stream size unaltered. The latter store leaves with KErrEof if it attempts to write beyond the current end-of-stream with.

Parameters

TStreamId anId The id stream to open for writing.

Return value

MStreamBuf* The stream write buffer.

Leave codes

KErrNotFound The stream id is not valid in this store.

virtual MStreamBuf* DoReplaceL(TStreamId anId);

Description

Opens the specified existing stream for safe replacement. A stream buffer for the new stream data is returned ready for writing the new stream data. This function provides the implementation for the RStoreWriteStream::ReplaceL() functions.

Note:

• This differs in behaviour from DoWriteL() for stores that provide atomic update support (such as CPermanentFileStore) as this guarantees to preserve the original stream data if the store is not successfully committed after writing the stream. Such a guarantee is not made for the stream buffer returned by DoWriteL().

Parameters

TStreamId anId The id stream to open for replacement.

Return value

MStreamBuf* The stream write buffer.

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 CommitL() function.

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 Revert() function.

Note:

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

virtual 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.

virtual 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.