Central Repository Data Access Tutorial

This tutorial describes how to access and modify the data in Central Repository at run time on the Symbian platform.

Context

Repositories cannot be created at runtime. Applications must register with Central Repository using the initialisation file. The Central Repository API is provided by the CRepository class. Applications access the repository with the UID of the repository. Applications must have appropriate access to the repositories.

Prerequisites

Before you start, you must:

Steps

  1. Open a repository

    The repositories are identified by a UID. To access the data in the Central Repository create a new CRepository object with the UID of the repository.

    Example:

    CRepository* repository = CRepository::NewL(KMyRepositoryUid);
    One CRepository object must be created for each repository.
  2. Retrieve data from the repository

    The data can be retrieved by using Get() or Find() functions of the CRepository class.

    1. Use Get() to retrieve an individual value

      Example:

      TInt Get(TUint32 aKey, TInt& aVal);    
    2. Use Find() function to retrieve the values by passing a range of keys The input parameters are a partial key and a key mask and the function returns all the settings that match the input range.

      Example:

      TInt FindL(TUint32 aPartialKey, TUint32 aKeyMask, RArray<TUint32>& aFoundKeys);
      aKey parameter represents a setting in a 32 bit unsigned integer and aVal represents the corresponding value of the setting.
  3. Modify the data of the repository opened

    The Set() functions of the CRepository class allows the applications to modify the data in the Central Repository.

    Set new values using Set()

    Example:

    TInt Set(TUint32 aKey, TInt aVal);
    
  4. Read the metadata of the repository
    1. Use GetMeta() to get the metadata of the repository. The eight most significant bits are reserved for internal purpose and clients must not use these values. The value of the reserved bits may change for each GetMeta() call.
    2. Applications must use logical AND function with the retun value of GetMeta() and the constant KMetaUnreserved to retrieve the user bits of the metadata. The constant KMetaUnreserved is defined in centralrepository.h.

    Example:

    TInt GetMeta(TUint32 aKey, TUint32& aMeta);
  5. Add a new setting

    To add a new setting in the repository use Create().

    Example:

    TInt Create(TUint32 aKey, TInt aVal);
    To delete an existing setting use Delete()

    Example:

    TInt Delete(TUint32 aKey);
  6. Move settings

    To move one or more settings from one key to another key use Move()

    Example:

    TInt Move (TUint32 aSourcePartialKey, TUint32 aTargetPartialKey, TUint32 aMask, TUint32 &aErrorKey) ;
    The source key, target key and the partial mask must be provided by the clients.
  7. Reset the settings
    1. To reset the settings of a repository to the default values use Reset()

      Example:

      TInt Reset();
    2. To reset a particular setting, pass the key of the setting as a parameter to the Reset() function.

      Example:

      TInt Reset(TUint32 aKey);
      Go back to step 2 if you want to modify the settings after a reset or continue to step 8
  8. Close the repository

    To close repository, use delete.

    Example:

    delete repository;
    
    Each instance of the CRepository object must be deleted to clean up the resources.

Results

The data in a repository will be modified with the new values by the application.

Related concepts