<?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>