<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task xml:lang="en" id="GUID-277BD68B-70CF-5798-A77D-E2B901FA613B"><title>Central Repository Data Access Tutorial</title><shortdesc>This tutorial describes how to access and modify the data in Central Repository at run time on the Symbian platform. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> <prereq id="GUID-04C96E61-FBDE-5A4E-AAD9-75FF4BB80531"><p>Before you start, you must: </p> <ul><li id="GUID-5B3953CA-CFC3-52D9-8177-9D08EC7CEF87"><p>understand the <xref href="GUID-CBC57511-7F28-596A-9763-5674EB41BCAC.dita">Central Repository</xref>  </p> </li> <li id="GUID-B2FFA28E-192F-5982-A331-557D8228BF4A"><p>know how to <xref href="GUID-E3BE62B2-9625-5F79-84A4-0248A3F36225.dita">register and use the repositories</xref> in the Central Repository </p> </li> </ul> </prereq> <context id="GUID-58A8A8B0-EAFA-5AEB-B978-10048CE3B821"><p>Repositories cannot be created at runtime. Applications must register with Central Repository using the initialisation file. The Central Repository API is provided by the <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>CRepository</apiname></xref> class. Applications access the repository with the UID of the repository. Applications must have appropriate access to the repositories. </p> </context> <steps id="GUID-6E0FE2B1-5AAD-5B2C-B304-6DDCFE312B6A"> <step id="GUID-5F2291E4-C723-5F10-BBCC-0FF996DE8201"><cmd> Open a repository</cmd> <info><p>The repositories are identified by a <codeph>UID</codeph>. To access the data in the Central Repository create a new <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>CRepository</apiname></xref> object with the <codeph>UID</codeph> of the repository. </p> </info> <stepxmp><codeblock id="GUID-A3E4A9D4-FFD0-56A3-944F-FE40B0978CD2" xml:space="preserve">CRepository* repository = CRepository::NewL(KMyRepositoryUid);</codeblock> </stepxmp> <info>One <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>CRepository</apiname></xref> object must be created for each repository. </info> </step> <step id="GUID-B986A80F-A665-563D-9B73-AA60DD6BE395"><cmd> Retrieve data from the repository</cmd> <info><p>The data can be retrieved by using <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Get()</apiname></xref> or <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Find()</apiname></xref> functions of the <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>CRepository</apiname></xref> class. </p> </info> <substeps id="GUID-610E555C-C29C-59D4-8931-4E1085943D09"><substep id="GUID-A7BE9113-5ECE-575B-A6F5-2AB183DE7774"><cmd/><info>Use <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Get()</apiname></xref> to retrieve an individual value </info> <stepxmp><codeblock id="GUID-11D2654B-688C-5A1C-916F-413469360511" xml:space="preserve">TInt Get(TUint32 aKey, TInt&amp; aVal);    </codeblock> </stepxmp> </substep> <substep id="GUID-D965F3C6-AAC0-5738-AB6B-9632AD7BA0E4"><cmd/><info>Use <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Find()</apiname></xref> function to retrieve the values by passing a range of keys </info> <info>The input parameters are a partial key and a key mask and the function returns all the settings that match the input range. </info> <stepxmp><codeblock id="GUID-33F36B37-9305-5244-B704-CE09067BAE24" xml:space="preserve">TInt FindL(TUint32 aPartialKey, TUint32 aKeyMask, RArray&lt;TUint32&gt;&amp; aFoundKeys);</codeblock> </stepxmp> <info> <codeph>aKey</codeph> parameter represents a setting in a 32 bit unsigned integer and <codeph>aVal</codeph> represents the corresponding value of the setting. </info> </substep> </substeps> </step> <step id="GUID-A916E538-CF26-512C-B47E-8A0AFF2AFD93"><cmd>Modify the data of the repository

                  opened</cmd> <info><p>The <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Set()</apiname></xref> functions of the <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>CRepository</apiname></xref> class allows the applications to modify the data in the Central Repository. </p> </info> <info>Set new values using <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Set()</apiname></xref>  </info> <stepxmp><codeblock id="GUID-75CEFCF2-8EDA-5601-831B-FD183434223F" xml:space="preserve">

TInt Set(TUint32 aKey, TInt aVal);

