<?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-1C683226-C142-5C7B-BD20-060058352B08" xml:lang="en"><title>Central

Repository Guide</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This topic describes key concepts of the Central Repository. </p>

<section id="GUID-F493C646-CD65-491D-9114-743C09AC8976"><title>Purpose </title> <p>The Central Repository is a collection

of data structures which retains the setup of an application or component

from one session to another. It is a fast, flexible mechanism for the persistence

of data and, being global, is preferable to the use of separate .ini files

for each application. It is typically used by applications such as messaging

services to retrieve logins, localisation data and information needed for

interprocess communication. </p> </section>

<section id="GUID-69A757C6-B9D1-475F-9DC0-B4CC65FEEDC4"><title> Architecture </title> <p>An individual data structure referring

to a particular application or component is termed a repository. An item of

information in a repository is termed a setting. 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. For some purposes developers can

safely think in terms of the folder/file/lines model, but for other purposes

an understanding of implementation is necessary. </p> </section>

<section id="GUID-491C4DA0-D143-4A80-BBEC-B248FE53AD49"><title> Usage: how not to use the Central Repository </title> <p>An

important feature of the Central Repository is best illustrated by a brief

guide to how not to use it. </p> <p>In your application code, create a C++

CCentralRepository object. At runtime, call its read function to retrieve

the settings of your application. You will find that the object has nothing

to read from because the repository it encapsulates has not previously been

created. Try calling the create repository function of the CCentralRepository

object. You will find that it has not got one. </p> <p>Go back to square one.

Create the repository from an initialisation file and convert it to binary

format, as explained in this guide. Now call the read function of the CCentralRepository

object. You will find that you cannot read or write to the repository: this

is because you didn't previously create an access policy for the repository. </p> <p>Go

back to square one. Define an access policy, as explained in this guide. Rewrite

the initialisation file and proceed as before. This time you may find that

the data you are trying to read has been lost because you didn't previously

provide for it to be backed up. </p> <p>Go back to square one. Define a backup

mechanism - No! Better still, throw this useless documentation out of the

window. And if it bounces back at you, that is because you didn't previously

open the window. </p> <p>The point is that use of the Central Repository to

persist application settings involves work at the design stage of the application.

You cannot first create the application and procede to interface to the Central

Repository as an afterthought. When an existing application with a different

persistence mechanism is migrated to the Central Repository, substantial rewriting

of the application code may be necessary. </p> </section>

<section id="GUID-CCEA88F5-54FB-47B9-A33F-391A4BBA3A51"><title>Structure of the Central Repository</title> <p>In the simplest

case, a repository holds an unordered list of items and the same application

reads, writes and backs up the data. However, a use case as simple as that

would be unusual. More often, the data has an internal structure which must

also be persisted. For instance, it might reflect the contents of a number

of C++ classes, of a number of data tables or of a number of arrays of different

data types. It is also common for data to be written to a repository by one

application and retrieved by another (this requires a mechanism for notification

of changes). Backup might be the responsibility of a different application

or component entirely. </p> </section>

<section id="GUID-3EFBD23C-2B88-47AE-B764-85EB42713E4D"><title>Structure of the initialisation file</title> <p>Repositories

are created from a text file called an initialisation file: the following

is an example of one. The structure of an initialisation file is the key to

understanding the functionality of the Central Repository. </p> <codeblock id="GUID-61573358-F16F-5C98-96A0-20D04FE5F7FD" xml:space="preserve"># 00000001.txt

# Test config file for central repository

cenrep

version 1

[owner]

0x12345

[defaultMeta]

0x00000010

0x100 0x400 0x00000020

0x1000 mask = 0x04 0x00000040

[platsec]

# default capabilities for this repository

cap_rd=ReadDeviceData cap_wr = WriteDeviceData

[main]

1 int 1 0

2 real 2.732 0xa

5 string "test\\\"string\"" 2

6 int 12 0xf

8 real 1.5 1

11 string string 0x305

12 string8 string 0x305

0x11 real 1.5 12

0x101 int 100 0

</codeblock> <p>The lines beginning with # are comments. The actual data consists

of five sections in this order: header, owner, default metadata, platform

security and main. </p> <p><b>The header </b> </p> <p>The header consists of the lines </p> <codeblock id="GUID-AD034D33-C9E5-5BCF-ABDD-D7C5E4325F69" xml:space="preserve">cenrep

