<?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->SetClientSid(KClientSid, EEqual);

filter->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->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->iClientSid,

   record->iEvaluatorId,

   record->iServiceId,

   record->iServerSid,

   record->iFingerprint,

   record->iClientEntity,

   record->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>