Central -Repository Initialisation Files Guide

Central -Repository Initialisation Files GuideThis topic describes the concepts of initialisation files used -by the Central Repository. -

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

-Central Repository - Overview -Central Repository -Guide -CenRep Converter -Tool Tutorial + + + + + +Central Repository Initialisation Files GuideThis topic describes the concepts of initialisation files +used by the Central Repository. +

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

+Central +Repository Overview +Central +Repository Guide +CenRep +Converter Tool Tutorial

\ No newline at end of file