Using UPS Management API

Introduction

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:

  • View "Always" and "Never" decisions

  • Delete "Always" and "Never" decisions

  • Change "Always" decisions to "Never" decisions and vice versa

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.

Applications that allow phone users to view their decisions need ReadDeviceData capability. Applications that allow phone users to delete their decisions need WriteDeviceData capability. Applications that allow phone users to change their decisions need AllFiles capability.

Note:

  • 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.

  • 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.

UPS management APIs implementation example

The following code uses the management APIs: 



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();
Parent topic: Tutorials
© Nokia 2010.