<?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="GUID-53E5C9EA-0A38-54A1-AE24-95B71BFFB4B5.dita">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>