version 1

</codeblock> <p>This is obligatory and the same for every repository. Cenrep

means Central Repository and version 1 refers to the file format: only version

1 exists. </p> <p><b>Owner </b> </p> <p>This section specifies a particular application as

the owner of the repository. It is the owning application which backs a repository

up. This section is optional: it is not obligatory to specify an owner. </p> <p><b>Default metadata </b> </p> <p>The default metadata section is optional.

It supplements the metadata specified in the main section and uses the key

space mechanism also used in the main section. </p> <p><b>Platform security </b> </p> <p>This section is theoretically optional.

However, if you omit it the application being persisted will have neither

read nor write permissions on the repository. The section assigns permissions

to particular applications and components or groups of them. The content of

the platform security section is called a security policy and its structure

is explained below. </p> <p><b>Main </b> </p> <p>This section is mandatory and it holds the initial data

to be written to the repository when it is created. The lines consist of attribute

value pairs and related data in a format which is partly laid down in the

Central Repository specification and partly user-defined. An understanding

of this format is required to use the library functions which read and modify

the repository once it is created. Each line of the section refers to a setting

or group of settings to be persisted and consists of four fields, for instance </p> <codeblock id="GUID-EE86ABAB-7FF5-5A09-9775-846B4CFFFF13" xml:space="preserve">0x11 real 1.5 12</codeblock> <p>called

key, type, value and metadata. </p> <p>The key field (0x11) represents an

attribute name. The type field (real) is the data type of its value: this

must be one of int, real, string, string8 or binary. The value field (1.5)

is the actual value. The metadata field (12) is a supplementary value, the

metadata value. </p> <p>The key field is the one which is difficult to understand.

It represents an attribute name such as 'password' or 'country code' which

has been converted into a numerical value using a translation scheme called

a key space. (The virtue of numerical values is that they improve retrieval

times.) The key space is specific to an application and is defined when the

application is being designed. </p> <p><b>Use of decimal and hexadecimal numbers </b> </p> <p>Numbers used to identify

settings and values in initialisation files may be written either in decimal

or hexadecimal notation (hexadecimal numbers take the prefix "0x"). Both notations

will be encountered in the examples given here. Use of decimal or hexadecimal

notation is purely a matter of convenience: hexadecimal notation is often

used for keys in order to reflect their internal structure. </p> </section>

<section id="GUID-01177FE1-7AED-54FD-B0C1-F29A6389F93A"><title>Key spaces</title> <p>The

Central Repository API accesses data items in a repository by their keys.

In source code, the data items which correspond to settings have meaningful

names such as pluginName and userID: the purpose of a key space is to translate

names into numerical keys for speed of retrieval. As part of the design process

of your application you identify the settings to be persisted and also identify

their dependencies. Then you construct a key space to represent them. A key

consists of 32 binary digits (bits): a key space imposes a structure on the

digits. You might use the 32 bits to represent pairs of 16 bit integers, or

reserve eight of them as binary flags and use the rest to represent 24 bit

integers, or define four key spaces using only 30 bits and use the other two

bits to indicate which of those four key spaces the key belongs to. </p> <p>Why

would you want to do this? The simplest use for 32 bits is to represent an

integer between 0 and 2<sup>32</sup>. If the data to be persisted consists

of a simple list, this is the right thing to do. For instance you might have

a list of telephone numbers representing missed calls and simply want to store

and retrieve them. In such a case, all you need to do is label the data items

with an integer: missed call 0, missed call 1, missed call 2 and so on up

to missed call 2<sup>32</sup> if necessary. This is also the appropriate strategy

if you are persisting a list of fixed size and various data types, for instance

an enumeration of userName, userID, password and the like. Data sets of this

kind would be stored in a data table as either a single column or a single

row. </p> <p>More commonly, the data to be persisted is comparable to the

contents of a data table with many columns and many rows. In C++ data sets

of this kind are often held as arrays of class objects. A register of missed

calls would probably not just list telephone numbers but also data such as

the time of the call and the name of the caller: a definite number of data

items information (table columns, class members) relating to an indefinite

number of missed calls (table rows, array items). To encode this information

in a key space we need to reserve part of the key to represent the column

names as 0, 1, 2... Suppose that there are 16 columns (2<sup>4</sup>). Four

