<?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 xml:lang="en" id="GUID-E3BE62B2-9625-5F79-84A4-0248A3F36225"><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><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 initialisation 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 initialisation 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 &aErrorKey)