<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-5EAED550-5FFC-54A6-BB4A-720975B127B8" xml:lang="en"><title>Stores
Overview</title><shortdesc>Provides structured data storage, using networks of streams.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-A750DA94-F7BD-49F2-AB3C-4B75665C211D"><title>Architectural relationships</title> <p>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. </p> <p>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. </p> <p>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. </p> <p>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. </p> </section>
<section id="GUID-5806D6A8-2256-4741-8691-AB75DF877598"><title>Description</title> <p>The API has five key concepts: stream
store base, persistent store base, embedded store, memory store, and dictionary
store base and streams.</p> <p><b>Stream store base</b> </p> <p>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. </p> <p>Some objects can save and restore their state to and from
a store. It is conventional to implement functions named <codeph>StoreL()</codeph> and <codeph>RestoreL()</codeph> for
these purposes. The most important case of this is the application document
class (<codeph>CEikDocument</codeph>), which can be implemented to store and
restore an application document. </p> <p>The stream store base class is <xref href="GUID-30726D8E-E18D-3A3A-8EFB-CCA4F04C984D.dita"><apiname>CStreamStore</apiname></xref>.</p> <p><b>Persistent
store base</b> </p> <p>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:</p> <p>a
root stream, from which all other streams within the store can be found</p> <p>open
and close store functions</p> <p>The persistent store base class is <xref href="GUID-21637329-EC49-39AD-8986-A22289D8CFE8.dita"><apiname>CPersistentStore</apiname></xref>.</p> <p><b>Embedded
store</b> </p> <p>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. </p> <p>The embedded store is a concrete type,
derived from <xref href="GUID-21637329-EC49-39AD-8986-A22289D8CFE8.dita"><apiname>CPersistentStore</apiname></xref>, and is provided by <xref href="GUID-F2EC3A9D-5F4B-3C98-98DC-44394C54B6DE.dita"><apiname>CEmbeddedStore</apiname></xref>.</p> <p><b>Memory
store</b> </p> <p>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.</p> <p>The memory store is a concrete type, derived
from <xref href="GUID-30726D8E-E18D-3A3A-8EFB-CCA4F04C984D.dita"><apiname>CStreamStore</apiname></xref>, and is provided by <xref href="GUID-5EC5199D-50F2-3BFA-BA45-4C5C017281DD.dita"><apiname>CBufStore</apiname></xref>.</p> <p><b>Dictionary
store base and streams</b> </p> <p>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 <filepath>.ini</filepath> files
for applications. </p> <p>The dictionary store base class is <xref href="GUID-9899DA2C-DB1B-3D67-8719-B7E13658B4D7.dita"><apiname>CDictionaryStore</apiname></xref>.
Specialised stream types, <xref href="GUID-F3322968-F922-3676-9BDD-611089C10D98.dita"><apiname>RDictionaryReadStream</apiname></xref> and <xref href="GUID-C8A4BDE0-9F00-376E-9BA3-BAC539800D17.dita"><apiname>RDictionaryWriteStream</apiname></xref>,
are provided for use with dictionary stores.</p> </section>
<section id="GUID-902CA56A-CAD2-4CB8-8640-FCB121773405"><title>See also</title> <p><xref href="GUID-21CF1D5F-44C5-5407-B3C9-8BC103C97079.dita">File
Stores Overview</xref> </p> <p><xref href="GUID-66ACFC54-5671-5B72-9DBC-A76F7A112D63.dita">Store
Streams Overview</xref> </p> <p><xref href="GUID-744ACF2C-963B-5E2F-A6B3-220AB899FD23.dita">Streaming
Overview</xref> </p> </section>
</conbody></concept>