bits of the key are required to represent the column names leaving another

28 to represent row numbers (missed call 0, missed call 1 etc as before).

This keyspace can conveniently be written as eight hexadecimal numbers, one

representing the column names and the rest representing the row numbers. </p> <p>A

further level of complexity arises when the data to be persisted is comparable

to the contents of several data tables. To extend our example of the missed

telephone calls, we might also want to persist data concerning calls actually

received. A record representing received calls would be different from one

representing a missed call: we should want to know the length of the call

and information such as the tariff, the network used and so on. In such a

case you need to represent three separate items of data: the table name, the

column name and the row number. If there are four tables, you need two bits

of the key to represent the table names, leaving 30 bits to represent the

rows and columns. It is important to know that you do not have to allocate

the 30 bits identically for each of the four tables. One of them might have

many columns, say 256, requiring eight bits to hold the column names and 22

to hold the row numbers. The others might only have 16 columns, requiring

four bits to hold the column names and 26 to hold the row numbers. </p> <p>For

the sake of simplicity the examples just given involve numbers which are exact

powers of two. In practice this will not usually be so, and a certain amount

of rounding up will be needed. </p> <p>You sometimes want to refer to a group

of settings without specifying each individual key. There are two ways of

doing this. One is to specify a range of contiguous keys by simply naming

the first and last key in the range: for instance the pair 0x00000011 0x0000001F

identifies a range of sixteen keys from 0x11 to 0x1F (17 to 31) inclusive.

The other way is to use a pattern matching mechanism to specify sets of keys

which are not necessarily contiguous. </p> <p>Suppose you have a key representing

two 16 bit integers encoding columns and rows of a data table, and you want

to set or retrieve all the row values for a particular column. In hexadecimal

notation the keys you want look like this. </p> <codeblock id="GUID-338B5AA2-0F87-51C7-B6BA-CDEA7CA2E71C" xml:space="preserve">

0x00080001

0x00080002

0x00080003

</codeblock> <p>In this example, you want the first four hexadecimal digits

of the key to match a pattern which you specify and the last four to match

any values. To do this you construct two hexadecimal numbers: a key mask and

a partial key. The key mask is a sequence of Fs and 0s in which the Fs mark

the mandatory fields and the 0s mark the non-mandatory ones: </p> <codeblock id="GUID-136AB57E-7F53-5076-930D-94FC01046A44" xml:space="preserve">0xFFFF0000</codeblock> <p>The

partial key is the pattern to be matched: where no values are to be matched

you write 0 instead: </p> <codeblock id="GUID-A258EB7B-686D-5BB4-BE72-AC0E0A2A21DE" xml:space="preserve">0x00080000</codeblock> <p>These

two numbers, key mask and partial key, taken together specify a list of all

the repository keys whose first four hexadecimal digits are 0008. Key mask

and partial key pairs are passed as parameters to API functions and are used

in the initialisation file to identify groups of keys. </p> </section>

<section id="GUID-07777876-8E76-57BD-8858-55EF3AD7641E"><title>Identifying

applications</title> <p>You need to specify which applications may access

your repository. Applications may be identified by individual secure IDs (SIDs)

or as groups by capabilities. The SID is the unique identifier of an application

which is given to it by Symbian Signed. Capabilities are categories to which

the Symbian platform assigns applications and components for purposes of security

classification. Each capability has a mnemonic, and is also defined by an

individual enum value of the <xref href="GUID-604DA570-08AC-300D-A7CE-1DA984556B10.dita"><apiname>TCapability</apiname></xref> enum. Follow the

link to the individual <xref href="GUID-604DA570-08AC-300D-A7CE-1DA984556B10.dita"><apiname>TCapability</apiname></xref> enum value: </p> <table id="GUID-4A0AD7D5-7016-51AE-B5EE-FA05BD9BA4BE">

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

<tbody>

<row>

<entry><p> <b>Capability mnemonic</b>  </p> </entry>

<entry><p> <b>TCapability Enum value</b>  </p> </entry>

</row>

<row>

<entry><p>TCB (trusted computing base) </p> </entry>

<entry><p> <xref href="GUID-0C19208D-732F-3B2B-9B0F-81CB1CB56DFC.dita"><apiname>ECapabilityTCB</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>CommDD (communications device drivers) </p> </entry>

<entry><p> <xref href="GUID-2714B609-120A-31C1-9415-235A2FEB9D9A.dita"><apiname>ECapabilityCommDD</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>PowerMgmt (power management) </p> </entry>

<entry><p> <xref href="GUID-76F4383B-4EA5-391A-A271-A8F65ED77EC0.dita"><apiname>ECapabilityPowerMgmt</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>MultimediaDD (multimedia device drivers) </p> </entry>

<entry><p> <xref href="GUID-48AA1686-C619-3C36-B4B5-6C5DE1F50B0A.dita"><apiname>ECapabilityMultimediaDD</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>ReadDeviceData </p> </entry>

<entry><p> <xref href="GUID-1AC4E327-14CE-382D-AA1A-1A7EDBA1863E.dita"><apiname>ECapabilityReadDeviceData</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>WriteDeviceData </p> </entry>

<entry><p> <xref href="GUID-C607209F-6FC5-31DE-8034-E5B799B857A8.dita"><apiname>ECapabilityWriteDeviceData</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>DRM (digital rights management) </p> </entry>

<entry><p> <xref href="GUID-C0EF5A59-F716-313A-911F-2D3D773DF597.dita"><apiname>ECapabilityDRM</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>TrustedUI </p> </entry>

<entry><p> <xref href="GUID-AFB7AB40-B829-37B8-AAB1-7A6FAED9671B.dita"><apiname>ECapabilityTrustedUI</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>ProtServ (server registered with a protected name </p> </entry>

<entry><p> <xref href="GUID-200CA018-2CB3-3E4A-A505-085FAD2E3E8B.dita"><apiname>ECapabilityProtServ</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>DiskAdmin </p> </entry>

<entry><p> <xref href="GUID-99D8A4E8-BC4F-39FF-A3DF-832CF0411629.dita"><apiname>ECapabilityDiskAdmin</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>NetworkControl </p> </entry>

<entry><p> <xref href="GUID-4AFB561B-34D7-3570-A4C9-24B4952C787A.dita"><apiname>ECapabilityNetworkControl</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>AllFiles </p> </entry>

<entry><p> <xref href="GUID-89631CF3-4AEE-3C2F-8AAE-5D9C3EB3B373.dita"><apiname>ECapabilityAllFiles</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>SwEvent (software key and pen events) </p> </entry>

<entry><p> <xref href="GUID-369B6584-AB7F-3AA2-B912-E912D2BCBE98.dita"><apiname>ECapabilitySwEvent</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>NetworkServices </p> </entry>

<entry><p> <xref href="GUID-07A09CBA-CB4E-3CBE-9FA3-930C455F3B0C.dita"><apiname>ECapabilityNetworkServices</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>LocalServices </p> </entry>

<entry><p> <xref href="GUID-7D0E447B-EC32-355B-8BBF-F074A1B10D8A.dita"><apiname>ECapabilityLocalServices</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>ReadUserData </p> </entry>

<entry><p> <xref href="GUID-4897D21D-5ACF-30A5-A38C-371A3983814D.dita"><apiname>ECapabilityReadUserData</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>WriteUserData </p> </entry>

<entry><p> <xref href="GUID-8908E5F7-AC6A-333B-8F65-6DDC46798F48.dita"><apiname>ECapabilityWriteUserData</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>Location (physical location, not locale) </p> </entry>

<entry><p> <xref href="GUID-1B530864-C77B-3CDE-B761-83C2EED44DB8.dita"><apiname>ECapabilityLocation</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>SurroundingsDD </p> </entry>

<entry><p> <xref href="GUID-8A207675-B0CF-314E-A4AD-12D839A01A4B.dita"><apiname>ECapabilitySurroundingsDD</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p>UserEnvironment </p> </entry>

<entry><p> <xref href="GUID-05F13261-5EDF-319A-93D6-0247F8C468A3.dita"><apiname>ECapabilityUserEnvironment</apiname></xref>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

</conbody><related-links>

<link href="GUID-CBC57511-7F28-596A-9763-5674EB41BCAC.dita"><linktext>Central Repository

Overview</linktext></link>

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

Access Guide</linktext></link>

<link href="GUID-C86A7929-DC0F-50FA-93CB-662A22C4CD35.dita"><linktext>Device Variant

Using Multiple Keyspace                 Files</linktext></link>

</related-links></concept>