Stores -Overview

Architectural relationships

A stream is a representation -of a data structure (such as an object) as a sequence of bytes. Structures -as complex as most applications require multiple streams to store their state. -This is termed a store. Stream types that work with stores are provided by -the Store Streams API.

The Stores API defines both base classes that -define store abstractions without specifying the storage medium, and some -concrete store types. The File Stores API defines further concrete stores, -which use file storage.

Concrete store types do not have to provides -all the stream manipulation functionality defined by the base class interfaces: -for example, direct file stores do not support individual deletion of streams -within a store.

Stores are integrated with the application architecture -as defined in the Uikon Core API. That expects file-based and embeddable applications -to handle their data storage through stores.

Description

The API has five key concepts: stream -store base, persistent store base, embedded store, memory store, and dictionary -store base and streams.

Stream store base

This defines -an interface for streams to be added and deleted to a store, a commit/revert -mechanism, and space compaction and reclamation. Stores return a stream ID -when a stream is created. A particular stream can be opened by specifying -its ID.

Some objects can save and restore their state to and from -a store. It is conventional to implement functions named StoreL() and RestoreL() for -these purposes. The most important case of this is the application document -class (CEikDocument), which can be implemented to store and -restore an application document.

The stream store base class is CStreamStore.

Persistent -store base

Most store types require that the store persists beyond -the lifetime of the application that created it. The persistent store base -extends the stream store base to provide this. In particular it provides:

a -root stream, from which all other streams within the store can be found

open -and close store functions

The persistent store base class is CPersistentStore.

Embedded -store

An embedded store can itself be stored as a stream in another -store. They are used to embed application documents in other application documents. -Once written, streams in the store cannot be modified: the store must be deleted -and rewritten in its entirety.

The embedded store is a concrete type, -derived from CPersistentStore, and is provided by CEmbeddedStore.

Memory -store

A memory store resides in memory and exists only for the -life of the store object. They can be used for transient complex dynamic structures -such as undo buffers.

The memory store is a concrete type, derived -from CStreamStore, and is provided by CBufStore.

Dictionary -store base and streams

A dictionary store contains a sequence -of streams, each of which is accessed using a UID, rather than a simple stream -ID. Dictionary stores are used by the application architecture to handle .ini files -for applications.

The dictionary store base class is CDictionaryStore. -Specialised stream types, RDictionaryReadStream and RDictionaryWriteStream, -are provided for use with dictionary stores.