--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-36539894-580E-5774-AA79-7F640E8C59E1.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,150 @@
+<?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>
\ No newline at end of file