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().

Error handling

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.

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.