Central Repository Initialisation Files Guide

Initialisation file properties

The mechanisms of key spaces, capabilities and SIDs are used to write the content of an initialisation file.

Owner

The owner of a repository (the application responsible for backing it up) is identified by its SID. Example:

[owner]
0x12345

Metadata

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.

• The least significant bit of the most significant byte is set to 1 to indicate that a backup operation applies to the setting.

• 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.

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:

03 02 01 00

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

00000011 00000010 00000001 00000000

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.

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:

[defaultMeta]
0x00000010
0x100 0x400 0x00000020
0x1000 mask = 0x04 0x00000040

Access policies

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.

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.

You create an access policy by combining these elements using the following syntax.

• A capname is one of 'TCB' 'CommDD' 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.

• A read sid statement is "sid_rd " followed by an SID.

• 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.

• 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.

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.

• A single policy is a default policy prefixed with a key referring to a single setting.

• 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.

• A mask policy is an access policy prefixed with a partial key and then "mask=" and a keymask.

• 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.

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.

Initial values

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 int, real, string, string8 or binary. Next comes the actual initial value of the setting and finally, as an optional item, the metadata value of the setting. Example:

[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

Initialisation file format

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 z:\private\10202BE9\ (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.

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 CenRep Converter Tool Tutorial. 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).