Central +Repository Access Guide

Runtime operations

Opening +and closing a repository

You open a repository by creating a CRepository object +in your code: there is no Open() function. To open several repositories you +must create one CRepository 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 CRepository functions +such as Get() and Set(). 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 CRepository object: there is no Close() function.

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.

Reading data +from a repository

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.

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.

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.

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.

Writing +data to a repository

The Set() functions of a CRepository object +write the values of a setting to a repository where the key already exists.

To +create a new key and write its value, use the Create() functions of a CRepository +object.

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.

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.

Changing +permissions on a setting

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.

TInt CRepository::Move (TUint32 aSourcePartialKey, TUint32 + aTargetPartialKey, TUint32 aMask, TUint32 &aErrorKey) +

The parameters aSourcePartialKey and aMask define +one range of keys, the source, and the parameters aTargetPartialKey and aMask 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.

Notification +of changes

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 RequestNotify() functions +of a CRepository object with a TRequestStatus 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 KUnspecifiedKey. To receive notification +of changes, your code must periodically poll this key. It must also renew +the RequestNotify() 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.

You +cancel notifications about specific settings or groups of settings using NotifyCancel(), +and you cancel all notifications using NotifyCancelAll().