<?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 &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>