<?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-CBC57511-7F28-596A-9763-5674EB41BCAC" xml:lang="en"><title>Central

Repository Overview</title><shortdesc>The Central Repository stores data such as application settings,

component settings, configuration parameters and data used for localisation

and customisation. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-04EC9C9F-C4CE-434F-ACEC-E001A68240AB"><title>Purpose</title> <p>The central repository was introduced to

avoid the use of multiple .ini files specific to each application. Typical

uses are persisting application data such as default file names, locale settings

and user preferences from one session to another: data of this kind can also

be used by device creaters to customise a device. Examples include phone book

data, bookmarks, event logging and default keyboard layout. </p> </section>

<section id="GUID-83C9CE66-A7FE-4D66-A84B-9CDF7AAE8B7E"><title>Required background</title> <p>The central repository is used

in the implementation of many libraries. Application developers using these

libraries generally do not need to access the central repository API directly.

Developers maintaining and extending such libraries need to know how to use

the API to read and modify repository data and set up change notification.

Developers creating new extensions to Symbian, such as device drivers need

to know when it is appropriate to use the central repository to persist settings.

They will also need to understand the mechanism of key spaces and initialisation

files used to implement the central repository and how to create repository

files, as explained in <xref href="GUID-36539894-580E-5774-AA79-7F640E8C59E1.dita">Central

Repository Initialisation Files Guide</xref>. Product integrators and device

creators need to know where in ROM central repository data can reside, to

know the installation mechanism and to understand the impact on data security. </p> </section>

<section id="GUID-4D55838D-2400-4766-B418-F94CFAD70E37"><title>Key concepts and terms</title> <dl>

<dlentry>

<dt>Repository</dt>

<dd><p>A data structure holding data to be persisted for a component or application,

equivalent to a file. Also called a keyspace. </p> </dd>

</dlentry>

<dlentry>

<dt>Setting</dt>

<dd><p>An item of data in a repository, equivalent to a line in a file. Also

called a key. </p> </dd>

</dlentry>

<dlentry>

<dt>Initialisation file</dt>

<dd><p>The text file from which a repository is created. </p> </dd>

</dlentry>

<dlentry>

<dt>Keyspaces</dt>

<dd><p>Another term for a repository. </p> </dd>

</dlentry>

<dlentry>

<dt> Access policies</dt>

<dd><p>Read or write permissions on a setting or group of settings. </p> </dd>

</dlentry>

</dl> </section>

<section id="GUID-4088D4CB-21C6-4C45-B86D-CDFC7DE3D924"><title>Architecture</title> <p>Many applications and modules come

with a data structure called a repository or keyspace which is used to persist

application data. The Central Repository is the component which stores and

manages repositories. Repositories are created and initialised individually

along with their associated application on installation, or as a group when

a device is built by device creators. The purpose of the Central Repository

API is to enable application developers and device creators to modify repository

data and to provide notification of changes to a repository. </p> <p>Conceptually,

the Central Repository is comparable to a folder, an individual repository

to a file and a setting to a line in a file. In fact repositories are implemented

as binary files held at various locations in memory and are accessed through

C++ classes which encapsulate them with a single API. Repositories are created

with the applications to which they refer at device build time or at installation

by the Application Installer on runtime. The Central Repository API is only

used to access repositories, not to create them. </p> </section>

<section id="GUID-94EC00B4-9190-4A56-BCC2-CB109A17FD35"><title>APIs</title> <p>The Central Repository API provides the <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>CRepository</apiname></xref> class

to provide access to repositories. </p> <table id="GUID-2241998F-DE1E-5098-8639-93FFA58834B5">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>API</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>CRepository</apiname></xref>  </p> </entry>

<entry><p>Provides the functionality to access the repository created with

an application. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-127F54F2-99E7-3FAB-9669-90B0B1985285.dita"><apiname>CCenRepNotifyHandler</apiname></xref>  </p> </entry>

<entry><p>Creates notification of changes to a repository. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-7BB13E80-C3B8-3E4F-B3ED-120258011558.dita"><apiname>MCenRepNotifyHandlerCallback</apiname></xref>  </p> </entry>

<entry><p>A callback interface to be implemented to respond to change notification. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section id="GUID-D9B11AA3-1E03-4D70-9569-C696E7FC5D3D"><title>Typical uses</title> <p>The Central Repository is typically

used by applications such as messaging services to retrieve logins, localisation

data and information needed for interprocess communication. </p> </section>

</conbody><related-links>

<link href="GUID-1C683226-C142-5C7B-BD20-060058352B08.dita"><linktext>Central Repository

Guide</linktext></link>

<link href="GUID-E3BE62B2-9625-5F79-84A4-0248A3F36225.dita"><linktext>Central Repository

Access Guide</linktext></link>

</related-links></concept>