--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-E3BE62B2-9625-5F79-84A4-0248A3F36225.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,108 @@
+<?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-E3BE62B2-9625-5F79-84A4-0248A3F36225" xml:lang="en"><title>Central
+Repository Access Guide</title><shortdesc>This section describes how to make an application read and modify
+a repository at runtime from function calls in its application code. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-02A4A2D8-4167-4AB3-B6B5-8C017D37CC1C"><title>Runtime operations </title> <p><b>Opening
+and closing a repository </b> </p> <p>You open a repository by creating a <codeph>CRepository</codeph> object
+in your code: there is no Open() function. To open several repositories you
+must create one <codeph>CRepository</codeph> object for each of them. These
+objects encapsulate client views of the Central Repository: data integrity
+is maintained by server classes which are not part of the exposed API. You
+read and modify the data in the repository using <codeph>CRepository</codeph> functions
+such as <codeph>Get()</codeph> and <codeph>Set()</codeph>. In order to prevent
+different clients corrupting the repository data with concurrent write operations,
+these operations are wrapped in sequences called transactions. Transactions
+will be explained in the next section. You close a repository by deleting
+the <codeph>CRepository</codeph> object: there is no Close() function. </p> <p>The
+keys are used in the initialization file to identify data items as we saw
+above. They are also used as parameters of the API functions which are used
+to get, set, create, delete, reset and find settings. </p> <p><b>Reading data
+from a repository </b> </p> <p>Various functions of a CRepository object read
+the values of the repository settings. These functions all return an error
+message (KErrNone on success). The data requested by a function is returned
+as the value of a parameter of the function, and the data type of the parameter
+must match the data returned. </p> <p>The Get() functions of a CRepository
+object take individual keys as parameters and retrieve the corresponding values.
+You cannot directly retrieve values by specifying a range of keys: you must
+convert a range to a list of individual keys and pass those keys to a Get()
+function. </p> <p>The Find() functions of a CRepository object convert a range
+of keys into a list of individual keys. The input parameters are a partial
+key and a key mask, defining the range: the list of keys is returned as the
+value of another parameter. The list may contain all the keys in the range,
+or may be restricted to keys with specified values. The restricted Find()
+functions take the value of a setting as an input parameter and return variously
+those keys in the range whose values are equal to the parameter or those which
+are not equal to it. </p> <p>The GetMeta() function of a CRepository object
+reads the metadata value assigned to a key. A metadata value is a 32 bit hexadecimal
+number of which the most significant 8 bits are reserved. The reserved bits
+should normally be masked out so that they cannot be used. To do this you
+use a constant defined for the purpose, KMetaUnreserved, with logical AND.
+A metadata value AND KMetaUnreserved has the reserved bits set to 1. </p> <p><b>Writing
+data to a repository </b> </p> <p>The Set() functions of a CRepository object
+write the values of a setting to a repository where the key already exists. </p> <p>To
+create a new key and write its value, use the Create() functions of a CRepository
+object. </p> <p>To delete a key and its value, use the Delete() functions.
+You can delete a group of keys using the partial key and key mask mechanism. </p> <p>To
+restore the default value of a setting, use the Reset() functions of a CRepository
+object. The default value of a setting is the most recent value which was
+explicitly assigned to it, or else the value assigned in the initialization
+file. If no value was ever assigned, a call to Reset() deletes the setting. </p> <p><b>Changing
+permissions on a setting </b> </p> <p>An access policy cannot be changed at
+run time. The permissions created on an area of keyspace are static: that
+area always has those permissions. However, it is possible to modify access
+to a setting at runtime by moving it from one area of keyspace to another
+area with different permissions. You do this by calling the Move() function
+of the CRepository class. </p> <codeblock id="GUID-C2BB8268-58B4-5492-A953-E7B99793CC80" xml:space="preserve">TInt CRepository::Move (TUint32 aSourcePartialKey, TUint32
+          aTargetPartialKey, TUint32 aMask, TUint32 &amp;aErrorKey) 
+        </codeblock> <p>The parameters <codeph>aSourcePartialKey</codeph> and <codeph>aMask</codeph> define
+one range of keys, the source, and the parameters <codeph>aTargetPartialKey</codeph> and <codeph>aMask</codeph> define
+another, the target. The effect of calling the function is to cause the values
+formerly accessed using the source keys to be accessed using the target keys.
+If the target keys have different permissions from the source, those permissions
+will in future govern access to the values concerned. </p> <p><b>Notification
+of changes </b> </p> <p>It will often be the case that your application accesses
+a repository in order to read data written by a separate application. If so,
+your application must request to be notified whenever the other application
+modifies the relevant settings. To request notification of changes to a setting
+or group of settings you use the <codeph>RequestNotify()</codeph> functions
+of a CRepository object with a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> object as
+parameter. The value of this parameter changes when the notification server
+detects a change to the repository. If a single setting has changed, the parameter
+takes the value of that setting: if more than one setting has changed, the
+parameter takes the value <codeph>KUnspecifiedKey</codeph>. To receive notification
+of changes, your code must periodically poll this key. It must also renew
+the <codeph>RequestNotify()</codeph> call before reading the setting which
+has changed. This is important because several changes may occur in quick
+succession and you want to read the latest state of the repository. </p> <p>You
+cancel notifications about specific settings or groups of settings using <codeph>NotifyCancel()</codeph>,
+and you cancel all notifications using <codeph>NotifyCancelAll()</codeph>. </p> </section>
+<section id="GUID-F82316AE-2BC2-4CDD-A1B2-67BE1506F4EE"><title>Error handling</title> <p>Two
+classes of error can occur when a keyspace is installed, upgraded or uninstalled.
+One is installation of a corrupt repository (one which does not conform to
+the specified text or binary format). If the central repository detects corrupt
+repositories, it deletes them. It is preferable to install a repository in
+binary format as corrupt files will then be detected at build time. </p> <p>The
+other class of possible error is system failures such as insufficient memory.
+These prevent the keyspaces from merging and the result is loss of synchronization
+between applications and their repositories. The remedy for errors of this
+kind is to maintain versioning information within the repositories, so that
+the version of a repository can be checked when it is opened and validated
+against the version expected by the client. </p> </section>
+</conbody><related-links>
+<link href="GUID-CBC57511-7F28-596A-9763-5674EB41BCAC.dita"><linktext>Central Repository
+Overview</linktext></link>
+<link href="GUID-36539894-580E-5774-AA79-7F640E8C59E1.dita"><linktext>Central Repository
+Initialization Files 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