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

    12 <concept id="GUID-5EAED550-5FFC-54A6-BB4A-720975B127B8" xml:lang="en"><title>Stores

    13 Overview</title><shortdesc>Provides structured data storage, using networks of streams.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-A750DA94-F7BD-49F2-AB3C-4B75665C211D"><title>Architectural relationships</title> <p>A stream is a representation

    15 of a data structure (such as an object) as a sequence of bytes. Structures

    16 as complex as most applications require multiple streams to store their state.

    17 This is termed a store. Stream types that work with stores are provided by

    18 the Store Streams API. </p> <p>The Stores API defines both base classes that

    19 define store abstractions without specifying the storage medium, and some

    20 concrete store types. The File Stores API defines further concrete stores,

    21 which use file storage. </p> <p>Concrete store types do not have to provides

    22 all the stream manipulation functionality defined by the base class interfaces:

    23 for example, direct file stores do not support individual deletion of streams

    24 within a store. </p> <p>Stores are integrated with the application architecture

    25 as defined in the Uikon Core API. That expects file-based and embeddable applications

    26 to handle their data storage through stores. </p> </section>

    27 <section id="GUID-5806D6A8-2256-4741-8691-AB75DF877598"><title>Description</title> <p>The API has five key concepts: stream

    28 store base, persistent store base, embedded store, memory store, and dictionary

    29 store base and streams.</p> <p><b>Stream store base</b> </p> <p>This defines

    30 an interface for streams to be added and deleted to a store, a commit/revert

    31 mechanism, and space compaction and reclamation. Stores return a stream ID

    32 when a stream is created. A particular stream can be opened by specifying

    33 its ID. </p> <p>Some objects can save and restore their state to and from

    34 a store. It is conventional to implement functions named <codeph>StoreL()</codeph> and <codeph>RestoreL()</codeph> for

    35 these purposes. The most important case of this is the application document

    36 class (<codeph>CEikDocument</codeph>), which can be implemented to store and

    37 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

    38 store base</b> </p> <p>Most store types require that the store persists beyond

    39 the lifetime of the application that created it. The persistent store base

    40 extends the stream store base to provide this. In particular it provides:</p> <p>a

    41 root stream, from which all other streams within the store can be found</p> <p>open

    42 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

    43 store</b> </p> <p>An embedded store can itself be stored as a stream in another

    44 store. They are used to embed application documents in other application documents.

    45 Once written, streams in the store cannot be modified: the store must be deleted

    46 and rewritten in its entirety. </p> <p>The embedded store is a concrete type,

    47 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

    48 store</b> </p> <p>A memory store resides in memory and exists only for the

    49 life of the store object. They can be used for transient complex dynamic structures

    50 such as undo buffers.</p> <p>The memory store is a concrete type, derived

    51 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

    52 store base and streams</b> </p> <p>A dictionary store contains a sequence

    53 of streams, each of which is accessed using a UID, rather than a simple stream

    54 ID. Dictionary stores are used by the application architecture to handle <filepath>.ini</filepath> files

    55 for applications. </p> <p>The dictionary store base class is <xref href="GUID-9899DA2C-DB1B-3D67-8719-B7E13658B4D7.dita"><apiname>CDictionaryStore</apiname></xref>.

    56 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>,

    57 are provided for use with dictionary stores.</p> </section>

    58 <section id="GUID-902CA56A-CAD2-4CB8-8640-FCB121773405"><title>See also</title> <p><xref href="GUID-21CF1D5F-44C5-5407-B3C9-8BC103C97079.dita">File

    59 Stores Overview</xref> </p> <p><xref href="GUID-66ACFC54-5671-5B72-9DBC-A76F7A112D63.dita">Store

    60 Streams Overview</xref> </p> <p><xref href="GUID-744ACF2C-963B-5E2F-A6B3-220AB899FD23.dita">Streaming

    61 Overview</xref> </p> </section>

    62 </conbody></concept>