<?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 concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-CCD3B91F-9E7F-5CE2-8AFC-4ABF787E5614" xml:lang="en"><title>Using
UPS Management API</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section><title>Introduction</title> <p>Decisions made by phone users are
stored in a decision database. The management APIs allow device creators to
implement a control panel-type application to enable phone users to carry
out the following tasks on stored decisions: </p> <ul>
<li id="GUID-63530E7D-3115-5CD6-9E76-A2D4991DB53E"><p>View "Always" and "Never"
decisions </p> </li>
<li id="GUID-2FD986BA-AA37-5D0B-98D4-CB874C964575"><p>Delete "Always" and
"Never" decisions </p> </li>
<li id="GUID-D72B1FA8-D636-52F0-A42E-DA8BC860AF5F"><p>Change "Always" decisions
to "Never" decisions and vice versa </p> </li>
</ul> <p>The APIs for viewing and deleting records can act on multiple records
in one operation. The set of records may be controlled via a filter, for example
only delete records for a client application with a particular SID. </p> <p>Applications
that allow phone users to view their decisions need <codeph>ReadDeviceData</codeph> capability.
Applications that allow phone users to delete their decisions need <codeph>WriteDeviceData</codeph> capability.
Applications that allow phone users to change their decisions need <codeph>AllFiles</codeph> capability. </p> <p> <b>Note</b>: </p> <ul>
<li id="GUID-2F16752F-9528-51EA-91C1-C06AE50A8D67"><p>Management APIs should
not be called from the policy evaluator or the dialog creator. Doing so could
lead to deadlock. It is best to call them from a control panel-type application. </p> </li>
<li id="GUID-0098B86A-7540-5EE5-83C0-05A2CEBF1760"><p>A query may fail if
another UPS operation is carried out at the same time as the query. For example,
installing a new policy file at the same time as making a query may result
in a conflict that causes the query to fail. </p> </li>
</ul> </section>
<example><title>UPS management APIs implementation example</title> <p>The
following code uses the management APIs: </p> <codeblock id="GUID-8ED40779-581B-5CCA-A16A-DE845BACC034" xml:space="preserve">

using namespace UserPromptService;
...

TRequestStatus rs;

// Create a management session and a handle to it
RUpsManagement mngmnt;
User::LeaveIfError(mngmnt.Connect());

// Create a filter, which stores the key values used to query the database. The empty
// filter is first created and then the required filter keys are set separately
CDecisionFilter *filter = CDecisionFilter::NewLC();
filter-&gt;SetClientSid(KClientSid, EEqual);
filter-&gt;SetServerSid(KServerSid, EEqual);

// Create a view with a filter and status as parameters
// Needs ReadDeviceData capability
mngmnt.CreateView(*filter, rs);
User::WaitForRequest(rs);

CleanupStack::PopAndDestroy(filter);

while(CDecisionRecord *record = mngmnt.NextMatchL())
{
 CleanupStack::PushL(record);
 // Update the decision value for the current recordId
 // Needs AllFiles capability
 mngmnt.UpdateDecision(record-&gt;iRecordId, ETrue, rs);
 User::WaitForRequest(rs);
 // Delete the record via an exact filter.
 // Needs WriteDeviceData capability.
 // We could have just passed "filter" directly to RemoveDecision to remove all
 // the matching decisions with a single call
 CDecisionFilter *exactFilter = CDecisionFilter::NewLC(record-&gt;iClientSid,
   record-&gt;iEvaluatorId,
   record-&gt;iServiceId,
   record-&gt;iServerSid,
   record-&gt;iFingerprint,
   record-&gt;iClientEntity,
   record-&gt;iMajorPolicyVersion);
 mngmnt.RemoveDecisionsL(*exactFilter);
 CleanupStack::PopAndDestroy(exactFilter);
 CleanupStack::PopAndDestroy(record);
};

// Cancel and close the view and session
mngmnt.CancelAndCloseView();

// Delete the existing decision database completely.
// Could also call RemoveDecisionsL( filter ) to remove parts of database
// Needs WriteDeviceData capability
mngmnt.DeleteDatabaseL();
mngmnt.Close();
</codeblock></example>
</conbody></concept>