<?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-36539894-580E-5774-AA79-7F640E8C59E1" xml:lang="en"><title>Central
Repository Initialisation Files Guide</title><shortdesc>This topic describes the concepts of initialisation files used
by the Central Repository. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-EAB04F5A-A208-4537-8EEF-6C6BE9F951ED"><title>Initialisation file properties</title> <p>The mechanisms of
key spaces, capabilities and SIDs are used to write the content of an initialisation
file. </p> <p><b>Owner </b> </p> <p>The owner of a repository (the application responsible
for backing it up) is identified by its SID. Example: </p> <codeblock id="GUID-3057056D-64F4-5A3D-9644-9B1417EFDC89" xml:space="preserve">
[owner]
0x12345
</codeblock> <p><b>Metadata </b> </p> <p>Settings of a repository are given values and also
metadata values. The Default Metadata section of a repository gives the settings
global default metadata values which may be overridden by individual metadata
values assigned in the Main section. A metadata value is held as a 32 bit
integer whose binary digits encode separate items of metadata. The most significant
eight bits (most significant byte) of the integer are reserved for internal
purposes. The other 24 bits of the integer have no reserved significance.
Two of the eight bits are exposed for use by application developers. </p> <ul>
<li id="GUID-65872DE7-F12A-5F1E-892C-937C81053E48"><p>The least significant
bit of the most significant byte is set to 1 to indicate that a backup operation
applies to the setting. </p> </li>
<li id="GUID-A13A915F-EDBC-5E69-8557-D4FC6789CE23"><p>The second least significant
bit of the most significant byte is set to 1 to indicate that a restore factory
settings operation applies to the setting. </p> </li>
</ul> <p>What is meant by least and most significant? An example may help.
A hexadecimal number such as 03020100 is stored as a single 32 bit integer.
The integer can be analysed as a sequence of four bytes: </p> <p>03 02 01
00 </p> <p>The leftmost byte, 03, is the most significant byte because it
represents a larger quantity (03000000) than the other three (02000, 0100
and 00). Each byte consists of eight bits. In binary notation they are </p> <p>00000011
00000010 00000001 00000000 </p> <p>The rightmost bit of the leftmost byte
is the least significant bit of the most significant byte because it represents
a smaller quantity (1) than its neighbour to the left (10) which is the second
least significant bit of the most significant byte. These are the two exposed
bits of the metadata value and the hexadecimal integer 03020100 has both of
them set to 1. The 32 bits are sometimes referred to by number (32 for the
leftmost down to 1 for the rightmost): thus the exposed bits are also called
bits 26 and 25. </p> <p>Global default metadata values consist simply of a
32 bit integer. Default metadata values can also be applied to a range of
settings by prefixing either a pair of keys representing a continuous range,
or else a partial key and a key mask prefixed by "mask=". Example: </p> <codeblock id="GUID-EC5F473A-86AB-58CF-878B-7AFD7EE69779" xml:space="preserve">
[defaultMeta]
0x00000010
0x100 0x400 0x00000020
0x1000 mask = 0x04 0x00000040
</codeblock> </section>
<section id="GUID-04903C24-0CEC-4937-BC94-77540BFC3F7D"><title>Access policies </title> <p>An access policy grants read or
write permissions on a setting or a group of settings to an application or
a group of applications. Applications are identified by their SID and groups
of applications by their capability name. </p> <p>Decide which applications
you want to grant permissions to, and whether you are going to identify them
by capability or SID. SIDs are unsigned integers which identify an application
and are assigned by Symbian Signed. Identify the settings and groups of settings
which are to be written and read: you will need their keys and partial keys.
Determine which applications need read or write permissions on which settings. </p> <p>You
create an access policy by combining these elements using the following syntax. </p> <ul>
<li id="GUID-A3E78BC6-7436-59E6-8C6F-B546B638BABB"><p>A capname is one of
'<codeph>TCB</codeph>' '<codeph>CommDD</codeph>' etc. A caplist is two or
three capnames separated by a comma and whitespace. A read caps statement
is "cap_rd" followed by a capname or a caplist. </p> </li>
<li id="GUID-5A76E256-BF6B-5CAD-A45C-C07140C4EEEE"><p>A read sid statement
is "<codeph>sid_rd</codeph> " followed by an SID. </p> </li>
<li id="GUID-0EE23D2A-2EED-5CEA-BF6D-7B23D11E9935"><p>A read policy is a read
sid statement or a read caps statement or one of each separated by whitespace.
A write policy is the same as a read policy with "_wr" instead of "_rd". An
access policy is a read policy or a write policy or one of each separated
by whitespace. </p> </li>
<li id="GUID-EAB2A33E-99C2-5B40-8333-232761A7BC91"><p>Instead of granting
or denying permissions to specified applications, you can create global permissions
by using the words 'AlwaysPass' or 'AlwaysFail' in place of an SID. For instance,
'sid_rd AlwaysPass' grants read permissions to all applications, 'sid_wr AlwaysFail'
denies write permissions to all applications and so on. </p> </li>
</ul> <p>An access policy constructed on these lines with no further qualification
creates permissions on all the settings in a repository (this is called a
default policy). To create permissions on individual settings (a single policy)
or a group of settings (a range policy or a mask policy depending on implementation)
we use the keys of those settings. </p> <ul>
<li id="GUID-F86D7F23-EB24-5169-B072-EED5BEC5925D"><p>A single policy is a
default policy prefixed with a key referring to a single setting. </p> </li>
<li id="GUID-0F83526E-BF07-5914-887B-E128CFC59775"><p>A range policy is a
default policy prefixed with two keys, the lowerkey and the upperkey. The
policy assigns permissions on all settings with keys between the lowerkey
and the upperkey inclusively. </p> </li>
<li id="GUID-BA19291D-8F06-5D6D-932C-8F0B8554DF51"><p>A mask policy is an
access policy prefixed with a partial key and then "mask=" and a keymask. </p> </li>
<li id="GUID-828D372D-0297-5CDF-93E7-10A63516E698"><p>A custom policy is a
single policy, a range policy or a mask policy. A policy list is a custom
policy or several custom policies separated by whitespace. </p> </li>
</ul> <p>We have now defined the structure of the access policy section of
an initialisation file. It consists of a line reading "[PlatSec]" followed
by a default policy or a policy list or one of each separated by whitespace.
Where several policies in a list apply to the same key, the later policy overrides
the earlier. The read policies, each on a separate line, must precede the
write policies, each on a separate line. </p> </section>
<section id="GUID-F2F1838D-D5A7-4720-9D10-3BEFFF64732E"><title> Initial values </title> <p>Initial values are assigned to
settings in the Main section of an initialisation file. Each line begins with
a setting identified by an individual key or a group of settings identified
by a pair of keys representing a range or else a keymask and a partial key.
Following the key or keys comes the data type of the setting, one of <codeph>int</codeph>, <codeph>real</codeph>,
string, <codeph>string8</codeph> or <codeph>binary</codeph>. Next comes the
actual initial value of the setting and finally, as an optional item, the
metadata value of the setting. Example: </p> <codeblock id="GUID-585347BA-219A-5372-8C62-77E927A5D690" xml:space="preserve">
[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> </section>
<section id="GUID-12599A2C-BE97-5B18-9BB9-EB833A40536A"><title>Initialisation
file format</title> <p>You use an initialisation file to register a repository
by saving it to device memory. Ideally you do this at ROM build time and save
to the directory <filepath>z:\private\10202BE9\</filepath> (this is the Central
Repository directory, named after its UID). It is also possible to register
a repository after build time using the Symbian Software Installer to save
it to the C drive. This process requires a signed SIS file and is explained
below. In either case, the file name of the repository is the same as its
UID. </p> <p>A repository may be saved to memory as a text file. The encoding
must be UTF-16, no other format being supported. However, you are recommended
to convert this text file to binary format and save the binary to device memory
for reasons of performance. Retrieval times are an order of magnitude faster
using binary files. You convert text to binary with the tool CentRepConv.exe
as documented in <xref href="id1236097240207" scope="external">CenRep Converter
Tool Tutorial</xref>. CentRepConv.exe can also be used to convert binary files
back to text format (in a slightly lossy way due to differences in the specification
of the two formats). </p> </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
Guide</linktext></link>
<link href="GUID-53E5C9EA-0A38-54A1-AE24-95B71BFFB4B5.dita"><linktext>CenRep Converter
Tool                 Tutorial</linktext></link>
</related-links></concept>