Central -Repository Access Guide

Central -Repository Access GuideThis section describes how to make an application read and modify -a repository at runtime from function calls in its application code. -

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.

-Central Repository -Overview -Central Repository -Initialization Files Guide -CenRep Converter -Tool Tutorial + + + + + +Central +Repository Access GuideThis section describes how to make an application read and modify +a repository at runtime from function calls in its application code. +

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.

+Central Repository +Overview +Central Repository +Initialization Files Guide +CenRep Converter +Tool Tutorial

\ No newline at end of file