<?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 xml:lang="en" id="GUID-5EAED550-5FFC-54A6-BB4A-720975B127B8"><title>Stores Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>Provides structured data storage, using networks of streams.</p> </section> <section><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><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><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>