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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-CCD3B91F-9E7F-5CE2-8AFC-4ABF787E5614" xml:lang="en"><title>Using

    13 UPS Management API</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section><title>Introduction</title> <p>Decisions made by phone users are

    15 stored in a decision database. The management APIs allow device creators to

    16 implement a control panel-type application to enable phone users to carry

    17 out the following tasks on stored decisions: </p> <ul>

    18 <li id="GUID-63530E7D-3115-5CD6-9E76-A2D4991DB53E"><p>View "Always" and "Never"

    19 decisions </p> </li>

    20 <li id="GUID-2FD986BA-AA37-5D0B-98D4-CB874C964575"><p>Delete "Always" and

    21 "Never" decisions </p> </li>

    22 <li id="GUID-D72B1FA8-D636-52F0-A42E-DA8BC860AF5F"><p>Change "Always" decisions

    23 to "Never" decisions and vice versa </p> </li>

    24 </ul> <p>The APIs for viewing and deleting records can act on multiple records

    25 in one operation. The set of records may be controlled via a filter, for example

    26 only delete records for a client application with a particular SID. </p> <p>Applications

    27 that allow phone users to view their decisions need <codeph>ReadDeviceData</codeph> capability.

    28 Applications that allow phone users to delete their decisions need <codeph>WriteDeviceData</codeph> capability.

    29 Applications that allow phone users to change their decisions need <codeph>AllFiles</codeph> capability. </p> <p> <b>Note</b>: </p> <ul>

    30 <li id="GUID-2F16752F-9528-51EA-91C1-C06AE50A8D67"><p>Management APIs should

    31 not be called from the policy evaluator or the dialog creator. Doing so could

    32 lead to deadlock. It is best to call them from a control panel-type application. </p> </li>

    33 <li id="GUID-0098B86A-7540-5EE5-83C0-05A2CEBF1760"><p>A query may fail if

    34 another UPS operation is carried out at the same time as the query. For example,

    35 installing a new policy file at the same time as making a query may result

    36 in a conflict that causes the query to fail. </p> </li>

    37 </ul> </section>

    38 <example><title>UPS management APIs implementation example</title> <p>The

    39 following code uses the management APIs: </p> <codeblock id="GUID-8ED40779-581B-5CCA-A16A-DE845BACC034" xml:space="preserve">

    40 

    41 using namespace UserPromptService;

    42 ...

    43 

    44 TRequestStatus rs;

    45 

    46 // Create a management session and a handle to it

    47 RUpsManagement mngmnt;

    48 User::LeaveIfError(mngmnt.Connect());

    49 

    50 // Create a filter, which stores the key values used to query the database. The empty

    51 // filter is first created and then the required filter keys are set separately

    52 CDecisionFilter *filter = CDecisionFilter::NewLC();

    53 filter->SetClientSid(KClientSid, EEqual);

    54 filter->SetServerSid(KServerSid, EEqual);

    55 

    56 // Create a view with a filter and status as parameters

    57 // Needs ReadDeviceData capability

    58 mngmnt.CreateView(*filter, rs);

    59 User::WaitForRequest(rs);

    60 

    61 CleanupStack::PopAndDestroy(filter);

    62 

    63 while(CDecisionRecord *record = mngmnt.NextMatchL())

    64 {

    65  CleanupStack::PushL(record);

    66  // Update the decision value for the current recordId

    67  // Needs AllFiles capability

    68  mngmnt.UpdateDecision(record->iRecordId, ETrue, rs);

    69  User::WaitForRequest(rs);

    70  // Delete the record via an exact filter.

    71  // Needs WriteDeviceData capability.

    72  // We could have just passed "filter" directly to RemoveDecision to remove all

    73  // the matching decisions with a single call

    74  CDecisionFilter *exactFilter = CDecisionFilter::NewLC(record->iClientSid,

    75    record->iEvaluatorId,

    76    record->iServiceId,

    77    record->iServerSid,

    78    record->iFingerprint,

    79    record->iClientEntity,

    80    record->iMajorPolicyVersion);

    81  mngmnt.RemoveDecisionsL(*exactFilter);

    82  CleanupStack::PopAndDestroy(exactFilter);

    83  CleanupStack::PopAndDestroy(record);

    84 };

    85 

    86 // Cancel and close the view and session

    87 mngmnt.CancelAndCloseView();

    88 

    89 // Delete the existing decision database completely.

    90 // Could also call RemoveDecisionsL( filter ) to remove parts of database

    91 // Needs WriteDeviceData capability

    92 mngmnt.DeleteDatabaseL();

    93 mngmnt.Close();

    94 </codeblock></example>

    95 </conbody></concept>