</codeblock> </stepxmp> </step> <step id="GUID-54F13AB8-9276-5B96-9355-2D8A5ADF5315"><cmd/><info>  Read the metadata of the repository  </info> <substeps id="GUID-C7CCC06D-A51A-504E-9B48-9568BF9183DB"><substep id="GUID-AD5DE28B-4C8E-5F24-BDED-9C2528D0BAE5"><cmd/><info>Use <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>GetMeta()</apiname></xref> to get the metadata of the repository. </info> <info>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 <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>GetMeta()</apiname></xref> call. </info> </substep> <substep id="GUID-21F48A2A-F372-5ABF-B067-80D34527D667"><cmd/><info>Applications must use logical AND function with the retun value of <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>GetMeta()</apiname></xref> and the constant <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>KMetaUnreserved</apiname></xref> to retrieve the user bits of the metadata. </info> <info>The constant <codeph>KMetaUnreserved</codeph> is defined in <codeph>centralrepository.h</codeph>. </info> </substep> </substeps> <stepxmp><codeblock id="GUID-AD43EA8A-0808-5F4B-9A92-E2FC84818A59" xml:space="preserve">TInt GetMeta(TUint32 aKey, TUint32&amp; aMeta);</codeblock> </stepxmp> </step> <step id="GUID-92638DAF-1888-5D21-8607-E159637193D5"><cmd> Add a new setting</cmd> <info><p>To add a new setting in the repository use <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Create()</apiname></xref>. </p> </info> <stepxmp><codeblock id="GUID-BC3684ED-9898-5AEF-BE12-E9A0FE8DFFF2" xml:space="preserve">TInt Create(TUint32 aKey, TInt aVal);</codeblock> </stepxmp> <info>To delete an existing setting use <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Delete()</apiname></xref>  </info> <stepxmp><codeblock id="GUID-CE998E02-C44A-525B-8CE1-97EFF2585848" xml:space="preserve">TInt Delete(TUint32 aKey);</codeblock> </stepxmp> </step> <step id="GUID-47F70785-7460-5052-85F4-C63CC042F77D"><cmd>Move settings</cmd> <info><p>To move one or more settings from one key to another key use <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Move()</apiname></xref>  </p> </info> <stepxmp><codeblock id="GUID-37DBA666-26C1-544D-9DC9-0B591A2DA9F0" xml:space="preserve">TInt Move (TUint32 aSourcePartialKey, TUint32 aTargetPartialKey, TUint32 aMask, TUint32 &amp;aErrorKey) ;</codeblock> </stepxmp> <info>The source key, target key and the partial mask must be provided by the clients. </info> </step> <step id="GUID-90C11E03-6017-502C-A569-FDE22C18B753"><cmd/><info> Reset the settings  </info> <substeps id="GUID-749BC68F-C733-5571-8086-E0B9F6E370A8"><substep id="GUID-AE2FCCFC-5E47-5511-917A-4B6F2A5CDDEC"><cmd/><info>To reset the settings of a repository to the default values use <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Reset()</apiname></xref>  </info> <stepxmp><codeblock id="GUID-0F53ECD1-8985-500B-B726-CD85B1ACAF55" xml:space="preserve">TInt Reset();</codeblock> </stepxmp> </substep> <substep id="GUID-5B520C2F-5742-5053-B880-A1333A7A02A2"><cmd/><info>To reset a particular setting, pass the key of the setting as a parameter to the <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>Reset()</apiname></xref> function. </info> <stepxmp><codeblock id="GUID-7D9928C4-5769-555A-A896-2A1F4DD61B99" xml:space="preserve">TInt Reset(TUint32 aKey);</codeblock> </stepxmp> <info>Go back to step 2 if you want to modify the settings after a reset or continue to step 8 </info> </substep> </substeps> </step> <step id="GUID-A7CEAD38-A92E-5A06-AC16-8FC91BD6CDF7"><cmd> Close the repository</cmd> <info><p>To close repository, use delete. </p> </info> <stepxmp><codeblock id="GUID-ED364F0C-0267-55FC-8600-885FFABADBB6" xml:space="preserve">delete repository;

</codeblock> </stepxmp> <info>Each instance of the <xref href="GUID-DEA618DF-D462-3B3E-A1E1-F21295AAFE78.dita"><apiname>CRepository</apiname></xref> object must be deleted to clean up the resources. </info> </step> </steps> <result id="GUID-6A19D562-87BE-5BAA-A523-4C7B0CC4C01F"><p>The data in a repository will be modified with the new values by the application. </p> </result> </taskbody><related-links><link href="GUID-AA5DEEB2-0B13-5FA8-8494-EC2F5C654FEF.dita"><linktext>CentRepExample: Using central repository for

                persistent storage</linktext> </link> </related-links></task>