Persistentdata for beginners: Store

Store provides the fundamental APIs for handling data on the Symbian platform – streams and stores.

Streams should be a familiar concept. They are part of the C++ standard library and Java’s I/O package. Objects can be externalized to a stream using the stream insertion operator and internalized from a stream using the stream extraction operator. The Symbian base classes that enable this behaviour are RReadStream and RWriteStream.

Stores are a collection (or network) of streams. Individual streams can be referenced by stream ID. Several types of stores derived from CStreamStore are provided to suit different needs.

Inheritance diagram for CStreamStore

Many applications use direct file stores (CDirectFileStore) to persist their preferences and DBMS uses the transactional properties of the permanent file store (CPermanentFileStore) to implement database transactions. However, stores do not have to be persistent (e.g. CBufStore).

Store API

The API is described below. Clients should link to estor.lib.

s32btree.h

s32btree.h provides an implementation of a B+ tree data structure (as used by DBMS for its index).

API Purpose
MBtreeIndexOrg Abstract interface for a B-tree index node organisation strategy
MBtreeKey Abstract interface for comparison of keys
MBtreeLeafOrg Abstract interface for a B-tree leaf node organisation strategy
MBtreeNodeOrg Abstract base class for B-tree node organisation strategies
TBtree Provides ordering of entries by key value in a B+ tree structure
TBtreeFix<Entry, Key> A B-tree for fixed-sized keys and entries
TBtreeFix<TAny, TAny> A specialisation of the B-tree for untyped fixed sized items (thin template idiom)
TBtreeFixBase Base class for TBtreeFix
TBtreeInlineIndexOrg Class for B-tree index node layout (strategy pattern)
TBtreeInlineLeafOrg Class for B-tree leaf node layout (strategy pattern)
TBtreeKey Concrete implementation of the MBtreeKey interface to provide B-tree ordering
TBtreeMark An iterator for a B-tree
TBtreePath Records the position within a TBtree
TBtreePos Identifies a position in a B-tree (uses TBtreePath)
TBtreeToken Encapsulates the persistent parameters for a TBtree

s32buf.h

s32buf.h defines the base class for stream I/O (MStreamBuf).

API Purpose
MStreamBuf Stream buffer. Provides a generic I/O interface for streamed data
MStreamInput An interface to an object that acts as a destination for read operations from a stream (data sink)
MStreamOutput An interface to an object that acts as source for write operations to a stream (data source)
TStreamBuf Adds buffering capabilities to a stream buffer
TStreamFilter Stream filter interface, allows stream data to be filtered after retrieval or filtered before it is written
TStreamPos Holds the position of the read or write mark within a seekable stream
TStreamTransfer Stream transfer object. Holds and maintains a value that represents how much data is to be transferred, or remains to be transferred, between streams

s32cont.h

s32cont.h adds a container-style interface on top of STORE B-trees.

API Purpose
TPagedMultiset<T> Template for a packaged B-tree that provides a persistent associative set of class T with a container-style interface. Duplicates are allowed.
TPagedMultiset<TAny> A specialisation of the TPagedMultiset for untyped items (thin-template idiom)
TPagedMultisetBase Base class for TPagedMultiset
TPagedSet<T> Template for a packaged B-tree that provides a persistent associative set of class T with a container-style interface. Duplicates are not allowed.
TPagedSet<TAny> A specialisation of the TPagedSet for untyped items (thin-template idiom)
TPagedSetBase Base class for TPagedSet
TPagedSetBiIter<T> Bi-directional iterator for sets
TPagedSetBiIter<TAny> Bi-directional iterator for sets
TPagedSetBiIterBase Base class for bi-directional iterator
TPagedSetIter<T> Forward only iterator for sets
TPagedSetIter<TAny> Forward only iterator for sets
TPagedSetIterBase Base class for forward only iterator
TPagedSetRIter<T> Reverse iterator for sets
TPagedSetRIter<TAny> Reverse iterator for sets
TPagedSetRIterBase Base class for reverse iterator
TPagedSetToken Encapsulates the persistent parameters for a TPagedSet

s32crypt.h

s32crypt.h provides encrypted streams and stores. It is a platform header.

API Purpose
CSecureStore A stream store whose streams are encrypted
RDecryptStream Supports the decrypting of a stream
REncryptStream Supports the encryption of a stream
RSecureStorePagePool Uses an encrypted store to implement the page pool interface MPagePool
TDecryptFilter A decrypting filter
TEncryptFilter An encrypting filter
TSecureFilter Base class used in the derivation of TEncryptFilter and TDecryptFilter

s32file.h

s32file.h provides a concrete implementation of the stream/store framework using files.

API Purpose
CDictionaryFileStore File based dictionary store. A dictionary store is a store where streams are accessed by UID rather than directly by stream ID
CDictionaryStore Abstract interface for dictionary stores
CDirectFileStore Direct file store. Direct file stores allow streams to be created and objects externalized to them, but once the streams have been committed and closed they cannot subsequently be changed (i.e. streams cannot be replaced, deleted, extended or changed in any way)
CFileStore File based 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.
CPermanentFileStore Permanent file store. This type of store supports full manipulation of store contents. Existing streams within this type of store can be changed.
FileStoreFactory This class provides factory functions for opening an existing direct file store and an existing permanent file
RFileBuf A stream buffer hosted by a file
RFilePagePool Uses a file directly to implement the page pool interface MPagePool
RFileReadStream Supports the reading of a stream from a file
RFileWriteStream Supports the writing of a stream to a file

