Persistentdata for beginners: Central Repository

The central repository component provides persistent storage of settings with support for transactions and change notification.

It is the standard way to store settings and configuration elements on the Symbian platform. Examples of settings stored in central repository include the default starting view for the Calendar application, configuration settings for Location Based Services, and the access points needed to browse the Internet on your device.

It is used throughout in the Symbian platform. Most packages rely on it. There are 665 users of centralrepository.dll in PDK 2.0.e according to the Agile Browser. This makes it one of the most used libraries in the platform (after efsrv, bafl, estor, and cone).

Centralrepository.dll binary users

Packages that use centralrepository.dll in PDK 2.0.e
visualized by the Agile Browser 2.0


Repositories and Settings

Central Repository uses a client-server architecture to allow multiple processes to access settings and to enable central repository to enforce an access control policy (TSecurityPolicy) on behalf of its clients. The component name suggests that there might be a single repository file or database that holds all settings. In fact, the settings are held in a collection of repository files stored within the private directory of the central repository server (\private\10202be9).

Each repository file is identified by UID. The filename of the repository file specifies the UID in hexadecimal (e.g. 101fd63d.txt). You can store up to 2^32 repositories, and each repository can contain up to 2^32 settings. Settings within a repository are identified by a 32-bit key. The type of settings that can be stored are signed integers, real numbers, binary data as 8-bit strings and Unicode strings. The maximum size of data that can be stored in a single setting is 2048 bytes or 1024 Unicode characters.

Creating a repository

It is not possible to create a repository using the API at run-time. You must initialise it first by supplying a text or compiled binary initialisation file at ROM build time if you’re a device creator or as part of your Software Install package file if you’re an after-market developer.

The initialisation file is a UTF-16 format text file and specifies:

  • Header: File format version for central repository usage only
  • Owner (optional): SID of the application or component which is responsible for backing up the repository
  • Metadata (optional): Metadata for settings (e.g. choose if setting is backed-up and restored)
  • Access control: Defines a read and write policy for a repository, a range of settings or an individual setting using capabilities or SID.
  • Initial content: Specify what settings the repository will contain when first opened

To improve performance when opening repositories, you can convert a text format initialisation file to a compiled binary format (.CRE) using the CentRepConv converter tool.

Accessing Central Repository

API (Header, Library) Purpose
CRepository
(centralrepository.h, centralrepository.lib)
Class to access and use the repository
CCenRepNotifyHandler (cenrepnotifyhandler.h, cenrepnotifhandler.lib) Class to start and stop notification of changes
MCenRepNotifyHandlerCallback (cenrepnotifyhandler.h, cenrepnotifhandler.lib) Callback interface to handle the notification events

The CRepository class provides access to a repository. The API includes methods to:

  • Create a new key (CRepository::Create)
  • Read a key (CRepository::Get)
  • Update a key (CRepository::Set)
  • Delete a key (CRepository::Delete)
  • Find a key (CRepository::FindL, FindEqL, FindNeqL)
  • Delete a key (CRepository::Delete)
  • Request notification (CRepository::NotifyRequest)
  • Start / commit a transaction
    (CRepository::StartTransaction, CRepository::CommitTransaction)

CCenRepNotifyHandler is an active object wrapper around the single-shot notification API (CRepository::NotifyRequest). It provides an easy way for Central Repository clients to monitor changes to an individual key or the whole repository.

To create a CCenRepNotifyHandler instance, the client needs to specify a connected CRepository session and callback class derived from MCenRepNotifyHandlerCallback. You use the CCenRepNotifyHandler::StartListeningL API to subscribe to notifications, and CCenRepNotifyHandler::StopListening to unsubscribe. Clients using CCenRepNotifyHandler derive from MCenRepNotifyHandlerCallback and implement the HandleNotify-methods that they are interested in and the HandleNotifyError method. For example, if you are listening for changes to an individual string key value you should implement HandleNotifyString and HandleNotifyError.

Further Resources
Links to further information about central repository:

I haven’t covered all of the features offered by central repository in this post. If you have further questions, please contact the package team (see details how on my About page) or add a comment to this post.

Coming up next…

The next part of the Persistentdata for beginners series will cover DBMS: the original Symbian database engine.

Advertisements

2 Responses to “Persistentdata for beginners: Central Repository”

  1. Suman Says:

    Hi,

    Can you let me know how to create a new database in central repository for my application that can be signed by open signed online.

    Thanks & Regard,
    Suman

    • cdudding Says:

      I don’t think this is possible. To install a new central repository keyspace, you need to update the central repository private directory and you are not the owner of this UID. I have quoted from Open Signed Online page below:

      “Open Signed Online currently does not allow you to sign a SIS that is allocated to someone else and hasn’t been enabled for Open Signing; i.e. if the email address you use for Open Signed Online MUST match the email address of the account which created a UID.”

      The Symbian Signed Test Criteria describes that you should work with a device manufacturer to update central repository.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


%d bloggers like this: