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