s32fileiter.h

s32fileiter.h provides an iterator for permanent file store files. It is a platform header.

API Purpose
RPermanentFileStoreIter Forward iterator for streams in a permanent file store

s32mem.h

s32mem.h provides a concrete implementation of the stream/store framework using in-memory data structures.

API Purpose
CBufStore In-memory non-persistent store
TBufBuf A stream buffer that uses a dynamic buffer for its implementation
RBufReadStream Supports the opening of an existing stream hosted by a dynamic buffer
RBufWriteStream Supports the writing of a stream to a dynamic buffer
TDesBuf A stream buffer that uses a descriptor for its implementation
RDesReadStream Supports the reading of a stream from an 8-bit descriptor
RDesWriteStream Supports the writing of a stream to a stream buffer hosted by an 8-bit descriptor
TMemBuf A stream buffer that uses memory for its implementation
RMemReadStream Supports the reading of a stream from a pointer of any type
RMemWriteStream Supports the writing of a stream to a pointer of any type

s32page.h

s32page.h defines the storage abstraction used by STORE B-trees, the “page pool” (MPagePool).

API Purpose
CMemPagePool Uses memory to implement the MPagePool page pool interface.
CPageCache Provides a cache for page pools
MPagePool Interface to a page pool, the storage abstraction used by the B-trees API
TCachePagePool Provides a page pool with cached pages
TPageRef Page reference

s32share.h

s32share.h contains definitions for shared stream buffers.

API Purpose
RShareBuf A shared stream buffer
RShareReadStream Supports reading of a stream which shares its host with other streams
RShareWriteStream Supports writing of a stream which shares its host with other streams
TStreamExchange Manages access to a shared host buffer for shared stream buffers
TStreamMark Manages the position of a read mark or a write mark within a shared stream

s32std.h

s32std.h contains key classes – TSwizzle, TStreamId and the CStreamDictionary.

API Purpose
CStoreMap Store map used when externalising swizzled in-memory objects
CStoreMap::TEntry An entry in the store map (swizzle, TStreamId)
CStreamDictionary Maintains two way associations between a UID (a TUid type) and a stream id (a TStreamId type)
RStoreReadStream Supports the opening and manipulation of an existing stream in a store
RStoreWriteStream Supports the writing of a stream to a store
TStreamId Provides unique identification for stream within a store
TSwizzle<T> Template class providing a dual representation of an object (memory, pointer) that allows the loading of objects into memory from a store to be deferred
TSwizzle<TAny> Instantiation of TSwizzle that maintains the representation of an untyped object as a non-const pointer or as a stream id
TSwizzleBase Base class for non-const swizzles containing common implementation. No accessible methods or data members
TSwizzleC<T> Template class for constant object swizzles
TSwizzleC<TAny> Instantiation of TSwizzle that maintains the representation of an untyped object as a const pointer or as a stream id
TSwizzleCBase Base class for swizzles

s32stor.h

s32stor.h defines the stream store (CStreamStore).

API Purpose
CEmbeddedStore A store that can be embedded in another store. The embedded store may contain an arbitrarily complex network of streams, but is viewed as simply another stream by the embedding store.
CPersistentStore Persistent store abstract base class
CStreamStore Abstract framework for stores allowing streams to be created and manipulated
MIncrementalCollector Abstract interface for incrementally reclaiming or compacting space in a stream store
RDictionaryReadStream Supports the opening and manipulation of a stream in a dictionary store
RDictionaryWriteStream Supports the creation or replacement of a stream a dictionary store
RStorePagePool Uses a store to implement the page pool interface MPagePool
RStoreReclaim Performs space reclamation or compaction on a permanent file store in incremental steps
TStorePagePoolToken Persistent settings to use for a RStorePagePool

s32strm.h

s32strm.h is the stream framework header.

API Purpose
Externalize A class whose members are used to distinguish between the two variants of the Symbian OS internal function DoExternalizeL()
Externalize::Function Indicates that an object will be externalized by calling a global ExternalizeL() function
Internalize::Function Indicates that an object will be internalized by calling a global InternalizeL() function
Internalize A class whose members are used to distinguish between the two variants of the Symbian OS internal function DoInternalizeL()
Internalize::Member Indicates that an object will be internalized by calling its InternalizeL() member
Externalize::Member Indicates that an object will be externalized by calling its ExternalizeL() member
MExternalizer<T> Template class defining an interface that can be implemented by classes that need to perform externalisation on behalf of others
MInternalizer<T> Template class defining an interface that can be implemented by classes that need to perform internalisation on behalf of others
RReadStream The read stream interface, enables internalizing from a stream
RWriteStream The write stream interface, enables externalizing to a stream
TCardinality Compact stream format for positive integer values in the range 0 to 536,870,911 ((2^29)-1)
TExternalizer<T> Template class used to perform externalization on behalf of other objects
TExternalizer<TAny> Instantiation of TExternalizer interface
TInternalizer<T> Template class used to perform internalisation on behalf of other objects
TInternalizer<TAny> Instantiation of TInternalizer interface
TStreamRef A proxy for perfoming externalisation for classes that do not have an externalisation member

Further resources

Coming up next…

The next part of the Persistentdata for beginners series will look at Event Logger. It is the database for the Logs application. It stores information such as who called you last and packet data connections.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


%d bloggers like this: