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