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