--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-1C683226-C142-5C7B-BD20-060058352B08.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,316 @@
+<?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-1C683226-C142-5C7B-BD20-060058352B08" xml:lang="en"><title>Central
+Repository Guide</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>This topic describes key concepts of the Central Repository. </p>
+<section id="GUID-F493C646-CD65-491D-9114-743C09AC8976"><title>Purpose </title> <p>The Central Repository is a collection
+of data structures which retains the setup of an application or component
+from one session to another. It is a fast, flexible mechanism for the persistence
+of data and, being global, is preferable to the use of separate .ini files
+for each application. It is typically used by applications such as messaging
+services to retrieve logins, localisation data and information needed for
+interprocess communication. </p> </section>
+<section id="GUID-69A757C6-B9D1-475F-9DC0-B4CC65FEEDC4"><title> Architecture </title> <p>An individual data structure referring
+to a particular application or component is termed a repository. An item of
+information in a repository is termed a setting. Conceptually, the Central
+Repository is comparable to a folder, an individual repository to a file and
+a setting to a line in a file. In fact repositories are implemented as binary
+files held at various locations in memory and are accessed through C++ classes
+which encapsulate them with a single API. For some purposes developers can
+safely think in terms of the folder/file/lines model, but for other purposes
+an understanding of implementation is necessary. </p> </section>
+<section id="GUID-491C4DA0-D143-4A80-BBEC-B248FE53AD49"><title> Usage: how not to use the Central Repository </title> <p>An
+important feature of the Central Repository is best illustrated by a brief
+guide to how not to use it. </p> <p>In your application code, create a C++
+CCentralRepository object. At runtime, call its read function to retrieve
+the settings of your application. You will find that the object has nothing
+to read from because the repository it encapsulates has not previously been
+created. Try calling the create repository function of the CCentralRepository
+object. You will find that it has not got one. </p> <p>Go back to square one.
+Create the repository from an initialisation file and convert it to binary
+format, as explained in this guide. Now call the read function of the CCentralRepository
+object. You will find that you cannot read or write to the repository: this
+is because you didn't previously create an access policy for the repository. </p> <p>Go
+back to square one. Define an access policy, as explained in this guide. Rewrite
+the initialisation file and proceed as before. This time you may find that
+the data you are trying to read has been lost because you didn't previously
+provide for it to be backed up. </p> <p>Go back to square one. Define a backup
+mechanism - No! Better still, throw this useless documentation out of the
+window. And if it bounces back at you, that is because you didn't previously
+open the window. </p> <p>The point is that use of the Central Repository to
+persist application settings involves work at the design stage of the application.
+You cannot first create the application and procede to interface to the Central
+Repository as an afterthought. When an existing application with a different
+persistence mechanism is migrated to the Central Repository, substantial rewriting
+of the application code may be necessary. </p> </section>
+<section id="GUID-CCEA88F5-54FB-47B9-A33F-391A4BBA3A51"><title>Structure of the Central Repository</title> <p>In the simplest
+case, a repository holds an unordered list of items and the same application
+reads, writes and backs up the data. However, a use case as simple as that
+would be unusual. More often, the data has an internal structure which must
+also be persisted. For instance, it might reflect the contents of a number
+of C++ classes, of a number of data tables or of a number of arrays of different
+data types. It is also common for data to be written to a repository by one
+application and retrieved by another (this requires a mechanism for notification
+of changes). Backup might be the responsibility of a different application
+or component entirely. </p> </section>
+<section id="GUID-3EFBD23C-2B88-47AE-B764-85EB42713E4D"><title>Structure of the initialisation file</title> <p>Repositories
+are created from a text file called an initialisation file: the following
+is an example of one. The structure of an initialisation file is the key to
+understanding the functionality of the Central Repository. </p> <codeblock id="GUID-61573358-F16F-5C98-96A0-20D04FE5F7FD" xml:space="preserve"># 00000001.txt
+# Test config file for central repository
+
+cenrep
+version 1
+
+[owner]
+0x12345
+
+[defaultMeta]
+0x00000010
+0x100 0x400 0x00000020
+0x1000 mask = 0x04 0x00000040
+
+[platsec]
+# default capabilities for this repository
+cap_rd=ReadDeviceData cap_wr = WriteDeviceData
+
+[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> <p>The lines beginning with # are comments. The actual data consists
+of five sections in this order: header, owner, default metadata, platform
+security and main. </p> <p><b>The header </b> </p> <p>The header consists of the lines </p> <codeblock id="GUID-AD034D33-C9E5-5BCF-ABDD-D7C5E4325F69" xml:space="preserve">cenrep
+version 1
+</codeblock> <p>This is obligatory and the same for every repository. Cenrep
+means Central Repository and version 1 refers to the file format: only version
+1 exists. </p> <p><b>Owner </b> </p> <p>This section specifies a particular application as
+the owner of the repository. It is the owning application which backs a repository
+up. This section is optional: it is not obligatory to specify an owner. </p> <p><b>Default metadata </b> </p> <p>The default metadata section is optional.
+It supplements the metadata specified in the main section and uses the key
+space mechanism also used in the main section. </p> <p><b>Platform security </b> </p> <p>This section is theoretically optional.
+However, if you omit it the application being persisted will have neither
+read nor write permissions on the repository. The section assigns permissions
+to particular applications and components or groups of them. The content of
+the platform security section is called a security policy and its structure
+is explained below. </p> <p><b>Main </b> </p> <p>This section is mandatory and it holds the initial data
+to be written to the repository when it is created. The lines consist of attribute
+value pairs and related data in a format which is partly laid down in the
+Central Repository specification and partly user-defined. An understanding
+of this format is required to use the library functions which read and modify
+the repository once it is created. Each line of the section refers to a setting
+or group of settings to be persisted and consists of four fields, for instance </p> <codeblock id="GUID-EE86ABAB-7FF5-5A09-9775-846B4CFFFF13" xml:space="preserve">0x11 real 1.5 12</codeblock> <p>called
+key, type, value and metadata. </p> <p>The key field (0x11) represents an
+attribute name. The type field (real) is the data type of its value: this
+must be one of int, real, string, string8 or binary. The value field (1.5)
+is the actual value. The metadata field (12) is a supplementary value, the
+metadata value. </p> <p>The key field is the one which is difficult to understand.
+It represents an attribute name such as 'password' or 'country code' which
+has been converted into a numerical value using a translation scheme called
+a key space. (The virtue of numerical values is that they improve retrieval
+times.) The key space is specific to an application and is defined when the
+application is being designed. </p> <p><b>Use of decimal and hexadecimal numbers </b> </p> <p>Numbers used to identify
+settings and values in initialisation files may be written either in decimal
+or hexadecimal notation (hexadecimal numbers take the prefix "0x"). Both notations
+will be encountered in the examples given here. Use of decimal or hexadecimal
+notation is purely a matter of convenience: hexadecimal notation is often
+used for keys in order to reflect their internal structure. </p> </section>
+<section id="GUID-01177FE1-7AED-54FD-B0C1-F29A6389F93A"><title>Key spaces</title> <p>The
+Central Repository API accesses data items in a repository by their keys.
+In source code, the data items which correspond to settings have meaningful
+names such as pluginName and userID: the purpose of a key space is to translate
+names into numerical keys for speed of retrieval. As part of the design process
+of your application you identify the settings to be persisted and also identify
+their dependencies. Then you construct a key space to represent them. A key
+consists of 32 binary digits (bits): a key space imposes a structure on the
+digits. You might use the 32 bits to represent pairs of 16 bit integers, or
+reserve eight of them as binary flags and use the rest to represent 24 bit
+integers, or define four key spaces using only 30 bits and use the other two
+bits to indicate which of those four key spaces the key belongs to. </p> <p>Why
+would you want to do this? The simplest use for 32 bits is to represent an
+integer between 0 and 2<sup>32</sup>. If the data to be persisted consists
+of a simple list, this is the right thing to do. For instance you might have
+a list of telephone numbers representing missed calls and simply want to store
+and retrieve them. In such a case, all you need to do is label the data items
+with an integer: missed call 0, missed call 1, missed call 2 and so on up
+to missed call 2<sup>32</sup> if necessary. This is also the appropriate strategy
+if you are persisting a list of fixed size and various data types, for instance
+an enumeration of userName, userID, password and the like. Data sets of this
+kind would be stored in a data table as either a single column or a single
+row. </p> <p>More commonly, the data to be persisted is comparable to the
+contents of a data table with many columns and many rows. In C++ data sets
+of this kind are often held as arrays of class objects. A register of missed
+calls would probably not just list telephone numbers but also data such as
+the time of the call and the name of the caller: a definite number of data
+items information (table columns, class members) relating to an indefinite
+number of missed calls (table rows, array items). To encode this information
+in a key space we need to reserve part of the key to represent the column
+names as 0, 1, 2... Suppose that there are 16 columns (2<sup>4</sup>). Four
+bits of the key are required to represent the column names leaving another
+28 to represent row numbers (missed call 0, missed call 1 etc as before).
+This keyspace can conveniently be written as eight hexadecimal numbers, one
+representing the column names and the rest representing the row numbers. </p> <p>A
+further level of complexity arises when the data to be persisted is comparable
+to the contents of several data tables. To extend our example of the missed
+telephone calls, we might also want to persist data concerning calls actually
+received. A record representing received calls would be different from one
+representing a missed call: we should want to know the length of the call
+and information such as the tariff, the network used and so on. In such a
+case you need to represent three separate items of data: the table name, the
+column name and the row number. If there are four tables, you need two bits
+of the key to represent the table names, leaving 30 bits to represent the
+rows and columns. It is important to know that you do not have to allocate
+the 30 bits identically for each of the four tables. One of them might have
+many columns, say 256, requiring eight bits to hold the column names and 22
+to hold the row numbers. The others might only have 16 columns, requiring
+four bits to hold the column names and 26 to hold the row numbers. </p> <p>For
+the sake of simplicity the examples just given involve numbers which are exact
+powers of two. In practice this will not usually be so, and a certain amount
+of rounding up will be needed. </p> <p>You sometimes want to refer to a group
+of settings without specifying each individual key. There are two ways of
+doing this. One is to specify a range of contiguous keys by simply naming
+the first and last key in the range: for instance the pair 0x00000011 0x0000001F
+identifies a range of sixteen keys from 0x11 to 0x1F (17 to 31) inclusive.
+The other way is to use a pattern matching mechanism to specify sets of keys
+which are not necessarily contiguous. </p> <p>Suppose you have a key representing
+two 16 bit integers encoding columns and rows of a data table, and you want
+to set or retrieve all the row values for a particular column. In hexadecimal
+notation the keys you want look like this. </p> <codeblock id="GUID-338B5AA2-0F87-51C7-B6BA-CDEA7CA2E71C" xml:space="preserve">
+0x00080001
+0x00080002
+0x00080003
+</codeblock> <p>In this example, you want the first four hexadecimal digits
+of the key to match a pattern which you specify and the last four to match
+any values. To do this you construct two hexadecimal numbers: a key mask and
+a partial key. The key mask is a sequence of Fs and 0s in which the Fs mark
+the mandatory fields and the 0s mark the non-mandatory ones: </p> <codeblock id="GUID-136AB57E-7F53-5076-930D-94FC01046A44" xml:space="preserve">0xFFFF0000</codeblock> <p>The
+partial key is the pattern to be matched: where no values are to be matched
+you write 0 instead: </p> <codeblock id="GUID-A258EB7B-686D-5BB4-BE72-AC0E0A2A21DE" xml:space="preserve">0x00080000</codeblock> <p>These
+two numbers, key mask and partial key, taken together specify a list of all
+the repository keys whose first four hexadecimal digits are 0008. Key mask
+and partial key pairs are passed as parameters to API functions and are used
+in the initialisation file to identify groups of keys. </p> </section>
+<section id="GUID-07777876-8E76-57BD-8858-55EF3AD7641E"><title>Identifying
+applications</title> <p>You need to specify which applications may access
+your repository. Applications may be identified by individual secure IDs (SIDs)
+or as groups by capabilities. The SID is the unique identifier of an application
+which is given to it by Symbian Signed. Capabilities are categories to which
+the Symbian platform assigns applications and components for purposes of security
+classification. Each capability has a mnemonic, and is also defined by an
+individual enum value of the <xref href="GUID-604DA570-08AC-300D-A7CE-1DA984556B10.dita"><apiname>TCapability</apiname></xref> enum. Follow the
+link to the individual <xref href="GUID-604DA570-08AC-300D-A7CE-1DA984556B10.dita"><apiname>TCapability</apiname></xref> enum value: </p> <table id="GUID-4A0AD7D5-7016-51AE-B5EE-FA05BD9BA4BE">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p> <b>Capability mnemonic</b>  </p> </entry>
+<entry><p> <b>TCapability Enum value</b>  </p> </entry>
+</row>
+<row>
+<entry><p>TCB (trusted computing base) </p> </entry>
+<entry><p> <xref href="GUID-0C19208D-732F-3B2B-9B0F-81CB1CB56DFC.dita"><apiname>ECapabilityTCB</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>CommDD (communications device drivers) </p> </entry>
+<entry><p> <xref href="GUID-2714B609-120A-31C1-9415-235A2FEB9D9A.dita"><apiname>ECapabilityCommDD</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>PowerMgmt (power management) </p> </entry>
+<entry><p> <xref href="GUID-76F4383B-4EA5-391A-A271-A8F65ED77EC0.dita"><apiname>ECapabilityPowerMgmt</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>MultimediaDD (multimedia device drivers) </p> </entry>
+<entry><p> <xref href="GUID-48AA1686-C619-3C36-B4B5-6C5DE1F50B0A.dita"><apiname>ECapabilityMultimediaDD</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>ReadDeviceData </p> </entry>
+<entry><p> <xref href="GUID-1AC4E327-14CE-382D-AA1A-1A7EDBA1863E.dita"><apiname>ECapabilityReadDeviceData</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>WriteDeviceData </p> </entry>
+<entry><p> <xref href="GUID-C607209F-6FC5-31DE-8034-E5B799B857A8.dita"><apiname>ECapabilityWriteDeviceData</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>DRM (digital rights management) </p> </entry>
+<entry><p> <xref href="GUID-C0EF5A59-F716-313A-911F-2D3D773DF597.dita"><apiname>ECapabilityDRM</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>TrustedUI </p> </entry>
+<entry><p> <xref href="GUID-AFB7AB40-B829-37B8-AAB1-7A6FAED9671B.dita"><apiname>ECapabilityTrustedUI</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>ProtServ (server registered with a protected name </p> </entry>
+<entry><p> <xref href="GUID-200CA018-2CB3-3E4A-A505-085FAD2E3E8B.dita"><apiname>ECapabilityProtServ</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>DiskAdmin </p> </entry>
+<entry><p> <xref href="GUID-99D8A4E8-BC4F-39FF-A3DF-832CF0411629.dita"><apiname>ECapabilityDiskAdmin</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>NetworkControl </p> </entry>
+<entry><p> <xref href="GUID-4AFB561B-34D7-3570-A4C9-24B4952C787A.dita"><apiname>ECapabilityNetworkControl</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>AllFiles </p> </entry>
+<entry><p> <xref href="GUID-89631CF3-4AEE-3C2F-8AAE-5D9C3EB3B373.dita"><apiname>ECapabilityAllFiles</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>SwEvent (software key and pen events) </p> </entry>
+<entry><p> <xref href="GUID-369B6584-AB7F-3AA2-B912-E912D2BCBE98.dita"><apiname>ECapabilitySwEvent</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>NetworkServices </p> </entry>
+<entry><p> <xref href="GUID-07A09CBA-CB4E-3CBE-9FA3-930C455F3B0C.dita"><apiname>ECapabilityNetworkServices</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>LocalServices </p> </entry>
+<entry><p> <xref href="GUID-7D0E447B-EC32-355B-8BBF-F074A1B10D8A.dita"><apiname>ECapabilityLocalServices</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>ReadUserData </p> </entry>
+<entry><p> <xref href="GUID-4897D21D-5ACF-30A5-A38C-371A3983814D.dita"><apiname>ECapabilityReadUserData</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>WriteUserData </p> </entry>
+<entry><p> <xref href="GUID-8908E5F7-AC6A-333B-8F65-6DDC46798F48.dita"><apiname>ECapabilityWriteUserData</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>Location (physical location, not locale) </p> </entry>
+<entry><p> <xref href="GUID-1B530864-C77B-3CDE-B761-83C2EED44DB8.dita"><apiname>ECapabilityLocation</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>SurroundingsDD </p> </entry>
+<entry><p> <xref href="GUID-8A207675-B0CF-314E-A4AD-12D839A01A4B.dita"><apiname>ECapabilitySurroundingsDD</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>UserEnvironment </p> </entry>
+<entry><p> <xref href="GUID-05F13261-5EDF-319A-93D6-0247F8C468A3.dita"><apiname>ECapabilityUserEnvironment</apiname></xref>  </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> </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
+Access Guide</linktext></link>
+<link href="GUID-C86A7929-DC0F-50FA-93CB-662A22C4CD35.dita"><linktext>Device Variant
+Using Multiple Keyspace                 Files</linktext></link>
+</related-links></concept>
\ No newline at end of file